From 00a08daf61e76a1aef3e1085676eb5b9e9995146 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 12:20:13 -0500 Subject: [PATCH 01/31] Remove core- prefix from .adoc files --- framework-docs/src/docs/asciidoc/core.adoc | 22 +++++++++---------- .../core/{core-aop-api.adoc => aop-api.adoc} | 0 .../asciidoc/core/{core-aop.adoc => aop.adoc} | 0 .../asciidoc/core/{core-aot.adoc => aot.adoc} | 0 .../{core-appendix.adoc => appendix.adoc} | 0 .../core/{core-beans.adoc => beans.adoc} | 0 ...uffer-codec.adoc => databuffer-codec.adoc} | 0 ...core-expressions.adoc => expressions.adoc} | 0 ...core-null-safety.adoc => null-safety.adoc} | 0 .../{core-resources.adoc => resources.adoc} | 0 .../{core-spring-jcl.adoc => spring-jcl.adoc} | 0 .../{core-validation.adoc => validation.adoc} | 0 12 files changed, 11 insertions(+), 11 deletions(-) rename framework-docs/src/docs/asciidoc/core/{core-aop-api.adoc => aop-api.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-aop.adoc => aop.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-aot.adoc => aot.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-appendix.adoc => appendix.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-beans.adoc => beans.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-databuffer-codec.adoc => databuffer-codec.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-expressions.adoc => expressions.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-null-safety.adoc => null-safety.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-resources.adoc => resources.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-spring-jcl.adoc => spring-jcl.adoc} (100%) rename framework-docs/src/docs/asciidoc/core/{core-validation.adoc => validation.adoc} (100%) diff --git a/framework-docs/src/docs/asciidoc/core.adoc b/framework-docs/src/docs/asciidoc/core.adoc index 35b85b16c333..1517d7510874 100644 --- a/framework-docs/src/docs/asciidoc/core.adoc +++ b/framework-docs/src/docs/asciidoc/core.adoc @@ -20,24 +20,24 @@ is also provided. AOT processing can be used to optimize your application ahead-of-time. It is typically used for native image deployment using GraalVM. -include::core/core-beans.adoc[leveloffset=+1] +include::core/beans.adoc[leveloffset=+1] -include::core/core-resources.adoc[leveloffset=+1] +include::core/resources.adoc[leveloffset=+1] -include::core/core-validation.adoc[leveloffset=+1] +include::core/validation.adoc[leveloffset=+1] -include::core/core-expressions.adoc[leveloffset=+1] +include::core/expressions.adoc[leveloffset=+1] -include::core/core-aop.adoc[leveloffset=+1] +include::core/aop.adoc[leveloffset=+1] -include::core/core-aop-api.adoc[leveloffset=+1] +include::core/aop-api.adoc[leveloffset=+1] -include::core/core-null-safety.adoc[leveloffset=+1] +include::core/null-safety.adoc[leveloffset=+1] -include::core/core-databuffer-codec.adoc[leveloffset=+1] +include::core/databuffer-codec.adoc[leveloffset=+1] -include::core/core-spring-jcl.adoc[leveloffset=+1] +include::core/spring-jcl.adoc[leveloffset=+1] -include::core/core-aot.adoc[leveloffset=+1] +include::core/aot.adoc[leveloffset=+1] -include::core/core-appendix.adoc[leveloffset=+1] +include::core/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/src/docs/asciidoc/core/core-aop-api.adoc b/framework-docs/src/docs/asciidoc/core/aop-api.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-aop-api.adoc rename to framework-docs/src/docs/asciidoc/core/aop-api.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-aop.adoc b/framework-docs/src/docs/asciidoc/core/aop.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-aop.adoc rename to framework-docs/src/docs/asciidoc/core/aop.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-aot.adoc b/framework-docs/src/docs/asciidoc/core/aot.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-aot.adoc rename to framework-docs/src/docs/asciidoc/core/aot.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-appendix.adoc b/framework-docs/src/docs/asciidoc/core/appendix.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-appendix.adoc rename to framework-docs/src/docs/asciidoc/core/appendix.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-beans.adoc b/framework-docs/src/docs/asciidoc/core/beans.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-beans.adoc rename to framework-docs/src/docs/asciidoc/core/beans.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-databuffer-codec.adoc b/framework-docs/src/docs/asciidoc/core/databuffer-codec.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-databuffer-codec.adoc rename to framework-docs/src/docs/asciidoc/core/databuffer-codec.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-expressions.adoc b/framework-docs/src/docs/asciidoc/core/expressions.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-expressions.adoc rename to framework-docs/src/docs/asciidoc/core/expressions.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-null-safety.adoc b/framework-docs/src/docs/asciidoc/core/null-safety.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-null-safety.adoc rename to framework-docs/src/docs/asciidoc/core/null-safety.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-resources.adoc b/framework-docs/src/docs/asciidoc/core/resources.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-resources.adoc rename to framework-docs/src/docs/asciidoc/core/resources.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-spring-jcl.adoc b/framework-docs/src/docs/asciidoc/core/spring-jcl.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-spring-jcl.adoc rename to framework-docs/src/docs/asciidoc/core/spring-jcl.adoc diff --git a/framework-docs/src/docs/asciidoc/core/core-validation.adoc b/framework-docs/src/docs/asciidoc/core/validation.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/core-validation.adoc rename to framework-docs/src/docs/asciidoc/core/validation.adoc From 47309003e2a28f5f67e947cb23d728d61c2b311a Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 12:22:27 -0500 Subject: [PATCH 02/31] Remove data-access- prefix from .adoc files --- framework-docs/src/docs/asciidoc/data-access.adoc | 2 +- .../data-access/{data-access-appendix.adoc => appendix.adoc} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename framework-docs/src/docs/asciidoc/data-access/{data-access-appendix.adoc => appendix.adoc} (100%) diff --git a/framework-docs/src/docs/asciidoc/data-access.adoc b/framework-docs/src/docs/asciidoc/data-access.adoc index 3a6a43699829..c223788e6d05 100644 --- a/framework-docs/src/docs/asciidoc/data-access.adoc +++ b/framework-docs/src/docs/asciidoc/data-access.adoc @@ -9136,4 +9136,4 @@ within Web Services. -include::data-access/data-access-appendix.adoc[leveloffset=+1] +include::data-access/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/src/docs/asciidoc/data-access/data-access-appendix.adoc b/framework-docs/src/docs/asciidoc/data-access/appendix.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/data-access/data-access-appendix.adoc rename to framework-docs/src/docs/asciidoc/data-access/appendix.adoc From b1ceee48af0ca68dfc400a9a0579eac2d28890bf Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 12:25:37 -0500 Subject: [PATCH 03/31] Remove integration- prefix from .adoc files --- framework-docs/src/docs/asciidoc/integration.adoc | 2 +- .../integration/{integration-appendix.adoc => appendix.adoc} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename framework-docs/src/docs/asciidoc/integration/{integration-appendix.adoc => appendix.adoc} (100%) diff --git a/framework-docs/src/docs/asciidoc/integration.adoc b/framework-docs/src/docs/asciidoc/integration.adoc index 2dd9aeb1e193..83f6b3c28f9f 100644 --- a/framework-docs/src/docs/asciidoc/integration.adoc +++ b/framework-docs/src/docs/asciidoc/integration.adoc @@ -20,4 +20,4 @@ include::integration/cache.adoc[leveloffset=+1] include::integration/observability.adoc[leveloffset=+1] -include::integration/integration-appendix.adoc[leveloffset=+1] +include::integration/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/src/docs/asciidoc/integration/integration-appendix.adoc b/framework-docs/src/docs/asciidoc/integration/appendix.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration/integration-appendix.adoc rename to framework-docs/src/docs/asciidoc/integration/appendix.adoc From 2bb9c176eafae7aad389cd21b6cad8bcd316de54 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 12:28:17 -0500 Subject: [PATCH 04/31] Remove -languages suffix from .adoc files --- framework-docs/src/docs/asciidoc/languages.adoc | 2 +- .../asciidoc/languages/{dynamic-languages.adoc => dynamic.adoc} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename framework-docs/src/docs/asciidoc/languages/{dynamic-languages.adoc => dynamic.adoc} (100%) diff --git a/framework-docs/src/docs/asciidoc/languages.adoc b/framework-docs/src/docs/asciidoc/languages.adoc index 1f37d2217c14..42c9615ae65e 100644 --- a/framework-docs/src/docs/asciidoc/languages.adoc +++ b/framework-docs/src/docs/asciidoc/languages.adoc @@ -7,6 +7,6 @@ include::languages/kotlin.adoc[leveloffset=+1] include::languages/groovy.adoc[leveloffset=+1] -include::languages/dynamic-languages.adoc[leveloffset=+1] +include::languages/dynamic.adoc[leveloffset=+1] diff --git a/framework-docs/src/docs/asciidoc/languages/dynamic-languages.adoc b/framework-docs/src/docs/asciidoc/languages/dynamic.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/languages/dynamic-languages.adoc rename to framework-docs/src/docs/asciidoc/languages/dynamic.adoc From 4d4e5c2df330d15f27bfc560b14ddb6db65dc8a6 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 12:34:06 -0500 Subject: [PATCH 05/31] Remove duplicated testing from .adoc file path --- framework-docs/src/docs/asciidoc/testing.adoc | 12 ++++++------ .../{testing-annotations.adoc => annotations.adoc} | 0 .../src/docs/asciidoc/testing/appendix.adoc | 6 ++++++ .../{integration-testing.adoc => integration.adoc} | 0 .../{testing-introduction.adoc => introduction.adoc} | 0 .../{testing-resources.adoc => resources.adoc} | 0 .../{testing-support-jdbc.adoc => support-jdbc.adoc} | 0 .../src/docs/asciidoc/testing/testing-appendix.adoc | 6 ------ .../testing/{unit-testing.adoc => unit.adoc} | 0 ...testing-webtestclient.adoc => webtestclient.adoc} | 0 10 files changed, 12 insertions(+), 12 deletions(-) rename framework-docs/src/docs/asciidoc/testing/{testing-annotations.adoc => annotations.adoc} (100%) create mode 100644 framework-docs/src/docs/asciidoc/testing/appendix.adoc rename framework-docs/src/docs/asciidoc/testing/{integration-testing.adoc => integration.adoc} (100%) rename framework-docs/src/docs/asciidoc/testing/{testing-introduction.adoc => introduction.adoc} (100%) rename framework-docs/src/docs/asciidoc/testing/{testing-resources.adoc => resources.adoc} (100%) rename framework-docs/src/docs/asciidoc/testing/{testing-support-jdbc.adoc => support-jdbc.adoc} (100%) delete mode 100644 framework-docs/src/docs/asciidoc/testing/testing-appendix.adoc rename framework-docs/src/docs/asciidoc/testing/{unit-testing.adoc => unit.adoc} (100%) rename framework-docs/src/docs/asciidoc/testing/{testing-webtestclient.adoc => webtestclient.adoc} (100%) diff --git a/framework-docs/src/docs/asciidoc/testing.adoc b/framework-docs/src/docs/asciidoc/testing.adoc index 941074726c1c..4f696b048d04 100644 --- a/framework-docs/src/docs/asciidoc/testing.adoc +++ b/framework-docs/src/docs/asciidoc/testing.adoc @@ -11,20 +11,20 @@ constructors on classes makes them easier to wire together in a test without hav set up service locator registries and similar structures). -include::testing/testing-introduction.adoc[leveloffset=+1] +include::testing/introduction.adoc[leveloffset=+1] -include::testing/unit-testing.adoc[leveloffset=+1] +include::testing/unit.adoc[leveloffset=+1] -include::testing/integration-testing.adoc[leveloffset=+1] +include::testing/integration.adoc[leveloffset=+1] -include::testing/testing-support-jdbc.adoc[leveloffset=+1] +include::testing/support-jdbc.adoc[leveloffset=+1] include::testing/testcontext-framework.adoc[leveloffset=+1] -include::testing/testing-webtestclient.adoc[leveloffset=+1] +include::testing/webtestclient.adoc[leveloffset=+1] include::testing/spring-mvc-test-framework.adoc[leveloffset=+1] include::testing/spring-mvc-test-client.adoc[leveloffset=+1] -include::testing/testing-appendix.adoc[leveloffset=+1] +include::testing/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/src/docs/asciidoc/testing/testing-annotations.adoc b/framework-docs/src/docs/asciidoc/testing/annotations.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/testing-annotations.adoc rename to framework-docs/src/docs/asciidoc/testing/annotations.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/appendix.adoc b/framework-docs/src/docs/asciidoc/testing/appendix.adoc new file mode 100644 index 000000000000..3d01da459c7f --- /dev/null +++ b/framework-docs/src/docs/asciidoc/testing/appendix.adoc @@ -0,0 +1,6 @@ +[[testing.appendix]] += Appendix + +include::annotations.adoc[leveloffset=+1] + +include::resources.adoc[leveloffset=+1] diff --git a/framework-docs/src/docs/asciidoc/testing/integration-testing.adoc b/framework-docs/src/docs/asciidoc/testing/integration.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/integration-testing.adoc rename to framework-docs/src/docs/asciidoc/testing/integration.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/testing-introduction.adoc b/framework-docs/src/docs/asciidoc/testing/introduction.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/testing-introduction.adoc rename to framework-docs/src/docs/asciidoc/testing/introduction.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/testing-resources.adoc b/framework-docs/src/docs/asciidoc/testing/resources.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/testing-resources.adoc rename to framework-docs/src/docs/asciidoc/testing/resources.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/testing-support-jdbc.adoc b/framework-docs/src/docs/asciidoc/testing/support-jdbc.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/testing-support-jdbc.adoc rename to framework-docs/src/docs/asciidoc/testing/support-jdbc.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/testing-appendix.adoc b/framework-docs/src/docs/asciidoc/testing/testing-appendix.adoc deleted file mode 100644 index f9fc1a1454b3..000000000000 --- a/framework-docs/src/docs/asciidoc/testing/testing-appendix.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[[testing.appendix]] -= Appendix - -include::testing-annotations.adoc[leveloffset=+1] - -include::testing-resources.adoc[leveloffset=+1] diff --git a/framework-docs/src/docs/asciidoc/testing/unit-testing.adoc b/framework-docs/src/docs/asciidoc/testing/unit.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/unit-testing.adoc rename to framework-docs/src/docs/asciidoc/testing/unit.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/testing-webtestclient.adoc b/framework-docs/src/docs/asciidoc/testing/webtestclient.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/testing-webtestclient.adoc rename to framework-docs/src/docs/asciidoc/testing/webtestclient.adoc From 6320416d2628a9cf624334176b4caa9de6434342 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:23:59 -0500 Subject: [PATCH 06/31] Migrate Structure --- .../assets/images/DataAccessException.png | Bin 0 -> 8884 bytes .../ROOT/assets/images/aop-proxy-call.png | Bin 0 -> 3511 bytes .../images/aop-proxy-plain-pojo-call.png | Bin 0 -> 2548 bytes .../ROOT/assets/images/container-magic.png | Bin 0 -> 8673 bytes .../images/message-flow-broker-relay.png | Bin 0 -> 80126 bytes .../images/message-flow-simple-broker.png | Bin 0 -> 65382 bytes .../assets/images/mvc-context-hierarchy.png | Bin 0 -> 64492 bytes .../assets/images/mvc-context-hierarchy.svg | 612 +++++++ .../ROOT/assets/images/oxm-exceptions.graffle | 1619 +++++++++++++++++ .../ROOT/assets/images/oxm-exceptions.png | Bin 0 -> 28027 bytes .../modules/ROOT/assets/images/prototype.png | Bin 0 -> 83478 bytes .../modules/ROOT/assets/images/singleton.png | Bin 0 -> 85523 bytes .../images/spring-mvc-and-webflux-venn.png | Bin 0 -> 104380 bytes .../modules/ROOT/assets/images/tx.png | Bin 0 -> 82811 bytes .../ROOT/assets/images/tx_prop_required.png | Bin 0 -> 40355 bytes .../assets/images/tx_prop_requires_new.png | Bin 0 -> 48060 bytes .../ROOT/pages}/appendix.adoc | 0 .../ROOT/pages}/attributes.adoc | 0 .../asciidoc => modules/ROOT/pages}/core.adoc | 0 .../ROOT/pages}/core/aop-api.adoc | 0 .../ROOT/pages}/core/aop.adoc | 0 .../ROOT/pages}/core/aot.adoc | 0 .../ROOT/pages}/core/appendix.adoc | 0 .../ROOT/pages}/core/beans.adoc | 0 .../ROOT/pages}/core/databuffer-codec.adoc | 0 .../ROOT/pages}/core/expressions.adoc | 0 .../ROOT/pages}/core/null-safety.adoc | 0 .../ROOT/pages}/core/resources.adoc | 0 .../ROOT/pages}/core/spring-jcl.adoc | 0 .../ROOT/pages}/core/validation.adoc | 0 .../ROOT/pages}/data-access.adoc | 0 .../ROOT/pages}/data-access/appendix.adoc | 0 .../ROOT/pages}/index.adoc | 0 .../ROOT/pages}/integration.adoc | 0 .../ROOT/pages}/integration/appendix.adoc | 0 .../ROOT/pages}/integration/cache.adoc | 0 .../ROOT/pages}/integration/email.adoc | 0 .../ROOT/pages}/integration/jms.adoc | 0 .../ROOT/pages}/integration/jmx.adoc | 0 .../pages}/integration/observability.adoc | 0 .../ROOT/pages}/integration/rest-clients.adoc | 0 .../ROOT/pages}/integration/scheduling.adoc | 0 .../ROOT/pages}/languages.adoc | 0 .../ROOT/pages}/languages/dynamic.adoc | 0 .../ROOT/pages}/languages/groovy.adoc | 0 .../ROOT/pages}/languages/kotlin.adoc | 0 .../ROOT/pages}/overview.adoc | 0 .../ROOT/pages}/page-layout.adoc | 0 .../ROOT/pages}/rsocket.adoc | 0 .../ROOT/pages}/testing.adoc | 0 .../ROOT/pages}/testing/annotations.adoc | 0 .../ROOT/pages}/testing/appendix.adoc | 0 .../ROOT/pages}/testing/integration.adoc | 0 .../ROOT/pages}/testing/introduction.adoc | 0 .../ROOT/pages}/testing/resources.adoc | 0 .../testing/spring-mvc-test-client.adoc | 0 .../testing/spring-mvc-test-framework.adoc | 0 .../ROOT/pages}/testing/support-jdbc.adoc | 0 .../pages}/testing/testcontext-framework.adoc | 0 .../ROOT/pages}/testing/unit.adoc | 0 .../ROOT/pages}/testing/webtestclient.adoc | 0 .../ROOT/pages}/web-reactive.adoc | 0 .../asciidoc => modules/ROOT/pages}/web.adoc | 0 .../ROOT/pages}/web/integration.adoc | 0 .../web/web-data-binding-model-design.adoc | 0 .../ROOT/pages}/web/web-uris.adoc | 0 .../ROOT/pages}/web/webflux-cors.adoc | 0 .../ROOT/pages}/web/webflux-functional.adoc | 0 .../ROOT/pages}/web/webflux-view.adoc | 0 .../ROOT/pages}/web/webflux-webclient.adoc | 0 .../ROOT/pages}/web/webflux-websocket.adoc | 0 .../ROOT/pages}/web/webflux.adoc | 0 .../ROOT/pages}/web/webmvc-client.adoc | 0 .../ROOT/pages}/web/webmvc-cors.adoc | 0 .../ROOT/pages}/web/webmvc-functional.adoc | 0 .../ROOT/pages}/web/webmvc-test.adoc | 0 .../ROOT/pages}/web/webmvc-view.adoc | 0 .../ROOT/pages}/web/webmvc.adoc | 0 .../ROOT/pages}/web/websocket-intro.adoc | 0 .../ROOT/pages}/web/websocket.adoc | 0 80 files changed, 2231 insertions(+) create mode 100644 framework-docs/modules/ROOT/assets/images/DataAccessException.png create mode 100644 framework-docs/modules/ROOT/assets/images/aop-proxy-call.png create mode 100644 framework-docs/modules/ROOT/assets/images/aop-proxy-plain-pojo-call.png create mode 100644 framework-docs/modules/ROOT/assets/images/container-magic.png create mode 100644 framework-docs/modules/ROOT/assets/images/message-flow-broker-relay.png create mode 100644 framework-docs/modules/ROOT/assets/images/message-flow-simple-broker.png create mode 100644 framework-docs/modules/ROOT/assets/images/mvc-context-hierarchy.png create mode 100644 framework-docs/modules/ROOT/assets/images/mvc-context-hierarchy.svg create mode 100644 framework-docs/modules/ROOT/assets/images/oxm-exceptions.graffle create mode 100644 framework-docs/modules/ROOT/assets/images/oxm-exceptions.png create mode 100644 framework-docs/modules/ROOT/assets/images/prototype.png create mode 100644 framework-docs/modules/ROOT/assets/images/singleton.png create mode 100644 framework-docs/modules/ROOT/assets/images/spring-mvc-and-webflux-venn.png create mode 100644 framework-docs/modules/ROOT/assets/images/tx.png create mode 100644 framework-docs/modules/ROOT/assets/images/tx_prop_required.png create mode 100644 framework-docs/modules/ROOT/assets/images/tx_prop_requires_new.png rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/appendix.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/attributes.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/aop-api.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/aop.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/aot.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/appendix.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/beans.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/databuffer-codec.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/expressions.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/null-safety.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/resources.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/spring-jcl.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/core/validation.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/data-access.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/data-access/appendix.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/index.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/integration.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/integration/appendix.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/integration/cache.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/integration/email.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/integration/jms.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/integration/jmx.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/integration/observability.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/integration/rest-clients.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/integration/scheduling.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/languages.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/languages/dynamic.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/languages/groovy.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/languages/kotlin.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/overview.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/page-layout.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/rsocket.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/annotations.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/appendix.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/integration.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/introduction.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/resources.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/spring-mvc-test-client.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/spring-mvc-test-framework.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/support-jdbc.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/testcontext-framework.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/unit.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/testing/webtestclient.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web-reactive.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/integration.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/web-data-binding-model-design.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/web-uris.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webflux-cors.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webflux-functional.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webflux-view.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webflux-webclient.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webflux-websocket.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webflux.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webmvc-client.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webmvc-cors.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webmvc-functional.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webmvc-test.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webmvc-view.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/webmvc.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/websocket-intro.adoc (100%) rename framework-docs/{src/docs/asciidoc => modules/ROOT/pages}/web/websocket.adoc (100%) diff --git a/framework-docs/modules/ROOT/assets/images/DataAccessException.png b/framework-docs/modules/ROOT/assets/images/DataAccessException.png new file mode 100644 index 0000000000000000000000000000000000000000..746f17399b995fa3e45cf0ac7c12a255abfd105b GIT binary patch literal 8884 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 literal 0 HcmV?d00001 diff --git a/framework-docs/modules/ROOT/assets/images/aop-proxy-plain-pojo-call.png b/framework-docs/modules/ROOT/assets/images/aop-proxy-plain-pojo-call.png new file mode 100644 index 0000000000000000000000000000000000000000..8ece077d34456a89d8864c95e3a97784f2c52cf1 GIT binary patch literal 2548 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 V?Yfd<4A(UWv>xfISE{~v{U6xW!2|#R literal 0 HcmV?d00001 diff --git a/framework-docs/modules/ROOT/assets/images/message-flow-broker-relay.png b/framework-docs/modules/ROOT/assets/images/message-flow-broker-relay.png new file mode 100644 index 0000000000000000000000000000000000000000..3cf93fa1439c63b39564c06008e1a07d508307de GIT binary patch literal 80126 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 literal 0 HcmV?d00001 diff --git a/framework-docs/modules/ROOT/assets/images/message-flow-simple-broker.png b/framework-docs/modules/ROOT/assets/images/message-flow-simple-broker.png new file mode 100644 index 0000000000000000000000000000000000000000..9afd54f57c23db5d535bee398bc3461e2e87b69c GIT binary patch literal 65382 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 + + +image/svg+xmlPage-1DispatcherServlet +Servlet WebApplicationContext +(containing controllers, view resolvers,and other web-related beans) +Controllers +ViewResolver +HandlerMapping +Root WebApplicationContext +(containing middle-tier services, datasources, etc.) +Services +Repositories +Delegates if no bean found + \ No newline at end of file diff --git a/framework-docs/modules/ROOT/assets/images/oxm-exceptions.graffle b/framework-docs/modules/ROOT/assets/images/oxm-exceptions.graffle new file mode 100644 index 000000000000..4b72bf45285b --- /dev/null +++ b/framework-docs/modules/ROOT/assets/images/oxm-exceptions.graffle @@ -0,0 +1,1619 @@ + + + + + ActiveLayerIndex + 0 + ApplicationVersion + + com.omnigroup.OmniGraffle + 137.11.0.108132 + + AutoAdjust + + BackgroundGraphic + + Bounds + {{0, 0}, {756, 553}} + Class + SolidGraphic + ID + 2 + Style + + shadow + + Draws + NO + + stroke + + Draws + NO + + + + CanvasOrigin + {0, 0} + ColumnAlign + 1 + ColumnSpacing + 36 + CreationDate + 2009-09-11 10:15:26 -0400 + Creator + Thomas Risberg + DisplayScale + 1 0/72 in = 1 0/72 in + GraphDocumentVersion + 6 + GraphicsList + + + Class + LineGraphic + FontInfo + + Font + Helvetica + Size + 18 + + ID + 42 + Points + + {334.726, 144} + {394.042, 102.288} + + Style + + stroke + + HeadArrow + FilledArrow + TailArrow + 0 + + + + + Class + LineGraphic + FontInfo + + Font + Helvetica + Size + 18 + + ID + 41 + Points + + {489.5, 143.713} + {430.452, 102.287} + + Style + + stroke + + HeadArrow + FilledArrow + TailArrow + 0 + + + + + Class + LineGraphic + FontInfo + + Font + Helvetica + Size + 18 + + Head + + ID + 4 + + ID + 40 + Points + + {230, 217} + {275.683, 175.337} + + Style + + stroke + + HeadArrow + FilledArrow + TailArrow + 0 + + + + + Class + LineGraphic + FontInfo + + Font + Helvetica + Size + 18 + + Head + + ID + 4 + + ID + 39 + Points + + {430.381, 216.81} + {329.369, 175.19} + + Style + + stroke + + HeadArrow + FilledArrow + TailArrow + 0 + + + Tail + + ID + 5 + + + + Bounds + {{56, 217}, {249, 30}} + Class + ShapedGraphic + FontInfo + + Font + Helvetica + Size + 18 + + ID + 6 + Shape + Rectangle + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf540 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\deftab720 +\pard\pardeftab720\qc + +\f0\fs36 \cf0 MarshallingFailureException} + + + + Bounds + {{325.5, 217}, {283.5, 30}} + Class + ShapedGraphic + FontInfo + + Font + Helvetica + Size + 18 + + ID + 5 + Shape + Rectangle + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf540 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\deftab720 +\pard\pardeftab720\qc + +\f0\fs36 \cf0 UnmarshallingFailureException} + + + + Bounds + {{184, 145}, {217, 30}} + Class + ShapedGraphic + FontInfo + + Font + Helvetica + Size + 18 + + ID + 4 + Shape + Rectangle + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf540 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\deftab720 +\pard\pardeftab720\qc + +\f0\fs36 \cf0 MarshallingException} + + + + Bounds + {{430, 145}, {239, 30}} + Class + ShapedGraphic + FontInfo + + Font + Helvetica + Size + 18 + + ID + 3 + Shape + Rectangle + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf540 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\deftab720 +\pard\pardeftab720\qc + +\f0\fs36 \cf0 ValidationFailureException} + + + + Bounds + {{294, 72}, {244, 30}} + Class + ShapedGraphic + FontInfo + + Font + Helvetica + Size + 18 + + ID + 1 + Shape + Rectangle + Style + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf540 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\deftab720 +\pard\pardeftab720\qc + +\f0\i\fs36 \cf0 XmlMappingException} + + Wrap + NO + + + GridInfo + + GuidesLocked + NO + GuidesVisible + YES + HPages + 1 + ImageCounter + 1 + KeepToScale + + Layers + + + Lock + NO + Name + Layer 1 + Print + YES + View + YES + + + LayoutInfo + + Animate + NO + circoMinDist + 18 + circoSeparation + 0.0 + layoutEngine + dot + neatoSeparation + 0.0 + twopiSeparation + 0.0 + + LinksVisible + NO + MagnetsVisible + NO + MasterSheets + + ModificationDate + 2009-09-11 10:38:54 -0400 + Modifier + Thomas Risberg + NotesVisible + NO + Orientation + 2 + OriginVisible + NO + PageBreaks + YES + PrintInfo + + NSBottomMargin + + float + 41 + + NSLeftMargin + + float + 18 + + NSOrientation + + int + 1 + + NSPaperSize + + size + {792, 612} + + NSRightMargin + + float + 18 + + NSTopMargin + + float + 18 + + + PrintOnePage + + QuickLookPreview + + JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPDwgL0xlbmd0aCA1IDAgUiAvRmls + dGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAGVlk1vG0cMhu/zK3h0Dx4Ph/N5rZsA + DRCgqdW0V0GVGhkryZGdoj+/L2e1q4W1cloLhhZrfr0PORx/pU/0lRw+OSaKUei4pt9p + T84m135oS3f3z0yrZ+L2eV7RrbPx9Nfz0ymAQYAN3f2yPq7WTy/flh0dt0jhU2ppoidf + hIIkWu3o7ucd00+HVoRPPFgEriRJTG/hRwupgwVnUYtTDBksxI1ZhION5Csqb3mCGfLk + c56pQeyD3P267pYv27/X94fucNzu1i/H7Uo1+BooRCYfAonrZTJ9AJPHntD9Q6vO0cM9 + BPdJbvVLsaIIDZAhv/kr5wfoBltvwNYRuDrAnngGThTADb4/LohLC3+L79tSbQwZDDMt + oO49W4eEi425+WPXfVw+PW33f737RxuwPex/oMUjvVsg2ZtNDeJIciEPyoO+STGjDLXj + AHLNbqpDZ2RORwwol6S2hr5Swi7aUpVMr8SflNDN53PdkzLeilWj9d7ly1DLbvsnenrY + v19uu2/H9Ws05jtouKDlioYz0KjkzbRPIxq1a2ianY7I0OJraHz1PZq5Jkc0WWqkbFqT + z2g+Lo/PX5Zd9/+7bMQjKkQkPYbt6bqc3lZFT20HSVenNmXrkcK3k/e63R6nMpZxcJsm + s9jQzW/73VnVlT59b4Sxwpqy8PYEw6yJamb/ZYC5YM2pIt1IrxWxWBdlZuomXZrTYy6O + 5GTMx5HCabNSOKDiZIvDNOxIpNjowZdzsTVxNd0waG1P6zpv51CELXtsH8nZuhJzc85W + cvV4x9anINQhYLUpKY6MJNwCfsHbS+8NAn/A7+Ps/I8enKOtjNg7I3LKx4VtFtQwycfI + x6Uw3k3ynb2brNOSNXN4PI6j9hLbNRUrSQ9gwVC5gpA6qT4H6zP2i0qT4kszxWNI1UgW + 6x2msYMdOOutU2zOIKYFzfleB6CzMXqosMTY9lpYnw3dqjaDyjkb9gU2VlAkk2yDr9lN + 5c8CD3oRYOWIzQzYuFYxGTHhlcu2ZqhtFEwQZZJxgWEVJ48rRG3Ra5GId9hBudUVgutp + hZBtKNI35sIblV3noJts9GAnmLaiHMZ8zM4G36gP+YxeA5FTbSTmvLWXw207NwgiwWaf + wCKgOimYP8DoORSvhDWCYN2Ggk3eODD+OVBbNAFDg3fQrBwxoCXjQNRoGpsk/TzMeb/N + YfRoHHB8W22nfE2zL+1AnPJRYyOpn4gLb1SrKj79C2PwIN4KZW5kc3RyZWFtCmVuZG9i + ago1IDAgb2JqCjkyNgplbmRvYmoKMiAwIG9iago8PCAvVHlwZSAvUGFnZSAvUGFyZW50 + IDMgMCBSIC9SZXNvdXJjZXMgNiAwIFIgL0NvbnRlbnRzIDQgMCBSIC9NZWRpYUJveCBb + MCAwIDc1NiA1NTNdCj4+CmVuZG9iago2IDAgb2JqCjw8IC9Qcm9jU2V0IFsgL1BERiAv + VGV4dCAvSW1hZ2VCIC9JbWFnZUMgL0ltYWdlSSBdIC9Db2xvclNwYWNlIDw8IC9DczIg + MTggMCBSCi9DczEgNyAwIFIgPj4gL0ZvbnQgPDwgL0YxLjAgMTkgMCBSIC9GMi4wIDIw + IDAgUiA+PiAvWE9iamVjdCA8PCAvSW0yIDEwIDAgUgovSW0zIDEyIDAgUiAvSW00IDE0 + IDAgUiAvSW01IDE2IDAgUiAvSW0xIDggMCBSID4+ID4+CmVuZG9iagoxMCAwIG9iago8 + PCAvTGVuZ3RoIDExIDAgUiAvVHlwZSAvWE9iamVjdCAvU3VidHlwZSAvSW1hZ2UgL1dp + ZHRoIDUyMiAvSGVpZ2h0IDEwNCAvQ29sb3JTcGFjZQoyMSAwIFIgL1NNYXNrIDIyIDAg + UiAvQml0c1BlckNvbXBvbmVudCA4IC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVh + bQp4Ae3QMQEAAADCoPVPbQhfiEBhwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMvAMDfE4AAQplbmRzdHJlYW0KZW5kb2JqCjExIDAgb2JqCjcz + NAplbmRvYmoKMTIgMCBvYmoKPDwgL0xlbmd0aCAxMyAwIFIgL1R5cGUgL1hPYmplY3Qg + L1N1YnR5cGUgL0ltYWdlIC9XaWR0aCA0NzggL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UK + MjQgMCBSIC9TTWFzayAyNSAwIFIgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9G + bGF0ZURlY29kZSA+PgpzdHJlYW0KeAHt0DEBAAAAwqD1T+1pCYhAYcCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYOADA0auAAEKZW5kc3RyZWFtCmVuZG9iagox + MyAwIG9iago2NzQKZW5kb2JqCjE0IDAgb2JqCjw8IC9MZW5ndGggMTUgMCBSIC9UeXBl + IC9YT2JqZWN0IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGggNjEyIC9IZWlnaHQgMTA0IC9D + b2xvclNwYWNlCjI3IDAgUiAvU01hc2sgMjggMCBSIC9CaXRzUGVyQ29tcG9uZW50IDgg + L0ZpbHRlciAvRmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB7dCBAAAAAMOg+VNf4AiFUGHA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgIE/MOn+AAEKZW5kc3RyZWFtCmVuZG9iagoxNSAwIG9iago4NTYK + ZW5kb2JqCjE2IDAgb2JqCjw8IC9MZW5ndGggMTcgMCBSIC9UeXBlIC9YT2JqZWN0IC9T + dWJ0eXBlIC9JbWFnZSAvV2lkdGggNTQyIC9IZWlnaHQgMTA0IC9Db2xvclNwYWNlCjMw + IDAgUiAvU01hc2sgMzEgMCBSIC9CaXRzUGVyQ29tcG9uZW50IDggL0ZpbHRlciAvRmxh + dGVEZWNvZGUgPj4Kc3RyZWFtCngB7dAxAQAAAMKg9U9tCy+IQGHAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgy8BwaUrgABCmVuZHN0cmVhbQplbmRvYmoKMTcgMCBvYmoKNzYxCmVuZG9i + ago4IDAgb2JqCjw8IC9MZW5ndGggOSAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUg + L0ltYWdlIC9XaWR0aCA1MzIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKMzMgMCBSIC9T + TWFzayAzNCAwIFIgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29k + ZSA+PgpzdHJlYW0KeAHt0DEBAAAAwqD1T20KP4hAYcCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMDAa2CIfgABCmVuZHN0 + cmVhbQplbmRvYmoKOSAwIG9iago3NDcKZW5kb2JqCjIyIDAgb2JqCjw8IC9MZW5ndGgg + MjMgMCBSIC9UeXBlIC9YT2JqZWN0IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGggNTIyIC9I + ZWlnaHQgMTA0IC9Db2xvclNwYWNlCi9EZXZpY2VHcmF5IC9CaXRzUGVyQ29tcG9uZW50 + IDggL0ZpbHRlciAvRmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB7Z3tT1PZFsZBCqXvLZS2 + 9GVaTgvtaSmdY4sFCtM2bXhHFISpM0LQqhkYkNHYSAZ1MIwSiSI4EF6iyBDRgEPAECVG + zfxrd53CvXOFcrD3fto96/lATDYmez/rl7XXaTlrZWWh0AF0AB1AB9ABdAAdQAfQAXQA + Hfh/HMhGZaADaREB5z/xj3JQGeHAPxE9AQH+CiD2KICzCwS5qIxzQCCA0LJQHAdDkoM9 + CPKEwvw9iVDEO7AfSqEwD+AGHI5hYZ+D3Nw8gEAkFkskEqlUKkNlgAMQSAinWCzKz2dp + 4GaBBSEH7gTAACCQyuRyhVKpQmWIA0qlQi6XAQ9igGGPhSOuiCQIkA9YDmRyhUpVUKhW + FxVpNFoU8Q5oNEVFanVhgUqlkMtYFiAvwBWRGgU2I7AJgeVACRRotLpivd5gNJpQxDtg + NBr0+mKdVgM0KJMsQFpgUUjxEJEEAQoEiRQ4AAyAAZPZYimhrKgMcIAqsVjMJuABYAAW + pBK2XEiNQjZbIwhFkBBUhRqdHiigrKVldgdNO50uFNEOOJ007bCXlVopoEGv0xSqIC2I + hGzdeDgpQEoAEPIlMoVKrdWbLJStjHaWuz0ehmFOogh3AILo8bjLnXSZjbKY9Fq1SiGD + rJArSHE/QEqAYlGcBMFgpkodLreH8Vae8lfXgAIogh1gI1jtP1XpZTxul6OUMhuSKIih + bEyRFLIhJeSLpXKVWmcwW+2uCsbnrw7UBUPhSCQSRRHtAIQwHArWBar9PqbCZbeaDTq1 + Si4V50NSOHg97KUECYCgNVhstJvxVQWC4Wh9Y1NLa9tpFOEOtLW2NDXWR8PBQJWPcdM2 + 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 + Wlpmd9C00+lCEe2A00nTDntZqZWymE16naZQJZdJRADCoXqR/etWSApQNEJWkMqVBWqN + Vm8wAg2WEsqKygAHqBILUGA06LUadYFSLoWMwN4NKVLCPgpwQYghLSgLCgEGXbEeeDCa + UMQ7YAQG9MU6wKAQOJBJxHA1HAVCVnYyK8CzZJIFhUoFNKiLijQaLYp4BzSaoiI1UKBS + KZIcQLGYBOHAhwn7rz4kURDkQloAFiRSmVyuUCpVqAxxQKlUyOUyqQTyAZsQoEY4kZ0a + BLgfICuwdSNbLuSLxICDRCqVylAZ4AAEEsIpFosAA8gHLAdHg8CWjXssAAxAA+CQlAhF + vAP7oRSyFOQKjuUg+QjBsnAiJydHwOKAyjAHAIIcNh1w5oP9aoFNDEka2N8Hwf9EZYAD + e9FM/oQA/yfYX/MP+H1UxjnwNZHH30EH0AF0AB1AB9ABdAAdQAfQAXTgaAf+BYU9EtcK + ZW5kc3RyZWFtCmVuZG9iagoyMyAwIG9iagoyNzE5CmVuZG9iagoyOCAwIG9iago8PCAv + TGVuZ3RoIDI5IDAgUiAvVHlwZSAvWE9iamVjdCAvU3VidHlwZSAvSW1hZ2UgL1dpZHRo + IDYxMiAvSGVpZ2h0IDEwNCAvQ29sb3JTcGFjZQovRGV2aWNlR3JheSAvQml0c1BlckNv + bXBvbmVudCA4IC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4Ae2d7U9T2RaH + BQql7y2U03LaTutpS3taS+fYaoXitKRNESm+oDh1FIJWzVSLHY2NzaAOxlEi8Q1HghhF + xohGHSKGqDGjmX/trl3MnTt290jvyf101+8DMfvI/vDkyVq7B9hrwwYMEkACSAAJIAEk + gASQABJAAkgACSCB/wWBOgwSWD+B2hSEfev/TgMGCYgR+FuVejBnPaqt+QV7ymSNGCSw + XgIyGThDdPuqZmXD1vRqksub16LAIIFqBD47Ipc3gY0g2tcs+2xYY2MT6KVQKlUqlVqt + 1mCQQHUCYAh4olQqmpuJZ1+xjCjWAB0SBAO91BqtVqfXGzBIQJyAXq/TajVgmhI0W7Os + WsMsKwY1jBim0eoMhpZWo7GtjWFMGCRQjQDDtLUZja0tBoNOqyGWQS2DhllFMlLFSBEj + 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 + WX1DQ4OMiIZBAusjAHo1kBImXsM+n8pIMSt7Rr4BAt+KQQLVCaxpUv4K5vzbonX9A74B + gwTWS2BdTuF/QgJIAAkgASSABJAAEkACSAAJIAEkUDuBfwFWtww3CmVuZHN0cmVhbQpl + bmRvYmoKMjkgMCBvYmoKMzAwNwplbmRvYmoKMzEgMCBvYmoKPDwgL0xlbmd0aCAzMiAw + IFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdlIC9XaWR0aCA1NDIgL0hlaWdo + dCAxMDQgL0NvbG9yU3BhY2UKL0RldmljZUdyYXkgL0JpdHNQZXJDb21wb25lbnQgOCAv + RmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAHtnetPU+kWxrkUer9B2S29TMtu + ueyW0tlSLFCclrQBykXkOnUUghTNwICMxkYyqINhlEgUwYFwiSJDRAMOAUOUGDXzr521 + CzlzhLKZnk/nvHs9H4zJWz+sZ/1ca+1e3pWWhkIH0AF0AB1AB9ABdAAdQAfQAXTg/9GB + dJRAHEiJTvAk429looh14O8sZ0DS/wEkB2SAHyJRFkoQDohEkG4OlNMASbBxAEa2WCw5 + kBRFpAOH6RWLs+E/ASByCh+HbGRlZQMYUplMLpcrFAolilAHILmQYplMKpFwhPDzwcGR + Cf0E0AAwFEqVSq3RaFEEO6DRqFUqJTAiA0AO+DihvSTggLrBsaFUqbXanFydLi+PovQo + Ih2gqLw8nS43R6tVq5QcH1A/oL0kx4OrHFzh4NjQABmU3pBvNJrMZguKSAfMZpPRmG/Q + U0CIJsEHlA8OjyQPLwk4YOCQK4ANQAO4sFhttgLajiLUAbrAZrNagBEABPhQyLnxIzke + 6dzMIZZC4dDmUgYjkEHbC4uKSxjG6XShiHPA6WSYkuKiQjsNhBgNVK4WyodUzM2mx4sH + lA6AQyJXqrU6vdFiox1FjLPU7fGwLHsGRaADkFiPx13qZIoctM1i1Ou0aiVUjyxRkt4C + pQMGUlkCDpOVLixxuT1secVZX1U1yI8izAEuq1W+sxXlrMftKimkraYEHjIYTZMUj3Qo + HRKZQqXVGUxWe7GrjPX6qvznAsHaUCgURhHnAKS1Nhg456/yedkyV7HdajLotCqFTALF + 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 + YQ5wWa3yna0oZz1uV0khzbUVrRr6SrLSAbUDiodYIk/gYbTYaEcR4yx1ezwsy55BEegA + JNbjcZc6mSIHbbMYE3DIJWIoHUfHDviSKcylgIdUrlRpcymD0WK10fbCouIShnE6XSji + HHA6GaakuKjQTtusFqOBytWqlHIpwHFsJuW+gQzFIzMrG6qHQqXJ0VF6o8kMhNgKaDuK + UAfoAhuQYTYZ9ZQuR6NSQOXg+kqS0nGIBzQXGZQPTU4uAGLINwIjZguKSAfMwIUx3wBo + 5AIbSrkM2spJcKSlJ6pHVrYkwYdaqwVCdHl5FKVHEekAReXl6YAMrVadYAMG0gQcR94K + O/xpSwIPURaUD+BDrlCqVGqNRosi2AGNRq1SKRVyqBtc4YCZIyM9ORzQW6B6cLMpN35I + pDJARK5QKJQoQh2A5EKKZTIpoAF1g2PjZDi40fSADwAECAFEEpKiiHTgML1ijows0als + JB5dOD4yMjMzRRwiKAE4AGBkcmWDt24cTh9cAUkQwr0eBP8SRagDBxlO/AlJ/zcA/+Qv + 8HqUIBz4JzTga9ABdAAdQAfQAXQAHUAH0AF0AB3433PgX6y7qcQKZW5kc3RyZWFtCmVu + ZG9iagozMiAwIG9iagoyNzYyCmVuZG9iagoyNSAwIG9iago8PCAvTGVuZ3RoIDI2IDAg + UiAvVHlwZSAvWE9iamVjdCAvU3VidHlwZSAvSW1hZ2UgL1dpZHRoIDQ3OCAvSGVpZ2h0 + IDEwNCAvQ29sb3JTcGFjZQovRGV2aWNlR3JheSAvQml0c1BlckNvbXBvbmVudCA4IC9G + aWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4Ae2d/U8T2RfGeSn0fToD7bRM222Z + Uui0lO4IWAFdIBAUAV9Q3LorBK2ahQW7GhubRV0Mq8RGEVwIL1FkiWjAJWCIErOa/de+ + Z4rZXaEdvt2f7iTn+cFoLiaH58Nz723pnJOTg0IH0AF0AB1AB9ABdAAdQAfQgf/mQC5K + IQ5kxRe+p7x/lI8i1oF/KOUBtP8D8g5Z+H5UqgKUIhxQqQCXBHo/wCm2O2AL1WrNjrQo + Ih34jEetLoQfQkC8D9/PbAsKCgGsVqfT6/UGg8GIItQBgAOIdDqtRiMRlucrwc2H/RjQ + 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 + KjV28CWuS69cQdl18MXu28Q12JYtKLvu29g5n8Du+HIlZdM5Px+nXhA42UKupGymXkjz + iHBiDYGDaTKWlNXEGpw2ReBEKbmSspg2hZPiiBsFt09B2UyKwymPxI1x3Keg7KY84oRW + IsewyhSVzYRWaTA6TlcmcIpyppKymK6cg5PRiZt9Ll9QNpPRga4UXp3RJM1Gd/FeXyAY + EqtrD4br6kENKMIckKjUhQ/WVouhYMDn5aXB2YwJJmcX7h2dnQN081QFao0+hZdzuvmy + csFfGQyFRFE8gCLQAQATCgUr/UJ5Ge92cim4eo26QJW3e7gyfMgKwgt4tXojxRSzNs7p + cvMeb3mFTxD8/gCKOAf8fkHwVZR7Pbzb5eRsbDFDGfUwN1u1Z+q99Ak6CC/szZBeA0UX + mVkrZ3cAYXcp70ER6gBf6gayDjtnZc1FNGWA5Er7cprofsYLm7MO4ksXFQNgWwkHjB1O + FJEOOIArV2IDtMXA1qjXwbacCW5Obiq9cLVK8TUxDBA2Wywsa0UR6QDLWixmIMswphRb + uFCl4H4x8eLvDzan8KoKIL7AV28wUpSJphkUwQ7QtImijAY95FYKLpy5ebnp4cLeDOmV + 7lbS8avR6gCx3mAwGFGEOgBwAJFOpwW0kFuJbWa40tVqhy8ABsKAOCUtikgHPuNRS2QL + VPuyTV2dJb55+fn5KgkxSgEOANh8Kbayuf3X+ZsiLH09CP4nilAHdgil/szNeN7+zfWL + v8DXoxThwBfY8B/oADqADqAD6AA6gA6gA+gAOpCFA/8DclEtHwplbmRzdHJlYW0KZW5k + b2JqCjI2IDAgb2JqCjI1NTgKZW5kb2JqCjM0IDAgb2JqCjw8IC9MZW5ndGggMzUgMCBS + IC9UeXBlIC9YT2JqZWN0IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGggNTMyIC9IZWlnaHQg + MTA0IC9Db2xvclNwYWNlCi9EZXZpY2VHcmF5IC9CaXRzUGVyQ29tcG9uZW50IDggL0Zp + bHRlciAvRmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB7Z3rT1PpFsZBCqX3Fnqjl2nZbaG7 + pXS2LZZSmLZpwx1REKbOCEGrZmBARmMjGdTBMEokiuBAuESRIaIBh4AhSoya86+dtQvn + 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 + kC48a6HuVQ+qfWqL2gpNPaa2q21qF9+OqgPlHcOclYkLrNtl9Sn2YGOa3spJV2aL4N/C + L4b/pV5hC9c0NPkPTbi5jGkJ3xHcNnCHlP/DX7MDDd4KZW5kc3RyZWFtCmVuZG9iagoz + NyAwIG9iago3OTIKZW5kb2JqCjcgMCBvYmoKWyAvSUNDQmFzZWQgMzYgMCBSIF0KZW5k + b2JqCjM4IDAgb2JqCjw8IC9MZW5ndGggMzkgMCBSIC9OIDMgL0FsdGVybmF0ZSAvRGV2 + aWNlUkdCIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4Ae1XiTvU2xs/YwnZ + 953JPoylsSY72UNIlqwzjG0GM3bZomyhRIgsIZHsW0KSkq0ikiSUJFfRvT9Kda97ht99 + +j2/5/YfdL7Pe87nvO857znfed/n+3kHAFacvo2NJQ0AgEAMJdmaGCAdnZyRdDOAHtAC + Btize2LJwZQ1cMlP2tYzgKCYnqJN7I8a3DcdqHu3Sc2SPdrIp7lelPyTTf+oWXDeZCwA + CDRUeJDg4QBQcUHMhd/DMhTstYe1KJhkb2sI19hAYcLvYpqTFOy1i/f5UnBEaHAoAPRQ + ABc2mETBxRCf9QrY1adS9OFYPNQzSACwjwPr64kDgFUD6tE4AhFixDmIbXEEHAUvQIwh + BIbBe+42ytsyeROP28HRCIoQMAVhwBtEARtgC6wBEhiCIBAIhQSxJZwZwVEG9mpAFSIT + gAEKUJBAHyhBpAQf1E/8q+36dwTy0LMfCIWnIIEZIAIs3EfxGbH7KIBIeNaeXQHaggAB + oGBM//3OPLs+/+2OSgBQ4g/tsBH5ATCg/HY8P3TOvQBkwpgIon/o5L8DoOQFQMM7bBgp + fG8v4p+BGtABRsAO+OBtUUAFvrEVcIX3TwC5oAb0gefgdwQzQhZhhvBDZCAaEJOIb1QS + VNZUMVQ1VDPU+6m1qUnUNdSvaYRonGjyaaZp+Wldaa/Sru5T3he3b4ROgC6Arpeek96f + /h6DMEM0w8z+Q/uLGRGMeMYnTJpM1cw8zGeZt1mILG9Z3Vhn2BzYptgd2Gc43DiWOYM4 + v3GlcfNz1/Lo8kzxEvjo+Sr5DfmXBFIE0YKTQnHCKOFpkRRRTdGPyKoDbmL8YtPilyQc + JYUk30jdkA6XMURxoJZkO+Sy0D7yegrCCt8VXyndPViNOa8crYJXdVAzVdfSwByS1ZQ8 + LKZ1QFtcR1pXQU9NX9/A2tDdKOTIGeNikzbTcbN1C1ZLzNETVvHWNTZTtjR2qva+x0sc + ph3Znaycs1yeuHK5ubhXemx46WCzca991PHZvu/9jQOqCHTEgKCJkMOk6lDusDPhXyKJ + UcsxHqfm4lzj5xOxp1eTyWd2UrLSRNObz5lmLmafusCfcyv35CVEfk2hXREobijxLOMu + H604W2VQjbjeX3umzrKeu2Ghqb4lvs22Q+YW6Jrt7uwt6Ivp9xgwfYB5iBxmHUWMbT3+ + OL7y9O3U0vTyzOrsp7lvC/SveZdklrVX7FcJa2kfr28M//5xk/uzzrb/t8I/h3d2fuXC + r1z4lQu/vgv//134wRtbU/+tG+R+6EA0JI44KL4/4S5/aBPa5ddgyLcUzsMDX8iLFC7E + QoZBgv/lSjScY3b59SBk0D2kvsuc+pCfA6GVwqp7Hsi7M29AhhxLAuGwx8GVYK9O2KMz + QI2A5QWsCAhUMzTGtM10ovQZDF8YcUzjLNqstew8HEmc69wneTx58XyB/CSBCMFYodPC + qSKZoheRhQdKxCrFayQaJC9JxUp7y1iilGUF5ajk3qPH5TsVShVTlIgHj2O0laVU2FS+ + qr5RG1Pv0Cg7lK5JPuyqZaKtpCOgS6P7QW9N/zeD94YrRu+OvDVeMnltumi2YP7KYs7y + 5dEXVjPWqzZfbRnthOzRx7UdrE64OQY5JTifdyk/2eza7/bUfcFjzXMbS4vj8BbxkcOr + +xr52fi7BvgHhhOSiNlBVcG3Q8ZJy+TvYRzhMhE6kXZRftHxMXmnbsT2xT2Ln0h4nDhy + ejDpXnLfme6znSmtqY1pN9NrMqrOlWeWZJ3O9jlvfkExhzPn88WXuX15lZfS8gkFxwpV + Lwtc/qvoZXHXlfySsFK7MqVylvK1q8MV1ZVnqrDX9KtFqr9fn6vpqb1yI67O7aZuvWj9 + TsNCY19TeXNii1erQZtYO1X7YkdfZ+mtuC7X21rdgt1fe2Z6O+/k94XfdehXvUd3b2ag + 7n7cA5tB8cHNh4NDhcOBIzqjbKNvxtoepTw2ekL15M74qYlDE1tPWyaDp+SnVp9VT3s/ + F3s+P1P8wnoWMdv6Ej8nMDf2KmEeM/92oWDRYvGv141vsEs8S71vfZaZl9veua7QrNS9 + t3//fbXiN4vf/li7/MHgwyqMvwKVC3UaTQftEh0HvR4DYX8R4xDTFosEqy1bAvtNjlRO + LJcOrC3+w/OIt4Yvmd9dQFOQW3BDaES4SiRBVFC0HXkMuXYgRUxMrEfcUfwPiSxJlOSA + lLvUV+k8GQOZDdQVWQvZL3LX0HbyCPl6BRdFBsV2JdxB9oN3MCRlSeXnKhmqOqq/q1Wp + O2owavQeCtGU0Hx+OENLR5tGe0gnW/e4nqDeon61QaAhxvCLUe+RZGMzE1aTKdNGs3Rz + bwtdSwHLzaOPrWqtk23cjx2y5bJdtxuyrzye6RBxwsPRzEnZWchln8v6yRmYM3XueR5x + nr5ex7AoHAI3493ok4r38NXwY/V7538nID8wiGBMFCFuBfUHZ4U4kSRJn8g9oWlh9uHI + 8LWIzsjkKOtoweh3MUOn6mKz4oLj7RJUE3kTv55+mdSbXH4m6ax3immqbOp8Wl66eQbI + aDsXkInMfJaVka2fvXW+7oJnDm/O6MWMXPM8+rzBS2fzjQqoC/oLEy7rwozqLo65onnl + S0lLKaFMumyxvPiqQwVbxTDMKt2q7Wst1cTrMtdf16TXKtfO3kiqk6ubvHmqXqJ+rCGs + UbjxfhOxmae5tyWglbd1oC24Xbh9qCO8U6zz8a2YLpmuyduJ3fLdL3oyerV71++U9dne + pb7b1u9zj+/e0EDMffT9Vw+yB/Vh/LWoIqlbaTb2oel86SsZFhiFmByZc1mesDGxm3Ik + c+K5zLjRPCw8n3if8rXzFwjECLoJ6QmLi9CKrIgOIyMPSB14KpYorij+UiJdUkNyWeqi + tL70ukwxyhz1Rfa6nCOaHn1L3k+BX2FIMUoJpfTiYDpGE7OqfFnFXJVFdVwtD8ZdSGP+ + UIWmz2HZwx+0mrRDddR1vun26hXohxhYGEoY/mU0faTJON0EZ6ptxmu2YT5sUWEZe5Rs + 5WftYeNw7KitoZ2mvdJxaQfhE5yO+52A02fnDy6zJx+6trtVul/wiPckeDljTXFq3uI+ + 7D47+DXfF34T/iMBA4HdhDZifdC14NKQAtJ5clro6bDocHJEYGRgFCGaGBN0Kig2OC4k + npRASiSfDk0KTYbF6dmIFNdUwzRUOmv6ZsbsubuZ1VmZ2eTzThd0cyQvMl78lDuV13Wp + JD+pAF9ocVmpiKtou3juSn/JtdL0sqByu6smFZqV8lXIa1zVdNVfr3+oWaydvDFYd/tm + fX15Q25jYVNpc2VLTWt9W0t7Z0dPZ/+twa6x2xPd0z0vexfvfL/L2698z2rA737yg9LB + 2w+fDX0aYRqVHjN85PY46knReM/E/CRiSvyZ8bTv8/SZuhePZjfmOF6pzDssRL7OWapb + frCysPr1A9e64iezP7CbsZ/zt5u+jfz5dmcHALKPMmaXERDM2wDQLUFSgMTABP8fbh7Y + 2dnZghnivrPzJzdACIX/Ddo0yhkKZW5kc3RyZWFtCmVuZG9iagozOSAwIG9iagoyNjM0 + CmVuZG9iagoyNyAwIG9iagpbIC9JQ0NCYXNlZCAzOCAwIFIgXQplbmRvYmoKNDAgMCBv + YmoKPDwgL0xlbmd0aCA0MSAwIFIgL04gMyAvQWx0ZXJuYXRlIC9EZXZpY2VSR0IgL0Zp + bHRlciAvRmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB7VeJO9TbGz9jCdn3nck+jKWxJjvZ + Q0iWrDOMbQYzdtmibKFEiCwhkexbQpKSrSKSJJQkV9G9P0p1r3uG3336Pb/n9h90vs97 + zue87znvOd953+f7eQcAVpy+jY0lDQCAQAwl2ZoYIB2dnJF0M4Ae0AIG2LN7YsnBlDVw + yU/a1jOAoJieok3sjxrcNx2oe7dJzZI92sinuV6U/JNN/6hZcN5kLAAINFR4kODhAFBx + QcyF38MyFOy1h7UomGRvawjX2EBhwu9impMU7LWL9/lScERocCgA9FAAFzaYRMHFEJ/1 + CtjVp1L04Vg81DNIALCPA+vriQOAVQPq0TgCEWLEOYhtcQQcBS9AjCEEhsF77jbK2zJ5 + E4/bwdEIihAwBWHAG0QBG2ALrAESGIIgEAiFBLElnBnBUQb2akAVIhOAAQpQkEAfKEGk + BB/UT/yr7fp3BPLQsx8IhacggRkgAizcR/EZsfsogEh41p5dAdqCAAGgYEz//c48uz7/ + 7Y5KAFDiD+2wEfkBMKD8djw/dM69AGTCmAiif+jkvwOg5AVAwztsGCl8by/in4Ea0AFG + wA744G1RQAW+sRVwhfdPALmgBvSB5+B3BDNCFmGG8ENkIBoQk4hvVBJU1lQxVDVUM9T7 + qbWpSdQ11K9phGicaPJppmn5aV1pr9Ku7lPeF7dvhE6ALoCul56T3p/+HoMwQzTDzP5D + +4sZEYx4xidMmkzVzDzMZ5m3WYgsb1ndWGfYHNim2B3YZzjcOJY5gzi/caVx83PX8ujy + TPES+Oj5KvkN+ZcEUgTRgpNCccIo4WmRFFFN0Y/IqgNuYvxi0+KXJBwlhSTfSN2QDpcx + RHGglmQ75LLQPvJ6CsIK3xVfKd09WI05rxytgld1UDNV19LAHJLVlDwspnVAW1xHWldB + T01f38Da0N0o5MgZ42KTNtNxs3ULVkvM0RNW8dY1NlO2NHaq9r7HSxymHdmdrJyzXJ64 + crm5uFd6bHjpYLNxr33U8dm+7/2NA6oIdMSAoImQw6TqUO6wM+FfIolRyzEep+biXOPn + E7GnV5PJZ3ZSstJE05vPmWYuZp+6wJ9zK/fkJUR+TaFdEShuKPEs4y4frThbZVCNuN5f + e6bOsp67YaGpviW+zbZD5hbomu3u7C3oi+n3GDB9gHmIHGYdRYxtPf44vvL07dTS9PLM + 6uynuW8L9K95l2SWtVfsVwlraR+vbwz//nGT+7POtv+3wj+Hd3Z+5cKvXPiVC7++C/// + XfjBG1tT/60b5H7oQDQkjjgovj/hLn9oE9rl12DItxTOwwNfyIsULsRChkGC/+VKNJxj + dvn1IGTQPaS+y5z6kJ8DoZXCqnseyLszb0CGHEsC4bDHwZVgr07YozNAjYDlBawICFQz + NMa0zXSi9BkMXxhxTOMs2qy17DwcSZzr3Cd5PHnxfIH8JIEIwVih08KpIpmiF5GFB0rE + KsVrJBokL0nFSnvLWKKUZQXlqOTeo8flOxVKFVOUiAePY7SVpVTYVL6qvlEbU+/QKDuU + rkk+7Kploq2kI6BLo/tBb03/N4P3hitG7468NV4yeW26aLZg/spizvLl0RdWM9arNl9t + Ge2E7NHHtR2sTrg5BjklOJ93KT/Z7Nrv9tR9wWPNcxtLi+PwFvGRw6v7GvnZ+LsG+AeG + E5KI2UFVwbdDxknL5O9hHOEyETqRdlF+0fExeaduxPbFPYufSHicOHJ6MOlect+Z7rOd + Ka2pjWk302syqs6VZ5Zknc72OW9+QTGHM+fzxZe5fXmVl9LyCQXHClUvC1z+q+hlcdeV + /JKwUrsypXKW8rWrwxXVlWeqsNf0q0Wqv1+fq+mpvXIjrs7tpm69aP1Ow0JjX1N5c2KL + V6tBm1g7VftiR19n6a24LtfbWt2C3V97Zno77+T3hd916Fe9R3dvZqDuftwDm0Hxwc2H + g0OFw4EjOqNso2/G2h6lPDZ6QvXkzvipiUMTW09bJoOn5KdWn1VPez8Xez4/U/zCehYx + 2/oSPycwN/YqYR4z/3ahYNFi8a/XjW+wSzxLvW99lpmX2965rtCs1L23f/99teI3i9/+ + WLv8weDDKoy/ApULdRpNB+0SHQe9HgNhfxHjENMWiwSrLVsC+02OVE4slw6sLf7D84i3 + hi+Z311AU5BbcENoRLhKJEFUULQdeQy5diBFTEysR9xR/A+JLEmU5ICUu9RX6TwZA5kN + 1BVZC9kvctfQdvII+XoFF0UGxXYl3EH2g3cwJGVJ5ecqGao6qr+rVak7ajBq9B4K0ZTQ + fH44Q0tHm0Z7SCdb97ieoN6ifrVBoCHG8ItR75FkYzMTVpMp00azdHNvC11LAcvNo4+t + aq2TbdyPHbLlsl23G7KvPJ7pEHHCw9HMSdlZyGWfy/rJGZgzde55HnGevl7HsCgcAjfj + 3eiTivfw1fBj9XvnfycgPzCIYEwUIW4F9QdnhTiRJEmfyD2haWH24cjwtYjOyOQo62jB + 6HcxQ6fqYrPiguPtElQTeRO/nn6Z1JtcfibprHeKaaps6nxaXrp5BshoOxeQicx8lpWR + rZ+9db7ugmcOb87oxYxc8zz6vMFLZ/ONCqgL+gsTLuvCjOoujrmieeVLSUspoUy6bLG8 + +KpDBVvFMMwq3artay3VxOsy11/XpNcq187eSKqTq5u8eapeon6sIaxRuPF+E7GZp7m3 + JaCVt3WgLbhduH2oI7xTrPPxrZguma7J24nd8t0vejJ6tXvX75T12d6lvtvW73OP797Q + QMx99P1XD7IH9WH8tagiqVtpNvah6XzpKxkWGIWYHJlzWZ6wMbGbciRz4rnMuNE8LDyf + eJ/ytfMXCMQIugnpCYuL0IqsiA4jIw9IHXgqliiuKP5SIl1SQ3JZ6qK0vvS6TDHKHPVF + 9rqcI5oefUveT4FfYUgxSgml9OJgOkYTs6p8WcVclUV1XC0Pxl1IY/5QhabPYdnDH7Sa + tEN11HW+6fbqFeiHGFgYShj+ZTR9pMk43QRnqm3Ga7ZhPmxRYRl7lGzlZ+1h43DsqK2h + naa90nFpB+ETnI77nYDTZ+cPLrMnH7q2u1W6X/CI9yR4OWNNcWre4j7sPjv4Nd8XfhP+ + IwEDgd2ENmJ90LXg0pAC0nlyWujpsOhwckRgZGAUIZoYE3QqKDY4LiSelEBKJJ8OTQpN + hsXp2YgU11TDNFQ6a/pmxuy5u5nVWZnZ5PNOF3RzJC8yXvyUO5XXdakkP6kAX2hxWamI + q2i7eO5Kf8m10vSyoHK7qyYVmpXyVchrXNV01V+vf6hZrJ28MVh3+2Z9fXlDbmNhU2lz + ZUtNa31bS3tnR09n/63BrrHbE93TPS97F+98v8vbr3zPasDvfvKD0sHbD58NfRphGpUe + M3zk9jjqSdF4z8T8JGJK/JnxtO/z9Jm6F49mN+Y4XqnMOyxEvs5Zqlt+sLKw+vUD17ri + J7M/sJuxn/O3m76N/Pl2ZwcAso8yZpcREMzbANAtQVKAxMAE/x9uHtjZ2dmCGeK+s/Mn + N0AIhf8N2jTKGQplbmRzdHJlYW0KZW5kb2JqCjQxIDAgb2JqCjI2MzQKZW5kb2JqCjI0 + IDAgb2JqClsgL0lDQ0Jhc2VkIDQwIDAgUiBdCmVuZG9iago0MiAwIG9iago8PCAvTGVu + Z3RoIDQzIDAgUiAvTiAzIC9BbHRlcm5hdGUgL0RldmljZVJHQiAvRmlsdGVyIC9GbGF0 + ZURlY29kZSA+PgpzdHJlYW0KeAHtV4k71NsbP2MJ2fedyT6MpbEmO9lDSJasM4xtBjN2 + 2aJsoUSILCGR7FtCkpKtIpIklCRX0b0/SnWve4bfffo9v+f2H3S+z3vO57zvOe8533nf + 5/t5BwBWnL6NjSUNAIBADCXZmhggHZ2ckXQzgB7QAgbYs3tiycGUNXDJT9rWM4CgmJ6i + TeyPGtw3Hah7t0nNkj3ayKe5XpT8k03/qFlw3mQsAAg0VHiQ4OEAUHFBzIXfwzIU7LWH + tSiYZG9rCNfYQGHC72KakxTstYv3+VJwRGhwKAD0UAAXNphEwcUQn/UK2NWnUvThWDzU + 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 + qu1rLdXE6zLXX9ek1yrXzt5IqpOrm7x5ql6ifqwhrFG48X4TsZmnubcloJW3daAtuF24 + fagjvFOs8/GtmC6Zrsnbid3y3S96Mnq1e9fvlPXZ3qW+29bvc4/v3tBAzH30/VcPsgf1 + Yfy1qCKpW2k29qHpfOkrGRYYhZgcmXNZnrAxsZtyJHPiucy40TwsPJ94n/K18xcIxAi6 + CekJi4vQiqyIDiMjD0gdeCqWKK4o/lIiXVJDclnqorS+9LpMMcoc9UX2upwjmh59S95P + gV9hSDFKCaX04mA6RhOzqnxZxVyVRXVcLQ/GXUhj/lCFps9h2cMftJq0Q3XUdb7p9uoV + 6IcYWBhKGP5lNH2kyTjdBGeqbcZrtmE+bFFhGXuUbOVn7WHjcOyoraGdpr3ScWkH4ROc + jvudgNNn5w8usycfura7Vbpf8Ij3JHg5Y01xat7iPuw+O/g13xd+E/4jAQOB3YQ2Yn3Q + teDSkALSeXJa6Omw6HByRGBkYBQhmhgTdCooNjguJJ6UQEoknw5NCk2GxenZiBTXVMM0 + VDpr+mbG7Lm7mdVZmdnk804XdHMkLzJe/JQ7ldd1qSQ/qQBfaHFZqYiraLt47kp/ybXS + 9LKgcrurJhWalfJVyGtc1XTVX69/qFmsnbwxWHf7Zn19eUNuY2FTaXNlS01rfVtLe2dH + T2f/rcGusdsT3dM9L3sX73y/y9uvfM9qwO9+8oPSwdsPnw19GmEalR4zfOT2OOpJ0XjP + xPwkYkr8mfG07/P0mboXj2Y35jheqcw7LES+zlmqW36wsrD69QPXuuInsz+wm7Gf87eb + vo38+XZnBwCyjzJmlxEQzNsA0C1BUoDEwAT/H24e2NnZ2YIZ4r6z8yc3QAiF/w3aNMoZ + CmVuZHN0cmVhbQplbmRvYmoKNDMgMCBvYmoKMjYzNAplbmRvYmoKMjEgMCBvYmoKWyAv + SUNDQmFzZWQgNDIgMCBSIF0KZW5kb2JqCjQ0IDAgb2JqCjw8IC9MZW5ndGggNDUgMCBS + IC9OIDEgL0FsdGVybmF0ZSAvRGV2aWNlR3JheSAvRmlsdGVyIC9GbGF0ZURlY29kZSA+ + PgpzdHJlYW0KeAGFUk9IFFEc/s02EoSIQYV4iHcKCZUprKyg2nZ1WZVtW5XSohhn37qj + szPTm9k1xZMEXaI8dQ+iY3Ts0KGbl6LArEvXIKkgCDx16PvN7OoohG95O9/7/f1+33tE + bZ2m7zspQVRzQ5UrpaduTk2Lgx8pRR3UTlimFfjpYnGMseu5kr+719Zn0tiy3se1dvv2 + PbWVZWAh6i22txD6IZFmAB+ZnyhlgLPAHZav2D4BPFgOrBrwI6IDD5q5MNPRnHSlsi2R + U+aiKCqvYjtJrvv5uca+i7WJg/5cj2bWjr2z6qrRTNS090ShvA+uRBnPX1T2bDUUpw3j + nEhDGinyrtXfK0zHEZErEEoGUjVkuZ9qTp114HUYu126k+P49hClPslgqIm16bKZHYV9 + AHYqy+wQ8AXo8bJiD+eBe2H/W1HDk8AnYT9kh3nWrR/2F65T4HuEPTXgzhSuxfHaih9e + LQFD91QjaIxzTcTT1zlzpIjvMdQZmPdGOaYLMXeWqhM3gDthH1mqZgqxXfuu6iXuewJ3 + 0+M70Zs5C1ygHElysRXZFNA8CVgUfYuwSQ48Ps4eVeB3qJjAHLmJ3M0o9x7VERtno1KB + VnqNV8ZP47nxxfhlbBjPgH6sdtd7fP/p4xV117Y+PPmNetw5rr2dG1VhVnFlC93/xzKE + j9knOabB06FZWGvYduQPmsxMsAwoxH8FPpf6khNV3NXu7bhFEsxQPixsJbpLVG4p1Oo9 + g0qsHCvYAHZwksQsWhy4U2u6OXh32CJ6bflNV7Lrhv769nr72vIebcqoKSgTzbNEZpSx + W6Pk3Xjb/WaREZ84Or7nvYpayf5JRRA/hTlaKvIUVfRWUNbEb2cOfhu2flw/pef1Qf08 + CT2tn9Gv6KMRvgx0Sc/Cc1Efo0nwsGkh4hKgioMz1E5UY40D4inx8rRbZJH9D0AZ/WYK + ZW5kc3RyZWFtCmVuZG9iago0NSAwIG9iago3MDQKZW5kb2JqCjE4IDAgb2JqClsgL0lD + Q0Jhc2VkIDQ0IDAgUiBdCmVuZG9iago0NiAwIG9iago8PCAvTGVuZ3RoIDQ3IDAgUiAv + TiAzIC9BbHRlcm5hdGUgL0RldmljZVJHQiAvRmlsdGVyIC9GbGF0ZURlY29kZSA+Pgpz + dHJlYW0KeAHtV4k71NsbP2MJ2fedyT6MpbEmO9lDSJasM4xtBjN22aJsoUSILCGR7FtC + kpKtIpIklCRX0b0/SnWve4bfffo9v+f2H3S+z3vO57zvOe8533nf5/t5BwBWnL6NjSUN + AIBADCXZmhggHZ2ckXQzgB7QAgbYs3tiycGUNXDJT9rWM4CgmJ6iTeyPGtw3Hah7t0nN + kj3ayKe5XpT8k03/qFlw3mQsAAg0VHiQ4OEAUHFBzIXfwzIU7LWHtSiYZG9rCNfYQGHC + 72KakxTstYv3+VJwRGhwKAD0UAAXNphEwcUQn/UK2NWnUvThWDzUM0gAsI8D6+uJA4BV + A+rROAIRYsQ5iG1xBBwFL0CMIQSGwXvuNsrbMnkTj9vB0QiKEDAFYcAbRAEbYAusARIY + giAQCIUEsSWcGcFRBvZqQBUiE4ABClCQQB8oQaQEH9RP/Kvt+ncE8tCzHwiFpyCBGSAC + LNxH8Rmx+yiASHjWnl0B2oIAAaBgTP/9zjy7Pv/tjkoAUOIP7bAR+QEwoPx2PD90zr0A + ZMKYCKJ/6OS/A6DkBUDDO2wYKXxvL+KfgRrQAUbADvjgbVFABb6xFXCF908AuaAG9IHn + 4HcEM0IWYYbwQ2QgGhCTiG9UElTWVDFUNVQz1PuptalJ1DXUr2mEaJxo8mmmaflpXWmv + 0q7uU94Xt2+EToAugK6XnpPen/4egzBDNMPM/kP7ixkRjHjGJ0yaTNXMPMxnmbdZiCxv + Wd1YZ9gc2KbYHdhnONw4ljmDOL9xpXHzc9fy6PJM8RL46Pkq+Q35lwRSBNGCk0Jxwijh + aZEUUU3Rj8iqA25i/GLT4pckHCWFJN9I3ZAOlzFEcaCWZDvkstA+8noKwgrfFV8p3T1Y + jTmvHK2CV3VQM1XX0sAcktWUPCymdUBbXEdaV0FPTV/fwNrQ3SjkyBnjYpM203GzdQtW + S8zRE1bx1jU2U7Y0dqr2vsdLHKYd2Z2snLNcnrhyubm4V3pseOlgs3GvfdTx2b7v/Y0D + qgh0xICgiZDDpOpQ7rAz4V8iiVHLMR6n5uJc4+cTsadXk8lndlKy0kTTm8+ZZi5mn7rA + n3Mr9+QlRH5NoV0RKG4o8SzjLh+tOFtlUI243l97ps6ynrthoam+Jb7NtkPmFuia7e7s + LeiL6fcYMH2AeYgcZh1FjG09/ji+8vTt1NL08szq7Ke5bwv0r3mXZJa1V+xXCWtpH69v + DP/+cZP7s862/7fCP4d3dn7lwq9c+JULv74L//9d+MEbW1P/rRvkfuhANCSOOCi+P+Eu + f2gT2uXXYMi3FM7DA1/IixQuxEKGQYL/5Uo0nGN2+fUgZNA9pL7LnPqQnwOhlcKqex7I + uzNvQIYcSwLhsMfBlWCvTtijM0CNgOUFrAgIVDM0xrTNdKL0GQxfGHFM4yzarLXsPBxJ + nOvcJ3k8efF8gfwkgQjBWKHTwqkimaIXkYUHSsQqxWskGiQvScVKe8tYopRlBeWo5N6j + x+U7FUoVU5SIB49jtJWlVNhUvqq+URtT79AoO5SuST7sqmWiraQjoEuj+0FvTf83g/eG + K0bvjrw1XjJ5bbpotmD+ymLO8uXRF1Yz1qs2X20Z7YTs0ce1HaxOuDkGOSU4n3cpP9ns + 2u/21H3BY81zG0uL4/AW8ZHDq/sa+dn4uwb4B4YTkojZQVXBt0PGScvk72Ec4TIROpF2 + UX7R8TF5p27E9sU9i59IeJw4cnow6V5y35nus50pramNaTfTazKqzpVnlmSdzvY5b35B + MYcz5/PFl7l9eZWX0vIJBccKVS8LXP6r6GVx15X8krBSuzKlcpbytavDFdWVZ6qw1/Sr + Raq/X5+r6am9ciOuzu2mbr1o/U7DQmNfU3lzYotXq0GbWDtV+2JHX2fprbgu19ta3YLd + X3tmejvv5PeF33XoV71Hd29moO5+3AObQfHBzYeDQ4XDgSM6o2yjb8baHqU8NnpC9eTO + +KmJQxNbT1smg6fkp1afVU97Pxd7Pj9T/MJ6FjHb+hI/JzA39iphHjP/dqFg0WLxr9eN + b7BLPEu9b32WmZfb3rmu0KzUvbd//3214jeL3/5Yu/zB4MMqjL8ClQt1Gk0H7RIdB70e + A2F/EeMQ0xaLBKstWwL7TY5UTiyXDqwt/sPziLeGL5nfXUBTkFtwQ2hEuEokQVRQtB15 + DLl2IEVMTKxH3FH8D4ksSZTkgJS71FfpPBkDmQ3UFVkL2S9y19B28gj5egUXRQbFdiXc + QfaDdzAkZUnl5yoZqjqqv6tVqTtqMGr0HgrRlNB8fjhDS0ebRntIJ1v3uJ6g3qJ+tUGg + Icbwi1HvkWRjMxNWkynTRrN0c28LXUsBy82jj61qrZNt3I8dsuWyXbcbsq88nukQccLD + 0cxJ2VnIZZ/L+skZmDN17nkecZ6+XsewKBwCN+Pd6JOK9/DV8GP1e+d/JyA/MIhgTBQh + bgX1B2eFOJEkSZ/IPaFpYfbhyPC1iM7I5CjraMHodzFDp+pis+KC4+0SVBN5E7+efpnU + m1x+Jumsd4ppqmzqfFpeunkGyGg7F5CJzHyWlZGtn711vu6CZw5vzujFjFzzPPq8wUtn + 840KqAv6CxMu68KM6i6OuaJ55UtJSymhTLpssbz4qkMFW8UwzCrdqu1rLdXE6zLXX9ek + 1yrXzt5IqpOrm7x5ql6ifqwhrFG48X4TsZmnubcloJW3daAtuF24fagjvFOs8/GtmC6Z + rsnbid3y3S96Mnq1e9fvlPXZ3qW+29bvc4/v3tBAzH30/VcPsgf1Yfy1qCKpW2k29qHp + fOkrGRYYhZgcmXNZnrAxsZtyJHPiucy40TwsPJ94n/K18xcIxAi6CekJi4vQiqyIDiMj + D0gdeCqWKK4o/lIiXVJDclnqorS+9LpMMcoc9UX2upwjmh59S95PgV9hSDFKCaX04mA6 + RhOzqnxZxVyVRXVcLQ/GXUhj/lCFps9h2cMftJq0Q3XUdb7p9uoV6IcYWBhKGP5lNH2k + yTjdBGeqbcZrtmE+bFFhGXuUbOVn7WHjcOyoraGdpr3ScWkH4ROcjvudgNNn5w8usycf + ura7Vbpf8Ij3JHg5Y01xat7iPuw+O/g13xd+E/4jAQOB3YQ2Yn3QteDSkALSeXJa6Omw + 6HByRGBkYBQhmhgTdCooNjguJJ6UQEoknw5NCk2GxenZiBTXVMM0VDpr+mbG7Lm7mdVZ + mdnk804XdHMkLzJe/JQ7ldd1qSQ/qQBfaHFZqYiraLt47kp/ybXS9LKgcrurJhWalfJV + yGtc1XTVX69/qFmsnbwxWHf7Zn19eUNuY2FTaXNlS01rfVtLe2dHT2f/rcGusdsT3dM9 + L3sX73y/y9uvfM9qwO9+8oPSwdsPnw19GmEalR4zfOT2OOpJ0XjPxPwkYkr8mfG07/P0 + mboXj2Y35jheqcw7LES+zlmqW36wsrD69QPXuuInsz+wm7Gf87ebvo38+XZnBwCyjzJm + lxEQzNsA0C1BUoDEwAT/H24e2NnZ2YIZ4r6z8yc3QAiF/w3aNMoZCmVuZHN0cmVhbQpl + bmRvYmoKNDcgMCBvYmoKMjYzNAplbmRvYmoKMzMgMCBvYmoKWyAvSUNDQmFzZWQgNDYg + MCBSIF0KZW5kb2JqCjQ4IDAgb2JqCjw8IC9MZW5ndGggNDkgMCBSIC9OIDMgL0FsdGVy + bmF0ZSAvRGV2aWNlUkdCIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4Ae1X + iTvU2xs/YwnZ953JPoylsSY72UNIlqwzjG0GM3bZomyhRIgsIZHsW0KSkq0ikiSUJFfR + vT9Kda97ht99+j2/5/YfdL7Pe87nvO857znfed/n+3kHAFacvo2NJQ0AgEAMJdmaGCAd + nZyRdDOAHtACBtize2LJwZQ1cMlP2tYzgKCYnqJN7I8a3DcdqHu3Sc2SPdrIp7lelPyT + Tf+oWXDeZCwACDRUeJDg4QBQcUHMhd/DMhTstYe1KJhkb2sI19hAYcLvYpqTFOy1i/f5 + UnBEaHAoAPRQABc2mETBxRCf9QrY1adS9OFYPNQzSACwjwPr64kDgFUD6tE4AhFixDmI + bXEEHAUvQIwhBIbBe+42ytsyeROP28HRCIoQMAVhwBtEARtgC6wBEhiCIBAIhQSxJZwZ + wVEG9mpAFSITgAEKUJBAHyhBpAQf1E/8q+36dwTy0LMfCIWnIIEZIAIs3EfxGbH7KIBI + eNaeXQHaggABoGBM//3OPLs+/+2OSgBQ4g/tsBH5ATCg/HY8P3TOvQBkwpgIon/o5L8D + oOQFQMM7bBgpfG8v4p+BGtABRsAO+OBtUUAFvrEVcIX3TwC5oAb0gefgdwQzQhZhhvBD + ZCAaEJOIb1QSVNZUMVQ1VDPU+6m1qUnUNdSvaYRonGjyaaZp+Wldaa/Sru5T3he3b4RO + gC6Arpeek96f/h6DMEM0w8z+Q/uLGRGMeMYnTJpM1cw8zGeZt1mILG9Z3Vhn2BzYptgd + 2Gc43DiWOYM4v3GlcfNz1/Lo8kzxEvjo+Sr5DfmXBFIE0YKTQnHCKOFpkRRRTdGPyKoD + bmL8YtPilyQcJYUk30jdkA6XMURxoJZkO+Sy0D7yegrCCt8VXyndPViNOa8crYJXdVAz + VdfSwByS1ZQ8LKZ1QFtcR1pXQU9NX9/A2tDdKOTIGeNikzbTcbN1C1ZLzNETVvHWNTZT + tjR2qva+x0scph3Znaycs1yeuHK5ubhXemx46WCzca991PHZvu/9jQOqCHTEgKCJkMOk + 6lDusDPhXyKJUcsxHqfm4lzj5xOxp1eTyWd2UrLSRNObz5lmLmafusCfcyv35CVEfk2h + XREobijxLOMuH604W2VQjbjeX3umzrKeu2Ghqb4lvs22Q+YW6Jrt7uwt6Ivp9xgwfYB5 + iBxmHUWMbT3+OL7y9O3U0vTyzOrsp7lvC/SveZdklrVX7FcJa2kfr28M//5xk/uzzrb/ + t8I/h3d2fuXCr1z4lQu/vgv//134wRtbU/+tG+R+6EA0JI44KL4/4S5/aBPa5ddgyLcU + zsMDX8iLFC7EQoZBgv/lSjScY3b59SBk0D2kvsuc+pCfA6GVwqp7Hsi7M29AhhxLAuGw + x8GVYK9O2KMzQI2A5QWsCAhUMzTGtM10ovQZDF8YcUzjLNqstew8HEmc69wneTx58XyB + /CSBCMFYodPCqSKZoheRhQdKxCrFayQaJC9JxUp7y1iilGUF5ajk3qPH5TsVShVTlIgH + j2O0laVU2FS+qr5RG1Pv0Cg7lK5JPuyqZaKtpCOgS6P7QW9N/zeD94YrRu+OvDVeMnlt + umi2YP7KYs7y5dEXVjPWqzZfbRnthOzRx7UdrE64OQY5JTifdyk/2eza7/bUfcFjzXMb + S4vj8BbxkcOr+xr52fi7BvgHhhOSiNlBVcG3Q8ZJy+TvYRzhMhE6kXZRftHxMXmnbsT2 + xT2Ln0h4nDhyejDpXnLfme6znSmtqY1pN9NrMqrOlWeWZJ3O9jlvfkExhzPn88WXuX15 + lZfS8gkFxwpVLwtc/qvoZXHXlfySsFK7MqVylvK1q8MV1ZVnqrDX9KtFqr9fn6vpqb1y + I67O7aZuvWj9TsNCY19TeXNii1erQZtYO1X7YkdfZ+mtuC7X21rdgt1fe2Z6O+/k94Xf + dehXvUd3b2ag7n7cA5tB8cHNh4NDhcOBIzqjbKNvxtoepTw2ekL15M74qYlDE1tPWyaD + p+SnVp9VT3s/F3s+P1P8wnoWMdv6Ej8nMDf2KmEeM/92oWDRYvGv141vsEs8S71vfZaZ + l9veua7QrNS9t3//fbXiN4vf/li7/MHgwyqMvwKVC3UaTQftEh0HvR4DYX8R4xDTFosE + qy1bAvtNjlROLJcOrC3+w/OIt4Yvmd9dQFOQW3BDaES4SiRBVFC0HXkMuXYgRUxMrEfc + UfwPiSxJlOSAlLvUV+k8GQOZDdQVWQvZL3LX0HbyCPl6BRdFBsV2JdxB9oN3MCRlSeXn + KhmqOqq/q1WpO2owavQeCtGU0Hx+OENLR5tGe0gnW/e4nqDeon61QaAhxvCLUe+RZGMz + E1aTKdNGs3RzbwtdSwHLzaOPrWqtk23cjx2y5bJdtxuyrzye6RBxwsPRzEnZWchln8v6 + yRmYM3XueR5xnr5ex7AoHAI3493ok4r38NXwY/V7538nID8wiGBMFCFuBfUHZ4U4kSRJ + n8g9oWlh9uHI8LWIzsjkKOtoweh3MUOn6mKz4oLj7RJUE3kTv55+mdSbXH4m6ax3immq + bOp8Wl66eQbIaDsXkInMfJaVka2fvXW+7oJnDm/O6MWMXPM8+rzBS2fzjQqoC/oLEy7r + wozqLo65onnlS0lLKaFMumyxvPiqQwVbxTDMKt2q7Wst1cTrMtdf16TXKtfO3kiqk6ub + vHmqXqJ+rCGsUbjxfhOxmae5tyWglbd1oC24Xbh9qCO8U6zz8a2YLpmuyduJ3fLdL3oy + erV71++U9dnepb7b1u9zj+/e0EDMffT9Vw+yB/Vh/LWoIqlbaTb2oel86SsZFhiFmByZ + c1mesDGxm3Ikc+K5zLjRPCw8n3if8rXzFwjECLoJ6QmLi9CKrIgOIyMPSB14KpYorij+ + UiJdUkNyWeqitL70ukwxyhz1Rfa6nCOaHn1L3k+BX2FIMUoJpfTiYDpGE7OqfFnFXJVF + dVwtD8ZdSGP+UIWmz2HZwx+0mrRDddR1vun26hXohxhYGEoY/mU0faTJON0EZ6ptxmu2 + YT5sUWEZe5Rs5WftYeNw7KitoZ2mvdJxaQfhE5yO+52A02fnDy6zJx+6trtVul/wiPck + eDljTXFq3uI+7D47+DXfF34T/iMBA4HdhDZifdC14NKQAtJ5clro6bDocHJEYGRgFCGa + GBN0Kig2OC4knpRASiSfDk0KTYbF6dmIFNdUwzRUOmv6ZsbsubuZ1VmZ2eTzThd0cyQv + Ml78lDuV13WpJD+pAF9ocVmpiKtou3juSn/JtdL0sqByu6smFZqV8lXIa1zVdNVfr3+o + WaydvDFYd/tmfX15Q25jYVNpc2VLTWt9W0t7Z0dPZ/+twa6x2xPd0z0vexfvfL/L2698 + z2rA737yg9LB2w+fDX0aYRqVHjN85PY46knReM/E/CRiSvyZ8bTv8/SZuhePZjfmOF6p + zDssRL7OWapbfrCysPr1A9e64iezP7CbsZ/zt5u+jfz5dmcHALKPMmaXERDM2wDQLUFS + gMTABP8fbh7Y2dnZghnivrPzJzdACIX/Ddo0yhkKZW5kc3RyZWFtCmVuZG9iago0OSAw + IG9iagoyNjM0CmVuZG9iagozMCAwIG9iagpbIC9JQ0NCYXNlZCA0OCAwIFIgXQplbmRv + YmoKMyAwIG9iago8PCAvVHlwZSAvUGFnZXMgL01lZGlhQm94IFswIDAgNzU2IDU1M10g + L0NvdW50IDEgL0tpZHMgWyAyIDAgUiBdID4+CmVuZG9iago1MCAwIG9iago8PCAvVHlw + ZSAvQ2F0YWxvZyAvUGFnZXMgMyAwIFIgL1ZlcnNpb24gLzEuNCA+PgplbmRvYmoKNTEg + MCBvYmoKPDwgL0xlbmd0aCA1MiAwIFIgL0xlbmd0aDEgNzE3MiAvRmlsdGVyIC9GbGF0 + ZURlY29kZSA+PgpzdHJlYW0KeAG9WXtYlNW6f9f3fXNBUG4Kw3Vm+BiugwgooJiMOMNF + TFEUGfMygCCSGClSlhK7dJd4OVtNbWtHs4s7JXME0gG2Ru7c6a6dVrub2043szpPPtU5 + dWqHzJzf+mYk7dn1+EdPfM87613X97d+77vW960FMSIKoDYSyVLTWNVEa2gAJa9AWmta + mg2bP5+0l4hNIxKX1TUtaQz+4C9/I5JcRMMClixbXff11rzpRCNeJNIa6murFn+jX9ZN + FHYJ/bPrURAwMOIOovBo5OPrG5vvtm1UP4O8BXnLsjtqqkJygxzItyEf11h1d5N25bDv + kX8SecPyqsbahPzouchjfEppumNlM3tGqEP+K+QLmlbUNv35geUZRLqxwHcOZQwP/wsg + Na1AaqOxvhKlWPkRflSv08TrdK8qIVFB1BANRAsh8qNh5I/xhys5TN2XBqJxPwWpTlCS + qo0ipXTSE3nehVzgqXuO57LqJQpyN3q+FvPQp4eL4M6fSP20mfbQEdh5GnoSLaRH6Cxr + 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 + MlwC69SfSnRJSF6IRc4SqO+P2at/PmaJ/iSkw1t1KBktjukPxizTb491sd2d+m0xLoY+ + W73Jqhh0PaZvTN6pX5yh1E/b6RI6OvXjUV9h8ddn5xr142Iu6dMTXVqGfFrMNH1Kxt/1 + 8eiIZgYMarIE66NjtusnoCo2xpY4AdLHDrE9lML2dJqm6nuhYrpdJcm5O13s3q7ipAyT + i91jyS5O2plcnGhKnqY3JRcmJkKvOKNZp7lNM1mTqUnFBW2CxqiJ0ozUhmiDtCO0Adph + Wq1W42LPdObr1X2sg/JBS0eXVq1VudizKJT62GGl8PBxraQVtKQd6fJ8gH/mMBrpYh3d + CAxGUI6pFU3tYoexFnjRYYseoYwNRKkIQoTxj2H+SwLTCgghJ9vsUtP6sJZ8XX7IpODx + hdaf+3EoNdd+U3/+T8dinDtxF+M8FGPHtRcUT4z9WnPdNeVn0+ZVqKotSE0tnbW6q6Wp + oU65xpNttQ7c5jk3tuBata3aYDja0OS7o0xwVNfU83ukqlpnk1xrdTbIVsPRFqUfL76u + uo5Xt8jWo1Rnm115tM5Sa+1ssbTY+HVmV3XBigU32NowZGtFwb+xVcAHW8FtVSv9fmJr + Aa+u5rYWcFsLuK1qS7Vii0/etrS8YGUzohNXfbhqSyp3lsycV4kbbbvVxQ7w+79V9P+8 + rYdICmVuZHN0cmVhbQplbmRvYmoKNTIgMCBvYmoKNDM3MQplbmRvYmoKNTMgMCBvYmoK + PDwgL1R5cGUgL0ZvbnREZXNjcmlwdG9yIC9Bc2NlbnQgNzcwIC9DYXBIZWlnaHQgNzI3 + IC9EZXNjZW50IC0yMzAgL0ZsYWdzIDk2Ci9Gb250QkJveCBbLTkzMyAtNDgxIDE1NzEg + MTEzOF0gL0ZvbnROYW1lIC9YUUlGU1crSGVsdmV0aWNhLU9ibGlxdWUgL0l0YWxpY0Fu + Z2xlCi0xMiAvU3RlbVYgMCAvTWF4V2lkdGggMTUwMCAvWEhlaWdodCA1MzEgL0ZvbnRG + aWxlMiA1MSAwIFIgPj4KZW5kb2JqCjU0IDAgb2JqClsgNjY3IDAgMCAwIDAgMCAwIDAg + ODMzIDAgMCAwIDAgMCAwIDAgMCAwIDAgNjY3IDAgMCAwIDAgMCAwIDAgMCA1NTYgMCA1 + MDAKMCA1NTYgMCA1NTYgMCAyMjIgMCAwIDIyMiA4MzMgNTU2IDU1NiA1NTYgMCAwIDAg + Mjc4IDAgMCAwIDUwMCBdCmVuZG9iagoxOSAwIG9iago8PCAvVHlwZSAvRm9udCAvU3Vi + dHlwZSAvVHJ1ZVR5cGUgL0Jhc2VGb250IC9YUUlGU1crSGVsdmV0aWNhLU9ibGlxdWUg + L0ZvbnREZXNjcmlwdG9yCjUzIDAgUiAvV2lkdGhzIDU0IDAgUiAvRmlyc3RDaGFyIDY5 + IC9MYXN0Q2hhciAxMjAgL0VuY29kaW5nIC9NYWNSb21hbkVuY29kaW5nCj4+CmVuZG9i + ago1NSAwIG9iago8PCAvTGVuZ3RoIDU2IDAgUiAvTGVuZ3RoMSA5OTcyIC9GaWx0ZXIg + L0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4Ab16e3iU1bX32vu9ziWTmcncM5PJZDIzmdxD + SMiQQMaQhHsMBCFBggkQCAg1YIyiwkGFIhGpQrkIPVS05RKKGUIKAxQ/ykHR1lPxitdW + j2i1T/N4Tg/aVpiZb+13Qgo+/fr5R5/OO/u+373X+q2199qXFwgAaGEdcBBeuKK9C54n + 4zHnFXRrF/Z0Zz7+xfi9AGQaALd8cdeSFYaP/uNXAHwUQK1dsnz14rJtr8wH0J0HMF7u + 7Ghf9Kf/XX4SwHMQ3y/vxAx1llSE6Y8wnd25ovu+RRUqC0AWj+l5y+9a2F4WHVuO6TZM + F69ov69LfkD9V0w/genM77Wv6Jj7wMPbMB3BdFbXXXd3000clmW9ienGrlUdXb945Hsl + AN5spO9VzCP4sJ8WRFiFYR2Mxhyq5F33uOuR4ZAH4Vs5yaSIgQQyqDBUgwbbZL8U0EEq + 6MGAcSOkgQnMSj5yJZwFvXAGcoR14OCLwA2QeBfdeyyM35b4TLgA+viKxP9wlfgGogQn + aby6Cs7C47AH+pHigxjPgfmwC14my+AkmQeD8DbJgEKUDw9RmAavkETiNVgMP8H63XAO + tsNRpCsHViAV02AL8SXux3QY4wtgfeIZyIYK+D6cgRC2ugWGEocSx7B0JtwGfXAY3/81 + 8dKjfFriucRl5HQGtrkeS15LTEv0I3f5UAONmLsetcLHvZfoBBtUInU/gh/DPvgl/JE8 + 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 + VrXe1Nemkb5W1fydvmpYY6tYXwuU977VVysrXsD6amV9tbK+FoQXKH0xCOqWNtXc3Y3a + iVfbeLWc0xSZPGNuM37B0VIbJfvZffc98H8BcaX7nAplbmRzdHJlYW0KZW5kb2JqCjU2 + IDAgb2JqCjY2ODkKZW5kb2JqCjU3IDAgb2JqCjw8IC9UeXBlIC9Gb250RGVzY3JpcHRv + ciAvQXNjZW50IDc3MCAvQ2FwSGVpZ2h0IDcyNyAvRGVzY2VudCAtMjMwIC9GbGFncyAz + MgovRm9udEJCb3ggWy05NTEgLTQ4MSAxNDQ1IDExMjJdIC9Gb250TmFtZSAvWFlVVFBT + K0hlbHZldGljYSAvSXRhbGljQW5nbGUgMAovU3RlbVYgOTggL01heFdpZHRoIDE1MDAg + L1N0ZW1IIDg1IC9YSGVpZ2h0IDUzMSAvRm9udEZpbGUyIDU1IDAgUiA+PgplbmRvYmoK + NTggMCBvYmoKWyA2NjcgNjExIDAgMCAwIDAgMCAwIDgzMyAwIDAgMCAwIDAgMCAwIDcy + MiA2NjcgMCAwIDAgMCAwIDAgMCAwIDAgMCA1NTYgMAo1MDAgNTU2IDU1NiAwIDU1NiA1 + NTYgMjIyIDAgMCAyMjIgODMzIDU1NiA1NTYgNTU2IDAgMzMzIDUwMCAyNzggNTU2IDAg + MCA1MDAKXQplbmRvYmoKMjAgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1Ry + dWVUeXBlIC9CYXNlRm9udCAvWFlVVFBTK0hlbHZldGljYSAvRm9udERlc2NyaXB0b3IK + NTcgMCBSIC9XaWR0aHMgNTggMCBSIC9GaXJzdENoYXIgNjkgL0xhc3RDaGFyIDEyMCAv + RW5jb2RpbmcgL01hY1JvbWFuRW5jb2RpbmcKPj4KZW5kb2JqCjEgMCBvYmoKPDwgL1Rp + dGxlIChVbnRpdGxlZCkgL0F1dGhvciAoVGhvbWFzIFJpc2JlcmcpIC9DcmVhdG9yIChP + bW5pR3JhZmZsZSkgL1Byb2R1Y2VyCihNYWMgT1MgWCAxMC41LjggUXVhcnR6IFBERkNv + bnRleHQpIC9DcmVhdGlvbkRhdGUgKEQ6MjAwOTA5MTExNDQwMzFaMDAnMDAnKQovTW9k + RGF0ZSAoRDoyMDA5MDkxMTE0NDAzMVowMCcwMCcpID4+CmVuZG9iagp4cmVmCjAgNTkK + MDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDQ5MjUyIDAwMDAwIG4gCjAwMDAwMDEwNDEg + MDAwMDAgbiAKMDAwMDAzNjY3MiAwMDAwMCBuIAowMDAwMDAwMDIyIDAwMDAwIG4gCjAw + MDAwMDEwMjIgMDAwMDAgbiAKMDAwMDAwMTE0NSAwMDAwMCBuIAowMDAwMDIxNzk2IDAw + MDAwIG4gCjAwMDAwMDUyMDQgMDAwMDAgbiAKMDAwMDAwNjEzMiAwMDAwMCBuIAowMDAw + MDAxMzY3IDAwMDAwIG4gCjAwMDAwMDIyODQgMDAwMDAgbiAKMDAwMDAwMjMwNCAwMDAw + MCBuIAowMDAwMDAzMTYxIDAwMDAwIG4gCjAwMDAwMDMxODEgMDAwMDAgbiAKMDAwMDAw + NDIyMCAwMDAwMCBuIAowMDAwMDA0MjQwIDAwMDAwIG4gCjAwMDAwMDUxODQgMDAwMDAg + biAKMDAwMDAzMTA0NSAwMDAwMCBuIAowMDAwMDQxNjkwIDAwMDAwIG4gCjAwMDAwNDkw + NzcgMDAwMDAgbiAKMDAwMDAzMDE4MCAwMDAwMCBuIAowMDAwMDA2MTUxIDAwMDAwIG4g + CjAwMDAwMDkwNDQgMDAwMDAgbiAKMDAwMDAyNzM4NSAwMDAwMCBuIAowMDAwMDE1MjI0 + IDAwMDAwIG4gCjAwMDAwMTc5NTYgMDAwMDAgbiAKMDAwMDAyNDU5MCAwMDAwMCBuIAow + MDAwMDA5MDY1IDAwMDAwIG4gCjAwMDAwMTIyNDYgMDAwMDAgbiAKMDAwMDAzNjYzNSAw + MDAwMCBuIAowMDAwMDEyMjY3IDAwMDAwIG4gCjAwMDAwMTUyMDMgMDAwMDAgbiAKMDAw + MDAzMzg0MCAwMDAwMCBuIAowMDAwMDE3OTc3IDAwMDAwIG4gCjAwMDAwMjA4NjAgMDAw + MDAgbiAKMDAwMDAyMDg4MSAwMDAwMCBuIAowMDAwMDIxNzc2IDAwMDAwIG4gCjAwMDAw + MjE4MzIgMDAwMDAgbiAKMDAwMDAyNDU2OSAwMDAwMCBuIAowMDAwMDI0NjI3IDAwMDAw + IG4gCjAwMDAwMjczNjQgMDAwMDAgbiAKMDAwMDAyNzQyMiAwMDAwMCBuIAowMDAwMDMw + MTU5IDAwMDAwIG4gCjAwMDAwMzAyMTcgMDAwMDAgbiAKMDAwMDAzMTAyNSAwMDAwMCBu + IAowMDAwMDMxMDgyIDAwMDAwIG4gCjAwMDAwMzM4MTkgMDAwMDAgbiAKMDAwMDAzMzg3 + NyAwMDAwMCBuIAowMDAwMDM2NjE0IDAwMDAwIG4gCjAwMDAwMzY3NTUgMDAwMDAgbiAK + MDAwMDAzNjgxOSAwMDAwMCBuIAowMDAwMDQxMjgwIDAwMDAwIG4gCjAwMDAwNDEzMDEg + MDAwMDAgbiAKMDAwMDA0MTUzNiAwMDAwMCBuIAowMDAwMDQxODczIDAwMDAwIG4gCjAw + MDAwNDg2NTIgMDAwMDAgbiAKMDAwMDA0ODY3MyAwMDAwMCBuIAowMDAwMDQ4OTA5IDAw + MDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgNTkgL1Jvb3QgNTAgMCBSIC9JbmZvIDEgMCBS + IC9JRCBbIDxmOTA3NjFiZGExNmY3ZTJlMDkyMjA2Mjg3ZmQ4ZjAzYT4KPGY5MDc2MWJk + YTE2ZjdlMmUwOTIyMDYyODdmZDhmMDNhPiBdID4+CnN0YXJ0eHJlZgo0OTQ2MAolJUVP + RgoxIDAgb2JqCjw8L0F1dGhvciAoVGhvbWFzIFJpc2JlcmcpL0NyZWF0aW9uRGF0ZSAo + RDoyMDA5MDkxMTE0MTUwMFopL0NyZWF0b3IgKE9tbmlHcmFmZmxlIDUuMS4xKS9Nb2RE + YXRlIChEOjIwMDkwOTExMTQzODAwWikvUHJvZHVjZXIgKE1hYyBPUyBYIDEwLjUuOCBR + dWFydHogUERGQ29udGV4dCkvVGl0bGUgKFVudGl0bGVkKT4+CmVuZG9iagp4cmVmCjEg + MQowMDAwMDUwNzk4IDAwMDAwIG4gCnRyYWlsZXIKPDwvSUQgWzxmOTA3NjFiZGExNmY3 + ZTJlMDkyMjA2Mjg3ZmQ4ZjAzYT4gPGY5MDc2MWJkYTE2ZjdlMmUwOTIyMDYyODdmZDhm + MDNhPl0gL0luZm8gMSAwIFIgL1ByZXYgNDk0NjAgL1Jvb3QgNTAgMCBSIC9TaXplIDU5 + Pj4Kc3RhcnR4cmVmCjUwOTkzCiUlRU9GCg== + + QuickLookThumbnail + + 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 + AdQB+wIkAk8CewKpAtkDCgM9A3IDqQPiBBwEWQSXBNcFGQVdBaIF6gYzBn4GywcaB2sH + vggTCGoIwwkdCXoJ2Qo5CpwLAQtnC9AMOgynDRYNhg35Dm4O5Q9eD9kQVhDVEVYR2RJe + EuYTbxP7FIkVGRWqFj8W1RdtGAgYpBlDGeQahxssG9Qcfh0pHdcehx86H+4gpSFeIhki + 1yOWJFglHCXjJqsndihDKRIp5Cq3K44sZi1ALh0u/C/eMMExpzKQM3o0ZzVWNkg3PDgy + OSo6JTsiPCE9Iz4nPy5ANkFBQk9DX0RxRYVGnEe1SNFJ70sPTDJNV05/T6lQ1VIEUzVU + aFWeVtdYEVlOWo5b0F0UXltfpGDwYj5jj2TiZjdnj2jpakZrpW0Hbmtv0nE7cqd0FXWF + dvh4bnnme2B83X5df9+BY4LqhHOF/4eOiR+KsoxIjeGPfJEZkrmUXJYBl6mZU5sAnK+e + YaAVocyjhqVCpwGowqqFrEyuFa/gsa6zf7VStyi5ALrbvLi+mMB7wmDESMYyyCDKD8wB + zfbP7tHo0+XV5Nfm2erb8d374AjiF+Qo5j3oVOpt7InuqPDK8u71Ffc++Wr7mf3K//9j + dXJ2AAAAAAAAAQAAAAAAAAEAAwAHAAsAEQAYACAAKQA0AEEATgBdAG4AgACUAKkAwADY + APIBDQEqAUkBaQGLAa8B1AH7AiQCTwJ7AqkC2QMKAz0DcgOpA+IEHARZBJcE1wUZBV0F + ogXqBjMGfgbLBxoHawe+CBMIagjDCR0JegnZCjkKnAsBC2cL0Aw6DKcNFg2GDfkObg7l + D14P2RBWENURVhHZEl4S5hNvE/sUiRUZFaoWPxbVF20YCBikGUMZ5BqHGywb1Bx+HSkd + 1x6HHzof7iClIV4iGSLXI5YkWCUcJeMmqyd2KEMpEinkKrcrjixmLUAuHS78L94wwTGn + MpAzejRnNVY2SDc8ODI5KjolOyI8IT0jPic/LkA2QUFCT0NfRHFFhUacR7VI0UnvSw9M + Mk1XTn9PqVDVUgRTNVRoVZ5W11gRWU5ajlvQXRReW1+kYPBiPmOPZOJmN2ePaOlqRmul + bQdua2/ScTtyp3QVdYV2+HhueeZ7YHzdfl1/34FjguqEc4X/h46JH4qyjEiN4Y98kRmS + uZRclgGXqZlTmwCcr55hoBWhzKOGpUKnAajCqoWsTK4Vr+CxrrN/tVK3KLkAutu8uL6Y + wHvCYMRIxjLIIMoPzAHN9s/u0ejT5dXk1+bZ6tvx3fvgCOIX5CjmPehU6m3sie6o8Mry + 7vUV9z75avuZ/cr//2N1cnYAAAAAAAABAAAAAAAAAQADAAcACwARABgAIAApADQAQQBO + AF0AbgCAAJQAqQDAANgA8gENASoBSQFpAYsBrwHUAfsCJAJPAnsCqQLZAwoDPQNyA6kD + 4gQcBFkElwTXBRkFXQWiBeoGMwZ+BssHGgdrB74IEwhqCMMJHQl6CdkKOQqcCwELZwvQ + DDoMpw0WDYYN+Q5uDuUPXg/ZEFYQ1RFWEdkSXhLmE28T+xSJFRkVqhY/FtUXbRgIGKQZ + QxnkGocbLBvUHH4dKR3XHocfOh/uIKUhXiIZItcjliRYJRwl4yarJ3YoQykSKeQqtyuO + LGYtQC4dLvwv3jDBMacykDN6NGc1VjZINzw4MjkqOiU7IjwhPSM+Jz8uQDZBQUJPQ19E + cUWFRpxHtUjRSe9LD0wyTVdOf0+pUNVSBFM1VGhVnlbXWBFZTlqOW9BdFF5bX6Rg8GI+ + Y49k4mY3Z49o6WpGa6VtB25rb9JxO3KndBV1hXb4eG555ntgfN1+XX/fgWOC6oRzhf+H + jokfirKMSI3hj3yRGZK5lFyWAZepmVObAJyvnmGgFaHMo4alQqcBqMKqhaxMrhWv4LGu + s3+1UrcouQC627y4vpjAe8JgxEjGMsggyg/MAc32z+7R6NPl1eTX5tnq2/Hd++AI4hfk + KOY96FTqbeyJ7qjwyvLu9RX3Pvlq+5n9yv//WFlaIAAAAAAAAPbVAAEAAAAA0ytYWVog + AAAAAAAAAHoAAAB+AAAAaG1sdWMAAAAAAAAAAQAAAAxlblVTAAAAagAAABwAQwBvAHAA + eQByAGkAZwBoAHQAIAAoAGMAKQAgAFgALQBSAGkAdABlACwAIAAyADAAMAAxAC0AMgAw + ADAANwAuACAAQQBsAGwAIABSAGkAZwBoAHQAcwAgAFIAZQBzAGUAcgB2AGUAZAAuAAB2 + Y2d0AAAAAAAAAAAAAwEAAAIAAAFtAtkERgWyBx8Iiwn4C2QM0Q49D6oRFhKDE+8VXBZh + F2cYbBlyGncbfRyCHYgejR+TIJkhniKkI6kkryWWJn0nZShMKTMqGysCK+ks0S24Lp8v + hzBuMVUyPTMmNBA0+jXjNs03tzigOYo6cztdPEc9MD4aPwQ/7UDsQetC6UPoROdF5Ubk + R+JI4UngSt5L3UzcTdpO2U/qUPpSC1McVCxVPVZOV15Yb1mAWpBboVyyXcJe01/gYOxh + +WMFZBJlHmYrZzdoRGlQal1ramx2bYNuj2+lcLtx0XLmc/x1EnYodz54U3lpen97lXyr + fcB+1n/SgM+By4LHg8OEwIW8hriHtIiwia2KqYuljKGNno6Cj2aQSpEvkhOS95PclMCV + pJaJl22YUZk1mhqa/pvcnLqdl551n1OgMKEOoeyiyqOnpIWlY6ZBpx6n/Kjdqb2qnat+ + rF6tP64frv+v4LDAsaGygbNitEK1IrYCtuG3wLifuX66Xbs8vBu8+r3Zvri/l8B2wVbC + NcMHw9nErMV+xlDHI8f1yMfJmcpsyz7MEMzjzbXOh89E0ALQv9F80jnS9tOz1HDVLdXq + 1qfXZdgi2N/ZnNpP2wHbtNxn3Rrdzd6A3zLf5eCY4Uvh/uKw42PkFuS+5WbmDea1513o + BOis6VTp/Oqj60vr8+ya7ULt6gAAAS4CWwOJBLcF5AcSCEAJbQqbC8kM9g4kD1IQgBGt + EogTYxQ+FRkV9BbOF6kYhBlfGjobFRvwHMsdpR6AHxsftiBRIOwhhyIiIr0jWCPzJI4l + KSXEJl8m+ieVKEIo8CmdKksq+CumLFMtAS2uLlsvCS+2MGQxETG/MnIzJTPYNIs1PjXy + NqU3WDgLOL45cTokOtg7izw+PQQ9yT6PP1VAG0DhQadCbEMyQ/hEvkWERklHD0fVSLBJ + ikplSz9MGkz1Tc9Oqk+EUF9ROVIUUu9TyVSkVY1Wd1dgWElZM1ocWwZb71zZXcJerF+V + YH5haGJRYylkAWTZZbBmiGdgaDhpD2nnar9rl2xvbUZuHm72b8JwjnFZciVy8XO9dIl1 + VHYgdux3uHiEeU96G3rne8l8rH2OfnB/U4A1gReB+oLcg76EoYWDhmWHSIgqiN+JlYpK + iwCLtYxrjSCN1o6Lj0GP9pCskWGSF5LMk4uUSpUIlceWhpdEmAOYwpmAmj+a/pu8nHud + Op34nrOfbaAnoOGhnKJWoxCjyqSFpT+l+aazp26oKKjiqYqqM6rbq4OsK6zUrXyuJK7N + r3WwHbDFsW6yFrK+s2u0F7TEtXC2HbbJt3a4IrjPuXu6KLrUu4G8LbzavYu+Pb7vv6DA + UsEDwbXCZsMYw8nEe8Usxd7Gj8dBAAABPAJ4A7QE8AYsB2gIpAngCxwMWA2UDtAQDBFI + EoQTZxRJFSwWDhbxF9MYthmYGnsbXhxAHSMeBR7oH8ogeCEmIdMigSMvI9wkiiU4JeYm + kydBJ+8onClKKfgqqCtYLAgsuS1pLhkuyS95MCkw2jGKMjoy6jOaNEo1DjXRNpU3WDgc + ON85ozpmOyo77TyxPXQ+Nz77P75AmEFxQktDJEP+RNdFsUaKR2RIPUkXSfBKykujTH1N + c05pT2BQVlFNUkNTOlQwVSdWHVcTWApZAFn3Wu1b21zIXbZepF+RYH9hbWJaY0hkNmUj + ZhFm/2fsaNpp0mrLa8RsvG21bq5vpnCfcZhykHOJdIJ1enZzd2x4bHltem57b3xvfXB+ + cX9ygHKBc4J0g3SEdYV2hneHXYhDiSmKD4r1i9uMwY2njo2Pc5BZkT+SJZMLk/GU1ZW6 + lp6Xg5hnmUuaMJsUm/mc3Z3CnqafiqBvoVOiR6M6pC2lIKYUpwen+qjtqeGq1KvHrLut + rq6hr5SwmbGfsqSzqbSutbO2uLe9uMK5x7rNu9K8173cvuG//MEXwjPDTsRpxYTGn8e7 + yNbJ8csMzCfNQ85ez3nQm9G90t/UAdUj1kbXaNiK2azaztvw3RLeNN9W4HjikuSs5sbo + 4Or67RTvL/FJ82P1ffeX+bH7y/3l//8AAHNmMzIAAAAAAAEN+QAAB+QAAAIBAAAMYwAA + 9SH////2AAABX////RUAARx2 + + ReadOnly + NO + RowAlign + 1 + RowSpacing + 36 + SheetTitle + Canvas 1 + SmartAlignmentGuidesActive + YES + SmartDistanceGuidesActive + YES + UniqueID + 1 + UseEntirePage + + VPages + 1 + WindowInfo + + CurrentSheet + 0 + ExpandedCanvases + + + name + Canvas 1 + + + Frame + {{218, 52}, {999, 826}} + ListView + + OutlineWidth + 142 + RightSidebar + + ShowRuler + + Sidebar + + SidebarWidth + 120 + VisibleRegion + {{-54, -59}, {864, 672}} + Zoom + 1 + ZoomValues + + + Canvas 1 + 1 + 1 + + + + saveQuickLookFiles + YES + + diff --git a/framework-docs/modules/ROOT/assets/images/oxm-exceptions.png b/framework-docs/modules/ROOT/assets/images/oxm-exceptions.png new file mode 100644 index 0000000000000000000000000000000000000000..8515e7c4887aa443e7966f6dc865038a8eb4bb2c GIT binary patch literal 28027 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 A=Kufz literal 0 HcmV?d00001 diff --git a/framework-docs/modules/ROOT/assets/images/singleton.png b/framework-docs/modules/ROOT/assets/images/singleton.png new file mode 100644 index 0000000000000000000000000000000000000000..591520ec1dcc6cad3a02b2a6a7ce0c3410fdbc71 GIT binary patch literal 85523 zcmd43^;=X?8#PQL-QA5!gLIdG5-NgpN=SE?bPEF#l2RgF(%p?B3`h>$-TCc#p7(wJ zfcK~G^5VjoIcLs3d*AoE*IM^JL~5wL#KEM*L_k2mQC5rmtSgBRsx^b@-mv9|MoK7GBl@d`&)d!&8D1@?bF{?F^6WQixTm_A^doe zgz)BnUs4zL|8}ud+|A{^J=?aslUFJ#Dm;|2zuQRvHkjdA$FirMDx-u@xM?5$GEKwZp4-WPLSTVp`}E|HlR zwwWD}wLMv6CRjpO3ntpBC2v>Mzdd`Ht2xGHTtevIB;t2^={>DfVak{~$!ZXl6$E5> z!+f3Fkr%JyxY}-Zp40lBy?OiY-ETLEf0OWFQ6R4Rz%i07m0bZoy&|C()!5U7$0fC- z1ye(-@x*rtNFG*jr*x58rjn{^?1d&g_?(C}G&Othr0($dtwY`@Z~br0;X%D-B#&Oo zI`Q|Q^#4XCB6Tp5Jd|M(ZScZs-25>WyV4)8!LL#X$8>_86W7+F@fWf}iKBi7N#Y)( z=O--H;J=uwblbPNyI;tepjP$L%k0=@>XFHfvz#aA$AWGD{o3AK$B~bwGn_}A;*Q?1 z6`~Hhh>MsDwHBO%2f{2`bk)h9<5O0FpZPpj*vKbwM1>MPFYa@#mruG@rMe=^7@EnQ zhnMdbmrFv=Cj^eJmIt$QjIh`_!VN-s+71(%>9mMi?x@U3y9P7OsiBCas&)huutuXC z7rDlbI-L{oX;$u$5cl&n5#6d+ecFxq|DAz2_c#o^2pJ-W&%f!zvPY2|M&nxSf5M*C zVjfc9_(&BEBJ^P@enU&eac<$gddMYrOGl&Sp7*Zy#Qb@%9NwoML$G?BGKFs=a&*pq z*}=5bx%6!ra?Nx7k_VcY@fSb$?5Li{6500{@9wZU9qMHS)o{AU(OuVgL8DV|cYSnD zcwDW?;_9n<*}meFu60kV?e}PWP!%>mep@u?ck6^YfBAmD)KB5yR;BOZW8DbLSqw$p z&UoGbnb6-|Z#bo0X-r2nRzA1acPzZ?9grwNH)jrn;@MnwZ0KL>KY_@^8PuasTXr8X z9%pQMGjn&t63n3cL7$x?sv=Bu4nkuao#SXwD_LK;FLD+l<2hksgseB``1wWDDRz~} zuBP}HuiHD`EPrm(IQV)Qi>6c=d6~bH9d(i4jkA#6G0L>IE5wafQE_pg+DO(U@L5bf z`KN`0q4P3>IVmKhAaq)){g_*fcPSkmPTFKAcvF61vyw z+_G`WMX2MHpXu_a4O1hX)FQ{`t;N$8DfJD)A)~7F<@4yAo~Pf};?GZXBLca`e{Yos z(h~QRDygDm8U(%>@WzGqYJb4cYt`uP_XFB4bWpMLjjhGL>PA*A{#&39q^larH~ z7BBwB#zq0FiNKA~Z;;ef&z`Y%N0@ANO$`PLlI!kttYR#s!fm2WC@2aKcc@7c+aJkN*} zSrm=q9GPiE)^D1JOR#+E`Y2b%>WK4V3hoQH^&wNu%Q3V^hDJI;n?=fogWYDZkgtxX zJQ#M@=k7|%!O=!xQbHZp20boSQbQ6Gb-Wy&vK#%2EuX0K3rxzu+Fb@KAb$)Q9;DzKKt>RSUnu?0~^$+3Nw)$F-fErLPF_?EPE z;upwg)@T)mD2P%VOBmyijI^lZh@MUYIe#(u?SsinS|&D4$fs!&&0vw)uo9|VLq6lc z{=!ZQw;ss4W4Dis$pdo-o;}|DIqI1Miy?2YOvw0<0i&=i3ep#2yf7mM*`v>r8gJ3e zn&mRD{tdQcnD7l;_2Lo~o+rxBgpqFbM;?u9d7hz1#0OdSMMgaHDEVm{m9Ep~E8@_4 zP8v0+B`$H0!^F;dv!YjTfgKXk=N8JeeuD=z0 zuVCT7vl3Sj92@mp?l0ziZ};ncAMY=FdU~jTpT^TkWtDQwS{pVvGD!GCEA{SUy9xUKN&Mlk`Dmm}k>sD>Wt!;lJAUIze*g+E2^omE<4iOBrX6xjnjr z^I-GZ>$E7YR$o~eOj*=0!kaIcx9+7YBQw=|_O}ff>NQzstAa)X~1B`ypz?e6xl^na0f2gHmkhuH@$fRam+V;}D_ga#uYg zZA9lj^V;ZU%Jn`+pi@P63Ut^lZkNgQZ_Xg)=m%6GKTPf{ZW~^g7xO}@V^m#qfwi7j zM=IC4P$n;?g7RhW_c}%;6f0#X*WX*`^Loe$WXEzm3U?%wq7rP_-Ly$9MH7yPKasbq zwM0PFH(!DP-0<{`1rMfMSy_Bm1 z(xYwAFnSOa*#hgXit^Wbq{*j=96SDrOy@Qu?O`tWAEsI{3NbFKL`-~r)UT1GI}!SMO_D0Fv`Zmal&o!Y%yJ#3G?_@-T-~-&iqlhnNHhN;;xNP1$b2j)T;p@T z*>C!pn=D#-XZl0eara%S(jc zVuYTJ4IMJrL!zx;HNNZAsBgR2l6HN%2}w$l&zAH95G?az)dzs`-Pxpi>TA}W>9XPN zqHHxSEmEn+JN~CnpJsUP6n`k2rtBXW9bLa%3g};V=Cz&S*@0HH8?8!80e#T^K$-Vj z35;#EFBX{||H;uHTlVs?=h5wbM!>`M%)YzDSjONlyE$?RZ`asdhal-d)o+5lmSfb| zXvpb>ysldslmb?PzpZ+WmugIVqmFoYp%s=xNl!gn4g2Eh==}XI4;DCdszXXk zIXFnMkkPPnoL2ijaD44HEV;Y$^}j#Yrp84#Xm&4<3&-`j-^-Hl>4JHI{}6>SBn;S0#xnoxc~?Go%a&* z?b|RIhw%B|cU7~tu*QRbb@U zuF-su5L~VA2-ZC~Fd)3_Qxbs-=no=q(p?j?dG?<-DsBM6@B)z4vykz8k$cxGJ-_W8 zeec{hSUy2CjZl-+Q|ZY%iHX28LLjtrT-D(Hep~+;LYH!xX!f!GDm0DfXU&?8?=NYU zj<_9ctY1o9ryKeNf{NX3E}XJrE86IgK<$IiyHcdxhyNhPwnC}Cq~cd)5B96RHsFf!IZpR1imE(i;!jNSuI(BP}Hz?VkrA++bRgdiO-1fzg@V5DNhVh#K zPsgcoO-$U0wB_boOExjlS&X&g0)8W{YOqh+=kdpc>#N|wGiV0!84{|I3$2Clw*|)W z&HKrefB8%>i@%6`s|1!&34~ZGK*t3mzh?G5iC=!)6b6*C0R=v$Dp(L2!12 zU^P?8pjDC_PU{`!l>k_RpD`+`QywrnmnO;3^fcx=E z@4RC-PM{~7%BxpiTe;zI9!?q^3i9i?he%zM|6$2<701wPokY-fCUAT+Pa&FA-+Q}Y z-fJ`SR=}#>eqrdnwgIXVu95;GpGj9pWeOt$LlB2q~A&Zy1VLv`Th7UV=gU9E>)?z$M_0y+ktNrms z`S~Huhi%`o{cj?{ts}3nSpTbiij0nH{wH4<5d5_-(4A4CrL{V!p&8(r05SOZ_^jrB zae^_>g9OD0-~yPm63u-wt>;kXw5o`pTlcAVO513(Cz9xrO6we)tT}{;fq`E%Ik*}x zHKuLk*L!om+pXve0Bw6B7ujRcYZEb)_+US4$qi}%v%DG;JM1y7Iy&yB)AkO7mg)6} zU=YnTy0C#Yz_rY9LZk0mDK5%d0bpi%x-kl1Rkz-L6dcoV@z18aUo3O1GW_kNKvZ;e z{5B|!jcLK&@DnR*$x|KQ^i8-WD#-9S)7MZOs z*k>aXa>lI=adjky`w%zH&8h*mLW@(4ZWkz%l*% ztL*t^RVs7)^1`c+z5&uh_x|o~l|3bGkMf5aTchuh*LSJHm7Htl&^dRN*wsGM9MC>p zVdhk85ySd5VBdbogL8+kuwFeZRohD5^gdLsiinm1t3DPVPiBherw04nUbDFbRiV5J zDjhCuyJyk?CC0G(K)R1FA>kCgvN#E1&$p@XapWf!c@e?n(VkK_bzhk8k;0$E7^=eV zBnjh^wOOyJ(i9SWEM9bDaIR4+;z%~C#7)&IS-poUR-?UqCY#%X$|Tx#=rM2?8@5AB z60Ya`j+#peC+u}-Hq%;aw!>E+ZEoeUMk#&6V=cE&?5i8ePmgnF#9n>n$o=u-NzR`! zv-fD&NOHS_nm|_st4eR(+7v{0d&&TI^Ix1u%z$ihB zSHI*h1_uV(`0(CnGHoJyAh|FD{0>_$56*S{fi9|iW5+`dDq836IXtvL1?iqH(@PVy zqf|{7D0bhAB6$uEO+XK3Yz2WXrVF^^<Tjc85xOjsK4YsXV(G}LqFjDT;FHEuBWe$ z&#Vu-95C8S?H!OJWv+*~mSrFb2FAuVN^8b|8*p7~J&6`L2w^+zK*j@DiGhJ(mEPCn zw%f4(YmS|pd$aBKKrFw`7Zyt9dG`AyVnl3guSE^)^ctSFpuTtPo`d4NsX`n5lX^fx z3M8^80B4b`=GQ1nRHGhYtgA=x%UYO%?OtYW2A+ zcc14U7Z2`+E$2hjz8kiBBg}g&`HA1|)xa9jkPx-X^#{+PM)BjDSkd8tmO;S55RjMr zz*`q}-I7*Q!v$nQ0!$ZKv&SK>j~X_b+z0$m>54!agocKi#18|A8}T`8MVE#n$7c6> zijf*U{xXeLkzJ>&VtN&pFu1 zRYAVT`KQ;D<`3zOAl`-#O8oH^i-?yaRk8Pr1{{IcgsW3zUkol~?3R19CUV=T`E!!V z8;%8^Lgz}-$ODU=CYmYEY`u-I>2rN!A2`=DGN~dv#T#PRs;-cnC7xFClx99*Fi08i zn~T$rh~cJpIsAjKJ5|h;AscyTK&jm2uS${;gH}8?Rb|3_xmJ0|mUxKo0P%sg7ugDZblcyN>zj>JXngJHgyaq*RD1FR1Zm1Kpo{QEsj#DxdlvR^?BJG`7M1VxA)Us{p=5>~o2SP>1&4Qg_&;1*f-3iJRpj1Z z3Y0bzWD9`1pvH$Sd5C8E9)~uVaJL-E{;RXmUiAWCFSO{%1ehW`*uk=%oSr`A;<8xj zi42S=Q--ikdA2OrZ`O=UcJH2_TyJKF8)XaH>CSjA)!C5283jmBV1&VqFL0*Fl1?oPnn6?Akc z=ncmw>fpu}oVZm$hXIB9p6F5_>=@^bNGQwp_RY{PSpvaCfoyVfSY=YwVWY3<{QK7* zJkXa;!^T!)J%#5<#u_VlFBG<@4=`Ph&^PfhPo1ux>4#qqeEnS}s;GMCbAR&C_ERWy zBY@cj{n=Pq;Vse5KI~_87)eFC!eWl-zj+{&h+_3L7*k9O2(MJkiV@h&(>@@9+a zKYB{IprC+5?-z%yw8OtzjFjQ`+YQJ%B|t{L)6hVW2I{$MGn>Z*2`;X%NI90fu((lr z$ho=6E)RjOQdUvv`c%gUlrnvyx??3!&?={MARaz`{Fq-*;57AKJM{G91<9ft{iXPs zZGTqUJamQ1cXHyX@;BU%qs71R*05sM}1J7CWgG z0YdCA7yX}kH5BzYcnzvP0s(&e-3b;J8CU6AZ1F$@0n;-(MWCCRTa=w{wu{W_bd}ZA z3IiS=0wXdt_^#n3_~-kQu7Wxs9YNY9_h?#4{M;zlyz>Wu0IQIDOaYnv8d`3ENZ`eQ zcnZviFey-xp<$=5%bRwdfqo(0P2-!twEZ#vX)yODu+;Kngv55V67X@^3F;N-N8zId zGqkwSszfc)<oMYmo_T^DsZAR*4EZk4tslgLRy7R zH^(cIl4!nvm#MG!dIZE4mU;nK6(-$bz%rO{Bv+-!7iPR?yU-^1@xDY0UNFhA(LjA8 z7qG(jyE!wNsWgFmz_2e($SguaDF9|-B>iq2yD-=s$3!+Y|8+_w)ul`NdCyQ0>iXa_ zReKyRCMV{!gM2)yIUjmn!2{L~I5B7TirpN+Je8+h3|vgFxU2@au(iK_3K8BCck$#l83dQhWp>gS)7K zPdba=6-^5lwX*nYn}b>b+srZT3IN3D{^oqn(j?-i;%$nNKgGihESwH^{2ZV^vV7p{ zZ-Sh66!HDt)gOl&j=He67hA=^?ZUv3B0qeDJ`N=vL5bMZ%#W5kvFRi;()cZrs*8Ee z`eKeGFy96(}>Hy8%t#LmfC z;I=#cx56kOJ8U6g4HQcdI1jKzpTpiyb=9Co`QPpf^~KS=dVIJ~6Z1Gg%-jUJs}Oi# z`i`Bb#AIYH3vN(eusI<3C+>S91{o)MP2UZ$vLBk=IiG8nWBa%Pg$Ed%M7|d`r9cEK z7Aaiby{#~ma6gzI{EUhP*Uww?jr?@JN1c-KQmH;!>FJbXuiz300hrF6hnK(^OI3jd zlT>((XGy?pa8Z!pXi!^Q`ziUSEcHOENb330(lr(qR=1I*g+G4TvKw-`Urd7B=I{}koNNmlVeRJ$Wvj-$Ia}+eb z-~<*xae1xYox^0_OFUYiJzn?yf4wK`!(Ko>@KVNtI1PhGa3X;=5tteiP``+Yi6=l6 zBjwT`0IX9TH287F-2Fk&!s;+X4+E3dz%^|OPUERX_-xrFPX?G^ZVN!Dz#TjIWcmim z<${U{SD^4R4kqLn2;q0_{(jCbE{&iw^E~ucbKUsRi(P*UU>GAH0svEy2`%3LCKB*I z+d6`Bw_P!&rKQ2I0;l{_c6OuT)7C;=nWE1S0bC)}00JJ)k) zeQ#F|Aj~9w0tn$W2_HdV$pPUW4w!K!t%P?-_jlZ+D3YeOhZ~#f>S~}IEP(Y;YSf<9 z)g^1+c5M;pC`_&K^zS6hQPcZ^_$3|Kb`$qXfN?4pJ6&b^L5RmH!2 zX$^pYCTS(FfuW%quycTT*PrN5bGGyu9O03+cjqA7a#g+Z=M>r6e=!WIbSY5gLV750BUva^HmXxmm{|6`F08gj zLJ-0I?N&_vQBaE;$44ArMU$H=#r%rUa-D1S5fwW<$*6oVZbG2=6X^|+C8WCVC7+W4 z^rN4If3b!~PUZng-8dlr1Hj(tS{nZ*6#sbJ{2S0Cp{`Ni zefA?T#0%B4$H{K*ZV)_?Lb zz!KgvjF;)uSir5fKyqCgG535xhGNKhKfhBG2?d2M#O&{*>d??oDxf4FLCyANs^Ih% z_}{<5_f_Tw^pa?Y;B)|IJPeWzCQJo{zZd9_Zcmp{ffYrScLiK0W`15DjMjBV_9y&W zV6?Eh9pHcgw!c!!%_LFjXHiPI5&Q1^KNWd~wb zW4i^w7hb>tz>FeL5nK=E)8J$oe2RucS*t!i^6=wbky?XPKd7xF{*w0X_wMd{Go5GK zlO^ja`>{Yghu+$^fGS=K%vQBbQQl8~*}<7T@Zjtvll8Ng_KyR$1lYzlOz9$>2!V8e z3^d>(1D9F{dN}XLj|fruB5C%ldH+u*6$3!88Y1eS(_aD4m~ZJ05B@;9PzK- zK^>%F8jnerVK=8G=y1RrpqANweV{HQJl(tnHTwkkgqlO^H^3*nKI+E12F_mB;6)S@ z*zJcNNV_-oV8p92$~u#d)r?hOesrv8itSsE{cnMLVP$R+U0pr=uN)S?sgNoA!85mp46WM|Em?ch6_3J3+$P)@BsVXgqM>7 zhQ7xNZ9u?PvM~@7nh8)UtE+DUtIh&=8L-4(kECD?3&78nuO#q%Ksx@c(w0$$yDlxj z-mA5pB?N{ju!i7e*S$Ft(BxB44<VuJ3G+4adfyuqK4&a;r?&l2P|FrK2KqGlSL zm;h9;vap1r(|QI9+Wq?ifye=m*=ngx0z}UWm_l4SqpD}Kok#EvCNO)xWMqs0%lt## zC(sd%hr5xW*AiaBj`%uVAQBGCJw5V*4vQn;Mu1-mNJ%!}{DS&4JI0LwA;?9XnStwM z{_$fK7#z4>$bx+l;K$;?`@Y>PaALm{Ctd+nPRQ5kKJ9jnUn$8Q*?P9%pF1Qe?u!gXzdfuNyyOT#Q!UxUa=CJAA z)iKzbPzkm*XqD-PE*%yDl|S#f8ViyZClGMXL@cfbgyw}YIXnq@XJ%GC)~Hf4vR6iE9&s!rZ>1C7ks${Zmqvp>=+XJb_Xd?`K%_ zszkxOJ&S!FDE*h$xqqLEtx{MYb#ebm0e8OaIwU?U!Dskg;%%a^>tYD`ae70`?E!c0 zZo=wStn9G-2k#sgud?tdIA$_qu_vVY6; zQX+}iKs)mJ`8ytRZ1}P@=yUl>8WkuyY-W1U0wC_%Jr5iHq$PfkZc~nN*&+;F!pm=( zh6%5@Ta)<5go6S10(2ky&*UV9q^~fIsOyif`g4V(CgKO}L94-Yw(nD-M@)_qUgufLt=;KLJ{_ z@@QW7m+c^+MMD6}t`3?HfvpX1Wy2fvQ&EJV00O>n6$I{tMs-s7u;tVWG}zYH*NI6< zSI)h=k)AO3=YuZx)%`;y8IOcS<~N5nikew{>)6ZlQxzvqtETc4T}{v2J!<0!nH2(K#{8P@60GvRwmcn#eo zGxNTibF>a<_(7L(jCp3qurNM6Z`$C`gSVK*ga%W#TZZwPE|-smfXy^)V`1E6gShu~ z!OMvc8f#y;V7Xk&P^}+VSAD&I<|nAIy(k_9Gv@R}tFzC4y7u{Rxr*3#u~m!N^UJIX zu(Jo3s3%@?Eg;tWav^~Y#1%%&yN*lHqfIp7*5~tHLyOJM{U4SK)qz_*L6~);(=^fU z<&?jqm_Y(|Hgb;WQ@8zYz%|AkboqvU9wCBvR0g$gAjwz1bx(R6bGqDyB7oGcyVDt zc54rzA-|{S2E>sN8+?dI^ilERlaK4yhD1|iS9BV4xJw5^^b{k4vTegRExT%SQtn4+ z9fuux=Qr&`n%k3XcA!Xw9E5nIj|Qxxq)S;i+4oE~7t2uRdu~I7(LeGn;wLn(jWA|e zCR!s$8Vw{oy)z? zWT=>}qZ>M1JMMh9ns4%*sX@|)4>p*+ym_0mbboaG{=}Ag`+?co$?=-X@nB6#qf|g_D ztnEDL<%D}tmjBviVaM-#a03FWeDbw(qMyAHY9%A|igq`C9T_%oaqftKcx=hu9?!fzjb; zvi))yUrwd|^e&8d1qZ?Nfo!(ZK?lA3@xy_^>rk9=)1oJhHfV#Xk-Vl2x5$i2D*6P+ z3HZq4qk$&-u#0zV;zUwJ4sx4ej68=~m{6RrW}}J?_b$AZoUD!Y>UZpy{T0!bEqeyS zMJc}1wjtX7kkb~Ys+j9_Mz8%7A_c1#DnWK$6L}ceHs}r`pCx)3aTPs6g)E2f{WkPP z9>$&?T@)}{1s+*9hje&!HbuoXB^l@)qc8`EPIP)jN<(H`+8{FL>b0w z@@J-d<;Bhih-LB<^AaR|m!aOuCjlF?+m4ftjZ(SPd7f1GzJ){jj8}2}8BD!xPk|Q% zKpvQ}fGKt*+j2E5Be6(=M+H`-q6q0pD#=;6SITB9C5+kv4t#lM?t%sm>=xu_rvh%o zdE0b9M!a!{YF^#x&i1NB5a9Lfk_~e?ee({)wQ=vh4d|?>N0&1Q6noiqRc{Wx=_2aU zXxouyytHb<$EK^Z55Mv~D#RYV!~Ng2MPp;E*i zzc^R$HD`{1>F9GcUrDxy5Y#D$#H#Usfd(a!LUd>K;Vr9zSuLIj4aD1z`^%udgi8xIB8OG>fmE)5ASMOVv;(s}Vb!2FpPH%V)C+Gs}xiG>y82ZTtj>YdFQk-?7aOSI(x%Z?vp zIW9~D#%?RYNXp@Vg$cg;8;qqS&>JQfjVJTUGV|Je|FhyP1)j{Te_r| zGEn2j!{8jX3LdC9@)QR}#*{D3YOzHGF6)8g7k}{={y@kvcP@$&ssQtA_GWqaVu)#P z<>l2gs+u6<(pFl8Y+Om?T6Z%D`tZg&_U^`FzoKo?!Criq__U74PhE4k3j%BiDYCKvB z8j~Zd-*e@uX-svGG%T%X^i%ViGEM}8#S=;!uIxRIU~*@}0OntdIgv0MK^5}oVY1mYynPKL5qw2=bl;QD z<7}UM){{?lKdP9QO58flr@}l!f%ee2b;fB9#PpK>nD(l^KrjP8= zs)?ad(XB__BvkofRE_-LO@4$x>bY)-p~pwTc=|_xhy1hhWTDbZ6K%$AFI&eoav-LO zf=;iqI@+(VnE_^@^Y1H+#NXQ=wr$$;c6ODmD5Sa)XrPh9Dn@fdiN-&qH9K$X1|T>O zGuIBA5|2xlvZSWcl#0J!AskmwqW8W}uyu8 zL@u|a-9QRKG%dy7h1_cFC2cBCGLDCHZaJNxnV0ige5iUQJDkEH;;P z0j-!R@Le%`bG<9Se`GWB-W#@)r>nmG=x@Z8xclIrw#I&DL!i8N@K>X6F^TCKpLFuU zqec~NP-xbG-HX<4xASwEX-=3*YhizZ*_Ky* zS@i_zMar@_c18oYPFiUJ?vWvp5>A3=)^A#mGYcbya!gsu(vQ${OroAla9c+HrWr!j z{e}Dw3dzWtD^fC4F|G8Klc6a6$08&8M#!HmZdo=odD)e(Bx8X3X=4=SwUe z16F~>(aWQ+ScqT$_t8pIBX-2M$hjH}DcbU#*M9lc8pW@Ma&M4K>D8ziVDgc?MzQ61leMOBD{m_4fEsmOR-mT%95OQ*)`TmH@T9~wUHc2FXoGj`Arzk2F)v^M(|&BF-EETC0i z#URo5@U;83(_(1zGFd!KYWfwSzjVrZ`zjW1gImvXz^4q)xD~VIs+u09`c(5c8Y&f* zV%czUorO8Fn<~;dNwD1r)V{iJ|BYftF^StD|urIfyPTZ zBbM>+!&r*#5tYqt#N%K3@#14bn=o$2@ZSFSX;6gsVV8m6p#_JiKrRNhqE-Z{1*E6$ zUYtvB8u4EC7P_aCVg&J`5LKC#5gO*byKYS~PISmbY1ni_hLyLJ7&&3%5GbIo zCwzGHi^WS&(GaYme&>drCsS_yN9b*2$;UAA0`zLF!74)1wWERbf2!l1WUq|8f25NWP z9w`O`b}Rv=&MWMT;$t-VJ1gBak&-Ll5ZNBtaZ4-g%p7f|nP%3CuJfWE#hXB4QAQEE zy2xkUdi?#LC=B6`;@*k<;A`opPiO5DQ*tZuX;1tqjpxtVN+LT|D!b+VQI1o7pg{ly zN3y8s#7D4Z&q7^?-6;E?a$-$)WZx}?oLI-PoKZ^Cv+;$T$TxTEj8Au|%)a`w1`kB)iE`deX{GpZlIMrQnBi3AO{JeduWbiIZ*W|h_N)vV8tk8s0ACy)t-<<}Uw|H$N7Q0Gnm3TM|6V_=BZTEi=kLzghAboPVY& zibc6&CL@TT$TFxu_Ss=4Z{hgSjM|{g4oZ2`Y6CfwL#^6w1t&4Nz!N@FhvUX=-_Kv7 z|9MLTj<7V@75E2CD4>bQ%AKUL{4|Go=YQYI-|`_OQcKV;Bt(?z^DdGeZh zKD-cO5}<(ndU|xqnT*B#-~17l1j9Y9Fy@mN?GG2txPAVi5UtF4P^aDS{^~88_(Skn z?a|H0`g>^}ssfDVHM(3K$`+n?E%ck`aZkQzi0I-_G_xK?6h<;sFnNjSR?6GeT?RvS z&hIB)Xh{TYolo2ZX1tt~R|-*?Lqn3r$;OHG*%o`tvpf|o|0C^nr4wEYuU^~bO^&LB za2}QGCuW-;P@VvUY_%8b8pk&!QIf%|@0Z7RFwO~KvlNapMg&wO<3yIB=x+Kc4Nq2^xN^3q#v0Ad2Ce z?Wl+M6pe-WxoR zc4WlbXcUKE#|wU2Z23R`PYeqCYtZ8N5-3bc<8{>0MesCyqW5i*?&+i{QbKpApv!vD zK?!>UnU4$aAF%gxYJ3t_Z_)iXw6X-h{7!27*Zqyc1U`!qf%AF z_Fwf18-2r2zsHs;$HyC0w#yGWE+LD;Piv;7y*6z6n*ER9fELwmH}Z$)4x7kfewE{) zb)~zI{zLn)=bC%64FzFI(v%XXY|nY%<>{zgE}#!(q3F7Q*y-uFR38Ce4lC zh2;?iW$MAh$k}%|pgmF^n+vw`_3aUQZdhKK2R%u7%w#YCPZ#GPa0EduI(KVw)Wqkd zD982)j{CNnN(1hhb#B9+CWnTU%e9&}Y#{5*on0A^6VXr>bSSV5_(_ySXUvh|=N6sF z|7Uiu4)ZQ(NnR2gkjXtXp3>JS$@gtSI}D1tHuQP@=^oI~>ciXVLK`9Au^!m^QqRn< zG=-3PaqPC%Hz>mu9-U`;@)}zaPA#lN(}$6FI^Ujt@3g{?mxE}MPw9-gnMie+$aqi8 z{VwF17nha)&CkC)S3t;RE)d~iaT3pnWKY46m2&Q5?9)cRb^X!tmiYSNAi-3gd;VGM z^=rkMM67y$hR;@i$l2XH4c;*sM)`9x?yloW>x#SDvoH1Q=4$g_d-tjxugt$7{AwFc zC5cwAeZmF4G~3#Uj#kv5Cs=Wv{aH5M#By!<3U6A~&(CB-PYfude^4yp9b`PqiW2^o zvD#~-ur)8H(xM*kkH@e5Qa(%u;>P(b{EdOUrsfELRhr3#Xqp^UG5OmEQHhCG42}T# zrrCHO8p*p?V%@k?FOu-YqQ&? z0{wG6GqnE&aWpn%)a(B75iicuWc${{WC5MYO)8ksdtC zVVJUA!kAq5YdzW$(Dl=A)%c6;NWhLj(9mE-VjFvQjf+*^)#B5ehv2wi%-iQiLwl{( z!r)+t?M5h{bLJ^8&IK68L8qClgwdasTt8$l&S^{o%0cL5d{~XoXNw>lpXHL?m07D) zr21@3ya2Y{^CK?}U6gehJh>?!lllQDi3E0)*7a$>cO&Z;A5w>49UEAt2;XB#c;FHn zE##Y2ijO&VUz&l__Ylk2eXg#7)#wl>o!6DdB~N1PV-;ew_Wm54c8?*Y@@W3d;9NkY zISBXQ3jIovj2ivl;_yfcb|5^E2&l>?%(IxHH2axq-XLj65iB++J$oNYSP$7Vz5BXf zRO9g309v1lfCNHT~iFi%;gI>`75twD*c8Us`{goAB zkvU7%V$Y)o3-2|qABt-me%|L1#r;7`Q0;-!b%5)^Ef`jqn=EwuB0uq6q|H+1+&$ve z7WW`V5gI3l{M)9GtpB|hd$_Q`);K8dx&74&tR=X>6Kc$f3l z9UaD@XuZ(L914|-`TS=-0%Xg}kp6%~^Q#uV)EXJWF*|g6d{=|6y0Bl-%(L3eeT=lp zYypV@Qq784WcA#MM*sbzFe~lRLx^vv-w3FR(X`jnej%1|85R-DJKjxE5dpL1L-Wz|>}|lke~K51uy5&)hTP&B zMBeD3n(RyXimTvgXd**U>t;40BM3$oT&l`>LS2nkHJ@CHTQ5xVyVM0fM^( z4{pH;?gR-0cM0z9?i$?P-SzI|`|DQSw_9~y;p{Verl;3h-K(d>`fXKl&IlPu<=hk# zt;ZOGW?I7TbLBp|?;x?9Pz2(R-o|aTjY!C^JQR;+JN%A(9YarU({Fz> z@y-id56+_g)us>iql@HwRxiApFU_XL{{7F%%5-Ss(e;;KJImxtn?Z=;S&gmJS(kN) zyRGr0Jw=nLG?1 z**F%~86MV3M?=)lcr>n((CWj%rC3X|it^AVHl(LhbRZ_hQg4Yrj2<2gpD%GiwiTzW zX6yi6*aUv{ZmSE%u7Dm+_UFCeQ(*NZzq>Q6i2N{N6KfZ1#Ry|TkNyH5EQQMspFd2K z=tCZ*y33Y5$rwN>zy}b5ein(OWQJ1hffSFBj$>ggabjC{VGEZ}JI{fJO*-+Un$7b} z)_{KLGR7Eovr_qMw|UEE3u`L$=6*qqJlovTp&AAdITZsak2fymM7>KT=4i6c4gAP^ zL#gp+CEp%?d+Cdbe==jav1GiyeWDGqAVm6qbb$9Q)v|wXLl7H4DM*i5jl=TS2Erqn zG+7wxXl@u}5BB00ZDE`MburhL?XS#@QGv>qq1i_l;!nD@(jlC5=S`3|#XY&HdtG+MeBt;VT>{b#Ut#W`6waWoMrE5>mxgHs#f=)=vtu| z7V&?1X0!ren)E`~XkBESr}i*UT-2Vbf9Y+IWd?aCou$eX)76#~F2^y(;)SB;sCdUY zFbUGXduuP0W$bJ3zk0A1l=|Zp>E~mJmG?XP{I`)!2P6CgY)ie_cKf-W!nOLptlZ%x z%klryv#H;g3|4%GTzUR5@dZ2p`^2Mc*yAsZ5k+$$$k00wkLz)UNJgq!khipWX2=5k zgx;(Pt|7=j&s{H}ZUoTfqknP@`-~M{M~n6^IQ0D>&w7SCAo2pIdfb(xxjrFTZ-QtL zB8G(F2Z!xDQ#fcwjkV3o5Qa}Y#yhe|X2vz1Vux%#qv}r+Y0XE=LYr(O*VKu#_$rZ8 z#t>GIoy^XcV%DF9o7)BjAS-4bGpJCJctPmC-NX@BJmgB}kQ-sJ!+rai!mFnkjQnqU zUvnU3SfPOeo!pUzP-rKjzIPM(1Fi{gmD?+O3ES5q|daGNK! zb2+etaW7Z-JA4|SPL_gubi$S6*Uj+^nLkfrY9qtv!#;VQg9+hGdhhVf$L;GzluJFK z_i1m1)v!~Jt))AADybOr{y?9BPNkt(k}Lj1eb)t;?$A>ncE9XQ0A&Qp+@+3ewF%tG zFBp*rBvBI(%`fzHZgNt4ZtsCO=AucG7t`*CF&n6Z4t8U~sQW{xQ)q-6?K8dBXp?<2 zSCd>9^JZvF7$IF+0)W#EDEX$$Iker8g#Q7Vd=W_B^Se?+0xU-R$a;6HL zuFDx&ccX$ds&R<((H|%aTu9(0xMz>D;zP0Zto;;_h8OXy6Aes3D=Ljo-pP*Xd&Z{9aNdsrozieodWo;kHR^CKgeQ@6VUVKH^Bvm9ko+CIC&@Je4L&viOb32J0^&@A=bX%})DfL>(Du3`*oz`IK9Qs0k7qqh`tN9>AuvoEX?hOQMWpp?V&}e(t7cDvZ$Ebh z+qfU2HdYezvk}@7AgE#w@0*le9C`s#lHw_S_m_U!2P>9dEu&pV?%b9a!#h}#k3=bj zJ#5?LJG3k?vbuq8Uv%}0lHgDQ4;J%Ixen0?Ue?0#DDlAm-l9%|XZ4^9qp8%Tk_}B- zc#qBpl+@|ib-TSDOhRz)_4VfxFT2tlaM4XYtbON7P%U6XBQI$53vuUzS}BQ zUB)t|%9y3xZ9i??Y{EkEN_Pxg2X|x2RKiFp?r2vdownHEhRmUx#2K~VfDckmnZ1lJ zyu)vJUobE5N3I(urJ2tCkQH=X*gUJbWZTJhaQZbEy9xgrZZy{248u36plcZC%h?AP z5^l*qkxstC{9HgAb@NV=Ea<0I>))sqzSK!<|3i&4m9S4JPK`H2cL2ewIeHPSK+G8| z(C5#g$HlQBM02@VT$x}B<#Hfi96J&3aF&)#ZM`U!Uof~qR+`Gh+{QB=uOPwNsypNt z5Icsg0X&M5gQh&Fc6jInmi0AU<|Nw*v&F5_{vLyV{hIz3*uO$P%nI=nBpd~DwRTCO z4!RD2Z44_Hk|k_zOJ{|((H^b)E*E!UA?O-VS5j=ogS=poY++jvXvt$gK9VR_fL`D^ zAG1}@(3FDasn#N-CPZh2h2I#c6N$5G=E8CI4om!0I+04)=-wymQY3UW72+&xIb^O{ z`rvlE?&b6@mSV`%$B!Y!mPM4CWMwsg*V)%07v_nGe=TI_dFh7P!ntwrGuM)gmmanX z5xXe%fuHkFg~&<6G{GuaCJ+TcIQpEvm+%}l%=JoWCk zkw3%f2@l{?f6Vd(hXh{@SWc44b`qdCQ^0JRQ#sI<`(+LbzKTH)T^bS;D^hYIvWTC3 z!K!y(-R6$MC%0Egdyl1Zs%P=Ti*YP|yvs^9`i|i<_1iUIBGQ{BQdpe_v8W^2V&2?Ub)gZy_1$M=nw8Knwcl||j5J8;7fFqD z0r!sqAHN7izf>vdK{ZzydmmY^zh_`8G&kO$J(A;_U1jkG+sc~Cq5)s1S9GlTI&tZN z1s8=;13Ss$+)s8-CG@f~naVnnp(U6AGr`j8h7_}2WBJmXl>G08;GIk1yj8E?;}NrR zw`cT#B~m`omddt9{ubSb*~GPZbK14*vQZJsU2*F4lJx<6xb2ZU+{fJQ@|?b&Upj=B zYl`)ef2(Ya`@&HlcqBt^AW}#SuU_?Rw$E(rZC>;f+sjJ1f5pDBqcQH>ukea2mjnH= z#u2I3yAtH(3Je*L^!T1Or`BB{m`0_asDh&_1jWl9ORW7x(cL%WySQ7!WnD(&PpK#Zu(a5kW8Y5()yu@u=6{u-=2$rJJw;OORpnw&XxuQf-i< z_oT)y$D8`O1z|#kI+|Uo4$R+BOE2aHtjRMk(BeyP&tn_uhoZM{c3}FrOxeoqV3DVk z1~|NAYauVJ+;#DRF3`@4q_hqqRjO;m)B290&f?Bc&Y(ZISF-t-=g49dqa%QH4Nw>S z^t(jV_TsWnN7R>p$%t^@kkabK(&2Bv2qii`oiX&;U{3V47cG!~nkOAk5qW(OnT@~~ zmzAeNFIA{Y#TS2`MhOQw5#mur=Q(UiLo_F`PN2xHE)Tjfek`#;X$kl3*>(#QtG&Yt z`ykuTbZy4wJD*!R<{45DRyf15O&Rx1+&= z5@!^-8lo>si~PDiIFbsSU3U_~F_=YZ-sLlq0?a78mcBz- zBjS-G<%^}`J9yMAsNXQ8A_!)8HX$@rr1>#6rFza-OClplQaha+eHquWp?ydw7&4#C zKhq=ES^iyqjL>J~IQrTd4Y^kEA19e2eAYGk5X4FaZCu4W--fJim;Wu zIUYrt==F{R`I0u_VC(?DST)X&)+@C}FGcw-=Ca=w z;`(mSBbrI~XsL*Tx!zB8&ZSOl@N?Kx?fd{qznhHlpED|fQse7m>8Ovt8c)T>1-21q z=iA--YnS6CZdJNP9Ct8GSdVm#+kj1|P!`L3N#3&O58Lygc>`JXMFQ8PQB%*$iJe5d zPMa0a1!ro}?uuv4xLbr}Kn-wO)v?HQMTQweKOF(~BG3PvQn#qT$ZcZ&G<}UB7@##= zCqfm_8sp^K4thY2SL4%>)K!Q@uYC z&9M#^a&d;*&eCw^vYoN@rp8VAJ2$QamH2ZUX1EE$|Lj`1hpC;*j2!lQfYbwzk)fqw z_0bPSU#K@(VK(MesW4KV9W{lu;gqyN5^>~W$6i>TAx3}QCl4jyHI`sIh`^#F} zPi9VB@rzUX3pTk5>{Al)?w&Oe|NO z@kQs-?WX9NWGrr?(=;^dZkHNUibENVMDmWf18`ZueC`Q7K{yWaBn#T2CK+JK>~LEf z9*^r_!M!82rO-#iAY>iScRA{tjluuEDWoz)yOdlDS}M>Nsp)0w$&Yr!evdAYa1{AX zXyW&B6*aozfm;^QQDE1z59G?xclp4VG1R@y&~oOp6t<~GE|$jC19#$Pwk5A80>8Zc z>pfon;lt$&_xv49?^Q2as99H`h-Gx?=U)Ox44CpSG65 zm0(+V!pdFF!|uM&y?spZyszZGHd5bjhxhx!q>rkXRM1Rw7yS1PM!VQ{7yV}Xg8(xo zUy=}E@j)nI*E7RZZ*3sq8)D@w2_}bv=w7(qa&r42lE-XI5+kmgA$za*Gb?6zZumi< zVe#Dt5HhH{H^;~;yx{+$Jjb&9P5`19qW@No|1BD9SgKK7Mi@3XHZEW{<>4cYLd703{4FXx z)C&E=?FXJ{=$o$(1TyuUQ|(YeTSX#|UxB4?2pKStH9MqtB=C*byTjRClLt~S?p8%% zPMJuUN_81^L@1J>IoU)GH3H7#t2N`da!=}O%#*rl6%tK#E`j=w-gx{Xz>Ap5sD~)R z5sIx{IAf=K3a9uLPwn_M@gHcZ=8~RI2z|=_fBPG^8cjSe z8(x~cA$He{*~x;xyAc0jaqct?)RgP7Pyz(u?W^6(iL(~1_-DrEas9rKc~n;?i1gz% z`9j_XBNj?=&!cdJWMqe0nWn%3_*~88#}C$y>)kjPY9&9_s_X_w8TO|cwoyE0eKk3l zJ`>#ka|4d%)6UnGj--j=S*|FUY^v!;PgR@xFfrKwf=c6DPCB+00N^5Yo3XHl+D|Y! z#vR8PB_O`?On#~AMA?dTI*=w=jLX^P9?PExq$nf8TYMiSU21xhHPHjXPGxcAYYE< zd{+z6h1Jer-`Hc`H$hV_*Fs6h!H->uCyCtCbML%0s!W27<;dm56FJ;h5c!U#Njj?3H>%xg;re}EYp{5@JvD3OhGeu!QGucu%KA&dlpnVf0SybGO!T32^+`@5?YW z!2U3sFaI&+Q~$gKIJTMvbEHDxVJ1|N0nvWtN&=HxW8;#qBwem#nxrbHu=kY7MB~t_ z9%o{pNF;Jmu{0mNY7ge`9Zj^H%3IZzNWv4W_3M=Y(N(~Y>yv)&1Kfe(B+`xb4SV|W z3f}1UcV}wCNTF-_V@ie)Ed~IRbr&)x5X6X{p zN4U@5B#Hcqp^*3go9U3pnxfeA#VG#~*UBG1V9%PDY|cN{JG;b~@_4%~!NB0KSE? zKf%8*IZM`^XqSHV8uWhBp6RE^p@b*h9@1x#>${y~nd{y5GR4BY$tM5SE9BDQN6ZrCk5hAL zKt>x^S_bTLaR86ReLYPi2}4gs5ZXRZciWuz<_Jg4Lg{b;i}MArvY3HKrjR{B&mO63_@7}eDJ#szxd9!R<0x1?<{|^E?RUye50cT zNLI23>);zE3>add$Vhe7Fm%&12JK8t^Upp@lKzzx1v^eMn$L-yK>1 zXR4(U`&re!#ja5XoY?cF@A)v7o5;c*@}4kU-UeZ)5*$Z;sKypG?;hZ>Mwt8qvK!)P(NH}s&D~Mipi#vPrE?rv}edmlNMH7WC zK?#)Ufh>2FY56&^jFe#pg8>e48!p% z1Vrh7kIGY~!q|JxWIi4Z|KMVmf24`0;%xl&ECjeC^PKt#f#W9XApW0E!`sK+WLAqb z?zsN2kKpzmH8hT2vwGXYy!KfU(&+wD9KQ;gb(Kq063ZsTYKIMu-3J+Tx-zPHqo2y{jx@TfT z0R3^d{(^Gm(mP%Q=*!a%R>kF;5{KuAC%)mLNJ?ioV*uA}u(g$4ruCmLy+Sp+Lo3 z$pCOd_OU_uDE*vo(~DCXzqgo&T#g6FmUqZdeY*N4smP609=`w@Bz(fz`sn#RdIep|CE_yrZL^4GNG2ccwu zkpr;*$GK@gkdxkMaH9oNKk4Sp?$!Pse51F-AM{`sJ*Yu=Wa50iCAEJK@8IsrVm|Qa z0Rnnq?8>+E6C!W3#_Rj$)m|0r{+QLKw!ioQyRoRLb&cRjq~5A1!>Spj7^RuCf;qJ!2o_T@9Z%7iVdMmxTREF9fwT)oud8l*8c{@ zkVPuj#95uo{%)fKd-F?Wop2rIZ=tqlq^j^@Y1&1kasDbg51AN^>|$N<&^GnK@~7tB zqFB|jIp>j(39E1#PY}1YDv%RP$DE32%PRqgr{5+r=8pBViQ0HX>BwuA_5xPuLlORb zKs$0qY@eTyBd)*Lt%WB_m$%=j46)pZ{~))TvIJ*iL?z?zvr zP?`|nEoJNX8&$RJ;9#G$8^m3g$ahtUMbiAj!0!nDlYm$EoX5@Yn)KGMgdegbkTD&RO?;Hh&9`2w>)n%$oFj=!T>1ov+Lr#o9Zj-`#k21`^OnuEe`C}5zB&hf9_Zr&d z8>g@3f_MVl*7W`D4IDPh@A%O*He=!I*%8whYyfalpS8U z-^SIr+wwU)q=Z`$)woh2n`1_+I~KLBxWEaG890GdMy9f!d}=P3-4h4MM$qlPzE!wO z19XOBy~($zCNOY9-npi@JIi@-&qu6~utkvA@+`RXXtH!}uPO_^G5kivUG0IMFDvwJ z$$}nhq4p+Z08A=kM~=)}NG*ab6mV-G)G-S46LFy=5uF|bs`)#(GocMO(<4-E%;?I=I}1R?~-mY7Nl11KcTRRO?th`|D!`p7Z0toF8N2g-A=_L%z5)&2CB0 z3(ntee3d>j=s<4>6lHf)rB^s zlBWttDZkvUO@JL#jL+u>fT~ayb3?ZIt|Bc|_wk5oqV8R%&ln`lD6UTEka!*8V?|ej zZ-~iAEK?cX`Z9HH`AR)Qqe~v&>L`QEKAzC%bf>Iv9caD#0^w5Bp>wtwjE2$WYDAn^ zQuRhJ6<}5tC~1foz5B+-1t^?j?o2UZgMz_>umc6O?AFRL1x90P>7<>LO zJ6B9;gQXNh`jSBiyl=Ej#kv*L7~&LilmeHdFH`!AeGZZ_9;iRGco9RWTH@fQ{2c9Q z5ZTUmXMfJ*3Md3^`F;9tHWD{&6$qoU*O{EB;A0eq)TWZ#CUS!E-l7b^#w|v73^6|A z7jofep7rhn^<^LRhi|MUZ`n&=JIhhF~cMt{AzfE6@v&(Z^499#sZB)rlQ&zQMl9N>Rqofgw#dhRB(Xd&VCE|UPAjBjva8N5%>p)lOK zR}m$Y@{-if!sqW@&(|b8cb((b?7~$TDQn=sXcI197;j=MG*x^MyM5!AmwEFp0Rz#7 zkWNRa-O@3ndtYcOeuN46klEZK_Lkt#p`UI&7(!jDLShjuR=z~1=OG~-K}kM|o}1SZ zq*&&;+C8*ETkd^XzW~W14t?eq_RzkgXl@c{*%cheb*Ybr!8c2%t;HgNIT=a^11Y6A zj*4Zc=?*5#Ve5l-p)TmJZUJ_nyRWWts!+0sBMF(%$hsJNZ&X`Y^ywr%cTFDtfQ+A> z^1+bE-Rt5&D;AyZeQJ7}l%ia=F`6+`DI%nnTe@1xwMulqR%d6S)}3VmSWujGIH34< zg?w?Bjq|!)tmt>nv14l=lq!{QPr~q8j31*h=^{#cYL|B|X~WJ2KZz}IuU57>8?{UK zr0euxN&UssZu^ZTO5ZMXtpF?mWZrRg0oMGwEfDt{Gt=}RHfY^9AqJUB+BxwY*HyQ7 zh%|0v^Li!M*zmuUd)ODwSj5h&Zj0Y&$&=Zj?h!phIF5reWOtGt8>C8h2$5KGR@RkH z$b9XzfoQ=MeAFqYnDVio&-+Bc1Y&37{HH7c9MG_NLC8XWokdfksrKX{5sG>i@XyD4jDkX_FLFt5P1CthfT&4fkNr zP&8|<@J$Re+GJmsn5v@!4J zWsA5Ed;IFALd2&uf6rRc2sr#{w9Z(i0P5N+2ExeZWlgq|7`0PGb^|4b;1m9v8|6+y z=cz&G%(f|x_n|A`)8uZJ2C_Q-JIAeiHMf^Ly$O%=%zu9(o~4i;=->~57t8)CVDS^i zybYnk04fRDFUc3H$6c6?CHx*xD3Iefvsvty_gUZF@v}x=fED|ex>@W{+47;>gV>gk zbiR!Rzx-L+wV}uQ`{;9gNpC0&3oQd>Cp0`KwF{v;-29JDi`d7l@8YSUvCXjdX^U_j zrQeA)2HUP5jZ9Ev!hG;0)9E?<(%)Hf}}mU;Wqq~ z)MP!sY&f~|>jrkft#S7~dIr+`HgL|x=!w?-g^IfYhg~Mo+QsAZ1X55AE%ffl;%DZ% zB}!3YKr#ElX{jOZ86Hjzl=7Q2fU5A~S@6P{L8DU{Dii>zpvP)!zBf1Wdtb(?vS|a6 zH*a0|d)>F%!rz}hZv(T1fEhCDfYEz*sY~_9`=rI9gKMK${$7?c0>4YN*P0o2&(R&z zMtn(MXX};trD!13*finAoK55L=Yxe0^*h7du81}Z80-Zu@T)Qr0ep)7Q+l0dK!-_~ zzi(F9rrKEe2V} zBAx3Zv>@&nq^HEMydy(2gYM7uD7QNR&xZ5s^Jng;tmGGPvq1g zN@RMUBF6=y!TT>Nf8sSuLVt{sp;hxbmM?W1e~+mEtRSx5g{3lx72-K;ba0wEzjK-Q z5UP@kmzzKy{Q2B{50vT!0#dsyX$Y;*whK`9HECby+IQLK*I&V!by+f%(JyG3z#az( z;)Aq0n#FceA^|EBw)NOPGD*#DlAb9D5**RI;Kr=L*gX0rTK&KROO=w14fXFtZ4 zGw?Q#x9_A2BqO_tdiRqn43rB$P?<)N5OQb-R`3yO;PLuNpSiX5H^m5roX>{^e$31F zL-Hx5VHGf7GX+uT_7L;y!+)W3>T%ldhBO#?Qj5*AA81MgQ>|}|6`{wJ#aHHsuJ9jE=Ko^X95O&uT~xV|h{_I^ zRLC_+Pt6sO2r{ndO+K1r-Q{PM!%_DT!2I1>wc(^)pf6mibqlRbpa&F2<;_Cp^7b_9 zGrN$EE|SR10X75o0_~w)XNZ(r+L2ctMZC(bSo+N*AW;mP&zrX*KQK5=ds0>}j>Y^S zL;a-+!(sdUK>d`c+i;4HJd99_3)G*nL)ctm)YLViq ziI?mQ3!r0?ven6fI`7tohWmTBmu&RO-6t_)*%`7nl}H%e8Jk!R;G#kgfn-J|4@e6 z68a}xtxYrt5k=kR#P0RZ4Hd=p)rG9v>WD14MxUQ||0eGJBkcB&Ds?n0pn*U%tm}-wD85u9M7TPx#w9FbO?+ukPZ zCPFcmB+qSl(SwH0T~^Gt%ksi%^QS4zH6X8V^NL zQ5fD18RKze0^-WN)g15QAL3bN3wlRU#w^o#W(B=Hfzkm4?7zoJ( zW==4LohxN9K+IWvr{LT1_7(28O(2_4Qy|qunef-Mj?-(U#t@39H7I!l8r5ktSl1}K zEguydx5V9VMYXQOCzJ;L1$&?#6S=r7!U<= zc4ZS)C53=-7u%jJLOq9f1PL{OBeM9x8r{A6UNTDnGTnA`In$|?Zt?@ErduefWy3iE zWs>0ujXO!5c`U~6ZFeEPZ@wJ_j3;zM^)X(kmQ@$S?vqGlc+Fh?){5WXUrETaMv)6$ zg0G)L8-QXsa`6GQfK>_O51w9RqOxg~ysDA2i7mVQSaN-Hfdw+V1r7Uy zOjSQ!Oxr0G8*M8?W7(Pm)|tY__3*pqF#x+CW9No)I{4L)h-JEcylF*or9bFxM8r2= z8AZ`OpbD=eJ{DivlEbMaX7;Gg5G3-D3@Bn64eGq~M)c3SmBRu+TpZZzwcL^%S z!vil|ETLi|6Rp&y?#kQ#2~`IF-A@jA)+1?hH6Dg5t=fy@zmy0sa7 z_d~yrmfbu8n9HOJiutNo0C(j8NRuqG;MjxbgA+BZ5a1IBSjhohE$xtk1xiU~@`N48 z+aj{W0hD}0K`1N>q8V|$phb8l`jQVA6>@`$qVl^RGF6gJkTm6|Kl&SDkr!&XmR=8& zBhk^QN7GSb*vTlEoH!|STrz)7_bry&%l_E%=Ah0pm`;S-kwu^E<_P6l4C!Htlu3** zOm`k0h~$*26?uVfj=XCdFrRHXecZFn$Lcf_;QeVU;8jC33VCGZ%BARDE;3*C{imNU zZ1c*;8d7eq!q5a@q^Oi^=}Lorc_iZ&nfO79=={NLSf@bTpKQ@SRP^r>aJ10|muxas zWH-YC93fIcPpb*sA7%EQ@wuiLkF|6p;B#cO33T6J()b>g6otMC*B0h-2VXoy`~qrc zTrnqp&njq(ibMgr5cF8w_`if1(#&B`>?Qs&G|*auBulI$!3lTi<=R3?8L*T3f4g6# z>R|K8!1W?4V_C4t8fu@+ITRvyTWQaOBKayho;-Odx*UpLG6poRLC>P|`8>J`7AbJx z=FD!{N5Bh(?``cS2=)68u3j{mjaV! zhY-#sY#oOq%>Scaiuz3Nb!COQREZ-YN05|S+Ohwr@(k_!J0P@h#Ot(&3Vf-dRYQS5 zJ9F9goZ)tG{tKK4FafY{vY0`2ahzxp#9^p0gf!fy1yuI@-6#;;!}w_bI!Z3>Dr?+5 zqM~4k|f?9t2_d*zLGasshUnR?a#KDpwDG*7JK$-^YUbmP_0+h193ej1mnaoWE88{VYey z*+PexWato52U>7yMV{W+HVcq!^PL(IML$nUK8XjQPpGrX?W=j}!5WWVvMcgaEUA8` zMv3rn5DR5VEqRrn_ZzKV1SrX=j2zKysKK|%4*|nw(Vyd{*}pN|=qvn*K++~}s@j@Y zo6wo@RGVmP*pkY=M|FMa1wGjQavqAVQ6tVRxVG~Ab=Y|dpu8@Cbm4l4ZEy6 zVH@OI-$|${9=h@X?^Po%`+j!%@{BLUz8>(+V8%*6V3Onf*0ap9uk!c29gFPssD^Kn zr`{!-WPo!($Hmvi8v*Wj1<)(H*F{q3kGAo1k~yKz#b@bJ!{=R%_@M@;WuJJ$6D9I1S z38fr(dFFvVkQT9O^eqQ-2+&cG&8@+Vd?Sk#pY*fCfOJK#oGoIMWeDCi*3X{SsA+}PEP8HOR1ngY9CwK(Z)1q; zg;k2KlTlMb<7!e@g{5QKGF6)@Ys8Lc2@U#p6ISuH5!#-vxI~OT4WLeJK;2*EouMj@QCGGFON^kJ(y5umQWz#@_$sAPXcnE$-cP)i6_nHrD4V-U&m~^y2dm7US7w zZ(wHYI%CkjdHCi&Y9~XFkvta~yuMJ{BLaYwG>`+$ef=Y$4nY}2s7dXJ$JM4%PZP+- zX=}{lk$n`)fTN?4bp~kPK#z$iAf(;jZLf1RcVkW2^PB_C>P=Yp-V;k-gZorecO+KehvkSX7&F0#@a z{rdBZ{VK_!v%waEzN*%juB}UvmZwQhO^DUwB$Uf4>`QcZ8I0^K(&K7IM51RA{p$w+ zflZgCZ#>k@b!`jDI*Ah=S_t~Gy)Y}6ANF)?qzeUPe`1+rR}0)Z#tGXzzv}E+?;h53 z99Kj(y83k$Ii?L;*aoLs0T>u$eN{%9ld(&fzEx6{lwng7+)|J-dT7?#9+lZ&JQ~s}hcHz`s25 z?>dh0f7CIYcDv$#da*Y$X!MBX_a&JywIax)9Cjf;y z*c#9VasM~ua+B4{3{xt?E5?5$VEKwH!5zzv|~C<`S6e8`07^8;KZ$y%RM0|6c# z!J0Te-6lrK)#05>UDVat@G^jm7jU_9Jy$v-$>yKPKm^P>B^PdVHe*~WZD41WzK66Y zUblN>zig$p=>w{o5*Fn3_>YS&{$y_)c4`0ny+IbY=!C{MCY+HbY<|qe+m2IJ7JH>* zdLy-oOxSsEsCD`vJG(%j4P@)9y}HuFscqx26BbBo#9eOm)JlX;KL>MqT0F^TsmGCTM{^)7Ylwy zI!c8BJ(JxfjuEr3lUf;!z* zthdGym@VFGowAcqx(?}d{?k+C%pab(=b-!wX*Ve>lyC-ltwXo}#e;_b0(nJ1WzXpm zjAc(Q&ECfVx1yJ3E$SE+F!tE0OLl5_5yfT3RkR?T*x0GrXk8;C@o6WN9ocaSp?YXN zAp7kF-gJ%<1BX+?a&QQz|DMN|r6bq$cBv%C{pWy@**qZ7#@jhDR4xMTEET5W6(tEJ z_L_2Wb4T&hS?n>&Hw>(B3qW7^&U#;O#n3kL;;nJzjw~q zKqP>Wzb1^UZX#P-Sj-)*43P)Hf~{GFC@F|aRp$?QWInWSg~7dcPqPD!c$b0>$tNEM zw7-PB{8`@|Jwq3b*Ml&34oRx;Th+2Rreo;_5b%+_`>rTY1q{+xRN{B!5jW9&$?34y zpPOX*u6sRSAWfwNDlh?NWL}QkW`Cz}7ss4>&&Qf5@|Z&Mi))y>=~^>3YfY9L8#8-M zAYYUBRpBV^r5WfuDQ{Ddea|QNOB^&68P~>pxy#`M&%1cooS|rs!r-mfMOEs4-vijJ zV7OYP{hnv1K6kxT3ceGPdEf~FJ5CN;4PqD<3~-q0IiT?!U?pZPPu&*N>x(yy@(Y$YL{*;v93DVbO2}p?89ewK}(xb=uVVP zyIM5wA6kLr^{V=?)~Xp;EJU*Zx?=_3lBj`Te(RSG&AO*0uo2L7r9Xny#FcH& z7^4IQ*`M-^jIb6mQy&3vYi)(lm}AGVD|cICog69%zU4sOnofk$tWu z?OUVyn@~lAQq1xIo)y*Ce%;sM=a8V&?nD zjBrkuzR4?SGRZW>-E;4^;r;3FRnO%rk86ifLJf3)+0( z%dB*i_DW&h%J2(i%l%f#wz=Cj7!#YCzhB;S?Ajf4{nl*v12x++-PpmuKMN+WXLVKU z*{{YzmZap9?$bD_DHSj}bdP0r<(dz!Y?m^daM(=5c#UU;bsb%gnA>Xz#w^1orGa^; zM2J*;)c2Dtc0|Sy{P|m*1uHHiBHj3d0iSfcs|Q^N4m$BAC(v9KDB0%TKFakGt^8fO zA3-mK=>y9Ghj?eNCfPT1EbB^G=Wpw#BwjPG&81)R&9j2*kau%6OW^H6X;%)Brz1Vc{ggHFaF( zN1Fv@5+nLmydG%p-p-q+z6A#R&PcVbM|;oB7-TZ_6~S*pYm_jR3`El$Xkht_-vl@m zyR~5IAf4go9o)%<$Unqx`)HzQq`^f^Z^ry_ly6lSUvH~ANi%TB8C^8|5Hpx|%Ul}( zI=)6B?& z${8Q{okwoBl@p^^lMXJ;)lUQI50%e%vqNLB5b>~irkr78i0>4}@y0u^<=`Zl3OfYLu_MJ=hZ+aO~per?&M zNX4M|A=aDAHEL+5=_<`jvff`m3#V_?wcdrepZ`X%1oX-5(V75)f%Qbk9^to%1$mc5 zz*Ar!sPTX-8448IC?RikF;qHCvrtlUNXvzi#uB}}BpI4=OM|c*`$-T5D+wzXW`)js z^Q;XobqOo(wZgB9WE6wCmP`RZn$${b#0sesG2d z#d2|7Vx+3^6LCoaYz= znmC^bSY!$Zx8snZD2f$^KQOlER7kW^GI`5vyGDu0(S5!Us1X<{5QA&GCz}>mM*H-s z>V9qHvgRI`>u_Av;B?X!(Pk*74D}f*&rKArczI;h%a^}pkv&C}v(wWcDemNC6mXR{ zy?<;|!cV)(v57QAe~O79w|w1MrFh?7e!TcUJiTRDU0u<A)~QcPLJAcXyZK&c@x{ zi@UoPZ-L^)-Cc{jyStyo{XXCMRjyup?=@FuW-^kQWb`v6kk;A>a2^R5!n6=LuBiKk z7=_3Lyj}|oKi;2^=Y-uCN5uOahbC}1O>s807vxH+LPz4DvX>ki^a0#CNCRYKXTR+> ze|eeMYI&HHH^`-2zgrQxU*T~cra$ek7qqxz+w$PsJ|o9?ki@`=1i zHl^q+_7v1*f5(2b#FU?tD^Y2owhua%c9&VUB}uU&XqmwGg073b!oKvWk@qOcW{xVA z|9XV-3N#NYy&wUvPB!M|F7!%^$VMj@WDgLam0DEDqNQ2-+FvLa3eK=%597_R%}WXm zkA4}iW724@j{@-)hMh}rg(h|40DIVE7(gat)eMuJmrXueMy0*x)}NCAS7ktVGN*bc z6~d}YQL5(i5{g|F@-2_k=sE1tQnO~YLZ&^!Li);!6_gg5Pa^?wh_#*M*8V)PDMIGaq+1bnyE1ign7j3D*jZ}p zHPs1ibr3~_*W!WSi5lH=vpJBAsK2Vvaz5Q_=+ZF!qE0q7EVFr2#V^!emRdZ!wqYmT z-<@@Q4Q?-G@L}ZDeklhv1D)-YOwhj|FjQA`j=ty1A?x(*MzFr7gibx2B&2sjv8$XN zE~vW1`2;Rh+phA$fVh;LOEYx!1GsDLlY*@Bkw>wR3#VJ$P@!RagLaDbU zYLCiEArK*>B*1o(1JlbT47VH}Y#?cA0z2j;v8De>?n0A^=-(Zy?{kLbWyuoWh4y{r zbHp|X@6y6Zm_2094U4(;m7*e=mWnd;YitJ*#B}`#{N9nNHvHha&^w}d|KgzBN;A~E zSBiXNN4d#LR>87JV=UH07NY*SQ0L5QpG^9nZ3u{n1r#gV?L$kyjh}rXE4pncxD4!1 zy`)DL;u3lC1XH`;5w65NCWPh;85U*IuO0NTu&&(R8dTW5cR_Ema}PO5>6<%C(n>M3 z{d0{t>F)bbP{-S?Q-F8)H6_{v5{}OMo60Qg4=eYWG~!C~Oa`@JQS`Gpxji`%={+ct znhF0q#~ei!;avRs-t%e|63-O87<>{VnH+tHmGR=-3FELF2HH(mUG1S@a=rj)_@ra# z^kb$rM=yZ@X5!G|=as?MOpLCtRXZ=-g4*jKQjrN5Xg8V+|X)K9UJga8I z87OqK5P^*w6C}m(-Kml32-W45PMf-@_*Ot0F19_NFaY+r9gB0NziPv-Tl$sjq~`s~ zQL`x~GaBI-A=}7lJokkQHME&)D1(BSZDe?J*CN4)v5N1dU0Q9wAQNRt#jPS?0G{n( zwGKD*=<^YL;n_kU9_%5kZGk!#`U{yv*aJN`v(}37 zL&ALFYPms|dx`C_u(+o6&B9KzUk3N(4i5)~`*w8%;~C z$#EVvHe=c2qw>U6-{1ky*B@fWd?BJS3oL!X^z0(ccV=mdTWR};ja9w})vv4kUjHadps zm!9V1?UM&e^&>E2)%H8+R%1JwDh+4;WvknuosT%qzF#R*Wh9nf=tsX0r9k4ia@b0g zIU_0LEfk}>du`S59Q(ik@z#%!?PK7i0zdSn>wBF>o#_5UsX_iy0#te?PN@y?Ba18D zENG=ZaOl+7B(a&MrI|tuJ|Up9u8=#q38DNwO|!!;N_YL@dE5tukYBI;0zG1{nEEC4 zCHtS!Fh$(qk-x~g{d?>O4=%t>z3p6zkJ5J+j#4|-Eb;9*3uho3(lpzUM2~^@diwO` z>8wlxTbr#=XR4-(Hd2GO|F9%?93Y5GKim8S2uF*Noq*yU3dt81kzi@B%TK{dC;B(B zZRpJ?wi7^;P{Zo&ytsKxBQ|YMb#3Cn4E+6@3k0koK)y|B$g^@Or@E!f)lPT zJtiZo8|}G1Z(IXKQMa!hpX3LaNaQTlNx#uf~2<}@O zD}w1d^yj>31``vG0aFCA-G{d2;U>zP-}>SU7NPJZ*n@9X)>a2(_KUmNOd{~!C2jJL zS_sVe(=QAOl1mNCg=n6C8v4m+r@>KR`hW2Wg(%lQcK>dt(rdu)VE*c~?GX0ktg2`n zFJ@?k>vVd1yNReseY6icQ0?2YuNJ)7n*uH&xN!?emZ;Iu?^}^h16I@w#r7v084=LF ztWF1L*tH<$)r2C0A?6IBHbsU-Nj|lva>+Hhlj=BlAH4Yk?A`Try94n$c$=Jxu~)PvJ#U6^2w}v)FTZA zS?lNU@tv8}Zs=MAlOpHGvvqom=|YQXg2(-$i;L9BS{V5?f?|fmknsB6ruAG%h8HT6 z$bs8nfqBWmzQ%9cK3i6Y55B`^jJ}`ZkSQwP;O*Y1S67f0#c*}k-nm|yaL+h}xmOe( zWrq1Cv`L}fKrP*CZDMhwx)2Jo@yD+qVtiL5_)~bZGdhA}9*nRJj|WZ^>+?~68GWpC zB|Xzpq(KFmjX(Ok84UQ)*>EPAPz%-<&tKd(oIGCN`z0lw3MIqwrqeD@9PD=j?Qg+I zB988yhDQ7)+LKHp76~my448GRexkePeojP8HO=gjq*js7TgZ6GmkCR67q863H0I{9 zb@ZF5W0X^dMecKrEaq}JI1Q_5?1Boz841HUzG0`t|`>hF=kOxKF zHPl{3?MnX%*7jA7cgN@UN133=W#a8e3*whX?225N4!Y3Fz3!~pnlY@9A-}=;cRU)9 zvHp0X(VyP|_ohRCaiHo(0#{^FbW2XZJtLii8=d`7FpHFg9oR{m@J3R`8pfy9fQ!wA zU)3JLZ{vfobyx3=*A3NAiNGpw0+q7(6vL4SrLQZZA1#>;#ayh@`x}J@&XeZH1>GM{ zUox5@@V>F(cVs%dovToh)CK#9&-t}icQUJPSDeD=8^bb@>iF$q*&l7V{JtuP$Oc0z zX(Rfv;C8Dw>))spXrY=X{g)~O4{+z&1TBcCjv!&bhjpB3Ca>5t!^VozAeuE~2;c^`V)np^Hs(MIS$fSb0F5d+bjXXPT3Vv`L_~4W= z=z*_g9#!?ySUc~RSAha{4&#}wTs533sj`a@nuAv(uFU?hT9EW53CWByJO zJ%?Tq2i!ns${7Kth1(_eXfy1RK2#`Ti26jZqdv*y8ZxngCTa)<3z-`QYUpAa`N=R= z$eoA%^JY~mzM6XXBSX(boYlh`0qWBc`^q4)76^TyCNnuQWq3WJ4amUJ;Iz zuH*2{LsY)N|7qJ|qrNYx?}NW2K{)*E6Pw&LH0J+y3bH0jhbRc9>(x}ty6w`W{o|Q> z_BarKjuUrA{EZz=-x-n#O~-|`z~sk3yhw3@Zgc3oVU=v+=!tcHJWRDYx?G>w8K(v& zqV_xmc}Q4X@&Dj5kT!Gg;j==>LJtt&fbKhhBdyB89|0C@Ey?@es@qfh%$^1Bvf@2p+x15IN)bpbA-#6u5Xq?F#kPd0rAl*pxi_Tm$)Ur9WYC6Wm3q&!a z|M6lO7niE~@DS1aL8Sbt%xwWR^mKpM_)eim6^f_}muIK#?t#1FR^F=C@TAr=A*q`< zS+AcWiLGO^CQBguF(q_3&(<9k}iTZg$8rtVdYI2BiSP3DqeXiy?i^~?O;7ZXNK?;c*ol%@WYLuE880aF(_2)(6iW?oOR_d zaXC+aV?41hUMxsm{Ij_D_xs}J5H)6&SYPdkj%>c`6d7gPb8ee+XQ{`XRg;BCgn#Hjse$lsT5 z^}<&|tO$sNWKef@G&{|HI%EUOwIxB+FmO3^gIQd94ThB<5JpG>)k_vyOUGH!GoE?LaaKWPtbkNGf_#@8e9*fYuXW- zd_yLYz3XwOhvp&|uj`1Mj`z;yXgX71;PWl0>twN! z4`)c}=jP(ZTk)=$QSOQ6;-c*1hEEJ0Qxr|CK*bbWF`k_~Jp=#Er;kTM`n_}!zdm0r z*X0flj#}ni@9$kbZO1x1E%<2M>{}xeOvdVWyr#%jx<$sC)Gj`}{NXtE(c{FAG0mRX z6ZQbCb9N&!7m-yNXjtbLjGz$ajRnmn+q`^`a!$N`z931%_8)y9Of)1LK+p`%ZPRiD zZ-1oO4X%ot%#L5h4Ke`6wFpl|`;{DK>_oKkB8>Y<3HJ%|g8NkjRQv%cdJSneUK=&; zLZIMr5yFN>^n=#h8B3wFURz<}WK(t4XQ3s<%C}t;s}eCu zU4IOJng1rBL=NZv00)Z);eKkiXtrdSR;^O;8m+(akFQr!z$j_Q0bP&k+OzNTgKhgx zno8);+rF*U3(nn_o)+n}q=9cv7kxTS3S8mmMfYZ1KOpk7ts3tHo9>|bQ@QZw#HcL} zJzu%65aK5>8@J?OeYBNTI}H3&8leH_{{Hwq0tuf>rIoB~7!9L$`r$-N1Bl!%y$<C5!~n7&&c`#U;RCsy zSaxkvw5WNic)yExD}PtWSvJtZWv<3>@RZCc-m0q4@)XbPma-LZRb%_=BV-ik9dj=> zd3=81$48`;PmQ#v5~adk0IxR6J9e$2we>v0A<09Iw{LuV%%*2<)x$@GhR(JJ?@-7L zS#5uGGSkGoHXSp*AT0Q$p*~y+G*Gd|UttdwV->JBv}+CDHS zUg55bgi6$=K@cnge0>D@MW5e;)U08B3#EiwKV6vXh*(HdIb^z=p@+fTs4 z0B%c3&L|69jTA98SNT5&2oFA-+4KQm0-2Gkn+ARPV&$6c_ww!+DLH z2C!wGzNOZ9^XkH-h9T}aIeZBGxulzF5Imh}YpCFu5#e8(jwPG+81_10Tcog4QefsC zc{Wpee%e&P_{$9Rlzu@G3*;X3?v-PDLQvj2=oG3Nr+g&26pa~3h8E1!L1BYFCF!=d zg~e};4C7A}r62z^Bmg@ACewev;c&4|WL$B70(!ki2!j(wITS-#oac`?_2&&=d1X678sgK9Gq^3br zxBX)na$651GWLgD*lO3IT2$;ra2d0&1_E-paN37Za~tl9A>b?k|o$3iTyIkV(}lN7t=O$rbnN0rmY2)u)P z&rY|H%^aINc0+pK9F+kq;M}g~T|$&Ol5!^GY^tiQ7aI`x-qTW}ZzkN=zL|Z5&!+=n zOh&&eel5_7^qJNwtLlxzA+0H>$s;}!`hH$pS@k3ECrHEIAk(>Ed{>z}R z88i)eLV?O^hT;*=}J=c}(F+Kr><}F&& zzFHA>yxx$mKHru!ia_&w?wV*dSjkih1wH~k#A3Fd?llCy@6g#W4Om>5!n${)>PQMI zLa4{?ROsd29<%k0d23VC&R~rGbnCagA`t|;ee&gk32^AG}cMWZ6S*b>o zI|`iHgz3fwiZei-=1T99iI7>r@|szx$?eBaI&dnpEdTBD`}0dWg3^T&7sED^f)d-u`LLs`(PWMSAs+S1$JgoV8jo)zqjaSJiX(Ty14D+EM19Ef_*GA*^;(MCWH=1vY*3}!%O%K=e zhYQxO&9|r8ErNjAC+c`XUH87=eU>@`wuUN{ZI+#L)rd+&m%m}Tv`3P;Z%jdt<#G)kM5N8>PV zk13>oY06NO1qPzBEa~7hUVQ5J`c%N zBQs${%-IQ>r+tsP?+@J7>UMB{_73a+{>slP3g6~k|8j<8$KCqpjKzMt3oqw=Zqfc# zD1mbwm0x5Y(hsD!m@Dk zo_r{ZQOvf&DN!QDHCfFNvG5%kw_~|dTDyhYz3&NF<&09}ThI`L*`K+YYiiP7rr~aI zIm2|tW5^7#0f#v}mvXW0b(XI@q4(LFpRj4u(-Vm>YRt5xxHKVioU2SpQl1ufw_B<~ z`CkR!Wt#UxT8I>_B|sQHWnXyLqua3f@Q|G9vAY=x0|oAUvX&i5xjM9=RDik`_4U1N z-Zx0R{ z4DTR$+>I}5Hn}qa(Fr2oDg1cr6E5J$hW#o!Feex8!$_-mvSpu-;BvB@@g%YwFiHEP zHh)-Ekg@P&s`c4uGTYIc;{yK=Wv1hSu$HAWmzs33Fvd}1IfVM@tm)nwY`XE!k;qddbF>{3~w$QZ>`TS@0|C|eny&@`W?^o?=AQAKy-udb}|^; zur_XMG+>AgRc)SRM%0*#r00(4Cx<}PdVz1I=R{D@f4)A5h8iAZ1(~a4_II#bcs>J> zFfCW%G28Q?fZW1Ue5#vkHze(Zmj!I&fkjrHQOu^GeNae+h8S=7G4F zDy#fy!QFDw&a>`!#kB78g3_1Goo9io%t>d@!EeOq!O^OP8W3;TY=>Dg!rG8`xDQYQ!jEnC19$alcvu0AXyVijnD3{5Sjj8|xkqN$W~m1H6BKNRn3=(nWKuX*JxUij$=;6vnMq(DUlQ z!PmY$&U2V28pL0)+O%Wg$31d-rs<4?^yXU>cfd7U^!C#|prg)^n z>#2b+C8b%25x92aw)UI>`D7HoZ#xb*SD@WI!$Q6A`aF|uU2|b1Ob@7adULW<7s@^V=uBY zOq|5~>8Z^7Ztqyf{@4Z{n?38wrKt6O#c2lvGXQE9W0%)wfQ%J^@X>%7h~q}nFKIfw zU)caW{{aPV2okZYC$P^v4>9&eACe_(A2FYD19Xb2M6K9fSu=kr(!rkD--&it|K zj%Z%8X`eFslaK^93e@%YYFf_o=6~wC-&RX_9K}f89L(qD-<^hw6#(gsri*&19gKRz zhU#tXn*E&H?uQ+ZhCB;I+OjvSN(;e~oIZTdUN-ZLmuh%?rhpf)tSOq4_ zm(TD$8?pMndxN#(@{OjVRfH~gP0>#mX(2+HcLZT#1-(YeSw5?`fZI33r2x)SpStQ} z>|1@qXMI)j5`6~@%|(){CD)@?v3)mA-O+5WK!IYp?T~@opQWv>cXq?9@XosX`tR-G zMR0FhT~-w&fZ1TFXwCr8;R;TA_(b|C(#JTCJ~fdUGX0XG+VUg5c3ofk+08FHuD?(I zHZ3I3GXptlfXKsOe)au;^DGL!*zcJR*u>=OP(twzVv&Q%zj!8AGT-&UWUkPfZx3a5 zpO^tqn(cK5%)!#{Je&MRqd5l6(B5fg*9IFVLB4VAu;DOZltIB#^47UL!H;L1aT z#b9_2K?#l`eb4l|;o=2#7VBU$jFt$} zGprwwsr6;B=b%}9_v!X8F$aJ-JD$&q_Wgh0JB@e1Ja~V&C1S6$Yz>o`%Xz!nhu0FK zrsrLC96-SXdU?kae=jz(u3 zym(29#l?d@DhX4zfD8;>3rNJChn9o_ihYRTz4e}B32;Y zowmPvKW88m5OM>N+}^(t`jX~+a2CRnMkC57cl?r(;NoNE5YKxtk@*^?@~bD2ny)2{ zJjCqAtq>sy1FUjeQ_+;FN6qq7$QuI_0^83D{9T*&25#Kx98MH1=PeBFrPT6mH;y?i z?|S1IRSY=kn!Vc&h`eX+Pw;EWrB{v>UOP-@?I);f-cR4MMoL=6u6-v(dEX#;1 zXf$UIJOPvSXQ`f?hBDNhRt+zv!~z#EA!BM_a9;^y0h~Y}zLh?H?bfgYP+PF`CU5SO!dcg0pQ(-h7TCMqh|h9l#9xn4D%< zQs8t(e2|g-c>F#vT^bvfXjI($dHWJZ;S+Hi_$rsK6(2}X?6IS>HphaS67d3!-#C~)S!&rd~d$wb_Oo!aj4~qh%MOH>;gnc05l=C^-o8J zC5#Pq=N*seo2FZ_ZP@;*#7Rm_VT`z=MSvKp(_jLiJ|+ZZ;mewuUm6WD>%LF%tM_=Z zq{OT>HMK)ls)PAWPM50cEO%8sfc~~#4fcGP{TS|J{2Ip^kJs>lYFf0G9w}PfJOCSL z)En>%b>y}NfCF0u`O~IE{&!P3OJ$15tS918fgK}KFKgnK$S^pdE;_aiWRG?`i}sw^ zqc5A#DWjPK%QJp?`86T=t=6{fH>j4>G*ICwjh9rCuF1eSg@%v2MrWzgsKZ#l=N) z*h-T+d9XkgVwg(Wi8b%+68_ix zocn^i@k4GK?z(-zeCy3g3$gom_QGRUB4Ke9aQIQmlYI#D1>3d-qtCzNkGaiks@<~rPxX?zFV(@sna z;H4W^2;1Mynaffcw!>J)yBXn2hlj%kwv+y7_7Gs{^@cHRSJD0!2Vsko%!}qo&oCDD zo?`aGMsN^Em}p^(XKBz8L1myRrh*%Ww2>yKKj0w9a(U91V;@{-j2$HE1>Ql4?&SITW!wn)AlO z2MxdTtRMhx(0{+qycZ|p(6kEM#TNA8R)0UAh)wR70CyKR2Lk?@$|d0Tx8EqYh6W3r zXQ@{Rk)U(kQA0q;(l?PByl#j%dJLBuQGg9A_Tvfe@`~DuqN&^~_RH?EFp@}2OdTjS z8Tkm37i~rt=rkVdCnu{97khCJRCGhxMlj>%Nuw&3s~2r(GX-+L5w#9@aIDF8?kB#) z8t>AKkPt@Z9eZ{!=c6Em{w^;k#)rA;tFvf*xgcG6=v6j0_3(J^P(XtXPIvE?`uxg2 zDykP*YytTBt6rN1MuP==D0m`bLQdTQ*3qSX@p+eu*7F|-6nS>?s#J0_fEr}E4T@6F zrve$FweB$P>wV`YjcRk0MEVy2)(-%X^Rv;Y#M5vwGjZhotR+)H&nsD1;&ce(e(imN z4=F{=)t3HV#{(xc+n3@8MQ_lUZHe=&^tgaA$!jRWem`Xn#msS$^;m`$!{*&EBC((> znwpwSO@)P&rczH*(9-F{8c?)j6D2ZH=yTUzH$pg&kx`lU_s(_h$&buXw94W(ILtyQ zq`<#gSHHw%&mNxT#}diB_n-n(DH?<4i0U}iwF)q=_T8hzlqUdE>3jat`_7t90$LZIKDt)ef)d%c0J*6 zmE)zjP>fKb>ws~u?}H)W{RG<*jU%Dz@z_scTCk4*1)k-6*$3$Jb>Fg`v3A7+%Ox8Q4is{{hWo^1sY{5IXAoB~&JVcb{`*|- zQLq7miJ*d5Irk#gFU#o4HP$#e<+OKP56D0w+gYo@CbF_QgLIr1&P^QZobO#gzG=tN z5Cw(wO_cJ)6+kpS1+mwox^9f8Wei-~rDa?jY1@-F>?j%U51Wt;9OJ5#_>mR?D6xs! z8iUFAs|r-ey@!s~=HvJj*?xooq6BB-ui!kx2EzV%-Wx`*GrvzJR&(|zVR@YR@=&q3 zeTS*~|HV;++mxShCssV5b6fAIi!D%Zp1F=QtPbZIh*C^YE*=}V^WnZ(&p^=-+g7x` z3*pO~*&r%?N4Gt&vvUF}o020jmDIiqPo7IOEFR&DP+~?`dB1tH>H>eT5r4K;Dc2qt z?u!KM(TLh%u%QztmG0k+KELtJLO6O`<~&})$jcRB*iQ$6{WwvudZ~w3Fav# zkUu*9qC2nq+@m0dHk~yevwP*D1U6sn!H!hfh#eYb*x#UC9Fiw|ex6pCmbA&`|Bbi= zfR%v)MmTvt@R+7;FGNBC%QAc?kJ->s?f1_#r5zNOAr1$>yTNc`=I|%4S-$YK6h2R5 zWD1!aDDdmD#+P1Pc_xqLL*0Di4FS&A^1)kyMC{&4%UO}!a(%QgGkZ|+@!$S%l*qj0 zQ{Z-tTle>GT_t(L+GRW(^bn8%xu+^CMgjl>s%hauXTH(2h8vre%!DVyz%A*Vgo~RE zDHa%G%hW{K_Avbe_F8Pl<;0bzxx%P-`yjlgWy)Mdc!3omb4*P;W}bCysajJGzrgjx z`Aa@KMD6TAmi21PH`_c(gd4RArj~0FUf)K1z)*a zbGE!?Gax-&mm3GIa!Ic}?=%7kccjKLH+QEtyLC;2mHIj-ZKC;H>MYaS_n2P>;hn!8 zlfI$lZc&hoxORlc17_Of(?cTPl6*5?187IoEo4J8L=CLJX6;^~9 z#xQHcB2T0KxnlV0kPyY5H{?u_RmDV4vi6PoU?vT>_9I=99w+jssp#muDW;4CLXI(t zN|vT0JvZ%DC$?5MJlv6x{;F>xF3LvGuw{{NB6gv{;Y~lx^yX{A2eu^dfAy=$IL5Gx z_Sm>cWT4B+O)*lMYb!T&nTnk2FzcI$kPS4m4IEci>|L;o_l6C?LI&d9SXz&CbU07v z&(PD!aC1o*P8U60aTMMQB^WPG+3iIxgyCG3IQ8pIhZ3WvLfIvQp+HIrZPY~yYUsjR zQ5W3@&@`%K&}2&je@vSb2V6uQz9-AiH4q^FX`Alz-1lllk2uB4Jj>_w zVud!1HTAeP##C)>RBbV%si$-0gV07JME*3g!laIY5m8)SWxh0%Z^cDMWAF`qOf2%+ zUn5+8_EFP*Oxu1p(|%g=VH0=ou28sW1@Qrt2NU*o`cr;J;e;EgeDk^uSZwGL8R!bs z@3f;4HCTBf#^?U*+k$7h2AeA9&%=*u7cxNntmlM0+6dw62QxR zWKGe$hu*co*ozsK31%2_ZbzV=x3E@43o%n}>6m$UKkX09YZnDxV#m1CNucvu8T9_c z{)uVUOiCwl%V0Gdf;Y-#sSc-FKSr41Iox=ifhsvr zzw>#lQU-KDXTRtUi*a4H#r37nHN5z6L2Io!+7M#F1<7@F#$8t(VkW{!YYfY;La~sj zY$(;44{sMtiIsy+-v2Yn7T3YDTKCVn*-m-lh>pqvEZX@pn4~=* z`syI&G_&5jeD@rnP1pu$_`ibj4B!cy2k0~q-O^jYx2&$63DS&{8n z&Q~aEfkn=B2?dfxm2#^0_V7b=h6RklCYnihyHio?rFHrIU@WH&^sxG=swP}c_7uf= zn&7qtCsMDSFxf^gW$wna5nl=FXXZ3Jv# zaTE0oJxo&g$tH1gZDMDkn0)qc#S)S0F_Zv9aL;*)O|a$$KqpVs6KN(*I4q(stuY6Y z+w&K?`|o*YY~;qJ-9~vEnOz@N%5pfh$tD>c({JhUJSDD z;WCR)&0WuLZ^Ve8>tbbHy8UH%zKy$|$DMsKH&a=2)382ibA+?5G-boCMyuOhmBTl~ zm!zdt_(>|?qG}E487c1FSA&W$Rz@%MdLXHj%Dp@2D`2HiNk z6K9>M|1Lg<9OK7R6Adt>JI|c|#B&dd_bXGB+>SplFpGs&zs9(PHvad5!(^4R(Q}B) zTxxWE-vrOvrW#o|n z2cN!3Lrwb|M&On%2^G8@7=T0n=lj@aQYM)GPcqbM1Wcm7G2}5$oq|KVVZ9(pN-33C zJdyx$SF~7}(Kysj(w3qt)ufLS{fL{*`hAY!*%?-tff3j~Y4&EjSl~8csz9QdK`8HG zV6^Ndak?)W%VygFo6DP5EQbl`LNKH(=!1(ROCj$U@SmTldyxFjG1c<>-Xf!Q%|0{b zL0@?}p@R}_G0|v>6@|bhmOw376&P8bFSg<0+7FVUWB)-5AH1yuKE-xOm?JzzTV9qE zEcUA61ZSbWQRvbfTCxDUNPjF`+W(G+C1(iuL{V8hJsXnKO97aT`7Ag#E=6Mx+a z*?VLRo{ziJk4J=x&7T-^EpuFQKNyvTWwbjZDFH185BW4)hFhjT z^&n~C9`P=?c?!MUBeIiBQ^De~z1bm7Vx0Axg#kN0cly7@D-q-tL5F}3UW z|Ba17jMjBi&icz?3IUdHfgDk3rn`~)zwd>-lORX_L;H%kF`4((XddYIs7CwWgc?_S z)+N)^=qb^^tRt*cmwt(7VAMbv@l1pg=0lOvL$b+_PkQ7m;Huku-pLyqq>0aEp7tTt4}`aKdyb(Cz>K318P);$$UK#ld@vd!9NgRYLauuPqS-z$4*m$2zDly;VPb?%eU&|2s-U z|L-V4%4;J&=B!1l1>4}NNX%8w-2>IbKwlOHrh2RV3M*clt;QsUlY-##RUohml#h!K zKpSQz$PSq6h7Aq)}s+u@X*P4Yv@;rn5EYL7dzV0sH@NjYB}M*3X3&^+Y+?*LXJC z$~Q(pVW{3P$=`lI6#M`d$oiAYih~*d^yAQi{~rehIu8zFX6krTCnZzx1t0A zRJ;~K_pL@#Y+fHi{P(|c(XP_mJ5d7`1xgCYEr=b-Ya(I?vHz(pt=e;Ye($?c!IK)Q zuStQ`TKvbRDE)WI1?;u*G$8sbJ_y`UkOgu~u!hc~>wg-88A+{2f_l&Kr6U4olJ4BS zMtAk&rSl1giAw&nGf;4WR~tl0P{m4wFVXhppw@uO|tle}ldi17S>M-&q-F>SM;_a33llD~wN5y8(HGS3}Ssi!w@ z#(WmLkVK8DIVX6RVY1^k_^=&5*f5Z`+#OcG4qQF(NSz6-dFNE3<>bQw3QxiOPceE7 zG#$Dx9Ra^ojv#BIdRvn8&_QYo#U#gw(v>Gf8u;h3+Q4>^^oE)fBb1J3HMLlgHJ|r^ z2X0v3{Ga<|U8jZ9bjt>-bp{X67)pgZbppO~I{!8@3YolMT@Tpf50Rm9$ZGAH*dK*U zB&MbUU365_qAT!TzCU1+;h!VNJN`VZ?-+-2N zcsgU>N58}Mr!8mwV&SQMKrx22CWc~GzN_>v;s%kl@o!g%Vnds;^*W0E@#y&9u+r7csio&0t!Mcl>$^mA_E% z)Xm_N^*2>t#A+u`z{z?bu?Ri`G%`gWo>Eiq!3H5H|Bx`;P}@)wN~ty^V-QtM-EVw2 zV*)56Ahw)Cj+UsVMZss!7N_a@6q0=9$mv25x*9n@n;ydjJw48oGM7&J3;uP;EHbu` zqNa3>DT`f0k0ls#cVepY_VF+W@O~*c-VAvXHS2ZJXk1GYxL+`1pg-?kYLD%O6s@gmUaX?dth3LZb)Aema+>2h zK!@ax7nI`3YNG3!&t-G-zvU9uJs9r2sQn3-33l8_xj;?wh8g1hPc^!_Gkk1cAZ5zd zKvKKQa=v#sg6nhdp>j?|UTI(Ypp=*eKe{660)RK4gY+$=<&3=jkzS58)=Tuet2lge zA!(BJ*q!@|SJxt&D_|~NRhO1#oDJdf)ll2T@NA{&|dnQb1$$$+c1Yt@tcA7t@!{L zEFQ!lJfD@xm*edw@Kn#8sz1N7CV8^ptf6s9t$T%7~;A1fWa48OW_27RoRX2J+a!(jevPrOJ- zL0b1{p7Y>ZZoQ`0wku}ddr#$GAsc!lk6Vc(NZ(2mif_DjZ_5#9KJfJ}X=;RnG&Kuo<*pB1{EEc~0+VPlr*72Na&3ap7`f zu@jcbg?WhqwuJFJ+7}RAN=2D~KI07-w~8 z0$Y@30y(0_70_yXYweBA1$>=)?~wXe4t-kw@4U1w{U-CEKYkQWb9}=Ueed%3H`K1e z#g$Dtf`xTTz`aa@PDx%L$A5^zv|1MiSvT=LAw1ZYlJ|x@t2wlBEw6g>5BbXd*Jn1? zsKkMwf5W(g)Tz3mjmf33`WzMRPE)L5{TtJligB~H(q@;{*@6tx(q~~tLasC z>;2$`XGg|8&-!keprKOBRWEC+Dn5@~j{7G$xC%e$aUz;+&%2gAtgrKJ2xcebYq1jT z0caB6@#^y}ZgZ`I^P9qO_@yCcs4nI5XgLFq28BzzN5XJ0??j8J2cVV&$pzp9-}-g# z;FpX~<(JFbzKvoF=d>VcR*Wyd;BxO1iZ{F%rK#U}wlQKMJT7PGJ~3uHAyNn!DK?jA zSEE%IUeTqfwCmHX92;sdR*fa28^gAh<e)G`8&~C(fNd z?|nbqweDK^nq>BzIse)F$B#z+21Pe!@yCJHA!v-jl%6Z>YbKLoIjejk)UmMqEG>LZ;UUMA>Fq7FRqBzEqb&8Ri!_W9vxonn7xZ^T8`t6 zZFqIZiR8No!+W>n0UhVne$dt4C`uI9W*6*`p&~S3q~$(C^|(ozoOX6xF?$&wGZVN4 za&&2Nu}I9dfEX^|2tvVM`DG6pB1U;!ie0-mS+d+^;=X12j&0v*zv4v)q5Jp%an9 zZuJAh6ygqttir|(!s>hn3)GVk`$i7J?rAV|LdDkLc4O&F2EhDu)&j-!4|MS!kf>ym zYf01WIy=rSB%^}_bDzTGKvuVL+mvXTB(3KmOLx)cU9^bV-^4U(+YfX; z)ivGq>)GHwn3%n^-+vi$^+eQDk*mU3%`vPD#-V6I;VSq!b}=MJeUDUPP;vX4UpBJie@hn#MP+zC8fT9LBS!}}O{9Kk=>s(nZLSN|1+jQx>r#t!T;cOL}*N{o-jX)_f+u|cQ4SHE+AYQS(HB5jBv$i^|*)ZlgM zKeqY$&E=cv7^Rbr)i;>E5OChUxMhaNcne_G{FDpIu{9j!y(Y%zkqu6P`V+kG$HAUM z!0GYM^{}bxX|NW|Cf@fEV&Ct*_5942grp zwLBGL+R?6bww~#>{H&bDl9n>VSH)}s^QxUaIbC6I#f~3_6h*g@M|~>@Y)0tUMbyr= zG*kMR0PW=;L2rnNL$^?j&G5OD#EU#yj7+&GbYdyc)cKEhZ>fQP&jP?NuBn$??p43R z6lk=c6QT@oZd`AzcuS* z5ZOjr;#10nqUvqUCib##fs?O#4|kN7@R0+d9)z!!&9)pz;mPa(Sc!xQ{o>{GM)!xv z+YbbkT@YbSDT-x6pWmJ#WIJ$}iP1tT^uzeQ!WX3%#U3W~DFVqNtb~Ciz!x~wz~R^* zxPtiYbdC3%3U6{~9gK%HNa4&3Q)W1H5BXm}vJAm0k#huUW@F z^(cPHntIxzANw>{2A3*XN_XSlQ1?<$mB+ zP-L~S);x3)q`$R`FD|q19pYY__Z-V%uM4tT9R!>E>+XcXyKZ7$R4A-(lzg#C3~fin zQn#h!Cvqy0o#WhB{Z5oHeq5#jM zAWtT^I{YcCt(WcZncC3d4ci+J)$GZsE6h4Z+>)T4$*1dM=xrN<|UO-Ko(kSO3O5ezX_ zQ4KY37z1NcblU^FZZZ_T5JB7|J~Cj>T_=?w93(16Cl}tjAff@9&DI-br#1c&$2(cD1Ljv^>sOUWv-zf`oWb@1 zAlby-P;qwtzwOarBlpK0WKi%&=K8O?&z$sHOeD&-P6K$#QOP%ds{Aq*DAw9n_cdJR$U@I zePL+2=Nh(DrAJUni4MoDi3W~!+kmORI(s{77MPX%4m&C|$O8htR~cr>ZGeF_D<+F!Zs*_!fx&c$?VO|fkz#0v8+y3MDvwQQua(t4k9JxTaNj7iZu1c`%CFfA;Pc_A3}=pBd;^NwR_SVK3~gR{($@C z=Y;dK$m$LqA;bBUIT{O62yKJjiG(o6rIYt;9v4j_?cPQ;4c6vyy2+f1{G~eBL77LR zLC@fwZgEc{Vv>oD=B^xkci_;kmbYXKumvpWz5-5c7$6j{|EIoG0OtU)5#tLSDiw|GqV!yWRWExb&Vn@RGAO z4K>EruZXe*!n`UDPOGZZVTADx?D}=?a2ZhK8 zMC1lkTq2@}cyogV@y7|?+2>L?U>1mtM>Vu}M09+{(Yf?C-R5Uf=5neR7d?PLiUJHcafSE;;h16^) z=*PDX)ii*pA&Er)AQp(H7J)>85Q`G;QnSa30|F~9`{))|Xl&O!`rGOpgRnl(N2F>Un* zB-C7=Oe=r7?+v)RMU(Q-*QM+qDz@iaByA)0b0dZIxTh^sHq}OZay~L_-Gyo0_GLkX zuNNieyTOdUgwBR*k?)D3=aNmQ>JsMNli9CrAF?i%xzQJR6QQLfU~TRGAeHje_2T;2 zWleXq@RSRSg0k(rsFd*Q{V%xed5#vIaT!a}1ClWJlfgvtiK>|Z_nsXp_B)TfaBR+# z`ctrGcvvMb^&^ry;m24%idAQR*y%K=cU-c?0;_+iA1h3(gkf z;|^oDp08h>UPPdRL@JoRuOZPCUOh|09_4WFYJw z`+(0bnbYFRQ7#z%NtRArYfD4=RYeQyC8Yd{j}`_1cMhw9*>7$!1|uO~U-!d)Ha^AU2xvHFZrJ05;}1Gc@^)wst62J& zrgM*dyU;UZ3hGOPwQZ1K&3`5MH(9S+X6eV_KIQZ@-1>soCAjeq+E1%j&wRxZPWm&c z=t0ftzlZAwG#A*liU^nVqrGC$Bb|Y!$6Z-+REYrx=aoX)v%f_*A-HV6WazXw6o$s$ zJ4L(Mo!AP4FPUU0?gj0nW1zwpizvzI{$x-_>}0}?CfK!ItwxG2y0wsVN$kvYH3cW| zoYyvMR~InLOx@n1(NJWbZ}3+9;UpM)RaRa)k5g`N4M~&>n@=`wweT*CR0rWBfiP;~ zt;X(69~K4sg!!Z~Kc*L$9#kip3^*Sg$!XJ#G16wP zWJ^+&;Z}dYuWgjQm%HzG;4uW-IU(o;iJh7n$jOALpa1@Lakn5nv*4P(YHBBasQy!A z!bMJ+1-f5xD>$u`H=bJt`7I<^`=yhDyM412YeF%0j69y}cxK{X}3~rW?U-9SC zr%96Q&y5@~%Z@lS8^2#%&hj>-XDZNOz*5R(1h1YS)Q`WpVfHFU{r&MrOr~=Y?Br2T zNd<4(h=&xLb^{w%JY8r~*_~o`_=)LYM_*+Mn#99RZ4y>Tm7xtvofsSrT>Hy7CVqK@ z3cpXzXqk-p@XGw0Z`ZG)Hw2v*f4XEga)sD2Dd($_JvdKtSeJ0z8cei*=ZY`xJ(-xlI$DKO&!gQE zadBl+p|hFU)Kc4p~w zRhzxms8J`kVrpmdbLXKsN@rx7b^wn}SNHmo)&JD%VxBAzSa3IXMqvRhA`lT#V*%kDo9}fkxc-}*2 zJ@_sZ%4of|qFV;?{m` z%|mN7G?4bu8+2GO>YJIT^(z$HX^3)44a}R-4t;my#ChBK&Mqro_lm*>kpyj_{3UA? zxMpDYTr1EBGgn{uk(efL;}1j8k21o#6N%mII&`wBakf4LI1Q>j4=6XF1f0s zNt7`;c5;auQpsaeI|e4(q!$eG?dS^7d)DcL1c=758Qo%fejEc2*TmT`p^&~h*}?|% z4vKXUwd*h_|L9mD=H^f}j@-JTcLK~l!7GVWW%M$POY3}5I~Ag{6bgPD;v%v7tSYNi z{+wp50^l-aiyO%7yuY)D`uuZINd_Wur72hj(;_A75#cAdP_L?;JF~uhL9|1(xu*K|`(Q2R)4RDk&6MbHN za9h?&OIfCl9m)e4m@#eF@7GF%g;~L7uVXT#mMTpqnU&Nna5YF>qjL3`O`EF@hdHjQ zS>_rK1A$QgsQqujyQgI_^uI{CGn?KnX|5HDXge!8lW1||%{GNhRas*}jl{#rGSwwS zj~9Lzp5R~H)=ZsKQ^(x{1cCaHCA+bV7EdQS-*2rGEG1(@my2R|nlV`m&*hE@tMfz9 z*nE9@UhvgbePetf+O#;=M@x~Ae^Xl5xF7>Mp6>vou|y-KUMJOsjI<~n*?QZzT!4>NIN}oTB_1<)2UB#% z(M3*uIvekZHwO*RaFPA2nI4V}fa<*sR=mI@tILorU6>ig{pHOZxV)g%b*X_;ejLl)3r`&;9vUo5#QO+!X5~>WwI}bVH45saM187PZztd%_st5ez+6{n=`de*d?I z6JQNEfREYmD#RTDV%{iKA7JDDrZT@7&2^ps#773sgsoSY9+#iE{~A3k3S9Np)o$co z%)UA|inct=TNmv)td;gKV1(2hjFqipv&v-)_=iP1Vib92xM|z8XDSg8k=dx$mA<@+v%IuJv9OJ` zj8Bos1---}eXqt)KG0Xwsa(e)?9h z3b%`fRp_CsOi{Yw=T1UT12tv}KnKHH3CQwtUg&9FPmoJ8c0IG|pOAjn^br+vu90$~ ze-FGN43mp)4y9Yppp?T%v^jbS7qa~ zPYz-#w!1z(g0*^-Ttkc}3>mDae4Ar<^vHQ46M1pczha5jc1s#$Tx540g7njoHB+v8 z9?IDTB1$Y15Ux1^vZ)?0ANpsL94{KjIW(xMmv`grPSn1k!lyHOasq330kkY!cArw# zE-^73z$I7L$tX7^7vJg|cMA;0@h>;@hVCbQS}n8Ko&JXGb1xI3RuJ#n9g&QV#vPVj zJSOtM#kcYWk#+P*`1cxhEMN(*!f$)29;lxeb;=X{{1PhKWY=+jE8}cGx$yIHqsmO4V4SW4j zYbP`pbKZahuB7hRP}9**+Y@tE6H;Vly?hMsvhcG>MSA-U>6etAuD)72P@rFxg1P3Z z&a7KIHss(GFiG)x?SkmBeD0~%UOwV?R|Hp?c5D|T4+J?J=sSSCjV%Q{BVX{i2GRr` z1RYKY0d-^A1M%4cVzq#fde$xL_G8)AggaoUaAyJ#SQdxF$^ic^YPw-S9@e1V+g7lh z#Q%$y*o5QfcS#zFaL)P1+8-z>bJ`Wfn zM+FdaZO5Y*)){j*8iR*?T2;43tT`L#^dfs$#(_W$tE)8{(#bI zYQVDQuL+~kL$SzSkJoukw{}bOa>;Jh|M<7%>V%2af~ylq|l)r^Y~>vIxPA|*WM zy!__7rt!?lcWiyOJXX%dP|Bl@KKkT+{;95IE70+$cT1xSK=C}dJucJNWCT_R2(~BD zTZAEY3mU5`oxBIAbu&>Tzlh73lFY|94amWFj&7a=to3&L3ynR{Ex((o4|a1~ zy2Ba_i>N^+lsi7GAX7j|5BfLOV~5sDw(GMjZe{fa9SadP$9paHvNHP1iAK#a zg72qd_ujBmV8-WiFynV?NBv`cD26?EOnDATen8g*+~7*UHGP8+cX`C$3HmjgSz8fr=6NZ3+6+ccvwq zy-G&|0zh-1dw%p~Z@tu!ir09l#PFAg!DLiy2BW(rq6l;#fqmhyF6h9+^`?ZKcEs1R zk08>mmQnG&xx4IpGj}w4ZQjD{u!U9)(}&3f~q@y^8;c~;_=xWUtYm!EEyyV zJww05ZOvjx|0Dq^a{a!X?3@9!aT!1*GARVeii+vKrlW2Cr5rb>5@GndcQ%uFh7~2PBl5v2*78L|em1 zj6}Pf3~dZFRT#wE<-$Tv4X1NvINf*kR^?=3z812r`Dl{kw_6aoYq31m zraJn?9^#>HArR1`Stl85r*m)cxdyc04rdZRr~HXcm6DN$rY_Y!?cL0NuJNgS*3Q<2 zAC0HA^6X_3@wl+=XCT`X&9%+wu~e9MgXT}1zQgG&?Cb8(&UH8TZx`J#npF1OZ8i+zwTS2-MY=!1P7 zAZ|XUF=@E)Od$XHZ7$G5*H0moN-HJURFCE3&<0t>ny1#)!{XHyY#DR;PbKej@e|yH zTf7J?` zn?D2!w#KYwCiC8J2^EJCuXmzt(|ZlceAQ-B52|aD$pjmUs3E2op{pc>&=X~R&x4AZ)4DIIDGbR>FbTvq6SaF7f8u4Xd7#_J7OH1RF z!Isv)zzqrQoig{(#vN5Go$R0br9Zk4!vl&Ab~+W*W1x256mGrL38{zgPewDlO;YKXTW=r0`Gi%u4{|<{_FvRaNbg}F7elANdi*G zBUKn=BBn1`dR9gWS0h=3@*b$4}hlML%?JBW9!B zMI1iGYm)D%Ou#FyObf#PMND^xbq?R+OKl|QeTPvqen5`af$wx-`n&xrONy!R>jdW2 zuAC5tLqA!rA%vv#GpC;(9|mY&w;^Etj}yidDT zu(X`90KrVKN@OdAdBAq|)2!=H=_*RXD6f4-TUdaxaYNn$c3sSgp^=&8xaH zE!TRsgPqZzT6lxv2`+|>#^wL12hD+|0A9-s>?P~+JOgj+1 zo`^W~dkQ?^6B;j;B=wYcgJ~|(qvA!7ghB#yZqvN+=M@*tZv7#b+dSjSDP2Y*)5~d; zSn*Zeh~rosV@o&Mxa+RF3SDqmk5o+mh+UcJ#mDpgwWtLtf#A9B<9VA7#z)EuI*RE6 zcb1nql6+DJEB4k@u!I+dr6haK zT$gk96RuMiB-56%CHlkdergmab}^o)|NagK3ci0N723=o6*ptWI%>h3Y0-4@V)PdQ zs5>;CLQKC0=cYYVV8a!>o2*V{@?w@bhm?9jIwPaRNcv0n8*jArxQV) z`O-li=->0f50Bc&!&x0P2A6(lA~DhmL>e>67`oW=STySl4C>77r{`!SNT+~9%yJXH zd)SAr&C&SxJg zk~J)BOaZ+8uq=5rSBSW;5`080H`%fd1$=B52V_nFV3JmNKKrM~D;>Db#!h93Wzo|g zGWwd@Gp3)IP=P4mkI(x+YW?7K903r^W{W#`4$Dq+{4Rrny+nGWe=ra03coug=HkU^ z&#W~)IEgoQsN9_^ow-nd{QY@UG0#C(w9k=jD+PJLVO%;X`FsVAaYdm&!imq}vaSqs z=OnJPMGmQxRW897d;$yV7#Vwf@H57EyM%r;TxlqQ$#N3JSTcJDQk^3efh=^k`vl)| zv?3cXA#2uIVsQkk%A!ehYB00qwhzsP;%59%>ss zisd{EI>4OENV%d7F`Fu8OgPbLP$%CxVrad@M*SEctT{Fv*b$S&+KPvcoq6K84KH)! zyY}PIFK#hrRqh76JDo}Dp_t;pAPt+j&ufs+kaB z?XLJpr=XzPl;cSCjdq(sC%gvH2X`NO@XG*WrJ#A=P%uN_U+wKdPPkTs+)t;U2-NWZ(&yFtf!hotX?}!_=x0>#Z;m!FQ#Qr4 zF*g*ai0G1F4`wI zECzltc6#=++N{R^t*cbEhnq`?ON>D7A5InW3++@VEZqz%_$7bG2hbC}EyxW*`IpH=GK@V*Kb(tc|rs8;|vFS)c8XKp4+ z>#j!)P_JjTjg2SO{t{9>s3c~?EdCNc(%dBFA*ll!o(N`6HE@7PV-F#{4)CT<0V>jB#Y8nqh-_p z4+Q6)njV$milTdff6YsO6x%a_~kvqM|LyxBaQ}i;U{U`1%n~JXxEks#X>_OrGW6X}a|A~z$tLG@-Jg#rc%2!N7 z4}Zh&dz|1-Ud0-gaC#w?(g4pn*@ojy=VmTTHx-?Lm#*eSRcw`SFLWj@cg1^)v%LM$ z>mWDl-%H@fCNLu=61-st=`tst1A-Crj?d!`~`HEok6NC?f152a4w*Z-#R2(le7_L9P3J7t#nUdgP1U?dM3}~=Fhl_$EN{r z+1}ZT=&l^l&pUBT<$oV?8mqTBK<#&`L34WQDA|+f`!oXgb^wDSC*%1&VYt%f%6lzo zro26Aq0o=n6 z7NJcY5G7-Xma~A31pt&j0alJED7g&{_{WQJm%V!TLkoZc_h=8RQY^#-gu`(eD7vm6 zbOn{vlkp;B{Q<4*zOR25OY+Rh+IoSn5e-C#!Mo~&_nNE=tp>Fl3cz3(FR~q_HNfX- z!oD5xk~&s2i+)!j7~?2B(KGX~YY(egiowxzp#cWCtez*TSzlWM*6%HT&)d3@{+f6>9o zkzoE3hr&jF#=5*)!1woS_Yqp>R5f4{7<7~FICI4Rb1PF^-T4D@-=2%X1AYFFw9nil zy9WmUZLFa~rhnq@1<>X~7gxX5AWd1(!knCZ___y7g?t9}DlmoN6~ zb2wn{I%qvZLtFUmuzKsbdTW(T0^0*Hi^i&GF*Q^udQxIX3JU-Sbn+fAWP{1cAn)nG z2mt+nJ?IT^TCo&-?GZ8>QuNbvMrR@WZHoH211SY(XWEsiuG}0BB66z4zapycxID|5 zH++CDUCRmHKUq+Q`NX=Oo~ux}x^v3M&Dx)dA6{MtJcAke1+d#heu*-ZDylRkZL*r5 zW?J6z8%cH34<%Rk#;^BxwR|2^S;8PJ@hBy|{_9b8!%D$4!cGC(O*-R3gfbV{BmGO~ zG-VS}ZxP?)tm=A6C-Lw?=K1XUM~Iae?2vRB%%r*6B-T=6k6MdJUTK)#v|%czhDsbu z+NDO8oSCIqq7h$4$`KQW*5n_|#oERje&Ds6Xnc9(V$d%yvW8HX@5S0v*_|wcXkTO};!JO<)_>~G0e0I$eAi-? zNUE%QiMdIbbI#T?#D~3vrx2`WB6gQav6Kcft*IE72_EKk2<0|kh^Ift`xfu!5~;(~0DXBq#G_Mu$5Q!OYm4RbDtG1KNcXxnbyd+SC4)M;MY0|+#F zojlw&zdv8a#Qu^Y;d==2Py#f8XvCvVjkr#B6%omgrU=a;l{ePfub3|@=dQelnR2=& z0M2TlFoitg$jo!hLGYzIgsMAv)5P&e4IvCM^do^O zQWfP8a)R!RFOPx=!<8Bm`%9>@%3HPwyjX`R-@7#JS}Yh}A(VKGQqa=4`U!B*ePt(6#42F;f zaW@xV+Ac@{X+9N7)j(Uk8^P#hosEVL@F+w9%@t*Dgm8o6iVR+ufU7T1%*^=g(5ye< zP8o?4M6;R|;q$}Odb_4cF=Hu(UDUR{)BgbOxZiie!74PB-B=HaChW|$e0q_I#&!l{bk3IOdfX)D>XTB7bGk*-5`Aa?BeKhvlu^LGK{nOv8}=c>ACYu8I~vkHNvy9AMsFkY>XlJQsk0fgVeXbyIt8O_6NHddlf+8W^1<6FN+FZSwM#0X!v}~ zu@7$-de?J%CH%v~%rEto`yXb}#ll~hiR>N~+fyz#iK+!qys)B39Kpj*YnjL))>QqS z^A2MTHyidffgJ*&u@*AWe>XLNCY;}}ZwDepvbPou+m(lVyn^Y7*^H_32MXD=yGQfl z1HXTJ6XS=Z`UiRogy`}1&rCV}EaGsuq`JD9Ce^j$mu>I-dJg+h6CzeFV7Nrcnn~9m z1z&)C|7RV2`g?O5EBO5O6drawaEFik&@+8ieM58_9iDd&B-JtQo6Rj5L%=0=bi7iW z!we+RP%X}7Uat!pO6}uKP`4%j?#*3lDt;G8FpAyw;P9{V4;f6hpX0cMd1~YhTfiZ! zJMZ&e#L zdKrXAfCJ%BBW2b93Jv)3zobT7d(U~-Di}N*b3SaFdt8ZnJkYT;uOp$7V8sT3nNa#} z_SJyk98zlf0q&d*sDm20S1$XX;ZT{3gkkcK4qHMz3lU^xdcuup8!`H}TRX3!80*hC zoq{s`AvWzE78ehaqP-N)5r<}P+CT{-lvf+jtRmvq^Ynowzl157+@=FDC8@8dCW^TI z5v3Ffq-I~-i2)eX55}4EX5b-K$1l?vu@}Vr-b{)-9IJUh00hCiH!La3Xa~Tvcq(i* z1G;chLiUrIq#;D1pa>u+aIZn|)FaP^xwIfW16{lyfNV-g#~Fq_j$}}I7YV61N>&Ae znGOm?L#s!Da}uB&B&9t$NN**$I+w2UGyU*E_FPKzo2mh8s2=Yhdt;nPK-;+m)+x+< z1(cldf@3T$UB~nKA;uPk)*G|3XOEaiJSzobo~aW2HT*=XJ)fy zDIj$^GYw}c|Mo)mprAESH z=-a3Iph`>%bx9J0hgV*le6q3LrpQOjLBegK@W_>Zu;muMxIZVjZ}7uxe`k5bW$a-i z4QV?2Bh?ucrQ$YLK;nLaPuQ`H(Mi*e(g%RkHjdW$vUU^TA(F#~qiqo-gyR(Dp=-y3 z;U;&Mc=o7#6w-aZ*CdODa6&9-06goG)nO=b+F0p@3P z!q8AKDcNjCWpxYY?{Rx&9+w9 z1#Leyu7a=8*Ym4eWmN2-uaVeQt3~{Fy<>3P{`5e|0=Q)J?rNfJrmM8uP>I^jobP@C z!P*;7?>6Qjl|!SU^Ms9Fna4(s#M7M;`0^y0sU?m&x)%Z33onc;;nRsc%d@rZZ^bx9 zo|6*v)gIZd0lB3}HT{kBXPmY6qAqDEK1AFu&_R*Y#)`B19@%=oeg6w50ro+*fyGkP z%7x<5TavobW38~Z&RY?Qh01EIj$gS%q7B|DdB+dEL_YwBd_D%LK&7P$sx{Xn>~|KC zw>ge$KJq#%w3xqtTV|R#=xLJ|3A~J54P+?FvCOE@K)c3;7H#|B!V#-;Ig05+Qz7m; z17cFTM=iT!zf61!YT9QiXQ?c=E7L%n07dfa42B|-dVbQZ`pQ4wvw)Vb3WSkP?GNg- z8im9%)gp@nCKzm6(`xmbz4xp+n!0?1xs#}Q2gpT3L6qBe#5@EaI6H!89zhZKu>)8x zu98!Uofc97MlBJ&FI!v>SHh!YWgQ7=^fkJ1kb?9-O1cBq+xu4EsVEX#+y)s#j5{Re zXhxPouGc9W3U}n*G~JQS`ZgnQDUrI4lb=juB-h}SzNCSkw(t*<`K7)MF#@fp0e~Mf zVgIag?k_rEVlD^4YbifMMbYUG6X}UhG!k#~tfY~%G0^2BrS*js1KmkfF!2`^)9@i41usqgGqo-*N;%NEfKE}b98*+Sji(L>6 zDN%Ku^`AZ&0qiNa6HMnVo$g=S=nD!1dH97$!#4B$V212FeBHlr2p6Aor&3ON&5+X} zT0}aL4W>|I$JfvvzE?-v4>@V3p@;!(HQRavx5~;4q0gOYM_S~IvjWIpl6nh>K(SH# zFB-BaOe)N@W==;&Go|G@sYW@m^^WSB9NN*ZXmoPRk2Q8fArkrFVM3?fC}H? zmZTe;z+e#%d36y^DX!(1qk7#4&gJLMU??}3@U!qUphY?d}YLhWp zr?GlyBX$bBLAGI0La@WXnBjq1KD$>GJ3pfPBa-1a$N0U)MtPWYfclg%NR&3m`WXar zTX#YJ5;s5KZr*E=I@X}*?yA1Hhu`8uOp##EEy*Vaq=Up(C{lk8V~E-avH0D!^%;1ujaS7a2hGfN-CjM4l8J_aX|8NU0gkp4@qiCo)ab-cc$d0sw$l5z;3Na zb}+_%>tICyRM5)!^ZPMe8;H{A+iV)S026icZu4loZ3+e5>l+Nc0h1t>Srm$t8-e@R zUwp(Hz^Dl};X&V4@*@3fl&$a-??N93CKu^&k@Iq^EJulzj3tH5(^g_Mk_x3+%-Tg| zL5Yy@6Q^hFv7j1TU%3-K))zULN<0$R*G@cX+jbjqHESEBOJEnW!L2M$m}%&zPYbmbL#RC3p6gX!%aME^pkUG4{F^UZKOGlgArvl^Pr}mr(wFg_ZZsgi3>2yq3PCLMZ}A%URhg=`+9*-qo^@w#M3cDq=3*Q$LgX@)4MOIVca$J0f|CFr4dhI+vO&Uc<^e z?=gbXmloOY7T-y&>m>i)E%$cg-Z>M?vdPcTQ=!n6&|g9OC%r+JOo~)@aJ5zI?|D6K zxw--a3bW&4(AGX=Jf&gMNovPDP11+os30p`DT1j!I^zm3+uoK&Fcy*ir7FfrB_)dp zt<6yH0skIiPW0tt|EcRPv0@QhVsLs3Aib6wnWc(nrvDwJMKel`3+Epfnel3h7uN~7 zmJLTo{UgO*QL0CvXc;*;hE`0-6VSNWhxT|lF|> z5g*VtENpKx1CCt>qZr}I`ZRgoEZaPk(Fs=1dAVH~l#uNh) zR$8Lbe|R{^qorknL*EDz=0C|P8(+4ozqS%JmZwp z2md5j1%gkfk5x+j51VWoW9qtCN&!T+6H>8vAMBpzlaWfkNS-9#|E?5$tJZ8*z#AV> z0-#3Ln8;0HEI|4f14tgnHl%9EB1((wS;PjmKNo+6k-mm=6F)opqpc%4pBo;}1*2() zx8fF#WG0}Qog|C`q|zMj|04U%!%&C;k3)N&=65m5^tfUmssV_U5Fqrn{=YCHb0y6D z_M>VDmLg$>SeZX?-Q9m7n>*j0YnSFV08N zYf!mN#uv}hVnia=t;5HeYE3)mh8<2PNedNmD63J={R?3HmkfaiDsBU22|1A0Q|&2% z#_>ITV4MbMCj5D6{k{LT4B=gjx%&$|JSf^wn+9ZHPb_;9qH0^LZ1tdL8?P-XtKO2J zi$b91{Oc5nl|an2!)u1unJco(JK_8!W_SZGv$_)>PE5w41C_X)(ig5g=uU9PhIc}n zgdasn`cm&9vh!_L?Dt(8Pu&mQ*uU%X%$aihZFeG*TCXkJbodFuFj)u500F< z1Vs8}FmF=S-6;;8foaFkvc|2R z_!{m`{9U7NZWOEYiMsCgy7!$f3dzEG51EY~AC0wsvyq|&N%SPx&24Lb*8!w=4{aWT z!b-J3;i1XDTHK_gh;Fp`?I&Lp)-0M?vP zLX;=B0iKo-m(EN+NNN7?zu=8kL7b^(Q|{H@lyvid=Nfl_6~GKiv#`Jn%K!?Hqb24_ z>bE0W1iHwWpRG8=C^|uU?(y4}x!i$3C^`DRebve)TlV=Z2NrNESkJ_cyIp`dmt?^G zJz$l}IN|R5iRkqs*3XJf1O`F)iwErcQ>vfSvNEFL%%lYAxvzwTPoJP%f4pZAzXDjv zz4wWZhf%re@KOztE|*g0mtu;X6uiwKBCIHnHcNbb7S(18@2vxHk;vb4?>@xKZ+1`s zTEeb5$1yVfL&?3rtY9mvOKi=a@hK%I>)VtK0Pq8Uu#XZOeGZxFYto6pbn}y>|YXan9r`n+VI`4d8tP*z7;ts{}&F`kk2uO2Bf-uB?CeqJ+c5^ z{ht%}od-Av25eI52v@R;O75BUpY{j=_PpvEn4o_p%X2#S*2$0n9oK>q$4CGfn7=8hK%)|5S*S|14^Q`Gw!IqY}@asAva%n5m ze;g1Zowtfb_72~DU=sxrc3ZQLbBzAGf563&`Zl(r(CZ~SweS0lI0&W4^cNyDO#O1b zj(KUvkY5%N&dTU#E+X`(7oiIe564qfCp-LDmf<>Lc(jUSP9Fp)4Y$$4!)sxOPihwb zaB|oG7~sJ*&%!JAQ0=t4Zcln9N2nO25%}N#mXBlQ_-TMBfW>#~*SD*EzK0zJk3Bl> z@1@wc+pS4EI=WE%AD2pyE6Yn0g<^uGLyV2DEIP#gd@hLF4bar>#A+c3DE+ANR&^Co zn#QWo$qdedeE0x8p_TX>D+Q7S6rsuE791R)2C1eD zWX}CJ-HZ>50Yji(qGE+2hTA0)pe-r96d?=+fVTMcUZXH6qW;x)=nA@1yuY~2COonR za4mi?WF4Tac~Z2gRf*0ohcTgZIU%pmW1f8S9`2O7++TPxdXpZn4m5TKHCvGY8|Lc@ zQ0gnD`%;gguF*FwW2lP!U=tH;GpYL#VrBH1N-i|fEi4M0NUKxC5phieU?%^DEs}dbt&RAkd#cCMt%p7o<=-;;+8+GX155Utw=p$uCU|f!K%{RfV{S z4#}lI@G659JMbV+lV1j3ud5$KuGUnqon)~;)MUfg$fMUKq{0G??>Qrtn9AQyW0L_- z*@P|>pq*UfxSDe%b)$u#U6=pgtC0Mi|9`6c%BZT^@7se&NQi)xsI(~E-5gK>X{Eb6 zq+6w1r4G7!qnr;X4P9PRxj#q2q^fV`c$1=k}Z@zkYv~`Fy0l9&v(qM>o|j z3cf7IabX!{fl*S842!%t{1_Xr-7h<7{-mXxY>`6MN2o+nU4oQP9f2?X@7FSj z|8w)Jf38}ga&T3Yz8)7x&va_NLJhi5<&Iy;Qd0LQ^8WLNK|VV#8g+`0sQpJB&}8aB zg%DSzJr?bs=)u|e@;~B zxiuC2+LZUJz#|Wn5C6s^+#eK=?Sj#N*I!-Wzx5vZ4KmX6&v%yo36cNnHRK?++rJlR zEA*dxqy6XV`@;WoGq- z0o|0aKI>eA8s~+Dg*<-|nJeeJNpD}3H8#F}F@ouT{N+-8|MF-N4WA``f)vKKJ_0*W zHbgh2>u94Tq0d@*zncA@{DC8jOAN!Ki>CcI?(Or~Yly-VUH)B?|2J1{cSGuMf!uFz zwI>7%TLkWmD(v4L|@eqBCJv`g%7w34Fd-QYWM}BJlt#glwu}IZ5v{%hHj4Tpdm+9WP_h)YP12%d+{JmE*NG`Bta& zdWMiwbZl%a*{#%_9gonkFa{~9)69>wSFaM0kdXNJ_|S`p)DDz&jW#Ge&CHCGkGMG3 z^PF{~a!Dy}8fJRGeWS|C%BuDFqiJXJ236xS6P}t%wLDVz!R@0|@aZ9IKtRCk z@81zZPLoNx*R?b?;TB2FHDf(z*|)Zy;GY#Y`t2$aWxOvgjv=DEb}eoL9+twcQ_}eu zhj4afg*~Xjd*k~0_d0Bp4`#>ishd$t&^6c)?2zF6#MJZfXqZ}`t=Fq(XD*j-mjs=i zcz>_=Bt&h_cg2wP%!CnAT_PiU>@@X(K|tWLv$J!)f$0VoV|y~YPGVXbKE2EA30HS- zZzueWLgC`#cK7u77QvH;`8q=*3kz?#KYTdjpB@?!!6YI=&8qsc_2g)OcPJaPy*Vd; ze0sDoztMiPWSTRUoK@9y^xggO25;`yuV2rut{w*wmS2vHkEgU^@A(^nR#J){FpH0m zpFdrjsv#vO$EGix38IZ=(#h}36!$JO>%cvagERMqy9IrM*~LP+xw*|>gH2QtfAP-} z+S%E?o?csBo%WxGGb#^03qt<<`0%gK?lMJhU!QVAx6)-H87Xz^uUT=D{(FtjYr~0Y z!)t3rEUm2Crl*^$OyUmdUOoKX@9N=!_VN<4AA7IIXctc_d@+^V1Q!M1HpKOK|FLFa zC)}&|X-Z1?`}gm?g~o-1g+GnMgPpb6;NOg&OwNO%tv_$F#bBfcODPB`m z*?OG7>$hVYdtI`=s&Y#@0?zogLd>*pqkZ+2q6fv8Pg~=YlZ?#Fc>>V|BQyfGmvD)% zXirXV1#Bci26`ki*+<0k)odm~0tTH2V= zBAt$}Ur7QnJ8dSxCpgJU`8w0Db8|IH3`HjblW zc05N}L2b|p#?{SDHl5Gv(zR=x>*S>Unc@*&rNH}+kB1i?m6mb~IgW?G2d^a0M3B&# z_hkrf?(CquqA4_*1AGGxf2Br7N3)d?{n`5YNw>j^Q@_TUxLTjs!NKA9xAa*XQ**7Q^SHT`d2W@_EAXM&D60|EohtgXWdDA-Kr+Qa6x$~yDzJ~y?n zz=reXFsi@&LdZ!DuF&e}$^86$nceV>kx~=7`$Z2FTwTlh^~L}Y=2uEv6szq=d3?7m z^YZdq2L{wP+-al&L_R0o!miej>w6&_bM!*kC0xH)5muE4g2vL)lK$pRd{tG|rGXsm z5|b8V`jVui%U4BQQIM4pxw%YNuU;K!^7jVR#6rbi6+K5wOZ&aiS4)E5x|e!`u5Jw^9a~w2s#i{MF9S`4Gxlyjg5(TE?-7~DByVOQ(1L&7cA7) z_Alk)jeuXDDOA#Uuzr0`mWOC9^V_vAM>9yjQOo}LCOe2gTwI)pR*2~7)2DvP4v?jQ zn(F1|3b19ffX(wY-@hBa6!RqLh#-l81%H{DsnHS?==h_)x;yZEd3pI;^_+8T_urit z78Xul{opu323J~EUfy>2_qW^180QYy*&jZ9NRtk3cBF|eP~F+t;dpgsZedaG{6lQy z-F-p`;7^c^9$Y$pTk|-85ZK(@+)y!0C#&p4e7Ey-#{~WN9Fy2}R8tf|XMFXbsNA~m zirWSfam@ju5)u;XZ&a@ZoSp3Jd$vJd@W5aD`1zTCuXVd~=g!TPUS%is;s+LxO7o|1 zJpd+VE-neDCr3=|?1X^#=r96`fkxkl6GJM6fwp5h04t^r4l$+87^NEy$|)SO#roB= zi;Ll+4;N<_dY*TG{yZe!^5@T=@g{#^F^?tG?c2A{szE-x?7%*<>G>jA0T2~lCSrvDs3dKIz`p7|2q z)FfH&wHD23@L~3=^clycy%#RckCKxq9335bZ2GT;hKIL*`9f&Z|B}?q<4@=KxUNLN z!KGhcQa`ClpD?$V>Q&-WuxZP@QO&$WLvw+hogK+_hi@f}u?1XPo0~EL0TS&U9fN>@ z+V6Eq8@$$@#pR;t1qCVm_f};g;|AW{XMZUbcqM^OI=r&7Qq|~njP&UN_Dt}ZBt!r< zEH4tfco(nU)Xcg}fP)|uzrS5QQm)G9Zjl%?}Jh?#V$WZT0TBNF7X0kE_?BpmZDbI&scK*oU zx^)YU_BcBYJST(d?(7V$_uk+-#gicjgROaNxi!<^opA2lIm{si|p>)o{7RZBnm)(s%pU7b`nq$8q(Pcz{iyFsh+nySrZjC;h|m zbFuHmFcf8v)9FGjRz^ns4~{fg^xody_ER4?tDS#jd`{(7Lv{D{#hII%qcdQs=MN#4 zp2x+-ar8U?sMpZce6||+t<*&A#*G^|Lp7C^xms^jd)m1SKEwh$AY6)uP|$>mmGdhj zIa$HJT3^C@f8A(n3gXB!MIOL@2@+H6=Lz&A3cA?X*h+WqTxzLnXo#7C>|#@H;mNeM zw^u4GJX@1m|IwiHsu@ci)^7=78OI~ygV4EBO~Vc?^n;}4IrVBkvGM}G8&tj z2#=?$?6mw2HgoQ50Q=G|))&-EyCP_x*wWH+a0WrZUF9q=^~(Bayxy~@)+Aqv!hX8Z z7mG#|kmk`|&OH+{Qm9L%13Z|W?5L=yiesfz$oXqx9(O2(n3+S9lvwT;>))@sMny$+ zP6jAx!OFMNn6j_g(r+Lk?E0plwXyUaPAY%Q!>_QU|>LKRLV(AM@RQgGoJwK6%fr! z8gpWUpFTzGt^X*}>W8ZS=XZ86<=N5Uq1`BpqN3smz}mU5Z~-QvYO1OQycQq3gLK%E z1-#b{Gwab*{`>1J{QUgIzRqLsX}Ugs{M_ykALzHcoPQq|8nb(7-+FXqpZ#lP6G6xE zMA$1sQ&5juvX&&TF#z zLP`2Y2zz0+?aBN#D9^WecoG3^Y~fy23mY41z>c^^P(6?*fMSt85f`s1wY9YgcrI&i z@9)2X6c~n>y2Z=;G%_-rh(-=&3p9Z-{@}ppoqEpWrB}wy0e4BROWfq)Io+FbvFlCa z1wzA|)C36_xI3yNVDXX2-QAt+Ng2OQf8;@p)085#+(ZITo;(R7EmXg0nHeJ_kZcXK z!?x!c3$g?DqwgrH9VedMP)Vc5jm*G}%xk6MHde_FJ{1K>f_2d;%}Pv$x)_ahHc@G# zkO8k=cH3E-N`=oM7^%z8X9?WyVXXoZpah!>>|`014(k=*#vsI+-Rbe+!rYuJs(Whc zg>j>gEZR5o(Fl#ct}bxGTw7=caEO|`%|hO4vq6EN!okD)LR1G461fTKo?IRC>J@#4 zbg&d`ay%gQQVe(VD=08p>gtz7#l>UFu<;bqT~%hfQ(jy9a;Btz3IayyyuwzWFJl&8xGa4$3C^#o65ze* z>gk!E&TlgWJSVK#0ie~&%1Xn_>%+kPf`S48%kE1E?(VKl=`2NfTOm&wSsuzKM4}e~ z!F33vw8%&E*cT)+21o}72cg8SO$xF>?a(tY7>2fnC2OYKBI12-R3tR2T?W9G7;TZEf!WGEmGl zc>G};I$p|6xG5r%25$&k=MffuQ&z^q$d-k*4YkjHDDMK+C8tM`OEoh=O!=C(Fliuq zFg~NjgF27dTT}j$!kNn;ACBKN_(~SrEQE!X^$TX0lu1$D)s^So3!ylW92A;PV7C~Z z`UF(&-LnIRUu8earlh9!=1VF!RUtWSxiSL-gB(|$>@ie5JNUT@#0y5^OY|;}&7gVN znXt)@@-EWI#g+8k4vpNt;gVP8xjd2s)qe23UZv&77Af32kf?h4`UFjq4r3ey7cUk7 z>5cJ$4wNR0A?clH_*@_A7aJC-kbj83U>J_ry4z=^GXi9B3XAs`}3qB-8UA|#_UfdWXpsGz7g z1W0VTe>?693;B6QUmFKlV`%+vyl!l(Sv0+q(c`nT^pyI$udnYQz`g?9C_#1P3+id& zWy#H%38@Qx@vhy84D&&E;K4~VIr4aJCNHpFi>gEFLfO*Plzx8T zczzqW^XKmFOJ_DVHp5WKkdoX^|8!tAkIS%@UdtIu`|Dh0Mt4`&OD)C5P5R$cac58n zCNTCTNT2Ewy~@LYywcM1`ExXCp!+EkVdm4lzkkWM?E9TrZrspxcdy`Z48le~d|>!c z2z`Ya4mSiBx&)lMy*qLHjh*cs{;dp8DbrSzUUP14ZlPhFd;6s%-D>+}p7YSz$)SCf z3^9|!KAWbbYUbvzmrQ4pu{2AKC3znP0Tp$dnV8TE{dR1hEBg0&Qj+#8duR#92b!Wx zG0%6csaY1E;(NsIUbu&i)_Md-)BJw6{e`BW| z91|mBs2gLTEDL61w!v|tVh76d5Fjb~(0gU<9ua0}c-X4)*G4<4(7367AY0h^dm?cV zf>Qj?%y2_M!V2vbcAC^C8W;4O0adT(+qYDdI&cC+T?iYi9w8BQ{;s=}8X1ZIbP*c= zFh`(}86}2wj4@1XY)YZKJ3Gt}Ssw%@h8w(HNcW&?Lddj!OHh;JW?q6}UzTLU0H3t? z`pd*3kRYOupc#3cBOftTaPP&^-r5v8$>#gr%Ab;cJBh?-kQBpuiRq+XMs8cb+ZB`n z#dE1WjPNoAg@T@*9^-p!XmD=I3G^VTO$?C!q9 zik#RmS-~~ zh}5=V16|$7mKb+`=!d<_x%NQjPvf__czk?3yS{!=N9P;kFff)hJ}UyKka(yx317a+ z8W$2E=FlL2X$O?ChUEw@$z93}_TR;MA)< z_S^^bo#VY*sLjaBOUld33xYpm79aBbFQU}I!v+og9?-aaVKIGBQD zI_50Ct*WBZ3DOsOLa8JeR-w%Om(tDTvmc6xG*CWmlA}%!Y9L%b4-e0!xuBC>9SQ%v z_v6kwpwlHFZ9L#Sh(SrNeQR@b48vGwm;3e#^sXyp?z_#kKqhzhT)hC5())dm4|uiNl67r3|Ac^YRnFSk(ILNj z#3LjW^u`Kr!D*TpVZ7swX5r@Q1V0F!pC^BSCdq5wiJ!!2Kxy?Q1t+oQY!;#@GAionnru>*cpygL z^z_IDex-17^wVRgfx4eYV}1^VvmOktO4!xUAB zcrz!bIN*=7upf~zG3+UL!a)4zvV2~-jbS{njVxJ_~LFNj^o9v!WJu?`K#6j}E2e)JHT* z#0!88AE!7-&je8FnC0Z<5mgw}hNI#iK9u*f5b7{&1_BV$#D+rad20mq2go`Qyt0SC zRUyx4fal{T3P=7KE2hQ0c=fHIaiH(!ELITa4=Y+xkr8qZ8g)<@<(_`EyOJR@J*%ea z2TR!sJ_CWo!{Y-t)Ii+@idJzu?5=#+J^YIoKaxlvhd`M!2bO>efjG(qq^0ID4H+YT zbXe!Lb_JTo80d-SVL9HKw493DJp|E4Ot^HB&b0}IXU7V)yLX?`^pJV4e{X}Rjd2R8 zt*bMesIY=EPT~B$_7N09EEG5u1C=&vJL^Aa!R6tszQ_d?=(q_SED(~bWYV6qsv%nO z*m9(dfiGoP0e=)yKlz^0GaA-=Tma%A_S0v^IW(pN!m3L)W^$XQr_!S!h6@`=1ulr# zs1R6wyJW$8Z}5Tej#t`{fE5-BawVd6n9tJ(pH^*2;XTMu)!KfOPS@8%YuC!1BYMFV zBngS&)5dYnvz3ZH|*;Pi<;$ljh5Qx;g5X^%XH<>4PJ}VfQZDex#zN zj%;mhJ!b}$ncdAt{`1ndi!b)yZl?5E8o}xCsMi02=0?<%TJg zR@gppLUE7?VPhizLirIYxT&*q{6_Q9MXdrAEL87HQF5>i$!(g6&qTDjq}h@QEI!7z0V|6|LIv0iQeKfgo}D#C{8Iq|ZLdoFFdG`+y4or;x`+5G%**keKG$4`*X4#M1;{NNM=sXsVjV`=$H_6aWH<9uC6J*<&T z+zLeO18Q1YCMG6%hh~A6z1oI`mDt;rblbbTUBWW~PeMb_=Nv&d-x;z7>OVEF`FSp* zdc=}LaLg9uj{Yo315?UFqhN;7i215y#ObK}+}oRUl9HLpx$^?F2iVGJm_l-P=CbZh zW585`V3-5-MZHkFtg@0_+ne&n!)NPzySo(EcenkY480tA50vx4Paf$FE!Jg1(l(F{ zme7oH4<4lOv_}6N?33wa3JVM6^p@NkbS9zB zw1Tr26cmKowjQPxunmDO6ZDr{b?o!qFXF&c?Sx|2C23+}VhG-JPEHQBn8!^>B?fC& zVj?0QyCLRsi8-UB1|g6>6F_%Byy)=o@TH;rF9z9s_I7qr5Z^g4et`_ez=aGWwxY+KU&t&^IiNmotS(P(6S2=+ObdVHw~fI7jz?R~G4%QdTZQGpqm> z0IHF8qT<5`MW}>`x3jRgI1h~`Nb&TH9C{V!!CnY~c>sjW&CZ5E_?to`!%ia`0XRHu zCrWeW%4^6H^TT%TmSaZTY0#oL1hMms8oYEXt%<>LoLgUy2dQg?XbO0^<8&hpaCpAd zPl%mTY)}Jr*8=dNZEWnrfB>}rj{%gKfRcjCmQ+VDy3iFvRR*UAg$&Y>Yn}Y52+N^7 zVm7?htGvNw+!%>a3^-$RKE#Kt9VyW+B!hv7cl=qvOLFw9?Q5YM28U3~*66)a10^tz zb13LcWH_7#$Go7)HU;|ve3j0wuBaoO5<^)u`aHay030>&QW`7y29x0V6m!ta!pH$5 z_zmZPJ#S@!K5$1(jeB!+8%mjZkA{p43T%bw`}<(Uv;!al%isj(^n79sy7H#vUrR9!-GS-sJK5Xe0^)%Z6B*(7>1h z(slRue+1m^Oe^B~)^+IS?k=}7R$LAqXx)<*SF_ z7PJpMkH0nGxf4>*yuG)l2$$}$SP7s$UhO~?d1ovev3}uMy>h@gpX&8@ArXbN^7&?`|g;LMl%?>pzcdDGF=rSSfKQ}9`He|6Ik#&EW!lDVg+ z2bhTTsauedka3E8@WR z*VUy4cQzh$jT~4PSI`Jneqddm?7{L?5`{8@oXh_HZLr+7fEf;Ih=_~lg60U0LRfXR zAW$_XcJDqGyp1as78U~bBlwVyKsh@=C>yMH&^g}yW+LLgfR6+*jHCdKT9F`}g{}(f z*(ICGDyJz*=;B`vGSIlVJXyq8_N7zVH95K=0R~3OCJ=w{40B;G-a>34RRH1z>>g|& zA7QDfshdB7q4FbEU0)wDAO=1mA^X_j&5dZpO2Z?$j`r{nKqw3BE&y|k+60KS9s(Ik zM<89mmC8UXWVtWcB4AwWI!E_gEl2$o(3N(SUZW2$E)jJIIN#>|FGcUDs34OfZlExL zFP-c5^W%7Ppg6<{Zy?44s3$g3R-mDtotwjwmX`Ja!+Ttr0TkpYP|v`B#0Fvmbp{Vo zfoZDYfwq5O_DG=?9&`(GDk`yw?09&1$6$XT9}{;)5Wo!&Dn~959#=1~k07a++kCwa zzmW$!7eqtQoQS|oDi1vJ+CiQumrn+9EmuP);d80Exf#S>Tre!ogDxr&bW9DTF(fnd z8V4sQGRFc4^I9?P3YagnSA-lRp{&h9kA{?ZAmpL&${d^~{AgO3lv>bxT{`G0Y)<1a z;DFoFo)Zxb-+5pekCgJ;>pfRGulPtyx5%j#fDpk46E0EW-s?#J0$fxPgd10Ap`c-Z z1zTr3-6(o|a$?0Q<n`^h$#Vrb)8|=qk~r zEvHw2r@l3);X+6VSi@IkjDv^4DR0^?(koT?gYGMXNv)5d2G9QbwVRMS3QvE8SCNtd zlS64@o@^guX`TQ{C{_;h%+V|y029kB1etaLSN&0OF(>pT;S}r-P~As-Z;R9*^caA( z%q=ZNLR&_F-8KV{A^-SMtR>ujxd=a$l0TxUh z@CXQWf|ucTxNW7Yug?e!DwYL;zBA7PQX5IUpFg!s(|6A}cCh^0o=K#lE?t+UYH{6eOo`HXWtt@pujIxUR+!ha9_A{MLI}AR7@9*4RuP@EtAr4c9vs&HYy z7?2~k*XdnO4#V0+WdulfVJ|chli_RdsXTCE78o0ull?S0T0MZFf99V&xD%O_m8A+~ zHYK0a2sRENO^8(J)~&m>FUP$45Zdz9p}x^nG7yslxF_JTq@KC^ z9mtEDv#c4+?I|w`s{XC0uFeOHA=k*FdIKEeQsVDP5AYBKK$)nhtRxp}hl;Z^0hKCHv~nx@NWPO$a>;2g|)v!?o4k2MA-ol3IH8* zcXNBXYxZnk=$_I1;^K|(eabq}S6cm+Af=d|NlQz+>^fJhY(n}gGvalrYNPAiW5@S6 zA#!qZORbNv=Yx%m%XS7?5Y3xs47wJ+uR$1}w$FWi`8b4>mqorQ*8`EX`YlP?^N9%3 z*gTfi2*#x5IZE66v7pwGB;V3fbf^ckNXh(G1vqfdrt+>%(AO7-U&X*Q$pzH9JaJ<> zg#>~ZuZdsr1x|^t+P9goxs8nkC^87ShH)`5q%$8W(jfunM7eSgP9_R$p^09f(*w`^ zwY9Z4z@8j%E>YW3`_41XP2-hvU@m=n#-iN$-nt{481#Wd^Ckx~E5J`0V1g6|9~|4D zf9SON3#e-b83Bz1xBK4>5Z~Q)mNZmeifHtTX}?v+f;V>ngX_v7q5s;^2e^yC2{cLw zEkY*vKDf+qjcF<>DD*VGzWiVjGZF?PEDuVJg*2m1|agb5t=`_y2L$aQs` z7l!+&K+}7qSqKNhfhpc7@C?kM!d2|nYEEJn3<|Z)VIT>CN)Qywp(Xv^;7x+eh{n?J zqZaz^C{<=DjQWC$f|Nv+bUuZVe2;e+(3UN)%j9uK4Czlm*jk*Op4bk)R(M*Wt!;F< zrWvHsO_;evM$iy?jEo+dn?EiwYG4E{1~>|Z3EYu*EgB53ayn*udKAnULOSU-`3ZhZ zpd$f=3E+_tW|x3qEKSvLhct2r4Xv8E{pubcr-ps)0&N~CohaXx$I@r;++XndIkK_0 zubzLeTYe6@?Au_*cAfxFq6YO58H0)85O-=37Zo)FB|x_&ND_KY*2XeHm+7l8fd-+6 zw=*4+=hDE&1#!>?Kk~TEqss$6|M+nYjAVq=fXBwr?zKE}0i>2Lo9sZ`hYuf8)6nDq zl|qg;R$|0H+=O(E1*(~BDNKN@k#P6uz#UQmbRHOTEAJeF31BFDBCfL`B2KjsM4)&i z9Au0Y>2SlClG=xt^G?eOCfm|eEy2OCYdRx(AOo6OTjM4xg&|G9xYuec6g4v|D;yYi zLdqf>4d#Oko+=NANR(>9T2&wfhzE!Y$Oh3?Y_O{A58k&z^dRG)$dbZH5^@-bM$`f) zVRCaXurn$U!`iCshS7ltLxal&-kQqcvY}LhNEU%ddvnrfha}+V!K5le^Fl*IO+ikp zDD8pD4x#*MC|_CO$Ac0>8qiofn*)z5-}F({IKNRze+*g%GPW#zyonujv?dJ3=Ox64 zG^_fv0^P9bOmpB8_|qYcyxkD?gD}CPcYH5H0O<`Dzh-mq*&Q4ln8Jwk0RSX#z=3O~ zZ+~_$l%yt)d8pjcu!k04xXYOw!q7HMURH3UF-s~&bI>;TLYbt zo`Zwv=f^m5lUNuWM2-za^~;{+?w?^iWbuH9nOa(&hlto&`9=c5+(%@J#}}zl@U)-v zP(?r^5pWn&`5hg5rf?aZM9{k9blteZ@&c3`gjY6Y+kw{&64TChEjbkx>z=2sfq{I! zCIe`=!1zJJ0U}0AX|r=j11&Y;$$TpWo2bhW6IHY za@1QVC-w2wprZrqlSP+RRItrzAOnG5CYDuIU8W^u*?$AQG9Oi37z{=}0v3Zz)eQ_> z0^tVqLTJ3GUNkb}yl0Ply`AymMa;s2r6mkKx3|C6oxa5ko)*ZzY*${EY{P((jJ-V@ z5Kl8xQxqfFN)&WR$P_B5Lvwlx4|`sg?B7vUg{c+XNPL(h({Gx-W5qOT;nt)HvJuix zQZpQWQU5C$B9YJD6V0q6V;qrf(gwq)hzOmMk^-dwW)kJVP8|OY?VcI2`O+D&=?TF#8&PDlqh$XGSk&>bM_=cp1f6N zB>M`c4k*p^oSejPvG56q1OjSqKW4z=zP-KuJI_iRYwH`Jf&g@#d-(9L93EGCdb)WF zj7B9-8-J|&BY6+>oy3!lo2DGVYH+N}mD(=6MPhAj4WrH-NH2+w14^DH;j8(o ziIfx$_B1&eM@ws1Zr>PwBqNhShmDCQvVPMP2O@*hIDTh?;n#iIX94;K1|6-fGNodv zFaY#T>7(11i9kfffO) zP~ii`+zhVeehE+lQaZZQ%7h{G@;)IuU7)3oNhbcWPR-qYc&V#G(8!&5X^iE;g9r4C za7uQ985=N2WH`D9X#ps6Gi8u%_h=HMeZk2Bx9|+cb(5=WAUUG%lED-feC6VfgYR;# zO`iL+1-T);dKhGtfse)CZ*Kf-RO^Z*D=TY$_D9+bx=x7kHke|b7K*MS@gs@+ARArK zMxWy#qeab@{H|4z-s!X6H%Bdv7m-kBkSWuxmh$o~1LDckBu94PY6X6)_9>Z~hSWm+P#zoxYf~cXz)XNWbm0!Jsix(01%;XKSnb zipXQMPH3n2%P~Qfh}{yOV^y^ps@*`vjQYxz<?&k2+jR|KR zZ|l9pa&_BvHnTF;emV4aqdn@8)SAA*)Zl0eOY{&wru)9z&3Hqs$=$a%Kz-8>=3Z{v z{u2Aar>Z9z#HZ;qVJ5qUk(HNo;;#$F3H*o2*$l;%|s4$xJ>Do&(vBI@~O6=r`2) zgVoBfp{zIPU3&04cw)I=d~XJHIHiG^e)RQZ%pa{HF;$GXenC3pl2{oe*zXhW{bYO#E!}lUKb{8DN%}#4THnWBC z6%dggLkgAGoydz`YXlh(`3}j-2h9-Tf6hoe{7WOt?MyX=97Ci-1l(g8xu_JiNl3JOZ3N zyxM$xVgiC<0>bP(d}2I2mf^ij|Kkl#E|zxIzW?VpP)vDb!y9OjPtbC)_V6}yw?fHU ix|mzh-*qyxvC_0Mv-EZAv66s4LfutRMVH8#KK@_O6qZx~ literal 0 HcmV?d00001 diff --git a/framework-docs/modules/ROOT/assets/images/spring-mvc-and-webflux-venn.png b/framework-docs/modules/ROOT/assets/images/spring-mvc-and-webflux-venn.png new file mode 100644 index 0000000000000000000000000000000000000000..6e0eeab744d4fc06d5315072a9da91815a79cef0 GIT binary patch literal 104380 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%0D>fHS=#@hC z$ja|#`vLB_^Lk0QOcb-{GAZ9&sb8M$7Rea|f>=Qa-n+9RF~#L@#WH1d>;;xjBdKnA zdqt#6vh%FAU>i2$i~&NDf=^(sa|ryiV#5aM+KP#8552}f7nI}|mNfo7P2Kv#l4V!k)LVjca`DY5PtEl0-BIak8CQ2^V|RxffXW@~_XBSa z=*YCTSW)4pl?4E@H@=O>$slx!3KF?}N#1x3s&}s|z}*tz7%51RtfKE{&HzvckG^Bf zsBSnCi9{>_(Bd+$y636cpZ#}nRWrVR4q!3L0g$BCIjb_pv)g0=6lQc8_GQV)bPOA!vWGzsjHl;na9% zLu&+Toi02e*g_A5k5E%AtLASyAOv%QdRo+^~74I7O%{fgpAQ0PoMM z889Lz_E&C>;yPv0DaBbDG|!64C9+(zbK?VVEZZCAPDRpWNs|dS!f!3!RIS^J(>*fB z+dwNKMZyZfibNENC0 zmB5al*8TpwDo`LbDXDFuR(IyI=1q9$iUC;~uFBtk^Gjd$> z{dVPj?=1PpyYv4vdmqRW#u!CvXDr_ILt*e(37Ie<<$HGA{MynjeyS;wrbwDBNoMf5 z8Jo%xBjCJfKqj_MzzapfcyjiUx6Nz}Gi zY}*^K52Uf&v}M=KwZ#@XcO(|)JTBg8S=2P`=D!=lL>heM11^A%AHDhOZM7bkQ&ALI zR#a6(;rzcn_IyDo8sFuDJ0^BCqNiRSZYbHmxPDRsfxM6J`Pav*C5Ka0Raur5Rdc%J zr60Zg)tUlD#x`@c&rJYkRP0(CwiJR8=NtgZiUaY0KS+;~G6(<=Sh^)ElA@}LggF34 z=H_Kz&irDrE<14JE@B8r3#UDL_ov@)(^OT}9Ga$SPEY05FQPnNu{kIZ#7Y1VR8|sHRg#e8jQPc-<|r{j&^BIOl^@KBQ_u9F0HHWkd)I4A zzp5geDyuH;-@a3l77a&MuHW^|?n=AbxZsK*1CwOivg<1ph?f0v+9G7vc|mZ?w#%ym z`$}tfR0JWy296o>kLw1sb;8k35=64g_y6$&qyG8ajM){{{`I>niVYix=f11@XUMi; z0|3~Rb?DLK)BEtRr+vR_+wKQms_4}rV`#^;ET2j^E3d9zxjBDTUR5~4MqM)I|GT_@UIBk^T1njUSrU&=U@+5_@yz${)5wZ>+4EFraO>B$sVOR&L0fyS>5= zo0m+!=!!Hr5X0V7k#2tbQ(?rQ?!<&kx+GSIj7Ggf9IEfS?y28@SFn0V(WVN0NUAeZ zyz!R5FDNFCyM8g@i7}b>x#CoU35rW_M#84-Yk{m^XyEwkZ@O^Sf97wTdgFylufFBH zA-&?9s621O*I!Pb_uWri?)>=k&u8MOZpR=?fUQT{kH7Dsd%pkuD+^zmI(f(H8^)eD zEF(THQnPRQ+>bw-F~{%wU;7_d^u*S=}$W(0sue(GP407fAg~0vu5{B z2o**WFTG?WwIRK20s!B>ZvM>AMs?Bl@2TlL`PxBt!~g(Eb6;@r71RIs(?1{lRka^= z8$WVj=M2tl0OXXy?>+mcC#QWOXLO(Xk58{3+x9>wKM^Q{lAtv(Sw$kZs6Y@SOoNsd z1_m~R`Kq}D762r-6pPU~noa5;BV_4*hN9JYcUO(kGGroNDZ(qGF5rP@DDP=&~zB+Se4=rRE zEOEduXT0>�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 W{axHN!6Om?0000IBV9Nv(J7$ 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 literal 0 HcmV?d00001 diff --git a/framework-docs/modules/ROOT/assets/images/tx_prop_required.png b/framework-docs/modules/ROOT/assets/images/tx_prop_required.png new file mode 100644 index 0000000000000000000000000000000000000000..218790aca6351fea6a1154a725271452e16d74a2 GIT binary patch literal 40355 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�xArjG;*L9a!*%gnl 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 z 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 rsz`nQ=|eu*f8QFy;I>#NnMSV#R2DnxSW literal 0 HcmV?d00001 diff --git a/framework-docs/src/docs/asciidoc/appendix.adoc b/framework-docs/modules/ROOT/pages/appendix.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/appendix.adoc rename to framework-docs/modules/ROOT/pages/appendix.adoc diff --git a/framework-docs/src/docs/asciidoc/attributes.adoc b/framework-docs/modules/ROOT/pages/attributes.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/attributes.adoc rename to framework-docs/modules/ROOT/pages/attributes.adoc diff --git a/framework-docs/src/docs/asciidoc/core.adoc b/framework-docs/modules/ROOT/pages/core.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core.adoc rename to framework-docs/modules/ROOT/pages/core.adoc diff --git a/framework-docs/src/docs/asciidoc/core/aop-api.adoc b/framework-docs/modules/ROOT/pages/core/aop-api.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/aop-api.adoc rename to framework-docs/modules/ROOT/pages/core/aop-api.adoc diff --git a/framework-docs/src/docs/asciidoc/core/aop.adoc b/framework-docs/modules/ROOT/pages/core/aop.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/aop.adoc rename to framework-docs/modules/ROOT/pages/core/aop.adoc diff --git a/framework-docs/src/docs/asciidoc/core/aot.adoc b/framework-docs/modules/ROOT/pages/core/aot.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/aot.adoc rename to framework-docs/modules/ROOT/pages/core/aot.adoc diff --git a/framework-docs/src/docs/asciidoc/core/appendix.adoc b/framework-docs/modules/ROOT/pages/core/appendix.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/appendix.adoc rename to framework-docs/modules/ROOT/pages/core/appendix.adoc diff --git a/framework-docs/src/docs/asciidoc/core/beans.adoc b/framework-docs/modules/ROOT/pages/core/beans.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/beans.adoc rename to framework-docs/modules/ROOT/pages/core/beans.adoc diff --git a/framework-docs/src/docs/asciidoc/core/databuffer-codec.adoc b/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/databuffer-codec.adoc rename to framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc diff --git a/framework-docs/src/docs/asciidoc/core/expressions.adoc b/framework-docs/modules/ROOT/pages/core/expressions.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/expressions.adoc rename to framework-docs/modules/ROOT/pages/core/expressions.adoc diff --git a/framework-docs/src/docs/asciidoc/core/null-safety.adoc b/framework-docs/modules/ROOT/pages/core/null-safety.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/null-safety.adoc rename to framework-docs/modules/ROOT/pages/core/null-safety.adoc diff --git a/framework-docs/src/docs/asciidoc/core/resources.adoc b/framework-docs/modules/ROOT/pages/core/resources.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/resources.adoc rename to framework-docs/modules/ROOT/pages/core/resources.adoc diff --git a/framework-docs/src/docs/asciidoc/core/spring-jcl.adoc b/framework-docs/modules/ROOT/pages/core/spring-jcl.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/spring-jcl.adoc rename to framework-docs/modules/ROOT/pages/core/spring-jcl.adoc diff --git a/framework-docs/src/docs/asciidoc/core/validation.adoc b/framework-docs/modules/ROOT/pages/core/validation.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/core/validation.adoc rename to framework-docs/modules/ROOT/pages/core/validation.adoc diff --git a/framework-docs/src/docs/asciidoc/data-access.adoc b/framework-docs/modules/ROOT/pages/data-access.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/data-access.adoc rename to framework-docs/modules/ROOT/pages/data-access.adoc diff --git a/framework-docs/src/docs/asciidoc/data-access/appendix.adoc b/framework-docs/modules/ROOT/pages/data-access/appendix.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/data-access/appendix.adoc rename to framework-docs/modules/ROOT/pages/data-access/appendix.adoc diff --git a/framework-docs/src/docs/asciidoc/index.adoc b/framework-docs/modules/ROOT/pages/index.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/index.adoc rename to framework-docs/modules/ROOT/pages/index.adoc diff --git a/framework-docs/src/docs/asciidoc/integration.adoc b/framework-docs/modules/ROOT/pages/integration.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration.adoc rename to framework-docs/modules/ROOT/pages/integration.adoc diff --git a/framework-docs/src/docs/asciidoc/integration/appendix.adoc b/framework-docs/modules/ROOT/pages/integration/appendix.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration/appendix.adoc rename to framework-docs/modules/ROOT/pages/integration/appendix.adoc diff --git a/framework-docs/src/docs/asciidoc/integration/cache.adoc b/framework-docs/modules/ROOT/pages/integration/cache.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration/cache.adoc rename to framework-docs/modules/ROOT/pages/integration/cache.adoc diff --git a/framework-docs/src/docs/asciidoc/integration/email.adoc b/framework-docs/modules/ROOT/pages/integration/email.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration/email.adoc rename to framework-docs/modules/ROOT/pages/integration/email.adoc diff --git a/framework-docs/src/docs/asciidoc/integration/jms.adoc b/framework-docs/modules/ROOT/pages/integration/jms.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration/jms.adoc rename to framework-docs/modules/ROOT/pages/integration/jms.adoc diff --git a/framework-docs/src/docs/asciidoc/integration/jmx.adoc b/framework-docs/modules/ROOT/pages/integration/jmx.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration/jmx.adoc rename to framework-docs/modules/ROOT/pages/integration/jmx.adoc diff --git a/framework-docs/src/docs/asciidoc/integration/observability.adoc b/framework-docs/modules/ROOT/pages/integration/observability.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration/observability.adoc rename to framework-docs/modules/ROOT/pages/integration/observability.adoc diff --git a/framework-docs/src/docs/asciidoc/integration/rest-clients.adoc b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration/rest-clients.adoc rename to framework-docs/modules/ROOT/pages/integration/rest-clients.adoc diff --git a/framework-docs/src/docs/asciidoc/integration/scheduling.adoc b/framework-docs/modules/ROOT/pages/integration/scheduling.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/integration/scheduling.adoc rename to framework-docs/modules/ROOT/pages/integration/scheduling.adoc diff --git a/framework-docs/src/docs/asciidoc/languages.adoc b/framework-docs/modules/ROOT/pages/languages.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/languages.adoc rename to framework-docs/modules/ROOT/pages/languages.adoc diff --git a/framework-docs/src/docs/asciidoc/languages/dynamic.adoc b/framework-docs/modules/ROOT/pages/languages/dynamic.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/languages/dynamic.adoc rename to framework-docs/modules/ROOT/pages/languages/dynamic.adoc diff --git a/framework-docs/src/docs/asciidoc/languages/groovy.adoc b/framework-docs/modules/ROOT/pages/languages/groovy.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/languages/groovy.adoc rename to framework-docs/modules/ROOT/pages/languages/groovy.adoc diff --git a/framework-docs/src/docs/asciidoc/languages/kotlin.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/languages/kotlin.adoc rename to framework-docs/modules/ROOT/pages/languages/kotlin.adoc diff --git a/framework-docs/src/docs/asciidoc/overview.adoc b/framework-docs/modules/ROOT/pages/overview.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/overview.adoc rename to framework-docs/modules/ROOT/pages/overview.adoc diff --git a/framework-docs/src/docs/asciidoc/page-layout.adoc b/framework-docs/modules/ROOT/pages/page-layout.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/page-layout.adoc rename to framework-docs/modules/ROOT/pages/page-layout.adoc diff --git a/framework-docs/src/docs/asciidoc/rsocket.adoc b/framework-docs/modules/ROOT/pages/rsocket.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/rsocket.adoc rename to framework-docs/modules/ROOT/pages/rsocket.adoc diff --git a/framework-docs/src/docs/asciidoc/testing.adoc b/framework-docs/modules/ROOT/pages/testing.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing.adoc rename to framework-docs/modules/ROOT/pages/testing.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/annotations.adoc b/framework-docs/modules/ROOT/pages/testing/annotations.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/annotations.adoc rename to framework-docs/modules/ROOT/pages/testing/annotations.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/appendix.adoc b/framework-docs/modules/ROOT/pages/testing/appendix.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/appendix.adoc rename to framework-docs/modules/ROOT/pages/testing/appendix.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/integration.adoc b/framework-docs/modules/ROOT/pages/testing/integration.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/integration.adoc rename to framework-docs/modules/ROOT/pages/testing/integration.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/introduction.adoc b/framework-docs/modules/ROOT/pages/testing/introduction.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/introduction.adoc rename to framework-docs/modules/ROOT/pages/testing/introduction.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/resources.adoc b/framework-docs/modules/ROOT/pages/testing/resources.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/resources.adoc rename to framework-docs/modules/ROOT/pages/testing/resources.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/spring-mvc-test-client.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-client.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/spring-mvc-test-client.adoc rename to framework-docs/modules/ROOT/pages/testing/spring-mvc-test-client.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/spring-mvc-test-framework.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/spring-mvc-test-framework.adoc rename to framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/support-jdbc.adoc b/framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/support-jdbc.adoc rename to framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/testcontext-framework.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/testcontext-framework.adoc rename to framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/unit.adoc b/framework-docs/modules/ROOT/pages/testing/unit.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/unit.adoc rename to framework-docs/modules/ROOT/pages/testing/unit.adoc diff --git a/framework-docs/src/docs/asciidoc/testing/webtestclient.adoc b/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/testing/webtestclient.adoc rename to framework-docs/modules/ROOT/pages/testing/webtestclient.adoc diff --git a/framework-docs/src/docs/asciidoc/web-reactive.adoc b/framework-docs/modules/ROOT/pages/web-reactive.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web-reactive.adoc rename to framework-docs/modules/ROOT/pages/web-reactive.adoc diff --git a/framework-docs/src/docs/asciidoc/web.adoc b/framework-docs/modules/ROOT/pages/web.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web.adoc rename to framework-docs/modules/ROOT/pages/web.adoc diff --git a/framework-docs/src/docs/asciidoc/web/integration.adoc b/framework-docs/modules/ROOT/pages/web/integration.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/integration.adoc rename to framework-docs/modules/ROOT/pages/web/integration.adoc diff --git a/framework-docs/src/docs/asciidoc/web/web-data-binding-model-design.adoc b/framework-docs/modules/ROOT/pages/web/web-data-binding-model-design.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/web-data-binding-model-design.adoc rename to framework-docs/modules/ROOT/pages/web/web-data-binding-model-design.adoc diff --git a/framework-docs/src/docs/asciidoc/web/web-uris.adoc b/framework-docs/modules/ROOT/pages/web/web-uris.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/web-uris.adoc rename to framework-docs/modules/ROOT/pages/web/web-uris.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webflux-cors.adoc b/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webflux-cors.adoc rename to framework-docs/modules/ROOT/pages/web/webflux-cors.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webflux-functional.adoc b/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webflux-functional.adoc rename to framework-docs/modules/ROOT/pages/web/webflux-functional.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webflux-view.adoc b/framework-docs/modules/ROOT/pages/web/webflux-view.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webflux-view.adoc rename to framework-docs/modules/ROOT/pages/web/webflux-view.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webflux-webclient.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webflux-webclient.adoc rename to framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webflux-websocket.adoc b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webflux-websocket.adoc rename to framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webflux.adoc b/framework-docs/modules/ROOT/pages/web/webflux.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webflux.adoc rename to framework-docs/modules/ROOT/pages/web/webflux.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webmvc-client.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webmvc-client.adoc rename to framework-docs/modules/ROOT/pages/web/webmvc-client.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webmvc-cors.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webmvc-cors.adoc rename to framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webmvc-functional.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webmvc-functional.adoc rename to framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webmvc-test.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webmvc-test.adoc rename to framework-docs/modules/ROOT/pages/web/webmvc-test.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webmvc-view.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webmvc-view.adoc rename to framework-docs/modules/ROOT/pages/web/webmvc-view.adoc diff --git a/framework-docs/src/docs/asciidoc/web/webmvc.adoc b/framework-docs/modules/ROOT/pages/web/webmvc.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/webmvc.adoc rename to framework-docs/modules/ROOT/pages/web/webmvc.adoc diff --git a/framework-docs/src/docs/asciidoc/web/websocket-intro.adoc b/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/websocket-intro.adoc rename to framework-docs/modules/ROOT/pages/web/websocket-intro.adoc diff --git a/framework-docs/src/docs/asciidoc/web/websocket.adoc b/framework-docs/modules/ROOT/pages/web/websocket.adoc similarity index 100% rename from framework-docs/src/docs/asciidoc/web/websocket.adoc rename to framework-docs/modules/ROOT/pages/web/websocket.adoc From 34856b33e95827134b8471fb662a12b833bd023e Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:23:59 -0500 Subject: [PATCH 07/31] Insert explicit ids for headers --- .../modules/ROOT/pages/core/appendix.adoc | 2 +- .../modules/ROOT/pages/core/null-safety.adoc | 2 ++ framework-docs/modules/ROOT/pages/index.adoc | 1 + .../modules/ROOT/pages/integration/cache.adoc | 1 + .../ROOT/pages/integration/scheduling.adoc | 1 + .../modules/ROOT/pages/languages/kotlin.adoc | 24 +++++++++++++++++++ .../modules/ROOT/pages/page-layout.adoc | 2 +- .../pages/testing/testcontext-framework.adoc | 9 +++++++ .../modules/ROOT/pages/web/web-uris.adoc | 3 +++ .../ROOT/pages/web/webflux-functional.adoc | 1 + .../ROOT/pages/web/webflux-webclient.adoc | 1 + .../modules/ROOT/pages/web/webflux.adoc | 6 +++++ .../ROOT/pages/web/webmvc-functional.adoc | 1 + .../modules/ROOT/pages/web/webmvc.adoc | 1 + .../ROOT/pages/web/websocket-intro.adoc | 3 +++ .../modules/ROOT/pages/web/websocket.adoc | 2 ++ 16 files changed, 58 insertions(+), 2 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/core/appendix.adoc b/framework-docs/modules/ROOT/pages/core/appendix.adoc index 0477c35aad1b..094ec6a11ee4 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix.adoc @@ -1667,4 +1667,4 @@ its behavior changes. | `spring.context.refresh` | Application context refresh phase. | -|=== \ No newline at end of file +|=== diff --git a/framework-docs/modules/ROOT/pages/core/null-safety.adoc b/framework-docs/modules/ROOT/pages/core/null-safety.adoc index ffed936d8407..2e649691ab4e 100644 --- a/framework-docs/modules/ROOT/pages/core/null-safety.adoc +++ b/framework-docs/modules/ROOT/pages/core/null-safety.adoc @@ -30,6 +30,7 @@ Spring application developers. +[[use-cases]] == Use cases In addition to providing an explicit declaration for Spring Framework API nullability, @@ -43,6 +44,7 @@ are available in the <>, @@ -942,6 +960,7 @@ class OrderServiceIntegrationTests(val orderService: OrderService, ==== +[[per_class-lifecycle]] ==== `PER_CLASS` Lifecycle Kotlin lets you specify meaningful test function names between backticks (```). @@ -986,6 +1005,7 @@ class IntegrationTests { ---- +[[specification-like-tests]] ==== Specification-like Tests You can create specification-like tests with JUnit 5 and Kotlin. @@ -1036,6 +1056,7 @@ https://spring.io/guides/tutorials/spring-boot-kotlin/[the dedicated tutorial]. +[[start-spring-io]] === `start.spring.io` The easiest way to start a new Spring Framework project in Kotlin is to create a new Spring @@ -1043,6 +1064,7 @@ Boot 2 project on https://start.spring.io/#!language=kotlin&type=gradle-project[ +[[choosing-the-web-flavor]] === Choosing the Web Flavor Spring Framework now comes with two different web stacks: <> and @@ -1073,6 +1095,7 @@ Kotlin and the Spring Framework: +[[examples]] === Examples The following Github projects offer examples that you can learn from and possibly even extend: @@ -1087,6 +1110,7 @@ The following Github projects offer examples that you can learn from and possibl +[[issues]] === Issues The following list categorizes the pending issues related to Spring and Kotlin support: diff --git a/framework-docs/modules/ROOT/pages/page-layout.adoc b/framework-docs/modules/ROOT/pages/page-layout.adoc index d7209280b2a6..4ed56e085570 100644 --- a/framework-docs/modules/ROOT/pages/page-layout.adoc +++ b/framework-docs/modules/ROOT/pages/page-layout.adoc @@ -1,4 +1,4 @@ :toc: left :toclevels: 4 :tabsize: 4 -:docinfo1: \ No newline at end of file +:docinfo1: diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc index 0fabda612d63..b1d41eda4fb8 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc @@ -38,6 +38,7 @@ test execution by providing dependency injection, managing transactions, and so class. See the {api-spring-framework}/test/context/package-summary.html[javadoc] and the Spring test suite for further information and examples of various implementations. +[[testcontext]] === `TestContext` `TestContext` encapsulates the context in which a test is run (agnostic of the @@ -45,6 +46,7 @@ actual testing framework in use) and provides context management and caching sup the test instance for which it is responsible. The `TestContext` also delegates to a `SmartContextLoader` to load an `ApplicationContext` if requested. +[[testcontextmanager]] === `TestContextManager` `TestContextManager` is the main entry point into the Spring TestContext Framework and is @@ -59,11 +61,13 @@ responsible for managing a single `TestContext` and signaling events to each reg * After any "`after`" or "`after each`" methods of a particular testing framework. * After any "`after class`" or "`after all`" methods of a particular testing framework. +[[testexecutionlistener]] === `TestExecutionListener` `TestExecutionListener` defines the API for reacting to test-execution events published by the `TestContextManager` with which the listener is registered. See <>. +[[context-loaders]] === Context Loaders `ContextLoader` is a strategy interface for loading an `ApplicationContext` for an @@ -1732,6 +1736,7 @@ through the `getPropertySourceLocations()` and `getPropertySourceProperties()` m `MergedContextConfiguration`. ==== +[[declaring-test-property-sources]] ==== Declaring Test Property Sources You can configure test properties files by using the `locations` or `value` attribute of @@ -1829,6 +1834,7 @@ meta-annotation. ==== +[[default-properties-file-detection]] ==== Default Properties File Detection If `@TestPropertySource` is declared as an empty annotation (that is, without explicit @@ -1838,6 +1844,7 @@ if the annotated test class is `com.example.MyTest`, the corresponding default p file is `classpath:com/example/MyTest.properties`. If the default cannot be detected, an `IllegalStateException` is thrown. +[[precedence]] ==== Precedence Test properties have higher precedence than those defined in the operating system's @@ -1881,6 +1888,7 @@ to specify properties both in a file and inline: } ---- +[[inheriting-and-overriding-test-property-sources]] ==== Inheriting and Overriding Test Property Sources `@TestPropertySource` supports boolean `inheritLocations` and `inheritProperties` @@ -2062,6 +2070,7 @@ properties. } ---- +[[precedence]] ==== Precedence Dynamic properties have higher precedence than those loaded from `@TestPropertySource`, diff --git a/framework-docs/modules/ROOT/pages/web/web-uris.adoc b/framework-docs/modules/ROOT/pages/web/web-uris.adoc index 26027a1a8d0d..05b427a99ab1 100644 --- a/framework-docs/modules/ROOT/pages/web/web-uris.adoc +++ b/framework-docs/modules/ROOT/pages/web/web-uris.adoc @@ -1,4 +1,5 @@ [id={chapter}.web-uricomponents] +[[uricomponents]] = UriComponents [.small]#Spring MVC and Spring WebFlux# @@ -102,6 +103,7 @@ You can shorten it further still with a full URI template, as the following exam [id={chapter}.web-uribuilder] +[[uribuilder]] = UriBuilder [.small]#Spring MVC and Spring WebFlux# @@ -194,6 +196,7 @@ that holds configuration and preferences, as the following example shows: [id={chapter}.web-uri-encoding] +[[uri-encoding]] = URI Encoding [.small]#Spring MVC and Spring WebFlux# diff --git a/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc b/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc index 4ebf6b429465..882c68200d7f 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc @@ -619,6 +619,7 @@ RouterFunction route = route() <4> `otherRoute` is a router function that is created elsewhere, and added to the route built. +[[nested-routes]] === Nested Routes It is common for a group of router functions to have a shared predicate, for instance a diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc index 34337a18a15e..6116d9273be3 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc @@ -869,6 +869,7 @@ inline-style, through the built-in `BodyInserters`, as the following example sho .awaitBody() ---- +[[partevent]] ==== `PartEvent` To stream multipart data sequentially, you can provide multipart content through `PartEvent` diff --git a/framework-docs/modules/ROOT/pages/web/webflux.adoc b/framework-docs/modules/ROOT/pages/web/webflux.adoc index 1bc6f9dabc31..8f771502e369 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux.adoc @@ -1,5 +1,6 @@ [[webflux]] :chapter: webflux +[[spring-webflux]] = Spring WebFlux The original web framework included in the Spring Framework, Spring Web MVC, was @@ -248,6 +249,7 @@ current thread (and rely on callbacks instead) means that you do not need extra there are no blocking calls to absorb. +[[invoking-a-blocking-api]] ==== Invoking a Blocking API What if you do need to use a blocking library? Both Reactor and RxJava provide the @@ -255,6 +257,7 @@ What if you do need to use a blocking library? Both Reactor and RxJava provide t easy escape hatch. Keep in mind, however, that blocking APIs are not a good fit for this concurrency model. +[[mutable-state]] ==== Mutable State In Reactor and RxJava, you declare logic through operators. At runtime, a reactive @@ -262,6 +265,7 @@ pipeline is formed where data is processed sequentially, in distinct stages. A k of this is that it frees applications from having to protect mutable state because application code within that pipeline is never invoked concurrently. +[[threading-model]] ==== Threading Model What threads should you expect to see on a server running with Spring WebFlux? @@ -287,6 +291,7 @@ specific thread pool `Scheduler` strategy. * Data access libraries and other third party dependencies can also create and use threads of their own. +[[configuring]] ==== Configuring The Spring Framework does not provide support for starting and stopping @@ -2841,6 +2846,7 @@ as the following example shows: <1> Using `@RequestBody`. -- +[[partevent]] ===== `PartEvent` To access multipart data sequentially, in a streaming fashion, you can use `@RequestBody` with diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc index 07178eaecfe9..2dc31aa9b7d9 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc @@ -599,6 +599,7 @@ The following example shows the composition of four routes: <4> `otherRoute` is a router function that is created elsewhere, and added to the route built. +[[nested-routes]] === Nested Routes It is common for a group of router functions to have a shared predicate, for instance a shared diff --git a/framework-docs/modules/ROOT/pages/web/webmvc.adoc b/framework-docs/modules/ROOT/pages/web/webmvc.adoc index 2e10ae6abb9e..9f732da708ea 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc.adoc @@ -1,5 +1,6 @@ [[mvc]] :chapter: mvc +[[spring-web-mvc]] = Spring Web MVC Spring Web MVC is the original web framework built on the Servlet API and has been included diff --git a/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc b/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc index 0c2b09685859..0b06b00b7244 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc @@ -1,4 +1,5 @@ [id={chapter}.websocket-intro] +[[introduction-to-websocket]] = Introduction to WebSocket The WebSocket protocol, https://tools.ietf.org/html/rfc6455[RFC 6455], provides a standardized @@ -55,6 +56,7 @@ instructions of the cloud provider related to WebSocket support. [id={chapter}.websocket-intro-architecture] +[[http-versus-websocket]] == HTTP Versus WebSocket Even though WebSocket is designed to be HTTP-compatible and starts with an HTTP request, @@ -81,6 +83,7 @@ In the absence of that, they need to come up with their own conventions. [id={chapter}.websocket-intro-when-to-use] +[[when-to-use-websockets]] == When to Use WebSockets WebSockets can make a web page be dynamic and interactive. However, in many cases, diff --git a/framework-docs/modules/ROOT/pages/web/websocket.adoc b/framework-docs/modules/ROOT/pages/web/websocket.adoc index 48832aa3f388..94196410daf1 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket.adoc @@ -1226,6 +1226,7 @@ referenced through `@DestinationVariable` method arguments. Applications can als a dot-separated destination convention for mappings, as explained in <>. +[[supported-method-arguments]] ===== Supported Method Arguments The following table describes the method arguments: @@ -1270,6 +1271,7 @@ Values are converted to the declared method argument type as necessary. |=== +[[return-values]] ===== Return Values By default, the return value from a `@MessageMapping` method is serialized to a payload From c346e732b06df57a01b0c137b619997f9fc97cf6 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:24:00 -0500 Subject: [PATCH 08/31] Remove unnecessary asciidoc attributes --- framework-docs/modules/ROOT/pages/overview.adoc | 2 -- framework-docs/modules/ROOT/pages/page-layout.adoc | 2 -- 2 files changed, 4 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/overview.adoc b/framework-docs/modules/ROOT/pages/overview.adoc index 7508ad354957..61b3b5bec02f 100644 --- a/framework-docs/modules/ROOT/pages/overview.adoc +++ b/framework-docs/modules/ROOT/pages/overview.adoc @@ -1,8 +1,6 @@ [[overview]] = Spring Framework Overview include::attributes.adoc[] -:toc: left -:toclevels: 1 :docinfo1: Spring makes it easy to create Java enterprise applications. It provides everything you diff --git a/framework-docs/modules/ROOT/pages/page-layout.adoc b/framework-docs/modules/ROOT/pages/page-layout.adoc index 4ed56e085570..92b4582968f7 100644 --- a/framework-docs/modules/ROOT/pages/page-layout.adoc +++ b/framework-docs/modules/ROOT/pages/page-layout.adoc @@ -1,4 +1,2 @@ -:toc: left -:toclevels: 4 :tabsize: 4 :docinfo1: From eb37a2ec74d338f81296b19c699fd96b0ffb3320 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:24:00 -0500 Subject: [PATCH 09/31] Fix image::image --- framework-docs/modules/ROOT/pages/core/aop.adoc | 4 ++-- framework-docs/modules/ROOT/pages/core/beans.adoc | 6 +++--- framework-docs/modules/ROOT/pages/data-access.adoc | 10 +++++----- framework-docs/modules/ROOT/pages/web/webflux.adoc | 2 +- framework-docs/modules/ROOT/pages/web/webmvc.adoc | 2 +- framework-docs/modules/ROOT/pages/web/websocket.adoc | 4 ++-- 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/core/aop.adoc b/framework-docs/modules/ROOT/pages/core/aop.adoc index 2ab57095200c..be7e6b7d9630 100644 --- a/framework-docs/modules/ROOT/pages/core/aop.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop.adoc @@ -3173,7 +3173,7 @@ code snippet shows: If you invoke a method on an object reference, the method is invoked directly on that object reference, as the following image and listing show: -image::images/aop-proxy-plain-pojo-call.png[] +image::aop-proxy-plain-pojo-call.png[] [source,java,indent=0,subs="verbatim",role="primary"] .Java @@ -3200,7 +3200,7 @@ image::images/aop-proxy-plain-pojo-call.png[] Things change slightly when the reference that client code has is a proxy. Consider the following diagram and code snippet: -image::images/aop-proxy-call.png[] +image::aop-proxy-call.png[] [source,java,indent=0,subs="verbatim",role="primary"] .Java diff --git a/framework-docs/modules/ROOT/pages/core/beans.adoc b/framework-docs/modules/ROOT/pages/core/beans.adoc index 3afd90965528..064d8376332e 100644 --- a/framework-docs/modules/ROOT/pages/core/beans.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans.adoc @@ -84,7 +84,7 @@ created and initialized, you have a fully configured and executable system or application. .The Spring IoC container -image::images/container-magic.png[] +image::container-magic.png[] @@ -2727,7 +2727,7 @@ defined by that bean definition. This single instance is stored in a cache of su singleton beans, and all subsequent requests and references for that named bean return the cached object. The following image shows how the singleton scope works: -image::images/singleton.png[] +image::singleton.png[] Spring's concept of a singleton bean differs from the singleton pattern as defined in the Gang of Four (GoF) patterns book. The GoF singleton hard-codes the scope of an @@ -2760,7 +2760,7 @@ singleton scope for stateless beans. The following diagram illustrates the Spring prototype scope: -image::images/prototype.png[] +image::prototype.png[] (A data access object (DAO) is not typically configured as a prototype, because a typical DAO does not hold diff --git a/framework-docs/modules/ROOT/pages/data-access.adoc b/framework-docs/modules/ROOT/pages/data-access.adoc index c223788e6d05..13fb9a203409 100644 --- a/framework-docs/modules/ROOT/pages/data-access.adoc +++ b/framework-docs/modules/ROOT/pages/data-access.adoc @@ -607,7 +607,7 @@ operations need to execute within the same Reactor context in the same reactive The following image shows a conceptual view of calling a method on a transactional proxy: -image::images/tx.png[] +image::tx.png[] [[transaction-declarative-first-example]] @@ -1967,7 +1967,7 @@ logical transactions, and how the propagation setting applies to this difference [[tx-propagation-required]] ===== Understanding `PROPAGATION_REQUIRED` -image::images/tx_prop_required.png[] +image::tx_prop_required.png[] `PROPAGATION_REQUIRED` enforces a physical transaction, either locally for the current scope if no transaction exists yet or participating in an existing 'outer' transaction @@ -2004,7 +2004,7 @@ indicate clearly that a rollback was performed instead. [[tx-propagation-requires_new]] ===== Understanding `PROPAGATION_REQUIRES_NEW` -image::images/tx_prop_requires_new.png[] +image::tx_prop_requires_new.png[] `PROPAGATION_REQUIRES_NEW`, in contrast to `PROPAGATION_REQUIRED`, always uses an independent physical transaction for each affected transaction scope, never @@ -2955,7 +2955,7 @@ The following image shows the exception hierarchy that Spring provides. (Note that the class hierarchy detailed in the image shows only a subset of the entire `DataAccessException` hierarchy.) -image::images/DataAccessException.png[] +image::DataAccessException.png[] @@ -8736,7 +8736,7 @@ underlying O-X mapping tool does not do so. The O-X Mapping exception hierarchy is shown in the following figure: -image::images/oxm-exceptions.png[] +image::oxm-exceptions.png[] diff --git a/framework-docs/modules/ROOT/pages/web/webflux.adoc b/framework-docs/modules/ROOT/pages/web/webflux.adoc index 8f771502e369..a50f9f08e1fc 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux.adoc @@ -140,7 +140,7 @@ continuity and consistency with each other, they are available side by side, and from each side benefits both sides. The following diagram shows how the two relate, what they have in common, and what each supports uniquely: -image::images/spring-mvc-and-webflux-venn.png[] +image::spring-mvc-and-webflux-venn.png[] We suggest that you consider the following specific points: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc.adoc b/framework-docs/modules/ROOT/pages/web/webmvc.adoc index 9f732da708ea..6df553ffb973 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc.adoc @@ -154,7 +154,7 @@ are effectively inherited and can be overridden (that is, re-declared) in the Se child `WebApplicationContext`, which typically contains beans local to the given `Servlet`. The following image shows this relationship: -image::images/mvc-context-hierarchy.png[] +image::mvc-context-hierarchy.png[] The following example configures a `WebApplicationContext` hierarchy: diff --git a/framework-docs/modules/ROOT/pages/web/websocket.adoc b/framework-docs/modules/ROOT/pages/web/websocket.adoc index 94196410daf1..d584e03fb61f 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket.adoc @@ -1114,7 +1114,7 @@ Both the Java configuration (that is, `@EnableWebSocketMessageBroker`) and the X workflow. The following diagram shows the components used when the simple built-in message broker is enabled: -image::images/message-flow-simple-broker.png[] +image::message-flow-simple-broker.png[] The preceding diagram shows three message channels: @@ -1126,7 +1126,7 @@ server-side application code. The next diagram shows the components used when an external broker (such as RabbitMQ) is configured for managing subscriptions and broadcasting messages: -image::images/message-flow-broker-relay.png[] +image::message-flow-broker-relay.png[] The main difference between the two preceding diagrams is the use of the "`broker relay`" for passing messages up to the external STOMP broker over TCP and for passing messages down from the From c6fae522a9369fd3903a012a43c39e1f04ed9efd Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:24:00 -0500 Subject: [PATCH 10/31] Copy default antora files --- .../.github/workflows/deploy-docs.yml | 33 +++++ framework-docs/antora-playbook.yml | 36 ++++++ framework-docs/antora.yml | 32 +++++ framework-docs/framework-docs.gradle | 120 ++++++------------ 4 files changed, 143 insertions(+), 78 deletions(-) create mode 100644 framework-docs/.github/workflows/deploy-docs.yml create mode 100644 framework-docs/antora-playbook.yml create mode 100644 framework-docs/antora.yml diff --git a/framework-docs/.github/workflows/deploy-docs.yml b/framework-docs/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000000..1435fc2171d1 --- /dev/null +++ b/framework-docs/.github/workflows/deploy-docs.yml @@ -0,0 +1,33 @@ +name: Deploy Docs +on: + push: + branches-ignore: [ gh-pages ] + tags: '**' + repository_dispatch: + types: request-build-reference # legacy + #schedule: + #- cron: '0 10 * * *' # Once per day at 10am UTC + workflow_dispatch: +permissions: + actions: write +jobs: + build: + runs-on: ubuntu-latest + # FIXME enable when pushed to spring-projects + # if: github.repository_owner == 'spring-projects' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: docs-build + fetch-depth: 1 + - name: Dispatch (partial build) + if: github.ref_type == 'branch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} + - name: Dispatch (full build) + if: github.ref_type == 'tag' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) diff --git a/framework-docs/antora-playbook.yml b/framework-docs/antora-playbook.yml new file mode 100644 index 000000000000..ffae717c22bc --- /dev/null +++ b/framework-docs/antora-playbook.yml @@ -0,0 +1,36 @@ +# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2 +# +# The purpose of this Antora playbook is to build the docs in the current branch. +antora: + extensions: + - '@antora/collector-extension' + - require: '@springio/antora-extensions/tabs-migration-extension' + unwrap_example_block: always +site: + title: Spring Framework Reference + url: https://https://rwinch.github.io/spring-framework/ +content: + sources: + - url: https://github.com/rwinch/spring-framework + branches: ./.. + start_path: framework-docs + worktrees: true +asciidoc: + attributes: + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip + snapshot: true \ No newline at end of file diff --git a/framework-docs/antora.yml b/framework-docs/antora.yml new file mode 100644 index 000000000000..cc7d6eb1638b --- /dev/null +++ b/framework-docs/antora.yml @@ -0,0 +1,32 @@ +name: framework +version: true +title: Spring Framework Documentation +nav: + - modules/ROOT/nav.adoc +ext: + collector: + run: + command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-boot-project:spring-boot-docs:generateAntoraResources + local: true + scan: + dir: ./build/generated-antora-resources + +asciidoc: + attributes: + attribute-missing: 'warn' + # FIXME: the copyright is not removed + # FIXME: The package is not renamed + chomp: 'all' + import-java: 'example$docs-src/main/java/org/springframework/docs' + spring-framework-main-code: 'https://github.com/spring-projects/spring-framework/tree/main' + docs-site: 'https://docs.spring.io' + docs-spring: "{docs-site}/spring-framework/docs/{spring-version}" + docs-spring-framework: '{docs_site}/spring-framework/docs/{spring-version}' + api-spring-framework: '{docs-spring-framework}/javadoc-api/org/springframework' + docs-graalvm: 'https://www.graalvm.org/22.3/reference-manual' + docs-spring-boot: '{docs-site}/spring-boot/docs/current/reference' + docs-spring-gemfire: '{docs_site}/spring-gemfire/docs/current/reference' + docs-spring-security: '{docs_site}/spring-security/reference' + gh-rsocket: 'https://github.com/rsocket' + gh-rsocket-extensions: '{gh-rsocket}/rsocket/blob/master/Extensions' + gh-rsocket-java: '{gh-rsocket}/rsocket-java{gh-rsocket}/rsocket-java' \ No newline at end of file diff --git a/framework-docs/framework-docs.gradle b/framework-docs/framework-docs.gradle index 2250e5bbc3ca..5c26a91b428f 100644 --- a/framework-docs/framework-docs.gradle +++ b/framework-docs/framework-docs.gradle @@ -1,24 +1,48 @@ +plugins { + id 'kotlin' + id 'io.spring.antora.generate-antora-yml' version '0.0.1' + id 'org.antora' version '1.0.0' +} + description = "Spring Framework Docs" -apply plugin: 'kotlin' -apply plugin: 'org.asciidoctor.jvm.convert' -apply plugin: 'org.asciidoctor.jvm.pdf' apply from: "${rootDir}/gradle/publications.gradle" -configurations { - asciidoctorExtensions +antora { + version = '3.2.0-alpha.2' + playbook = 'antora-playbook.yml' +// playbookProvider { +// repository = 'rwinch/spring-framework' +// branch = 'docs-build' +// path = 'lib/antora/templates/per-branch-antora-playbook.yml' +// checkLocalBranch = true +// } + options = ['--clean', '--stacktrace'] + environment = [ + 'ALGOLIA_API_KEY': '82c7ead946afbac3cf98c32446154691', + 'ALGOLIA_APP_ID': '244V8V9FGG', + 'ALGOLIA_INDEX_NAME': 'framework-docs' + ] + dependencies = [ + '@antora/atlas-extension': '1.0.0-alpha.1', + '@antora/collector-extension': '1.0.0-alpha.3', + '@asciidoctor/tabs': '1.0.0-beta.3', + '@opendevise/antora-release-line-extension': '1.0.0-alpha.2', + '@springio/antora-extensions': '1.1.0', + '@springio/asciidoctor-extensions': '1.0.0-alpha.9' + ] } -dependencies { - api(project(":spring-context")) - api(project(":spring-web")) - api("jakarta.servlet:jakarta.servlet-api") - implementation(project(":spring-core-test")) - implementation("org.assertj:assertj-core") +tasks.named("generateAntoraYml") { + dependsOn dependencyVersions + asciidocAttributes = project.provider( { + return ["spring-version": project.version ] + } ) } + jar { enabled = false } @@ -27,8 +51,10 @@ javadoc { enabled = false } -dependencies { - asciidoctorExtensions "io.spring.asciidoctor.backends:spring-asciidoctor-backends:0.0.5" +repositories { + maven { + url "https://repo.spring.io/release" + } } /** @@ -82,69 +108,10 @@ rootProject.tasks.dokkaHtmlMultiModule.configure { outputDirectory.set(project.file("$buildDir/docs/kdoc")) } -asciidoctorj { - version = '2.4.3' - fatalWarnings ".*" - options doctype: 'book', eruby: 'erubis' - attributes([ - icons: 'font', - idprefix: '', - idseparator: '-', - revnumber: project.version, - sectanchors: '', - sectnums: '', - 'spring-version': project.version - ]) -} - -/** - * Generate the Spring Framework Reference documentation from - * "src/docs/asciidoc" in "build/docs/ref-docs/html5". - */ -asciidoctor { - baseDirFollowsSourceDir() - configurations "asciidoctorExtensions" - sources { - include '*.adoc' - } - resources { - from(sourceDir) { - include 'images/*.png' - } - } - outputDir "$buildDir/docs/ref-docs/html5" - outputOptions { - backends "spring-html" - } - forkOptions { - jvmArgs += ["--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED"] - } - logDocuments = true -} - -asciidoctor.mustRunAfter "check" - -/** - * Generate the Spring Framework Reference documentation from "src/docs/asciidoc" - * in "build/docs/ref-docs/pdf". - */ -asciidoctorPdf { - baseDirFollowsSourceDir() - configurations 'asciidoctorExtensions' - sources { - include 'spring-framework.adocbook' - } - outputDir "$buildDir/docs/ref-docs/pdf" - forkOptions { - jvmArgs += ["--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED"] - } - logDocuments = true -} - /** * Zip all docs (API and reference) into a single archive */ -task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'asciidoctorPdf', rootProject.tasks.dokkaHtmlMultiModule]) { +task docsZip(type: Zip, dependsOn: ['api', 'antora', rootProject.tasks.dokkaHtmlMultiModule]) { group = "Distribution" description = "Builds -${archiveClassifier} archive containing api and reference " + "for deployment at https://docs.spring.io/spring-framework/docs/." @@ -157,12 +124,9 @@ task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'asciidoctorPdf', root from (api) { into "javadoc-api" } - from ("$asciidoctor.outputDir") { + from ("build/site") { into "reference/html" } - from ("$asciidoctorPdf.outputDir") { - into "reference/pdf" - } from (rootProject.tasks.dokkaHtmlMultiModule.outputDirectory) { into "kdoc-api" } @@ -251,4 +215,4 @@ publishing { artifact distZip } } -} +} \ No newline at end of file From 99ccdba49bbb6a30c6b43b445158ec19a2f11780 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:26:16 -0500 Subject: [PATCH 11/31] Split files --- .../modules/ROOT/pages/core/aop-api.adoc | 1751 --- .../ROOT/pages/core/aop-api/advice.adoc | 538 + .../ROOT/pages/core/aop-api/advised.adoc | 136 + .../ROOT/pages/core/aop-api/advisor.adoc | 19 + .../ROOT/pages/core/aop-api/autoproxy.adoc | 131 + .../pages/core/aop-api/concise-proxy.adoc | 71 + .../pages/core/aop-api/extensibility.adoc | 15 + .../modules/ROOT/pages/core/aop-api/pfb.adoc | 323 + .../ROOT/pages/core/aop-api/pointcuts.adoc | 250 + .../modules/ROOT/pages/core/aop-api/prog.adoc | 48 + .../ROOT/pages/core/aop-api/targetsource.adoc | 220 + .../modules/ROOT/pages/core/aop.adoc | 4292 ------ .../pages/core/aop/aspectj-programmatic.adoc | 53 + .../ROOT/pages/core/aop/ataspectj.adoc | 15 + .../ROOT/pages/core/aop/ataspectj/advice.adoc | 837 ++ .../core/aop/ataspectj/aspectj-support.adoc | 55 + .../pages/core/aop/ataspectj/at-aspectj.adoc | 62 + .../pages/core/aop/ataspectj/example.adoc | 166 + .../aop/ataspectj/instantiation-models.adoc | 59 + .../core/aop/ataspectj/introductions.adoc | 67 + .../pages/core/aop/ataspectj/pointcuts.adoc | 575 + .../modules/ROOT/pages/core/aop/choosing.adoc | 107 + .../pages/core/aop/introduction-defn.adoc | 79 + .../pages/core/aop/introduction-proxies.adoc | 21 + .../core/aop/introduction-spring-defn.adoc | 61 + .../ROOT/pages/core/aop/mixing-styles.adoc | 11 + .../modules/ROOT/pages/core/aop/proxying.adoc | 251 + .../ROOT/pages/core/aop/resources.adoc | 11 + .../modules/ROOT/pages/core/aop/schema.adoc | 921 ++ .../ROOT/pages/core/aop/using-aspectj.adoc | 941 ++ .../modules/ROOT/pages/core/appendix.adoc | 1664 --- .../appendix/application-startup-steps.adoc | 57 + .../ROOT/pages/core/appendix/xml-custom.adoc | 958 ++ .../ROOT/pages/core/appendix/xsd-schemas.adoc | 649 + .../modules/ROOT/pages/core/beans.adoc | 11290 ---------------- .../pages/core/beans/annotation-config.adoc | 81 + .../annotation-config/autowired-primary.adoc | 102 + .../autowired-qualifiers.adoc | 532 + .../beans/annotation-config/autowired.adoc | 432 + .../custom-autowire-configurer.adoc | 33 + .../generics-as-qualifiers.adoc | 83 + ...tconstruct-and-predestroy-annotations.adoc | 64 + .../beans/annotation-config/resource.adoc | 129 + .../annotation-config/value-annotations.adoc | 200 + .../modules/ROOT/pages/core/beans/basics.adoc | 390 + .../ROOT/pages/core/beans/beanfactory.adoc | 159 + .../core/beans/child-bean-definitions.adoc | 84 + .../pages/core/beans/classpath-scanning.adoc | 937 ++ .../core/beans/context-introduction.adoc | 951 ++ .../core/beans/context-load-time-weaver.adoc | 46 + .../ROOT/pages/core/beans/definition.adoc | 430 + .../ROOT/pages/core/beans/dependencies.adoc | 11 + .../beans/dependencies/factory-autowire.adoc | 127 + .../dependencies/factory-collaborators.adoc | 560 + .../beans/dependencies/factory-dependson.adoc | 40 + .../beans/dependencies/factory-lazy-init.adoc | 42 + .../factory-method-injection.adoc | 398 + .../factory-properties-detailed.adoc | 608 + .../ROOT/pages/core/beans/environment.adoc | 729 + .../pages/core/beans/factory-extension.adoc | 481 + .../ROOT/pages/core/beans/factory-nature.adoc | 643 + .../ROOT/pages/core/beans/factory-scopes.adoc | 714 + .../ROOT/pages/core/beans/introduction.adoc | 43 + .../modules/ROOT/pages/core/beans/java.adoc | 18 + .../pages/core/beans/java/basic-concepts.adoc | 82 + .../core/beans/java/bean-annotation.adoc | 518 + .../java/composing-configuration-classes.adoc | 777 ++ .../beans/java/configuration-annotation.adoc | 240 + .../beans/java/instantiating-container.adoc | 255 + .../core/beans/standard-annotations.adoc | 351 + .../modules/ROOT/pages/core/expressions.adoc | 2123 --- .../ROOT/pages/core/expressions/beandef.adoc | 195 + .../pages/core/expressions/evaluation.adoc | 467 + .../core/expressions/example-classes.adoc | 205 + .../pages/core/expressions/language-ref.adoc | 24 + .../language-ref/array-construction.adoc | 33 + .../language-ref/bean-references.adoc | 53 + .../language-ref/collection-projection.adoc | 30 + .../language-ref/collection-selection.adoc | 50 + .../language-ref/constructors.adoc | 35 + .../expressions/language-ref/functions.adoc | 80 + .../language-ref/inline-lists.adoc | 28 + .../expressions/language-ref/inline-maps.adoc | 31 + .../expressions/language-ref/literal.adoc | 68 + .../expressions/language-ref/methods.adoc | 29 + .../language-ref/operator-elvis.adoc | 79 + .../operator-safe-navigation.adoc | 45 + .../language-ref/operator-ternary.adoc | 53 + .../expressions/language-ref/operators.adoc | 297 + .../language-ref/properties-arrays.adoc | 124 + .../expressions/language-ref/templating.adoc | 72 + .../core/expressions/language-ref/types.adoc | 36 + .../expressions/language-ref/variables.adoc | 89 + .../modules/ROOT/pages/core/validation.adoc | 1973 --- .../pages/core/validation/beans-beans.adoc | 612 + .../pages/core/validation/beanvalidation.adoc | 343 + .../pages/core/validation/conversion.adoc | 28 + .../ROOT/pages/core/validation/convert.adoc | 330 + ...uring-formatting-globaldatetimeformat.adoc | 115 + .../ROOT/pages/core/validation/format.adoc | 363 + .../ROOT/pages/core/validation/validator.adoc | 182 + .../modules/ROOT/pages/data-access.adoc | 9124 ------------- .../modules/ROOT/pages/data-access/dao.adoc | 176 + .../modules/ROOT/pages/data-access/jdbc.adoc | 58 + .../ROOT/pages/data-access/jdbc/advanced.adoc | 284 + .../pages/data-access/jdbc/choose-style.adoc | 31 + .../pages/data-access/jdbc/connections.adoc | 223 + .../ROOT/pages/data-access/jdbc/core.adoc | 955 ++ .../jdbc/embedded-database-support.adoc | 276 + .../jdbc/initializing-datasource.adoc | 146 + .../ROOT/pages/data-access/jdbc/object.adoc | 544 + .../ROOT/pages/data-access/jdbc/packages.adoc | 36 + .../data-access/jdbc/parameter-handling.adoc | 322 + .../ROOT/pages/data-access/jdbc/simple.adoc | 707 + .../modules/ROOT/pages/data-access/orm.adoc | 7 + .../ROOT/pages/data-access/orm/general.adoc | 108 + .../ROOT/pages/data-access/orm/hibernate.adoc | 490 + .../pages/data-access/orm/introduction.adoc | 66 + .../ROOT/pages/data-access/orm/jpa.adoc | 577 + .../modules/ROOT/pages/data-access/oxm.adoc | 563 + .../modules/ROOT/pages/data-access/r2dbc.adoc | 654 + .../ROOT/pages/data-access/transaction.adoc | 40 + .../application-server-integration.adoc | 51 + .../data-access/transaction/declarative.adoc | 53 + .../transaction/declarative/annotations.adoc | 598 + .../applying-more-than-just-tx-advice.adoc | 216 + .../transaction/declarative/aspectj.adoc | 60 + .../transaction/declarative/diff-tx.adoc | 114 + .../declarative/first-example.adoc | 399 + .../transaction/declarative/rolling-back.adoc | 170 + .../declarative/tx-decl-explained.adoc | 47 + .../declarative/tx-propagation.adoc | 72 + .../declarative/txadvice-settings.adoc | 63 + .../pages/data-access/transaction/event.adoc | 61 + .../data-access/transaction/motivation.adoc | 90 + .../data-access/transaction/programmatic.adoc | 442 + .../data-access/transaction/resources.adoc | 17 + .../solutions-to-common-problems.adoc | 22 + .../data-access/transaction/strategies.adoc | 284 + .../transaction/tx-decl-vs-prog.adoc | 19 + .../tx-resource-synchronization.adoc | 83 + .../modules/ROOT/pages/integration/cache.adoc | 1058 -- .../pages/integration/cache/annotations.adoc | 636 + .../integration/cache/declarative-xml.adoc | 56 + .../ROOT/pages/integration/cache/jsr-107.adoc | 123 + .../ROOT/pages/integration/cache/plug.adoc | 14 + .../integration/cache/specific-config.adoc | 10 + .../cache/store-configuration.adoc | 143 + .../pages/integration/cache/strategies.adoc | 76 + .../modules/ROOT/pages/integration/jms.adoc | 1410 -- .../ROOT/pages/integration/jms/annotated.adoc | 280 + .../jms/jca-message-endpoint-manager.adoc | 88 + .../ROOT/pages/integration/jms/namespace.adoc | 301 + .../ROOT/pages/integration/jms/receiving.adoc | 311 + .../ROOT/pages/integration/jms/sending.adoc | 134 + .../ROOT/pages/integration/jms/using.adoc | 296 + .../modules/ROOT/pages/integration/jmx.adoc | 1349 -- .../ROOT/pages/integration/jmx/exporting.adoc | 283 + .../ROOT/pages/integration/jmx/interface.adoc | 417 + .../ROOT/pages/integration/jmx/jsr160.adoc | 103 + .../ROOT/pages/integration/jmx/naming.adoc | 175 + .../pages/integration/jmx/notifications.adoc | 308 + .../ROOT/pages/integration/jmx/proxy.adoc | 49 + .../ROOT/pages/integration/jmx/resources.adoc | 14 + .../modules/ROOT/pages/languages/kotlin.adoc | 1102 -- .../pages/languages/kotlin/annotations.adoc | 29 + .../languages/kotlin/bean-definition-dsl.adoc | 116 + .../languages/kotlin/classes-interfaces.adoc | 19 + .../pages/languages/kotlin/coroutines.adoc | 257 + .../pages/languages/kotlin/extensions.adoc | 46 + .../languages/kotlin/getting-started.adoc | 32 + .../pages/languages/kotlin/null-safety.adoc | 38 + .../pages/languages/kotlin/requirements.adoc | 20 + .../pages/languages/kotlin/resources.adoc | 45 + .../languages/kotlin/spring-projects-in.adoc | 360 + .../ROOT/pages/languages/kotlin/web.adoc | 140 + .../ROOT/pages/testing/annotations.adoc | 1916 --- .../integration-junit-jupiter.adoc | 349 + .../annotations/integration-junit4.adoc | 184 + .../testing/annotations/integration-meta.adoc | 264 + .../annotations/integration-spring.adoc | 29 + .../annotation-activeprofiles.adoc | 69 + .../annotation-aftertransaction.adoc | 30 + .../annotation-beforetransaction.adoc | 32 + .../annotation-bootstrapwith.adoc | 8 + .../integration-spring/annotation-commit.adoc | 34 + .../annotation-contextconfiguration.adoc | 122 + .../annotation-contexthierarchy.adoc | 63 + .../annotation-dirtiescontext.adoc | 223 + .../annotation-dynamicpropertysource.adoc | 59 + .../annotation-recordapplicationevents.adoc | 13 + .../annotation-rollback.adoc | 40 + .../integration-spring/annotation-sql.adoc | 32 + .../annotation-sqlconfig.adoc | 31 + .../annotation-sqlgroup.adoc | 38 + .../annotation-sqlmergemode.adoc | 84 + .../annotation-testexecutionlisteners.adoc | 41 + .../annotation-testpropertysource.adoc | 59 + .../annotation-webappconfiguration.adoc | 75 + .../annotations/integration-standard.adoc | 37 + .../testing/spring-mvc-test-framework.adoc | 1860 --- .../async-requests.adoc | 69 + .../server-defining-expectations.adoc | 210 + .../server-filters.adoc | 21 + .../server-htmlunit.adoc | 20 + .../server-htmlunit/geb.adoc | 125 + .../server-htmlunit/mah.adoc | 242 + .../server-htmlunit/webdriver.adoc | 503 + .../server-htmlunit/why.adoc | 187 + .../server-performing-requests.adoc | 136 + .../server-resources.adoc | 10 + .../server-setup-options.adoc | 164 + .../server-setup-steps.adoc | 53 + .../server-static-imports.adoc | 17 + .../spring-mvc-test-framework/server.adoc | 23 + .../vs-end-to-end-integration-tests.adoc | 46 + .../vs-streaming-response.adoc | 34 + .../pages/testing/testcontext-framework.adoc | 4709 ------- .../testing/testcontext-framework/aot.adoc | 58 + .../application-events.adoc | 89 + .../testcontext-framework/bootstrapping.adoc | 26 + .../testcontext-framework/ctx-management.adoc | 113 + .../ctx-management/caching.adoc | 126 + .../dynamic-property-sources.adoc | 97 + .../ctx-management/env-profiles.adoc | 482 + .../ctx-management/groovy.adoc | 113 + .../ctx-management/hierarchies.adoc | 218 + .../ctx-management/inheritance.adoc | 160 + .../ctx-management/initializers.adoc | 79 + .../ctx-management/javaconfig.adoc | 127 + .../ctx-management/mixed-config.adoc | 33 + .../ctx-management/property-sources.adoc | 268 + .../ctx-management/web-mocks.adoc | 77 + .../ctx-management/web.adoc | 142 + .../ctx-management/xml.adoc | 103 + .../testcontext-framework/executing-sql.adoc | 400 + .../testcontext-framework/fixture-di.adoc | 215 + .../key-abstractions.adoc | 86 + .../parallel-test-execution.adoc | 48 + .../support-classes.adoc | 609 + .../testcontext-framework/tel-config.adoc | 192 + .../test-execution-events.adoc | 88 + .../testing/testcontext-framework/tx.adoc | 600 + .../web-scoped-beans.adoc | 160 + .../ROOT/pages/web/webflux-webclient.adoc | 1202 -- .../webflux-webclient/client-attributes.adoc | 46 + .../web/webflux-webclient/client-body.adoc | 291 + .../web/webflux-webclient/client-builder.adoc | 466 + .../web/webflux-webclient/client-context.adoc | 33 + .../webflux-webclient/client-exchange.adoc | 47 + .../web/webflux-webclient/client-filter.adoc | 128 + .../webflux-webclient/client-retrieve.adoc | 96 + .../webflux-webclient/client-synchronous.adoc | 85 + .../web/webflux-webclient/client-testing.adoc | 10 + .../modules/ROOT/pages/web/webflux.adoc | 4686 ------- .../web/webflux/ann-rest-exceptions.adoc | 151 + .../ROOT/pages/web/webflux/caching.adoc | 177 + .../ROOT/pages/web/webflux/config.adoc | 741 + .../ROOT/pages/web/webflux/controller.adoc | 39 + .../web/webflux/controller/ann-advice.adoc | 69 + .../webflux/controller/ann-exceptions.adoc | 81 + .../webflux/controller/ann-initbinder.adoc | 107 + .../web/webflux/controller/ann-methods.adoc | 9 + .../controller/ann-methods/arguments.adoc | 121 + .../controller/ann-methods/cookievalue.adoc | 42 + .../controller/ann-methods/httpentity.adoc | 27 + .../controller/ann-methods/jackson.adoc | 83 + .../ann-methods/matrix-variables.adoc | 136 + .../ann-methods/modelattrib-method-args.adoc | 148 + .../ann-methods/multipart-forms.adoc | 279 + .../controller/ann-methods/requestattrib.adoc | 30 + .../controller/ann-methods/requestbody.adoc | 75 + .../controller/ann-methods/requestheader.adoc | 62 + .../controller/ann-methods/requestparam.adoc | 76 + .../controller/ann-methods/responsebody.adoc | 44 + .../ann-methods/responseentity.adoc | 43 + .../controller/ann-methods/return-types.adoc | 82 + .../ann-methods/sessionattribute.adoc | 37 + .../ann-methods/sessionattributes.adoc | 86 + .../ann-methods/typeconversion.adoc | 21 + .../controller/ann-modelattrib-methods.adoc | 140 + .../controller/ann-requestmapping.adoc | 452 + .../pages/web/webflux/controller/ann.adoc | 68 + .../pages/web/webflux/dispatcher-handler.adoc | 252 + .../modules/ROOT/pages/web/webflux/http2.adoc | 8 + .../ROOT/pages/web/webflux/new-framework.adoc | 286 + .../pages/web/webflux/reactive-spring.adoc | 716 + .../ROOT/pages/web/webflux/security.adoc | 17 + .../ROOT/pages/web/webflux/uri-building.adoc | 12 + .../modules/ROOT/pages/web/webmvc-view.adoc | 2060 --- .../pages/web/webmvc-view/mvc-document.adoc | 85 + .../ROOT/pages/web/webmvc-view/mvc-feeds.adoc | 97 + .../pages/web/webmvc-view/mvc-freemarker.adoc | 445 + .../web/webmvc-view/mvc-groovymarkup.adoc | 98 + .../pages/web/webmvc-view/mvc-jackson.adoc | 46 + .../ROOT/pages/web/webmvc-view/mvc-jsp.adoc | 820 ++ .../pages/web/webmvc-view/mvc-script.adoc | 256 + .../pages/web/webmvc-view/mvc-thymeleaf.adoc | 21 + .../web/webmvc-view/mvc-xml-marshalling.adoc | 13 + .../ROOT/pages/web/webmvc-view/mvc-xslt.adoc | 183 + .../modules/ROOT/pages/web/webmvc.adoc | 6321 --------- .../ROOT/pages/web/webmvc/filters.adoc | 102 + .../ROOT/pages/web/webmvc/mvc-ann-async.adoc | 490 + .../web/webmvc/mvc-ann-rest-exceptions.adoc | 189 + .../ROOT/pages/web/webmvc/mvc-caching.adoc | 194 + .../ROOT/pages/web/webmvc/mvc-config.adoc | 17 + .../web/webmvc/mvc-config/advanced-java.adoc | 39 + .../web/webmvc/mvc-config/advanced-xml.adoc | 37 + .../mvc-config/content-negotiation.adoc | 65 + .../web/webmvc/mvc-config/conversion.adoc | 116 + .../web/webmvc/mvc-config/customize.adoc | 37 + .../mvc-config/default-servlet-handler.adoc | 95 + .../pages/web/webmvc/mvc-config/enable.adoc | 50 + .../web/webmvc/mvc-config/interceptors.adoc | 60 + .../webmvc/mvc-config/message-converters.adoc | 102 + .../web/webmvc/mvc-config/path-matching.adoc | 61 + .../webmvc/mvc-config/static-resources.adoc | 146 + .../web/webmvc/mvc-config/validation.adoc | 91 + .../webmvc/mvc-config/view-controller.adoc | 52 + .../web/webmvc/mvc-config/view-resolvers.adoc | 119 + .../ROOT/pages/web/webmvc/mvc-controller.adoc | 48 + .../web/webmvc/mvc-controller/ann-advice.adoc | 65 + .../mvc-controller/ann-exceptionhandler.adoc | 262 + .../webmvc/mvc-controller/ann-initbinder.adoc | 102 + .../webmvc/mvc-controller/ann-methods.adoc | 9 + .../mvc-controller/ann-methods/arguments.adoc | 142 + .../ann-methods/cookievalue.adoc | 41 + .../ann-methods/flash-attributes.adoc | 46 + .../ann-methods/httpentity.adoc | 27 + .../mvc-controller/ann-methods/jackson.adoc | 145 + .../ann-methods/matrix-variables.adoc | 141 + .../ann-methods/modelattrib-method-args.adoc | 194 + .../ann-methods/multipart-forms.adoc | 186 + .../ann-methods/redirecting-passing-data.adoc | 52 + .../ann-methods/requestattrib.adoc | 30 + .../ann-methods/requestbody.adoc | 55 + .../ann-methods/requestheader.adoc | 62 + .../ann-methods/requestparam.adoc | 77 + .../ann-methods/responsebody.adoc | 43 + .../ann-methods/responseentity.adoc | 40 + .../ann-methods/return-types.adoc | 105 + .../ann-methods/sessionattribute.adoc | 39 + .../ann-methods/sessionattributes.adoc | 85 + .../ann-methods/typeconversion.adoc | 34 + .../ann-modelattrib-methods.adoc | 99 + .../mvc-controller/ann-requestmapping.adoc | 502 + .../pages/web/webmvc/mvc-controller/ann.adoc | 85 + .../ROOT/pages/web/webmvc/mvc-http2.adoc | 14 + .../ROOT/pages/web/webmvc/mvc-security.adoc | 19 + .../ROOT/pages/web/webmvc/mvc-servlet.adoc | 111 + .../pages/web/webmvc/mvc-servlet/config.adoc | 20 + .../webmvc/mvc-servlet/container-config.adoc | 184 + .../webmvc/mvc-servlet/context-hierarchy.adoc | 107 + .../webmvc/mvc-servlet/exceptionhandlers.adoc | 112 + .../handlermapping-interceptor.adoc | 34 + .../mvc-servlet/handlermapping-path.adoc | 52 + .../webmvc/mvc-servlet/localeresolver.adoc | 145 + .../pages/web/webmvc/mvc-servlet/logging.adoc | 81 + .../web/webmvc/mvc-servlet/multipart.adoc | 77 + .../web/webmvc/mvc-servlet/sequence.adoc | 74 + .../mvc-servlet/special-bean-types.adoc | 61 + .../web/webmvc/mvc-servlet/themeresolver.adoc | 92 + .../web/webmvc/mvc-servlet/viewresolver.adoc | 129 + .../pages/web/webmvc/mvc-uri-building.adoc | 280 + .../modules/ROOT/pages/web/websocket.adoc | 2502 ---- .../ROOT/pages/web/websocket/fallback.adoc | 379 + .../ROOT/pages/web/websocket/server.adoc | 426 + .../ROOT/pages/web/websocket/stomp.adoc | 12 + .../stomp/application-context-events.adoc | 40 + .../stomp/authentication-token-based.adoc | 74 + .../web/websocket/stomp/authentication.adoc | 34 + .../web/websocket/stomp/authorization.adoc | 12 + .../pages/web/websocket/stomp/benefits.adoc | 20 + .../pages/web/websocket/stomp/client.adoc | 109 + .../stomp/configuration-performance.adoc | 163 + .../stomp/destination-separator.adoc | 80 + .../pages/web/websocket/stomp/enable.adoc | 109 + .../websocket/stomp/handle-annotations.adoc | 185 + .../stomp/handle-broker-relay-configure.adoc | 68 + .../websocket/stomp/handle-broker-relay.adoc | 79 + .../web/websocket/stomp/handle-send.adoc | 35 + .../websocket/stomp/handle-simple-broker.adoc | 45 + .../web/websocket/stomp/interceptors.adoc | 52 + .../web/websocket/stomp/message-flow.adoc | 114 + .../web/websocket/stomp/ordered-messages.adoc | 51 + .../pages/web/websocket/stomp/overview.adoc | 97 + .../ROOT/pages/web/websocket/stomp/scope.adoc | 69 + .../web/websocket/stomp/server-config.adoc | 33 + .../ROOT/pages/web/websocket/stomp/stats.adoc | 59 + .../pages/web/websocket/stomp/testing.adoc | 41 + .../web/websocket/stomp/user-destination.adoc | 117 + 391 files changed, 62477 insertions(+), 62392 deletions(-) create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/advice.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/advised.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/advisor.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/autoproxy.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/extensibility.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/prog.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop-api/targetsource.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/ataspectj/at-aspectj.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/ataspectj/instantiation-models.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/ataspectj/introductions.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/choosing.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/mixing-styles.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/proxying.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/resources.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/schema.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/appendix/application-startup-steps.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-primary.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/annotation-config/custom-autowire-configurer.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/annotation-config/generics-as-qualifiers.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/annotation-config/resource.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/basics.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/child-bean-definitions.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/definition.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/dependencies.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/environment.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/introduction.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/java.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/java/basic-concepts.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/beans/standard-annotations.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/beandef.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/example-classes.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/array-construction.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-projection.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-selection.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/constructors.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/functions.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-lists.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-maps.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/literal.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/methods.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-elvis.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-safe-navigation.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-ternary.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/templating.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/types.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/expressions/language-ref/variables.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/validation/conversion.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/validation/convert.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/validation/format.adoc create mode 100644 framework-docs/modules/ROOT/pages/core/validation/validator.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/dao.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/choose-style.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/initializing-datasource.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/parameter-handling.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/orm.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/orm/general.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/oxm.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/application-server-integration.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative/diff-tx.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-propagation.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/event.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/motivation.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/resources.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/tx-decl-vs-prog.adoc create mode 100644 framework-docs/modules/ROOT/pages/data-access/transaction/tx-resource-synchronization.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/cache/plug.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/cache/specific-config.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jms/jca-message-endpoint-manager.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jms/sending.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jms/using.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jmx/jsr160.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jmx/notifications.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jmx/proxy.adoc create mode 100644 framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/annotations.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/bean-definition-dsl.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/classes-interfaces.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/coroutines.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/extensions.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/requirements.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/resources.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc create mode 100644 framework-docs/modules/ROOT/pages/languages/kotlin/web.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-aftertransaction.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-beforetransaction.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-commit.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dirtiescontext.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlconfig.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlgroup.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlmergemode.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-webappconfiguration.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-defining-expectations.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-resources.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-steps.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-end-to-end-integration-tests.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-streaming-response.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/bootstrapping.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/initializers.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/mixed-config.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/xml.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc create mode 100644 framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-webclient/client-attributes.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-webclient/client-body.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-webclient/client-exchange.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-webclient/client-filter.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-webclient/client-retrieve.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-webclient/client-synchronous.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-webclient/client-testing.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/caching.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/config.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/http2.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/security.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-document.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-feeds.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-groovymarkup.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-xml.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/default-servlet-handler.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-controller.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/container-config.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/server.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/application-context-events.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/authentication-token-based.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/authentication.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/authorization.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/destination-separator.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-send.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/message-flow.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/ordered-messages.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/overview.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/scope.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/stats.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/testing.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc diff --git a/framework-docs/modules/ROOT/pages/core/aop-api.adoc b/framework-docs/modules/ROOT/pages/core/aop-api.adoc index c36aff8c83f1..c3c3e571f8fe 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api.adoc @@ -9,1754 +9,3 @@ previous chapter. -[[aop-api-pointcuts]] -== Pointcut API in Spring - -This section describes how Spring handles the crucial pointcut concept. - - - -[[aop-api-concepts]] -=== Concepts - -Spring's pointcut model enables pointcut reuse independent of advice types. You can -target different advice with the same pointcut. - -The `org.springframework.aop.Pointcut` interface is the central interface, used to -target advice to particular classes and methods. The complete interface follows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface Pointcut { - - ClassFilter getClassFilter(); - - MethodMatcher getMethodMatcher(); - } ----- - -Splitting the `Pointcut` interface into two parts allows reuse of class and method -matching parts and fine-grained composition operations (such as performing a "`union`" -with another method matcher). - -The `ClassFilter` interface is used to restrict the pointcut to a given set of target -classes. If the `matches()` method always returns true, all target classes are -matched. The following listing shows the `ClassFilter` interface definition: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface ClassFilter { - - boolean matches(Class clazz); - } ----- - -The `MethodMatcher` interface is normally more important. The complete interface follows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface MethodMatcher { - - boolean matches(Method m, Class targetClass); - - boolean isRuntime(); - - boolean matches(Method m, Class targetClass, Object... args); - } ----- - -The `matches(Method, Class)` method is used to test whether this pointcut ever -matches a given method on a target class. This evaluation can be performed when an AOP -proxy is created to avoid the need for a test on every method invocation. If the -two-argument `matches` method returns `true` for a given method, and the `isRuntime()` -method for the MethodMatcher returns `true`, the three-argument matches method is -invoked on every method invocation. This lets a pointcut look at the arguments passed -to the method invocation immediately before the target advice starts. - -Most `MethodMatcher` implementations are static, meaning that their `isRuntime()` method -returns `false`. In this case, the three-argument `matches` method is never invoked. - -TIP: If possible, try to make pointcuts static, allowing the AOP framework to cache the -results of pointcut evaluation when an AOP proxy is created. - - - -[[aop-api-pointcut-ops]] -=== Operations on Pointcuts - -Spring supports operations (notably, union and intersection) on pointcuts. - -Union means the methods that either pointcut matches. -Intersection means the methods that both pointcuts match. -Union is usually more useful. -You can compose pointcuts by using the static methods in the -`org.springframework.aop.support.Pointcuts` class or by using the -`ComposablePointcut` class in the same package. However, using AspectJ pointcut -expressions is usually a simpler approach. - - - -[[aop-api-pointcuts-aspectj]] -=== AspectJ Expression Pointcuts - -Since 2.0, the most important type of pointcut used by Spring is -`org.springframework.aop.aspectj.AspectJExpressionPointcut`. This is a pointcut that -uses an AspectJ-supplied library to parse an AspectJ pointcut expression string. - -See the <> for a discussion of supported AspectJ pointcut primitives. - - - -[[aop-api-pointcuts-impls]] -=== Convenience Pointcut Implementations - -Spring provides several convenient pointcut implementations. You can use some of them -directly; others are intended to be subclassed in application-specific pointcuts. - - -[[aop-api-pointcuts-static]] -==== Static Pointcuts - -Static pointcuts are based on the method and the target class and cannot take into account -the method's arguments. Static pointcuts suffice -- and are best -- for most usages. -Spring can evaluate a static pointcut only once, when a method is first invoked. -After that, there is no need to evaluate the pointcut again with each method invocation. - -The rest of this section describes some of the static pointcut implementations that are -included with Spring. - -[[aop-api-pointcuts-regex]] -===== Regular Expression Pointcuts - -One obvious way to specify static pointcuts is regular expressions. Several AOP -frameworks besides Spring make this possible. -`org.springframework.aop.support.JdkRegexpMethodPointcut` is a generic regular -expression pointcut that uses the regular expression support in the JDK. - -With the `JdkRegexpMethodPointcut` class, you can provide a list of pattern strings. -If any of these is a match, the pointcut evaluates to `true`. (As a consequence, -the resulting pointcut is effectively the union of the specified patterns.) - -The following example shows how to use `JdkRegexpMethodPointcut`: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - .*set.* - .*absquatulate - - - ----- - -Spring provides a convenience class named `RegexpMethodPointcutAdvisor`, which lets us -also reference an `Advice` (remember that an `Advice` can be an interceptor, before advice, -throws advice, and others). Behind the scenes, Spring uses a `JdkRegexpMethodPointcut`. -Using `RegexpMethodPointcutAdvisor` simplifies wiring, as the one bean encapsulates both -pointcut and advice, as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - .*set.* - .*absquatulate - - - ----- - -You can use `RegexpMethodPointcutAdvisor` with any `Advice` type. - -[[aop-api-pointcuts-attribute-driven]] -===== Attribute-driven Pointcuts - -An important type of static pointcut is a metadata-driven pointcut. This uses the -values of metadata attributes (typically, source-level metadata). - - -[[aop-api-pointcuts-dynamic]] -==== Dynamic pointcuts - -Dynamic pointcuts are costlier to evaluate than static pointcuts. They take into account -method arguments as well as static information. This means that they must be -evaluated with every method invocation and that the result cannot be cached, as arguments will -vary. - -The main example is the `control flow` pointcut. - -[[aop-api-pointcuts-cflow]] -===== Control Flow Pointcuts - -Spring control flow pointcuts are conceptually similar to AspectJ `cflow` pointcuts, -although less powerful. (There is currently no way to specify that a pointcut runs -below a join point matched by another pointcut.) A control flow pointcut matches the -current call stack. For example, it might fire if the join point was invoked by a method -in the `com.mycompany.web` package or by the `SomeCaller` class. Control flow pointcuts -are specified by using the `org.springframework.aop.support.ControlFlowPointcut` class. - -NOTE: Control flow pointcuts are significantly more expensive to evaluate at runtime than even -other dynamic pointcuts. In Java 1.4, the cost is about five times that of other dynamic -pointcuts. - - - -[[aop-api-pointcuts-superclasses]] -=== Pointcut Superclasses - -Spring provides useful pointcut superclasses to help you to implement your own pointcuts. - -Because static pointcuts are most useful, you should probably subclass -`StaticMethodMatcherPointcut`. This requires implementing only one -abstract method (although you can override other methods to customize behavior). The -following example shows how to subclass `StaticMethodMatcherPointcut`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - class TestStaticPointcut extends StaticMethodMatcherPointcut { - - public boolean matches(Method m, Class targetClass) { - // return true if custom criteria match - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class TestStaticPointcut : StaticMethodMatcherPointcut() { - - override fun matches(method: Method, targetClass: Class<*>): Boolean { - // return true if custom criteria match - } - } ----- - -There are also superclasses for dynamic pointcuts. -You can use custom pointcuts with any advice type. - - - -[[aop-api-pointcuts-custom]] -=== Custom Pointcuts - -Because pointcuts in Spring AOP are Java classes rather than language features (as in -AspectJ), you can declare custom pointcuts, whether static or dynamic. Custom -pointcuts in Spring can be arbitrarily complex. However, we recommend using the AspectJ pointcut -expression language, if you can. - -NOTE: Later versions of Spring may offer support for "`semantic pointcuts`" as offered by JAC -- -for example, "`all methods that change instance variables in the target object.`" - - - - -[[aop-api-advice]] -== Advice API in Spring - -Now we can examine how Spring AOP handles advice. - - - -[[aop-api-advice-lifecycle]] -=== Advice Lifecycles - -Each advice is a Spring bean. An advice instance can be shared across all advised -objects or be unique to each advised object. This corresponds to per-class or -per-instance advice. - -Per-class advice is used most often. It is appropriate for generic advice, such as -transaction advisors. These do not depend on the state of the proxied object or add new -state. They merely act on the method and arguments. - -Per-instance advice is appropriate for introductions, to support mixins. In this case, -the advice adds state to the proxied object. - -You can use a mix of shared and per-instance advice in the same AOP proxy. - - - -[[aop-api-advice-types]] -=== Advice Types in Spring - -Spring provides several advice types and is extensible to support -arbitrary advice types. This section describes the basic concepts and standard advice types. - - -[[aop-api-advice-around]] -==== Interception Around Advice - -The most fundamental advice type in Spring is interception around advice. - -Spring is compliant with the AOP `Alliance` interface for around advice that uses method -interception. Classes that implement `MethodInterceptor` and that implement around advice should also implement the -following interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface MethodInterceptor extends Interceptor { - - Object invoke(MethodInvocation invocation) throws Throwable; - } ----- - -The `MethodInvocation` argument to the `invoke()` method exposes the method being -invoked, the target join point, the AOP proxy, and the arguments to the method. The -`invoke()` method should return the invocation's result: the return value of the join -point. - -The following example shows a simple `MethodInterceptor` implementation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class DebugInterceptor implements MethodInterceptor { - - public Object invoke(MethodInvocation invocation) throws Throwable { - System.out.println("Before: invocation=[" + invocation + "]"); - Object rval = invocation.proceed(); - System.out.println("Invocation returned"); - return rval; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class DebugInterceptor : MethodInterceptor { - - override fun invoke(invocation: MethodInvocation): Any { - println("Before: invocation=[$invocation]") - val rval = invocation.proceed() - println("Invocation returned") - return rval - } - } ----- - -Note the call to the `proceed()` method of `MethodInvocation`. This proceeds down the -interceptor chain towards the join point. Most interceptors invoke this method and -return its return value. However, a `MethodInterceptor`, like any around advice, can -return a different value or throw an exception rather than invoke the proceed method. -However, you do not want to do this without good reason. - -NOTE: `MethodInterceptor` implementations offer interoperability with other AOP Alliance-compliant AOP -implementations. The other advice types discussed in the remainder of this section -implement common AOP concepts but in a Spring-specific way. While there is an advantage -in using the most specific advice type, stick with `MethodInterceptor` around advice if -you are likely to want to run the aspect in another AOP framework. Note that pointcuts -are not currently interoperable between frameworks, and the AOP Alliance does not -currently define pointcut interfaces. - - -[[aop-api-advice-before]] -==== Before Advice - -A simpler advice type is a before advice. This does not need a `MethodInvocation` -object, since it is called only before entering the method. - -The main advantage of a before advice is that there is no need to invoke the `proceed()` -method and, therefore, no possibility of inadvertently failing to proceed down the -interceptor chain. - -The following listing shows the `MethodBeforeAdvice` interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface MethodBeforeAdvice extends BeforeAdvice { - - void before(Method m, Object[] args, Object target) throws Throwable; - } ----- - -(Spring's API design would allow for -field before advice, although the usual objects apply to field interception and it is -unlikely for Spring to ever implement it.) - -Note that the return type is `void`. Before advice can insert custom behavior before the join -point runs but cannot change the return value. If a before advice throws an -exception, it stops further execution of the interceptor chain. The exception -propagates back up the interceptor chain. If it is unchecked or on the signature of -the invoked method, it is passed directly to the client. Otherwise, it is -wrapped in an unchecked exception by the AOP proxy. - -The following example shows a before advice in Spring, which counts all method invocations: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class CountingBeforeAdvice implements MethodBeforeAdvice { - - private int count; - - public void before(Method m, Object[] args, Object target) throws Throwable { - ++count; - } - - public int getCount() { - return count; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class CountingBeforeAdvice : MethodBeforeAdvice { - - var count: Int = 0 - - override fun before(m: Method, args: Array, target: Any?) { - ++count - } - } ----- - -TIP: Before advice can be used with any pointcut. - - -[[aop-api-advice-throws]] -==== Throws Advice - -Throws advice is invoked after the return of the join point if the join point threw -an exception. Spring offers typed throws advice. Note that this means that the -`org.springframework.aop.ThrowsAdvice` interface does not contain any methods. It is a -tag interface identifying that the given object implements one or more typed throws -advice methods. These should be in the following form: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - afterThrowing([Method, args, target], subclassOfThrowable) ----- - -Only the last argument is required. The method signatures may have either one or four -arguments, depending on whether the advice method is interested in the method and -arguments. The next two listing show classes that are examples of throws advice. - -The following advice is invoked if a `RemoteException` is thrown (including from subclasses): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class RemoteThrowsAdvice implements ThrowsAdvice { - - public void afterThrowing(RemoteException ex) throws Throwable { - // Do something with remote exception - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class RemoteThrowsAdvice : ThrowsAdvice { - - fun afterThrowing(ex: RemoteException) { - // Do something with remote exception - } - } ----- - -Unlike the preceding -advice, the next example declares four arguments, so that it has access to the invoked method, method -arguments, and target object. The following advice is invoked if a `ServletException` is thrown: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ServletThrowsAdviceWithArguments implements ThrowsAdvice { - - public void afterThrowing(Method m, Object[] args, Object target, ServletException ex) { - // Do something with all arguments - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ServletThrowsAdviceWithArguments : ThrowsAdvice { - - fun afterThrowing(m: Method, args: Array, target: Any, ex: ServletException) { - // Do something with all arguments - } - } ----- - -The final example illustrates how these two methods could be used in a single class -that handles both `RemoteException` and `ServletException`. Any number of throws advice -methods can be combined in a single class. The following listing shows the final example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static class CombinedThrowsAdvice implements ThrowsAdvice { - - public void afterThrowing(RemoteException ex) throws Throwable { - // Do something with remote exception - } - - public void afterThrowing(Method m, Object[] args, Object target, ServletException ex) { - // Do something with all arguments - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class CombinedThrowsAdvice : ThrowsAdvice { - - fun afterThrowing(ex: RemoteException) { - // Do something with remote exception - } - - fun afterThrowing(m: Method, args: Array, target: Any, ex: ServletException) { - // Do something with all arguments - } - } ----- - -NOTE: If a throws-advice method throws an exception itself, it overrides the -original exception (that is, it changes the exception thrown to the user). The overriding -exception is typically a RuntimeException, which is compatible with any method -signature. However, if a throws-advice method throws a checked exception, it must -match the declared exceptions of the target method and is, hence, to some degree -coupled to specific target method signatures. _Do not throw an undeclared checked -exception that is incompatible with the target method's signature!_ - -TIP: Throws advice can be used with any pointcut. - - -[[aop-api-advice-after-returning]] -==== After Returning Advice - -An after returning advice in Spring must implement the -`org.springframework.aop.AfterReturningAdvice` interface, which the following listing shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface AfterReturningAdvice extends Advice { - - void afterReturning(Object returnValue, Method m, Object[] args, Object target) - throws Throwable; - } ----- - -An after returning advice has access to the return value (which it cannot modify), -the invoked method, the method's arguments, and the target. - -The following after returning advice counts all successful method invocations that have -not thrown exceptions: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class CountingAfterReturningAdvice implements AfterReturningAdvice { - - private int count; - - public void afterReturning(Object returnValue, Method m, Object[] args, Object target) - throws Throwable { - ++count; - } - - public int getCount() { - return count; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class CountingAfterReturningAdvice : AfterReturningAdvice { - - var count: Int = 0 - private set - - override fun afterReturning(returnValue: Any?, m: Method, args: Array, target: Any?) { - ++count - } - } ----- - -This advice does not change the execution path. If it throws an exception, it is -thrown up the interceptor chain instead of the return value. - -TIP: After returning advice can be used with any pointcut. - - -[[aop-api-advice-introduction]] -==== Introduction Advice - -Spring treats introduction advice as a special kind of interception advice. - -Introduction requires an `IntroductionAdvisor` and an `IntroductionInterceptor` that -implement the following interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface IntroductionInterceptor extends MethodInterceptor { - - boolean implementsInterface(Class intf); - } ----- - -The `invoke()` method inherited from the AOP Alliance `MethodInterceptor` interface must -implement the introduction. That is, if the invoked method is on an introduced -interface, the introduction interceptor is responsible for handling the method call -- it -cannot invoke `proceed()`. - -Introduction advice cannot be used with any pointcut, as it applies only at the class, -rather than the method, level. You can only use introduction advice with the -`IntroductionAdvisor`, which has the following methods: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface IntroductionAdvisor extends Advisor, IntroductionInfo { - - ClassFilter getClassFilter(); - - void validateInterfaces() throws IllegalArgumentException; - } - - public interface IntroductionInfo { - - Class[] getInterfaces(); - } ----- - -There is no `MethodMatcher` and, hence, no `Pointcut` associated with introduction -advice. Only class filtering is logical. - -The `getInterfaces()` method returns the interfaces introduced by this advisor. - -The `validateInterfaces()` method is used internally to see whether or not the -introduced interfaces can be implemented by the configured `IntroductionInterceptor`. - -Consider an example from the Spring test suite and suppose we want to -introduce the following interface to one or more objects: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public interface Lockable { - void lock(); - void unlock(); - boolean locked(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - interface Lockable { - fun lock() - fun unlock() - fun locked(): Boolean - } ----- - -This illustrates a mixin. We want to be able to cast advised objects to `Lockable`, -whatever their type and call lock and unlock methods. If we call the `lock()` method, we -want all setter methods to throw a `LockedException`. Thus, we can add an aspect that -provides the ability to make objects immutable without them having any knowledge of it: -a good example of AOP. - -First, we need an `IntroductionInterceptor` that does the heavy lifting. In this -case, we extend the `org.springframework.aop.support.DelegatingIntroductionInterceptor` -convenience class. We could implement `IntroductionInterceptor` directly, but using -`DelegatingIntroductionInterceptor` is best for most cases. - -The `DelegatingIntroductionInterceptor` is designed to delegate an introduction to an -actual implementation of the introduced interfaces, concealing the use of interception -to do so. You can set the delegate to any object using a constructor argument. The -default delegate (when the no-argument constructor is used) is `this`. Thus, in the next example, -the delegate is the `LockMixin` subclass of `DelegatingIntroductionInterceptor`. -Given a delegate (by default, itself), a `DelegatingIntroductionInterceptor` instance -looks for all interfaces implemented by the delegate (other than -`IntroductionInterceptor`) and supports introductions against any of them. -Subclasses such as `LockMixin` can call the `suppressInterface(Class intf)` -method to suppress interfaces that should not be exposed. However, no matter how many -interfaces an `IntroductionInterceptor` is prepared to support, the -`IntroductionAdvisor` used controls which interfaces are actually exposed. An -introduced interface conceals any implementation of the same interface by the target. - -Thus, `LockMixin` extends `DelegatingIntroductionInterceptor` and implements `Lockable` -itself. The superclass automatically picks up that `Lockable` can be supported for -introduction, so we do not need to specify that. We could introduce any number of -interfaces in this way. - -Note the use of the `locked` instance variable. This effectively adds additional state -to that held in the target object. - -The following example shows the example `LockMixin` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class LockMixin extends DelegatingIntroductionInterceptor implements Lockable { - - private boolean locked; - - public void lock() { - this.locked = true; - } - - public void unlock() { - this.locked = false; - } - - public boolean locked() { - return this.locked; - } - - public Object invoke(MethodInvocation invocation) throws Throwable { - if (locked() && invocation.getMethod().getName().indexOf("set") == 0) { - throw new LockedException(); - } - return super.invoke(invocation); - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class LockMixin : DelegatingIntroductionInterceptor(), Lockable { - - private var locked: Boolean = false - - fun lock() { - this.locked = true - } - - fun unlock() { - this.locked = false - } - - fun locked(): Boolean { - return this.locked - } - - override fun invoke(invocation: MethodInvocation): Any? { - if (locked() && invocation.method.name.indexOf("set") == 0) { - throw LockedException() - } - return super.invoke(invocation) - } - - } ----- - -Often, you need not override the `invoke()` method. The -`DelegatingIntroductionInterceptor` implementation (which calls the `delegate` method if -the method is introduced, otherwise proceeds towards the join point) usually -suffices. In the present case, we need to add a check: no setter method can be invoked -if in locked mode. - -The required introduction only needs to hold a distinct -`LockMixin` instance and specify the introduced interfaces (in this case, only -`Lockable`). A more complex example might take a reference to the introduction -interceptor (which would be defined as a prototype). In this case, there is no -configuration relevant for a `LockMixin`, so we create it by using `new`. -The following example shows our `LockMixinAdvisor` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class LockMixinAdvisor extends DefaultIntroductionAdvisor { - - public LockMixinAdvisor() { - super(new LockMixin(), Lockable.class); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class LockMixinAdvisor : DefaultIntroductionAdvisor(LockMixin(), Lockable::class.java) ----- - -We can apply this advisor very simply, because it requires no configuration. (However, it -is impossible to use an `IntroductionInterceptor` without an -`IntroductionAdvisor`.) As usual with introductions, the advisor must be per-instance, -as it is stateful. We need a different instance of `LockMixinAdvisor`, and hence -`LockMixin`, for each advised object. The advisor comprises part of the advised object's -state. - -We can apply this advisor programmatically by using the `Advised.addAdvisor()` method or -(the recommended way) in XML configuration, as any other advisor. All proxy creation -choices discussed below, including "`auto proxy creators,`" correctly handle introductions -and stateful mixins. - - - - - -[[aop-api-advisor]] -== The Advisor API in Spring - -In Spring, an Advisor is an aspect that contains only a single advice object associated -with a pointcut expression. - -Apart from the special case of introductions, any advisor can be used with any advice. -`org.springframework.aop.support.DefaultPointcutAdvisor` is the most commonly used -advisor class. It can be used with a `MethodInterceptor`, `BeforeAdvice`, or -`ThrowsAdvice`. - -It is possible to mix advisor and advice types in Spring in the same AOP proxy. For -example, you could use an interception around advice, throws advice, and before advice in -one proxy configuration. Spring automatically creates the necessary interceptor -chain. - - - - -[[aop-pfb]] -== Using the `ProxyFactoryBean` to Create AOP Proxies - -If you use the Spring IoC container (an `ApplicationContext` or `BeanFactory`) for your -business objects (and you should be!), you want to use one of Spring's AOP -`FactoryBean` implementations. (Remember that a factory bean introduces a layer of indirection, letting -it create objects of a different type.) - -NOTE: The Spring AOP support also uses factory beans under the covers. - -The basic way to create an AOP proxy in Spring is to use the -`org.springframework.aop.framework.ProxyFactoryBean`. This gives complete control over -the pointcuts, any advice that applies, and their ordering. However, there are simpler -options that are preferable if you do not need such control. - - - -[[aop-pfb-1]] -=== Basics - -The `ProxyFactoryBean`, like other Spring `FactoryBean` implementations, introduces a -level of indirection. If you define a `ProxyFactoryBean` named `foo`, objects that -reference `foo` do not see the `ProxyFactoryBean` instance itself but an object -created by the implementation of the `getObject()` method in the `ProxyFactoryBean` . This -method creates an AOP proxy that wraps a target object. - -One of the most important benefits of using a `ProxyFactoryBean` or another IoC-aware -class to create AOP proxies is that advice and pointcuts can also be -managed by IoC. This is a powerful feature, enabling certain approaches that are hard to -achieve with other AOP frameworks. For example, an advice may itself reference -application objects (besides the target, which should be available in any AOP -framework), benefiting from all the pluggability provided by Dependency Injection. - - - -[[aop-pfb-2]] -=== JavaBean Properties - -In common with most `FactoryBean` implementations provided with Spring, the -`ProxyFactoryBean` class is itself a JavaBean. Its properties are used to: - -* Specify the target you want to proxy. -* Specify whether to use CGLIB (described later and see also <>). - -Some key properties are inherited from `org.springframework.aop.framework.ProxyConfig` -(the superclass for all AOP proxy factories in Spring). These key properties include -the following: - -* `proxyTargetClass`: `true` if the target class is to be proxied, rather than the - target class's interfaces. If this property value is set to `true`, then CGLIB proxies - are created (but see also <>). -* `optimize`: Controls whether or not aggressive optimizations are applied to proxies - created through CGLIB. You should not blithely use this setting unless you fully - understand how the relevant AOP proxy handles optimization. This is currently used - only for CGLIB proxies. It has no effect with JDK dynamic proxies. -* `frozen`: If a proxy configuration is `frozen`, changes to the configuration are - no longer allowed. This is useful both as a slight optimization and for those cases - when you do not want callers to be able to manipulate the proxy (through the `Advised` - interface) after the proxy has been created. The default value of this property is - `false`, so changes (such as adding additional advice) are allowed. -* `exposeProxy`: Determines whether or not the current proxy should be exposed in a - `ThreadLocal` so that it can be accessed by the target. If a target needs to obtain - the proxy and the `exposeProxy` property is set to `true`, the target can use the - `AopContext.currentProxy()` method. - -Other properties specific to `ProxyFactoryBean` include the following: - -* `proxyInterfaces`: An array of `String` interface names. If this is not supplied, a CGLIB - proxy for the target class is used (but see also <>). -* `interceptorNames`: A `String` array of `Advisor`, interceptor, or other advice names to - apply. Ordering is significant, on a first come-first served basis. That is to say - that the first interceptor in the list is the first to be able to intercept the - invocation. -+ -The names are bean names in the current factory, including bean names from ancestor -factories. You cannot mention bean references here, since doing so results in the -`ProxyFactoryBean` ignoring the singleton setting of the advice. -+ -You can append an interceptor name with an asterisk (`*`). Doing so results in the -application of all advisor beans with names that start with the part before the asterisk -to be applied. You can find an example of using this feature in <>. - -* singleton: Whether or not the factory should return a single object, no matter how - often the `getObject()` method is called. Several `FactoryBean` implementations offer - such a method. The default value is `true`. If you want to use stateful advice - for - example, for stateful mixins - use prototype advice along with a singleton value of - `false`. - - - -[[aop-pfb-proxy-types]] -=== JDK- and CGLIB-based proxies - -This section serves as the definitive documentation on how the `ProxyFactoryBean` -chooses to create either a JDK-based proxy or a CGLIB-based proxy for a particular target -object (which is to be proxied). - -NOTE: The behavior of the `ProxyFactoryBean` with regard to creating JDK- or CGLIB-based -proxies changed between versions 1.2.x and 2.0 of Spring. The `ProxyFactoryBean` now -exhibits similar semantics with regard to auto-detecting interfaces as those of the -`TransactionProxyFactoryBean` class. - -If the class of a target object that is to be proxied (hereafter simply referred to as -the target class) does not implement any interfaces, a CGLIB-based proxy is -created. This is the easiest scenario, because JDK proxies are interface-based, and no -interfaces means JDK proxying is not even possible. You can plug in the target bean -and specify the list of interceptors by setting the `interceptorNames` property. Note that a -CGLIB-based proxy is created even if the `proxyTargetClass` property of the -`ProxyFactoryBean` has been set to `false`. (Doing so makes no sense and is best -removed from the bean definition, because it is, at best, redundant, and, at worst -confusing.) - -If the target class implements one (or more) interfaces, the type of proxy that is -created depends on the configuration of the `ProxyFactoryBean`. - -If the `proxyTargetClass` property of the `ProxyFactoryBean` has been set to `true`, -a CGLIB-based proxy is created. This makes sense and is in keeping with the -principle of least surprise. Even if the `proxyInterfaces` property of the -`ProxyFactoryBean` has been set to one or more fully qualified interface names, the fact -that the `proxyTargetClass` property is set to `true` causes CGLIB-based -proxying to be in effect. - -If the `proxyInterfaces` property of the `ProxyFactoryBean` has been set to one or more -fully qualified interface names, a JDK-based proxy is created. The created -proxy implements all of the interfaces that were specified in the `proxyInterfaces` -property. If the target class happens to implement a whole lot more interfaces than -those specified in the `proxyInterfaces` property, that is all well and good, but those -additional interfaces are not implemented by the returned proxy. - -If the `proxyInterfaces` property of the `ProxyFactoryBean` has not been set, but -the target class does implement one (or more) interfaces, the -`ProxyFactoryBean` auto-detects the fact that the target class does actually -implement at least one interface, and a JDK-based proxy is created. The interfaces -that are actually proxied are all of the interfaces that the target class -implements. In effect, this is the same as supplying a list of each and every -interface that the target class implements to the `proxyInterfaces` property. However, -it is significantly less work and less prone to typographical errors. - - - -[[aop-api-proxying-intf]] -=== Proxying Interfaces - -Consider a simple example of `ProxyFactoryBean` in action. This example involves: - -* A target bean that is proxied. This is the `personTarget` bean definition in - the example. -* An `Advisor` and an `Interceptor` used to provide advice. -* An AOP proxy bean definition to specify the target object (the `personTarget` bean), - the interfaces to proxy, and the advice to apply. - -The following listing shows the example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - - myAdvisor - debugInterceptor - - - ----- - -Note that the `interceptorNames` property takes a list of `String`, which holds the bean names of the -interceptors or advisors in the current factory. You can use advisors, interceptors, before, after -returning, and throws advice objects. The ordering of advisors is significant. - -NOTE: You might be wondering why the list does not hold bean references. The reason for this is -that, if the singleton property of the `ProxyFactoryBean` is set to `false`, it must be able to -return independent proxy instances. If any of the advisors is itself a prototype, an -independent instance would need to be returned, so it is necessary to be able to obtain -an instance of the prototype from the factory. Holding a reference is not sufficient. - -The `person` bean definition shown earlier can be used in place of a `Person` implementation, as -follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Person person = (Person) factory.getBean("person"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val person = factory.getBean("person") as Person; ----- - -Other beans in the same IoC context can express a strongly typed dependency on it, as -with an ordinary Java object. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -The `PersonUser` class in this example exposes a property of type `Person`. As far as -it is concerned, the AOP proxy can be used transparently in place of a "`real`" person -implementation. However, its class would be a dynamic proxy class. It would be possible -to cast it to the `Advised` interface (discussed later). - -You can conceal the distinction between target and proxy by using an anonymous -inner bean. Only the `ProxyFactoryBean` definition is different. The -advice is included only for completeness. The following example shows how to use an -anonymous inner bean: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - myAdvisor - debugInterceptor - - - ----- - -Using an anonymous inner bean has the advantage that there is only one object of type `Person`. This is useful if we want -to prevent users of the application context from obtaining a reference to the un-advised -object or need to avoid any ambiguity with Spring IoC autowiring. There is also, -arguably, an advantage in that the `ProxyFactoryBean` definition is self-contained. -However, there are times when being able to obtain the un-advised target from the -factory might actually be an advantage (for example, in certain test scenarios). - - - -[[aop-api-proxying-class]] -=== Proxying Classes - -What if you need to proxy a class, rather than one or more interfaces? - -Imagine that in our earlier example, there was no `Person` interface. We needed to advise -a class called `Person` that did not implement any business interface. In this case, you -can configure Spring to use CGLIB proxying rather than dynamic proxies. To do so, set the -`proxyTargetClass` property on the `ProxyFactoryBean` shown earlier to `true`. While it is best to -program to interfaces rather than classes, the ability to advise classes that do not -implement interfaces can be useful when working with legacy code. (In general, Spring -is not prescriptive. While it makes it easy to apply good practices, it avoids forcing a -particular approach.) - -If you want to, you can force the use of CGLIB in any case, even if you do have -interfaces. - -CGLIB proxying works by generating a subclass of the target class at runtime. Spring -configures this generated subclass to delegate method calls to the original target. The -subclass is used to implement the Decorator pattern, weaving in the advice. - -CGLIB proxying should generally be transparent to users. However, there are some issues -to consider: - -* `final` classes cannot be proxied, because they cannot be extended. -* `final` methods cannot be advised, because they cannot be overridden. -* `private` methods cannot be advised, because they cannot be overridden. - -NOTE: There is no need to add CGLIB to your classpath. CGLIB is repackaged and included -in the `spring-core` JAR. In other words, CGLIB-based AOP works "out of the box", as do -JDK dynamic proxies. - -There is little performance difference between CGLIB proxies and dynamic proxies. -Performance should not be a decisive consideration in this case. - - - -[[aop-global-advisors]] -=== Using "`Global`" Advisors - -By appending an asterisk to an interceptor name, all advisors with bean names that match -the part before the asterisk are added to the advisor chain. This can come in handy -if you need to add a standard set of "`global`" advisors. The following example defines -two global advisors: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - global* - - - - - - ----- - - - - -[[aop-concise-proxy]] -== Concise Proxy Definitions - -Especially when defining transactional proxies, you may end up with many similar proxy -definitions. The use of parent and child bean definitions, along with inner bean -definitions, can result in much cleaner and more concise proxy definitions. - -First, we create a parent, template, bean definition for the proxy, as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - PROPAGATION_REQUIRED - - - ----- - -This is never instantiated itself, so it can actually be incomplete. Then, each proxy -that needs to be created is a child bean definition, which wraps the target of the -proxy as an inner bean definition, since the target is never used on its own anyway. -The following example shows such a child bean: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -You can override properties from the parent template. In the following example, -we override the transaction propagation settings: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - PROPAGATION_REQUIRED,readOnly - PROPAGATION_REQUIRED,readOnly - PROPAGATION_REQUIRED,readOnly - PROPAGATION_REQUIRED - - - ----- - -Note that in the parent bean example, we explicitly marked the parent bean definition as -being abstract by setting the `abstract` attribute to `true`, as described -<>, so that it may not actually ever be -instantiated. Application contexts (but not simple bean factories), by default, -pre-instantiate all singletons. Therefore, it is important (at least for singleton beans) -that, if you have a (parent) bean definition that you intend to use only as a template, -and this definition specifies a class, you must make sure to set the `abstract` -attribute to `true`. Otherwise, the application context actually tries to -pre-instantiate it. - - - - -[[aop-prog]] -== Creating AOP Proxies Programmatically with the `ProxyFactory` - -It is easy to create AOP proxies programmatically with Spring. This lets you use -Spring AOP without dependency on Spring IoC. - -The interfaces implemented by the target object are -automatically proxied. The following listing shows creation of a proxy for a target object, with one -interceptor and one advisor: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ProxyFactory factory = new ProxyFactory(myBusinessInterfaceImpl); - factory.addAdvice(myMethodInterceptor); - factory.addAdvisor(myAdvisor); - MyBusinessInterface tb = (MyBusinessInterface) factory.getProxy(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val factory = ProxyFactory(myBusinessInterfaceImpl) - factory.addAdvice(myMethodInterceptor) - factory.addAdvisor(myAdvisor) - val tb = factory.proxy as MyBusinessInterface ----- - -The first step is to construct an object of type -`org.springframework.aop.framework.ProxyFactory`. You can create this with a target -object, as in the preceding example, or specify the interfaces to be proxied in an alternate -constructor. - -You can add advice (with interceptors as a specialized kind of advice), advisors, or both -and manipulate them for the life of the `ProxyFactory`. If you add an -`IntroductionInterceptionAroundAdvisor`, you can cause the proxy to implement additional -interfaces. - -There are also convenience methods on `ProxyFactory` (inherited from `AdvisedSupport`) -that let you add other advice types, such as before and throws advice. -`AdvisedSupport` is the superclass of both `ProxyFactory` and `ProxyFactoryBean`. - -TIP: Integrating AOP proxy creation with the IoC framework is best practice in most -applications. We recommend that you externalize configuration from Java code with AOP, -as you should in general. - - - - -[[aop-api-advised]] -== Manipulating Advised Objects - -However you create AOP proxies, you can manipulate them BY using the -`org.springframework.aop.framework.Advised` interface. Any AOP proxy can be cast to this -interface, no matter which other interfaces it implements. This interface includes the -following methods: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Advisor[] getAdvisors(); - - void addAdvice(Advice advice) throws AopConfigException; - - void addAdvice(int pos, Advice advice) throws AopConfigException; - - void addAdvisor(Advisor advisor) throws AopConfigException; - - void addAdvisor(int pos, Advisor advisor) throws AopConfigException; - - int indexOf(Advisor advisor); - - boolean removeAdvisor(Advisor advisor) throws AopConfigException; - - void removeAdvisor(int index) throws AopConfigException; - - boolean replaceAdvisor(Advisor a, Advisor b) throws AopConfigException; - - boolean isFrozen(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun getAdvisors(): Array - - @Throws(AopConfigException::class) - fun addAdvice(advice: Advice) - - @Throws(AopConfigException::class) - fun addAdvice(pos: Int, advice: Advice) - - @Throws(AopConfigException::class) - fun addAdvisor(advisor: Advisor) - - @Throws(AopConfigException::class) - fun addAdvisor(pos: Int, advisor: Advisor) - - fun indexOf(advisor: Advisor): Int - - @Throws(AopConfigException::class) - fun removeAdvisor(advisor: Advisor): Boolean - - @Throws(AopConfigException::class) - fun removeAdvisor(index: Int) - - @Throws(AopConfigException::class) - fun replaceAdvisor(a: Advisor, b: Advisor): Boolean - - fun isFrozen(): Boolean ----- - -The `getAdvisors()` method returns an `Advisor` for every advisor, interceptor, or -other advice type that has been added to the factory. If you added an `Advisor`, the -returned advisor at this index is the object that you added. If you added an -interceptor or other advice type, Spring wrapped this in an advisor with a -pointcut that always returns `true`. Thus, if you added a `MethodInterceptor`, the advisor -returned for this index is a `DefaultPointcutAdvisor` that returns your -`MethodInterceptor` and a pointcut that matches all classes and methods. - -The `addAdvisor()` methods can be used to add any `Advisor`. Usually, the advisor holding -pointcut and advice is the generic `DefaultPointcutAdvisor`, which you can use with -any advice or pointcut (but not for introductions). - -By default, it is possible to add or remove advisors or interceptors even once a proxy -has been created. The only restriction is that it is impossible to add or remove an -introduction advisor, as existing proxies from the factory do not show the interface -change. (You can obtain a new proxy from the factory to avoid this problem.) - -The following example shows casting an AOP proxy to the `Advised` interface and examining and -manipulating its advice: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Advised advised = (Advised) myObject; - Advisor[] advisors = advised.getAdvisors(); - int oldAdvisorCount = advisors.length; - System.out.println(oldAdvisorCount + " advisors"); - - // Add an advice like an interceptor without a pointcut - // Will match all proxied methods - // Can use for interceptors, before, after returning or throws advice - advised.addAdvice(new DebugInterceptor()); - - // Add selective advice using a pointcut - advised.addAdvisor(new DefaultPointcutAdvisor(mySpecialPointcut, myAdvice)); - - assertEquals("Added two advisors", oldAdvisorCount + 2, advised.getAdvisors().length); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val advised = myObject as Advised - val advisors = advised.advisors - val oldAdvisorCount = advisors.size - println("$oldAdvisorCount advisors") - - // Add an advice like an interceptor without a pointcut - // Will match all proxied methods - // Can use for interceptors, before, after returning or throws advice - advised.addAdvice(DebugInterceptor()) - - // Add selective advice using a pointcut - advised.addAdvisor(DefaultPointcutAdvisor(mySpecialPointcut, myAdvice)) - - assertEquals("Added two advisors", oldAdvisorCount + 2, advised.advisors.size) ----- - -NOTE: It is questionable whether it is advisable (no pun intended) to modify advice on a -business object in production, although there are, no doubt, legitimate usage cases. -However, it can be very useful in development (for example, in tests). We have sometimes -found it very useful to be able to add test code in the form of an interceptor or other -advice, getting inside a method invocation that we want to test. (For example, the advice can -get inside a transaction created for that method, perhaps to run SQL to check that -a database was correctly updated, before marking the transaction for roll back.) - -Depending on how you created the proxy, you can usually set a `frozen` flag. In that -case, the `Advised` `isFrozen()` method returns `true`, and any attempts to modify -advice through addition or removal results in an `AopConfigException`. The ability -to freeze the state of an advised object is useful in some cases (for example, to -prevent calling code removing a security interceptor). - - - - -[[aop-autoproxy]] -== Using the "auto-proxy" facility - -So far, we have considered explicit creation of AOP proxies by using a `ProxyFactoryBean` or -similar factory bean. - -Spring also lets us use "`auto-proxy`" bean definitions, which can automatically -proxy selected bean definitions. This is built on Spring's "`bean post processor`" -infrastructure, which enables modification of any bean definition as the container loads. - -In this model, you set up some special bean definitions in your XML bean definition file -to configure the auto-proxy infrastructure. This lets you declare the targets -eligible for auto-proxying. You need not use `ProxyFactoryBean`. - -There are two ways to do this: - -* By using an auto-proxy creator that refers to specific beans in the current context. -* A special case of auto-proxy creation that deserves to be considered separately: - auto-proxy creation driven by source-level metadata attributes. - - - -[[aop-autoproxy-choices]] -=== Auto-proxy Bean Definitions - -This section covers the auto-proxy creators provided by the -`org.springframework.aop.framework.autoproxy` package. - - -[[aop-api-autoproxy]] -==== `BeanNameAutoProxyCreator` - -The `BeanNameAutoProxyCreator` class is a `BeanPostProcessor` that automatically creates -AOP proxies for beans with names that match literal values or wildcards. The following -example shows how to create a `BeanNameAutoProxyCreator` bean: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - myInterceptor - - - ----- - -As with `ProxyFactoryBean`, there is an `interceptorNames` property rather than a list -of interceptors, to allow correct behavior for prototype advisors. Named "`interceptors`" -can be advisors or any advice type. - -As with auto-proxying in general, the main point of using `BeanNameAutoProxyCreator` is -to apply the same configuration consistently to multiple objects, with minimal volume of -configuration. It is a popular choice for applying declarative transactions to multiple -objects. - -Bean definitions whose names match, such as `jdkMyBean` and `onlyJdk` in the preceding -example, are plain old bean definitions with the target class. An AOP proxy is -automatically created by the `BeanNameAutoProxyCreator`. The same advice is applied -to all matching beans. Note that, if advisors are used (rather than the interceptor in -the preceding example), the pointcuts may apply differently to different beans. - - -[[aop-api-autoproxy-default]] -==== `DefaultAdvisorAutoProxyCreator` - -A more general and extremely powerful auto-proxy creator is -`DefaultAdvisorAutoProxyCreator`. This automagically applies eligible advisors in the -current context, without the need to include specific bean names in the auto-proxy -advisor's bean definition. It offers the same merit of consistent configuration and -avoidance of duplication as `BeanNameAutoProxyCreator`. - -Using this mechanism involves: - -* Specifying a `DefaultAdvisorAutoProxyCreator` bean definition. -* Specifying any number of advisors in the same or related contexts. Note that these - must be advisors, not interceptors or other advice. This is necessary, - because there must be a pointcut to evaluate, to check the eligibility of each advice - to candidate bean definitions. - -The `DefaultAdvisorAutoProxyCreator` automatically evaluates the pointcut contained -in each advisor, to see what (if any) advice it should apply to each business object -(such as `businessObject1` and `businessObject2` in the example). - -This means that any number of advisors can be applied automatically to each business -object. If no pointcut in any of the advisors matches any method in a business object, -the object is not proxied. As bean definitions are added for new business objects, -they are automatically proxied if necessary. - -Auto-proxying in general has the advantage of making it impossible for callers or -dependencies to obtain an un-advised object. Calling `getBean("businessObject1")` on this -`ApplicationContext` returns an AOP proxy, not the target business object. (The "`inner -bean`" idiom shown earlier also offers this benefit.) - -The following example creates a `DefaultAdvisorAutoProxyCreator` bean and the other -elements discussed in this section: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - ----- - -The `DefaultAdvisorAutoProxyCreator` is very useful if you want to apply the same advice -consistently to many business objects. Once the infrastructure definitions are in place, -you can add new business objects without including specific proxy configuration. -You can also easily drop in additional aspects (for example, tracing or -performance monitoring aspects) with minimal change to configuration. - -The `DefaultAdvisorAutoProxyCreator` offers support for filtering (by using a naming -convention so that only certain advisors are evaluated, which allows the use of multiple, -differently configured, AdvisorAutoProxyCreators in the same factory) and ordering. -Advisors can implement the `org.springframework.core.Ordered` interface to ensure -correct ordering if this is an issue. The `TransactionAttributeSourceAdvisor` used in the -preceding example has a configurable order value. The default setting is unordered. - - - - -[[aop-targetsource]] -== Using `TargetSource` Implementations - -Spring offers the concept of a `TargetSource`, expressed in the -`org.springframework.aop.TargetSource` interface. This interface is responsible for -returning the "`target object`" that implements the join point. The `TargetSource` -implementation is asked for a target instance each time the AOP proxy handles a method -invocation. - -Developers who use Spring AOP do not normally need to work directly with `TargetSource` implementations, but -this provides a powerful means of supporting pooling, hot swappable, and other -sophisticated targets. For example, a pooling `TargetSource` can return a different target -instance for each invocation, by using a pool to manage instances. - -If you do not specify a `TargetSource`, a default implementation is used to wrap a -local object. The same target is returned for each invocation (as you would expect). - -The rest of this section describes the standard target sources provided with Spring and how you can use them. - -TIP: When using a custom target source, your target will usually need to be a prototype -rather than a singleton bean definition. This allows Spring to create a new target -instance when required. - - - -[[aop-ts-swap]] -=== Hot-swappable Target Sources - -The `org.springframework.aop.target.HotSwappableTargetSource` exists to let the target -of an AOP proxy be switched while letting callers keep their references to it. - -Changing the target source's target takes effect immediately. The -`HotSwappableTargetSource` is thread-safe. - -You can change the target by using the `swap()` method on HotSwappableTargetSource, as the follow example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HotSwappableTargetSource swapper = (HotSwappableTargetSource) beanFactory.getBean("swapper"); - Object oldTarget = swapper.swap(newTarget); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val swapper = beanFactory.getBean("swapper") as HotSwappableTargetSource - val oldTarget = swapper.swap(newTarget) ----- - -The following example shows the required XML definitions: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - ----- - -The preceding `swap()` call changes the target of the swappable bean. Clients that hold a -reference to that bean are unaware of the change but immediately start hitting -the new target. - -Although this example does not add any advice (it is not necessary to add advice to -use a `TargetSource`), any `TargetSource` can be used in conjunction with -arbitrary advice. - - - -[[aop-ts-pool]] -=== Pooling Target Sources - -Using a pooling target source provides a similar programming model to stateless session -EJBs, in which a pool of identical instances is maintained, with method invocations -going to free objects in the pool. - -A crucial difference between Spring pooling and SLSB pooling is that Spring pooling can -be applied to any POJO. As with Spring in general, this service can be applied in a -non-invasive way. - -Spring provides support for Commons Pool 2.2, which provides a -fairly efficient pooling implementation. You need the `commons-pool` Jar on your -application's classpath to use this feature. You can also subclass -`org.springframework.aop.target.AbstractPoolingTargetSource` to support any other -pooling API. - -NOTE: Commons Pool 1.5+ is also supported but is deprecated as of Spring Framework 4.2. - -The following listing shows an example configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ... properties omitted - - - - - - - - - - - ----- - -Note that the target object (`businessObjectTarget` in the preceding example) must be a -prototype. This lets the `PoolingTargetSource` implementation create new instances -of the target to grow the pool as necessary. See the {api-spring-framework}/aop/target/AbstractPoolingTargetSource.html[javadoc of -`AbstractPoolingTargetSource`] and the concrete subclass you wish to use for information -about its properties. `maxSize` is the most basic and is always guaranteed to be present. - -In this case, `myInterceptor` is the name of an interceptor that would need to be -defined in the same IoC context. However, you need not specify interceptors to -use pooling. If you want only pooling and no other advice, do not set the -`interceptorNames` property at all. - -You can configure Spring to be able to cast any pooled object to the -`org.springframework.aop.target.PoolingConfig` interface, which exposes information -about the configuration and current size of the pool through an introduction. You -need to define an advisor similar to the following: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - -This advisor is obtained by calling a convenience method on the -`AbstractPoolingTargetSource` class, hence the use of `MethodInvokingFactoryBean`. This -advisor's name (`poolConfigAdvisor`, here) must be in the list of interceptors names in -the `ProxyFactoryBean` that exposes the pooled object. - -The cast is defined as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - PoolingConfig conf = (PoolingConfig) beanFactory.getBean("businessObject"); - System.out.println("Max pool size is " + conf.getMaxSize()); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val conf = beanFactory.getBean("businessObject") as PoolingConfig - println("Max pool size is " + conf.maxSize) ----- - -NOTE: Pooling stateless service objects is not usually necessary. We do not believe it should -be the default choice, as most stateless objects are naturally thread safe, and instance -pooling is problematic if resources are cached. - -Simpler pooling is available by using auto-proxying. You can set the `TargetSource` implementations -used by any auto-proxy creator. - - - -[[aop-ts-prototype]] -=== Prototype Target Sources - -Setting up a "`prototype`" target source is similar to setting up a pooling `TargetSource`. In this -case, a new instance of the target is created on every method invocation. Although -the cost of creating a new object is not high in a modern JVM, the cost of wiring up the -new object (satisfying its IoC dependencies) may be more expensive. Thus, you should not -use this approach without very good reason. - -To do this, you could modify the `poolTargetSource` definition shown earlier as follows -(we also changed the name, for clarity): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -The only property is the name of the target bean. Inheritance is used in the -`TargetSource` implementations to ensure consistent naming. As with the pooling target -source, the target bean must be a prototype bean definition. - - - -[[aop-ts-threadlocal]] -=== `ThreadLocal` Target Sources - -`ThreadLocal` target sources are useful if you need an object to be created for each -incoming request (per thread that is). The concept of a `ThreadLocal` provides a JDK-wide -facility to transparently store a resource alongside a thread. Setting up a -`ThreadLocalTargetSource` is pretty much the same as was explained for the other types -of target source, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -NOTE: `ThreadLocal` instances come with serious issues (potentially resulting in memory leaks) when -incorrectly using them in multi-threaded and multi-classloader environments. You -should always consider wrapping a `ThreadLocal` in some other class and never directly use -the `ThreadLocal` itself (except in the wrapper class). Also, you should -always remember to correctly set and unset (where the latter simply involves a call to -`ThreadLocal.set(null)`) the resource local to the thread. Unsetting should be done in -any case, since not unsetting it might result in problematic behavior. Spring's -`ThreadLocal` support does this for you and should always be considered in favor of using -`ThreadLocal` instances without other proper handling code. - - - - -[[aop-extensibility]] -== Defining New Advice Types - -Spring AOP is designed to be extensible. While the interception implementation strategy -is presently used internally, it is possible to support arbitrary advice types in -addition to the interception around advice, before, throws advice, and -after returning advice. - -The `org.springframework.aop.framework.adapter` package is an SPI package that lets -support for new custom advice types be added without changing the core framework. -The only constraint on a custom `Advice` type is that it must implement the -`org.aopalliance.aop.Advice` marker interface. - -See the {api-spring-framework}/aop/framework/adapter/package-summary.html[`org.springframework.aop.framework.adapter`] -javadoc for further information. diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/advice.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/advice.adoc new file mode 100644 index 000000000000..fc026e81cba1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/advice.adoc @@ -0,0 +1,538 @@ +[[aop-api-advice]] += Advice API in Spring + +Now we can examine how Spring AOP handles advice. + + + +[[aop-api-advice-lifecycle]] +== Advice Lifecycles + +Each advice is a Spring bean. An advice instance can be shared across all advised +objects or be unique to each advised object. This corresponds to per-class or +per-instance advice. + +Per-class advice is used most often. It is appropriate for generic advice, such as +transaction advisors. These do not depend on the state of the proxied object or add new +state. They merely act on the method and arguments. + +Per-instance advice is appropriate for introductions, to support mixins. In this case, +the advice adds state to the proxied object. + +You can use a mix of shared and per-instance advice in the same AOP proxy. + + + +[[aop-api-advice-types]] +== Advice Types in Spring + +Spring provides several advice types and is extensible to support +arbitrary advice types. This section describes the basic concepts and standard advice types. + + +[[aop-api-advice-around]] +=== Interception Around Advice + +The most fundamental advice type in Spring is interception around advice. + +Spring is compliant with the AOP `Alliance` interface for around advice that uses method +interception. Classes that implement `MethodInterceptor` and that implement around advice should also implement the +following interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface MethodInterceptor extends Interceptor { + + Object invoke(MethodInvocation invocation) throws Throwable; + } +---- + +The `MethodInvocation` argument to the `invoke()` method exposes the method being +invoked, the target join point, the AOP proxy, and the arguments to the method. The +`invoke()` method should return the invocation's result: the return value of the join +point. + +The following example shows a simple `MethodInterceptor` implementation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class DebugInterceptor implements MethodInterceptor { + + public Object invoke(MethodInvocation invocation) throws Throwable { + System.out.println("Before: invocation=[" + invocation + "]"); + Object rval = invocation.proceed(); + System.out.println("Invocation returned"); + return rval; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class DebugInterceptor : MethodInterceptor { + + override fun invoke(invocation: MethodInvocation): Any { + println("Before: invocation=[$invocation]") + val rval = invocation.proceed() + println("Invocation returned") + return rval + } + } +---- + +Note the call to the `proceed()` method of `MethodInvocation`. This proceeds down the +interceptor chain towards the join point. Most interceptors invoke this method and +return its return value. However, a `MethodInterceptor`, like any around advice, can +return a different value or throw an exception rather than invoke the proceed method. +However, you do not want to do this without good reason. + +NOTE: `MethodInterceptor` implementations offer interoperability with other AOP Alliance-compliant AOP +implementations. The other advice types discussed in the remainder of this section +implement common AOP concepts but in a Spring-specific way. While there is an advantage +in using the most specific advice type, stick with `MethodInterceptor` around advice if +you are likely to want to run the aspect in another AOP framework. Note that pointcuts +are not currently interoperable between frameworks, and the AOP Alliance does not +currently define pointcut interfaces. + + +[[aop-api-advice-before]] +=== Before Advice + +A simpler advice type is a before advice. This does not need a `MethodInvocation` +object, since it is called only before entering the method. + +The main advantage of a before advice is that there is no need to invoke the `proceed()` +method and, therefore, no possibility of inadvertently failing to proceed down the +interceptor chain. + +The following listing shows the `MethodBeforeAdvice` interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface MethodBeforeAdvice extends BeforeAdvice { + + void before(Method m, Object[] args, Object target) throws Throwable; + } +---- + +(Spring's API design would allow for +field before advice, although the usual objects apply to field interception and it is +unlikely for Spring to ever implement it.) + +Note that the return type is `void`. Before advice can insert custom behavior before the join +point runs but cannot change the return value. If a before advice throws an +exception, it stops further execution of the interceptor chain. The exception +propagates back up the interceptor chain. If it is unchecked or on the signature of +the invoked method, it is passed directly to the client. Otherwise, it is +wrapped in an unchecked exception by the AOP proxy. + +The following example shows a before advice in Spring, which counts all method invocations: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class CountingBeforeAdvice implements MethodBeforeAdvice { + + private int count; + + public void before(Method m, Object[] args, Object target) throws Throwable { + ++count; + } + + public int getCount() { + return count; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class CountingBeforeAdvice : MethodBeforeAdvice { + + var count: Int = 0 + + override fun before(m: Method, args: Array, target: Any?) { + ++count + } + } +---- + +TIP: Before advice can be used with any pointcut. + + +[[aop-api-advice-throws]] +=== Throws Advice + +Throws advice is invoked after the return of the join point if the join point threw +an exception. Spring offers typed throws advice. Note that this means that the +`org.springframework.aop.ThrowsAdvice` interface does not contain any methods. It is a +tag interface identifying that the given object implements one or more typed throws +advice methods. These should be in the following form: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + afterThrowing([Method, args, target], subclassOfThrowable) +---- + +Only the last argument is required. The method signatures may have either one or four +arguments, depending on whether the advice method is interested in the method and +arguments. The next two listing show classes that are examples of throws advice. + +The following advice is invoked if a `RemoteException` is thrown (including from subclasses): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class RemoteThrowsAdvice implements ThrowsAdvice { + + public void afterThrowing(RemoteException ex) throws Throwable { + // Do something with remote exception + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class RemoteThrowsAdvice : ThrowsAdvice { + + fun afterThrowing(ex: RemoteException) { + // Do something with remote exception + } + } +---- + +Unlike the preceding +advice, the next example declares four arguments, so that it has access to the invoked method, method +arguments, and target object. The following advice is invoked if a `ServletException` is thrown: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ServletThrowsAdviceWithArguments implements ThrowsAdvice { + + public void afterThrowing(Method m, Object[] args, Object target, ServletException ex) { + // Do something with all arguments + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ServletThrowsAdviceWithArguments : ThrowsAdvice { + + fun afterThrowing(m: Method, args: Array, target: Any, ex: ServletException) { + // Do something with all arguments + } + } +---- + +The final example illustrates how these two methods could be used in a single class +that handles both `RemoteException` and `ServletException`. Any number of throws advice +methods can be combined in a single class. The following listing shows the final example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static class CombinedThrowsAdvice implements ThrowsAdvice { + + public void afterThrowing(RemoteException ex) throws Throwable { + // Do something with remote exception + } + + public void afterThrowing(Method m, Object[] args, Object target, ServletException ex) { + // Do something with all arguments + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class CombinedThrowsAdvice : ThrowsAdvice { + + fun afterThrowing(ex: RemoteException) { + // Do something with remote exception + } + + fun afterThrowing(m: Method, args: Array, target: Any, ex: ServletException) { + // Do something with all arguments + } + } +---- + +NOTE: If a throws-advice method throws an exception itself, it overrides the +original exception (that is, it changes the exception thrown to the user). The overriding +exception is typically a RuntimeException, which is compatible with any method +signature. However, if a throws-advice method throws a checked exception, it must +match the declared exceptions of the target method and is, hence, to some degree +coupled to specific target method signatures. _Do not throw an undeclared checked +exception that is incompatible with the target method's signature!_ + +TIP: Throws advice can be used with any pointcut. + + +[[aop-api-advice-after-returning]] +=== After Returning Advice + +An after returning advice in Spring must implement the +`org.springframework.aop.AfterReturningAdvice` interface, which the following listing shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface AfterReturningAdvice extends Advice { + + void afterReturning(Object returnValue, Method m, Object[] args, Object target) + throws Throwable; + } +---- + +An after returning advice has access to the return value (which it cannot modify), +the invoked method, the method's arguments, and the target. + +The following after returning advice counts all successful method invocations that have +not thrown exceptions: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class CountingAfterReturningAdvice implements AfterReturningAdvice { + + private int count; + + public void afterReturning(Object returnValue, Method m, Object[] args, Object target) + throws Throwable { + ++count; + } + + public int getCount() { + return count; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class CountingAfterReturningAdvice : AfterReturningAdvice { + + var count: Int = 0 + private set + + override fun afterReturning(returnValue: Any?, m: Method, args: Array, target: Any?) { + ++count + } + } +---- + +This advice does not change the execution path. If it throws an exception, it is +thrown up the interceptor chain instead of the return value. + +TIP: After returning advice can be used with any pointcut. + + +[[aop-api-advice-introduction]] +=== Introduction Advice + +Spring treats introduction advice as a special kind of interception advice. + +Introduction requires an `IntroductionAdvisor` and an `IntroductionInterceptor` that +implement the following interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface IntroductionInterceptor extends MethodInterceptor { + + boolean implementsInterface(Class intf); + } +---- + +The `invoke()` method inherited from the AOP Alliance `MethodInterceptor` interface must +implement the introduction. That is, if the invoked method is on an introduced +interface, the introduction interceptor is responsible for handling the method call -- it +cannot invoke `proceed()`. + +Introduction advice cannot be used with any pointcut, as it applies only at the class, +rather than the method, level. You can only use introduction advice with the +`IntroductionAdvisor`, which has the following methods: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface IntroductionAdvisor extends Advisor, IntroductionInfo { + + ClassFilter getClassFilter(); + + void validateInterfaces() throws IllegalArgumentException; + } + + public interface IntroductionInfo { + + Class[] getInterfaces(); + } +---- + +There is no `MethodMatcher` and, hence, no `Pointcut` associated with introduction +advice. Only class filtering is logical. + +The `getInterfaces()` method returns the interfaces introduced by this advisor. + +The `validateInterfaces()` method is used internally to see whether or not the +introduced interfaces can be implemented by the configured `IntroductionInterceptor`. + +Consider an example from the Spring test suite and suppose we want to +introduce the following interface to one or more objects: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public interface Lockable { + void lock(); + void unlock(); + boolean locked(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + interface Lockable { + fun lock() + fun unlock() + fun locked(): Boolean + } +---- + +This illustrates a mixin. We want to be able to cast advised objects to `Lockable`, +whatever their type and call lock and unlock methods. If we call the `lock()` method, we +want all setter methods to throw a `LockedException`. Thus, we can add an aspect that +provides the ability to make objects immutable without them having any knowledge of it: +a good example of AOP. + +First, we need an `IntroductionInterceptor` that does the heavy lifting. In this +case, we extend the `org.springframework.aop.support.DelegatingIntroductionInterceptor` +convenience class. We could implement `IntroductionInterceptor` directly, but using +`DelegatingIntroductionInterceptor` is best for most cases. + +The `DelegatingIntroductionInterceptor` is designed to delegate an introduction to an +actual implementation of the introduced interfaces, concealing the use of interception +to do so. You can set the delegate to any object using a constructor argument. The +default delegate (when the no-argument constructor is used) is `this`. Thus, in the next example, +the delegate is the `LockMixin` subclass of `DelegatingIntroductionInterceptor`. +Given a delegate (by default, itself), a `DelegatingIntroductionInterceptor` instance +looks for all interfaces implemented by the delegate (other than +`IntroductionInterceptor`) and supports introductions against any of them. +Subclasses such as `LockMixin` can call the `suppressInterface(Class intf)` +method to suppress interfaces that should not be exposed. However, no matter how many +interfaces an `IntroductionInterceptor` is prepared to support, the +`IntroductionAdvisor` used controls which interfaces are actually exposed. An +introduced interface conceals any implementation of the same interface by the target. + +Thus, `LockMixin` extends `DelegatingIntroductionInterceptor` and implements `Lockable` +itself. The superclass automatically picks up that `Lockable` can be supported for +introduction, so we do not need to specify that. We could introduce any number of +interfaces in this way. + +Note the use of the `locked` instance variable. This effectively adds additional state +to that held in the target object. + +The following example shows the example `LockMixin` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class LockMixin extends DelegatingIntroductionInterceptor implements Lockable { + + private boolean locked; + + public void lock() { + this.locked = true; + } + + public void unlock() { + this.locked = false; + } + + public boolean locked() { + return this.locked; + } + + public Object invoke(MethodInvocation invocation) throws Throwable { + if (locked() && invocation.getMethod().getName().indexOf("set") == 0) { + throw new LockedException(); + } + return super.invoke(invocation); + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class LockMixin : DelegatingIntroductionInterceptor(), Lockable { + + private var locked: Boolean = false + + fun lock() { + this.locked = true + } + + fun unlock() { + this.locked = false + } + + fun locked(): Boolean { + return this.locked + } + + override fun invoke(invocation: MethodInvocation): Any? { + if (locked() && invocation.method.name.indexOf("set") == 0) { + throw LockedException() + } + return super.invoke(invocation) + } + + } +---- + +Often, you need not override the `invoke()` method. The +`DelegatingIntroductionInterceptor` implementation (which calls the `delegate` method if +the method is introduced, otherwise proceeds towards the join point) usually +suffices. In the present case, we need to add a check: no setter method can be invoked +if in locked mode. + +The required introduction only needs to hold a distinct +`LockMixin` instance and specify the introduced interfaces (in this case, only +`Lockable`). A more complex example might take a reference to the introduction +interceptor (which would be defined as a prototype). In this case, there is no +configuration relevant for a `LockMixin`, so we create it by using `new`. +The following example shows our `LockMixinAdvisor` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class LockMixinAdvisor extends DefaultIntroductionAdvisor { + + public LockMixinAdvisor() { + super(new LockMixin(), Lockable.class); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class LockMixinAdvisor : DefaultIntroductionAdvisor(LockMixin(), Lockable::class.java) +---- + +We can apply this advisor very simply, because it requires no configuration. (However, it +is impossible to use an `IntroductionInterceptor` without an +`IntroductionAdvisor`.) As usual with introductions, the advisor must be per-instance, +as it is stateful. We need a different instance of `LockMixinAdvisor`, and hence +`LockMixin`, for each advised object. The advisor comprises part of the advised object's +state. + +We can apply this advisor programmatically by using the `Advised.addAdvisor()` method or +(the recommended way) in XML configuration, as any other advisor. All proxy creation +choices discussed below, including "`auto proxy creators,`" correctly handle introductions +and stateful mixins. + + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/advised.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/advised.adoc new file mode 100644 index 000000000000..f216c9b4d444 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/advised.adoc @@ -0,0 +1,136 @@ +[[aop-api-advised]] += Manipulating Advised Objects + +However you create AOP proxies, you can manipulate them BY using the +`org.springframework.aop.framework.Advised` interface. Any AOP proxy can be cast to this +interface, no matter which other interfaces it implements. This interface includes the +following methods: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Advisor[] getAdvisors(); + + void addAdvice(Advice advice) throws AopConfigException; + + void addAdvice(int pos, Advice advice) throws AopConfigException; + + void addAdvisor(Advisor advisor) throws AopConfigException; + + void addAdvisor(int pos, Advisor advisor) throws AopConfigException; + + int indexOf(Advisor advisor); + + boolean removeAdvisor(Advisor advisor) throws AopConfigException; + + void removeAdvisor(int index) throws AopConfigException; + + boolean replaceAdvisor(Advisor a, Advisor b) throws AopConfigException; + + boolean isFrozen(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun getAdvisors(): Array + + @Throws(AopConfigException::class) + fun addAdvice(advice: Advice) + + @Throws(AopConfigException::class) + fun addAdvice(pos: Int, advice: Advice) + + @Throws(AopConfigException::class) + fun addAdvisor(advisor: Advisor) + + @Throws(AopConfigException::class) + fun addAdvisor(pos: Int, advisor: Advisor) + + fun indexOf(advisor: Advisor): Int + + @Throws(AopConfigException::class) + fun removeAdvisor(advisor: Advisor): Boolean + + @Throws(AopConfigException::class) + fun removeAdvisor(index: Int) + + @Throws(AopConfigException::class) + fun replaceAdvisor(a: Advisor, b: Advisor): Boolean + + fun isFrozen(): Boolean +---- + +The `getAdvisors()` method returns an `Advisor` for every advisor, interceptor, or +other advice type that has been added to the factory. If you added an `Advisor`, the +returned advisor at this index is the object that you added. If you added an +interceptor or other advice type, Spring wrapped this in an advisor with a +pointcut that always returns `true`. Thus, if you added a `MethodInterceptor`, the advisor +returned for this index is a `DefaultPointcutAdvisor` that returns your +`MethodInterceptor` and a pointcut that matches all classes and methods. + +The `addAdvisor()` methods can be used to add any `Advisor`. Usually, the advisor holding +pointcut and advice is the generic `DefaultPointcutAdvisor`, which you can use with +any advice or pointcut (but not for introductions). + +By default, it is possible to add or remove advisors or interceptors even once a proxy +has been created. The only restriction is that it is impossible to add or remove an +introduction advisor, as existing proxies from the factory do not show the interface +change. (You can obtain a new proxy from the factory to avoid this problem.) + +The following example shows casting an AOP proxy to the `Advised` interface and examining and +manipulating its advice: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Advised advised = (Advised) myObject; + Advisor[] advisors = advised.getAdvisors(); + int oldAdvisorCount = advisors.length; + System.out.println(oldAdvisorCount + " advisors"); + + // Add an advice like an interceptor without a pointcut + // Will match all proxied methods + // Can use for interceptors, before, after returning or throws advice + advised.addAdvice(new DebugInterceptor()); + + // Add selective advice using a pointcut + advised.addAdvisor(new DefaultPointcutAdvisor(mySpecialPointcut, myAdvice)); + + assertEquals("Added two advisors", oldAdvisorCount + 2, advised.getAdvisors().length); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val advised = myObject as Advised + val advisors = advised.advisors + val oldAdvisorCount = advisors.size + println("$oldAdvisorCount advisors") + + // Add an advice like an interceptor without a pointcut + // Will match all proxied methods + // Can use for interceptors, before, after returning or throws advice + advised.addAdvice(DebugInterceptor()) + + // Add selective advice using a pointcut + advised.addAdvisor(DefaultPointcutAdvisor(mySpecialPointcut, myAdvice)) + + assertEquals("Added two advisors", oldAdvisorCount + 2, advised.advisors.size) +---- + +NOTE: It is questionable whether it is advisable (no pun intended) to modify advice on a +business object in production, although there are, no doubt, legitimate usage cases. +However, it can be very useful in development (for example, in tests). We have sometimes +found it very useful to be able to add test code in the form of an interceptor or other +advice, getting inside a method invocation that we want to test. (For example, the advice can +get inside a transaction created for that method, perhaps to run SQL to check that +a database was correctly updated, before marking the transaction for roll back.) + +Depending on how you created the proxy, you can usually set a `frozen` flag. In that +case, the `Advised` `isFrozen()` method returns `true`, and any attempts to modify +advice through addition or removal results in an `AopConfigException`. The ability +to freeze the state of an advised object is useful in some cases (for example, to +prevent calling code removing a security interceptor). + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/advisor.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/advisor.adoc new file mode 100644 index 000000000000..8bdccc6a73f3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/advisor.adoc @@ -0,0 +1,19 @@ +[[aop-api-advisor]] += The Advisor API in Spring + +In Spring, an Advisor is an aspect that contains only a single advice object associated +with a pointcut expression. + +Apart from the special case of introductions, any advisor can be used with any advice. +`org.springframework.aop.support.DefaultPointcutAdvisor` is the most commonly used +advisor class. It can be used with a `MethodInterceptor`, `BeforeAdvice`, or +`ThrowsAdvice`. + +It is possible to mix advisor and advice types in Spring in the same AOP proxy. For +example, you could use an interception around advice, throws advice, and before advice in +one proxy configuration. Spring automatically creates the necessary interceptor +chain. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/autoproxy.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/autoproxy.adoc new file mode 100644 index 000000000000..60438bbc174d --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/autoproxy.adoc @@ -0,0 +1,131 @@ +[[aop-autoproxy]] += Using the "auto-proxy" facility + +So far, we have considered explicit creation of AOP proxies by using a `ProxyFactoryBean` or +similar factory bean. + +Spring also lets us use "`auto-proxy`" bean definitions, which can automatically +proxy selected bean definitions. This is built on Spring's "`bean post processor`" +infrastructure, which enables modification of any bean definition as the container loads. + +In this model, you set up some special bean definitions in your XML bean definition file +to configure the auto-proxy infrastructure. This lets you declare the targets +eligible for auto-proxying. You need not use `ProxyFactoryBean`. + +There are two ways to do this: + +* By using an auto-proxy creator that refers to specific beans in the current context. +* A special case of auto-proxy creation that deserves to be considered separately: + auto-proxy creation driven by source-level metadata attributes. + + + +[[aop-autoproxy-choices]] +== Auto-proxy Bean Definitions + +This section covers the auto-proxy creators provided by the +`org.springframework.aop.framework.autoproxy` package. + + +[[aop-api-autoproxy]] +=== `BeanNameAutoProxyCreator` + +The `BeanNameAutoProxyCreator` class is a `BeanPostProcessor` that automatically creates +AOP proxies for beans with names that match literal values or wildcards. The following +example shows how to create a `BeanNameAutoProxyCreator` bean: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + myInterceptor + + + +---- + +As with `ProxyFactoryBean`, there is an `interceptorNames` property rather than a list +of interceptors, to allow correct behavior for prototype advisors. Named "`interceptors`" +can be advisors or any advice type. + +As with auto-proxying in general, the main point of using `BeanNameAutoProxyCreator` is +to apply the same configuration consistently to multiple objects, with minimal volume of +configuration. It is a popular choice for applying declarative transactions to multiple +objects. + +Bean definitions whose names match, such as `jdkMyBean` and `onlyJdk` in the preceding +example, are plain old bean definitions with the target class. An AOP proxy is +automatically created by the `BeanNameAutoProxyCreator`. The same advice is applied +to all matching beans. Note that, if advisors are used (rather than the interceptor in +the preceding example), the pointcuts may apply differently to different beans. + + +[[aop-api-autoproxy-default]] +=== `DefaultAdvisorAutoProxyCreator` + +A more general and extremely powerful auto-proxy creator is +`DefaultAdvisorAutoProxyCreator`. This automagically applies eligible advisors in the +current context, without the need to include specific bean names in the auto-proxy +advisor's bean definition. It offers the same merit of consistent configuration and +avoidance of duplication as `BeanNameAutoProxyCreator`. + +Using this mechanism involves: + +* Specifying a `DefaultAdvisorAutoProxyCreator` bean definition. +* Specifying any number of advisors in the same or related contexts. Note that these + must be advisors, not interceptors or other advice. This is necessary, + because there must be a pointcut to evaluate, to check the eligibility of each advice + to candidate bean definitions. + +The `DefaultAdvisorAutoProxyCreator` automatically evaluates the pointcut contained +in each advisor, to see what (if any) advice it should apply to each business object +(such as `businessObject1` and `businessObject2` in the example). + +This means that any number of advisors can be applied automatically to each business +object. If no pointcut in any of the advisors matches any method in a business object, +the object is not proxied. As bean definitions are added for new business objects, +they are automatically proxied if necessary. + +Auto-proxying in general has the advantage of making it impossible for callers or +dependencies to obtain an un-advised object. Calling `getBean("businessObject1")` on this +`ApplicationContext` returns an AOP proxy, not the target business object. (The "`inner +bean`" idiom shown earlier also offers this benefit.) + +The following example creates a `DefaultAdvisorAutoProxyCreator` bean and the other +elements discussed in this section: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + +---- + +The `DefaultAdvisorAutoProxyCreator` is very useful if you want to apply the same advice +consistently to many business objects. Once the infrastructure definitions are in place, +you can add new business objects without including specific proxy configuration. +You can also easily drop in additional aspects (for example, tracing or +performance monitoring aspects) with minimal change to configuration. + +The `DefaultAdvisorAutoProxyCreator` offers support for filtering (by using a naming +convention so that only certain advisors are evaluated, which allows the use of multiple, +differently configured, AdvisorAutoProxyCreators in the same factory) and ordering. +Advisors can implement the `org.springframework.core.Ordered` interface to ensure +correct ordering if this is an issue. The `TransactionAttributeSourceAdvisor` used in the +preceding example has a configurable order value. The default setting is unordered. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc new file mode 100644 index 000000000000..7fa0edea71b2 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc @@ -0,0 +1,71 @@ +[[aop-concise-proxy]] += Concise Proxy Definitions + +Especially when defining transactional proxies, you may end up with many similar proxy +definitions. The use of parent and child bean definitions, along with inner bean +definitions, can result in much cleaner and more concise proxy definitions. + +First, we create a parent, template, bean definition for the proxy, as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + PROPAGATION_REQUIRED + + + +---- + +This is never instantiated itself, so it can actually be incomplete. Then, each proxy +that needs to be created is a child bean definition, which wraps the target of the +proxy as an inner bean definition, since the target is never used on its own anyway. +The following example shows such a child bean: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + +You can override properties from the parent template. In the following example, +we override the transaction propagation settings: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + PROPAGATION_REQUIRED,readOnly + PROPAGATION_REQUIRED,readOnly + PROPAGATION_REQUIRED,readOnly + PROPAGATION_REQUIRED + + + +---- + +Note that in the parent bean example, we explicitly marked the parent bean definition as +being abstract by setting the `abstract` attribute to `true`, as described +<>, so that it may not actually ever be +instantiated. Application contexts (but not simple bean factories), by default, +pre-instantiate all singletons. Therefore, it is important (at least for singleton beans) +that, if you have a (parent) bean definition that you intend to use only as a template, +and this definition specifies a class, you must make sure to set the `abstract` +attribute to `true`. Otherwise, the application context actually tries to +pre-instantiate it. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/extensibility.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/extensibility.adoc new file mode 100644 index 000000000000..b6b9eb683059 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/extensibility.adoc @@ -0,0 +1,15 @@ +[[aop-extensibility]] += Defining New Advice Types + +Spring AOP is designed to be extensible. While the interception implementation strategy +is presently used internally, it is possible to support arbitrary advice types in +addition to the interception around advice, before, throws advice, and +after returning advice. + +The `org.springframework.aop.framework.adapter` package is an SPI package that lets +support for new custom advice types be added without changing the core framework. +The only constraint on a custom `Advice` type is that it must implement the +`org.aopalliance.aop.Advice` marker interface. + +See the {api-spring-framework}/aop/framework/adapter/package-summary.html[`org.springframework.aop.framework.adapter`] +javadoc for further information. diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc new file mode 100644 index 000000000000..4de522e0c95c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc @@ -0,0 +1,323 @@ +[[aop-pfb]] += Using the `ProxyFactoryBean` to Create AOP Proxies + +If you use the Spring IoC container (an `ApplicationContext` or `BeanFactory`) for your +business objects (and you should be!), you want to use one of Spring's AOP +`FactoryBean` implementations. (Remember that a factory bean introduces a layer of indirection, letting +it create objects of a different type.) + +NOTE: The Spring AOP support also uses factory beans under the covers. + +The basic way to create an AOP proxy in Spring is to use the +`org.springframework.aop.framework.ProxyFactoryBean`. This gives complete control over +the pointcuts, any advice that applies, and their ordering. However, there are simpler +options that are preferable if you do not need such control. + + + +[[aop-pfb-1]] +== Basics + +The `ProxyFactoryBean`, like other Spring `FactoryBean` implementations, introduces a +level of indirection. If you define a `ProxyFactoryBean` named `foo`, objects that +reference `foo` do not see the `ProxyFactoryBean` instance itself but an object +created by the implementation of the `getObject()` method in the `ProxyFactoryBean` . This +method creates an AOP proxy that wraps a target object. + +One of the most important benefits of using a `ProxyFactoryBean` or another IoC-aware +class to create AOP proxies is that advice and pointcuts can also be +managed by IoC. This is a powerful feature, enabling certain approaches that are hard to +achieve with other AOP frameworks. For example, an advice may itself reference +application objects (besides the target, which should be available in any AOP +framework), benefiting from all the pluggability provided by Dependency Injection. + + + +[[aop-pfb-2]] +== JavaBean Properties + +In common with most `FactoryBean` implementations provided with Spring, the +`ProxyFactoryBean` class is itself a JavaBean. Its properties are used to: + +* Specify the target you want to proxy. +* Specify whether to use CGLIB (described later and see also <>). + +Some key properties are inherited from `org.springframework.aop.framework.ProxyConfig` +(the superclass for all AOP proxy factories in Spring). These key properties include +the following: + +* `proxyTargetClass`: `true` if the target class is to be proxied, rather than the + target class's interfaces. If this property value is set to `true`, then CGLIB proxies + are created (but see also <>). +* `optimize`: Controls whether or not aggressive optimizations are applied to proxies + created through CGLIB. You should not blithely use this setting unless you fully + understand how the relevant AOP proxy handles optimization. This is currently used + only for CGLIB proxies. It has no effect with JDK dynamic proxies. +* `frozen`: If a proxy configuration is `frozen`, changes to the configuration are + no longer allowed. This is useful both as a slight optimization and for those cases + when you do not want callers to be able to manipulate the proxy (through the `Advised` + interface) after the proxy has been created. The default value of this property is + `false`, so changes (such as adding additional advice) are allowed. +* `exposeProxy`: Determines whether or not the current proxy should be exposed in a + `ThreadLocal` so that it can be accessed by the target. If a target needs to obtain + the proxy and the `exposeProxy` property is set to `true`, the target can use the + `AopContext.currentProxy()` method. + +Other properties specific to `ProxyFactoryBean` include the following: + +* `proxyInterfaces`: An array of `String` interface names. If this is not supplied, a CGLIB + proxy for the target class is used (but see also <>). +* `interceptorNames`: A `String` array of `Advisor`, interceptor, or other advice names to + apply. Ordering is significant, on a first come-first served basis. That is to say + that the first interceptor in the list is the first to be able to intercept the + invocation. ++ +The names are bean names in the current factory, including bean names from ancestor +factories. You cannot mention bean references here, since doing so results in the +`ProxyFactoryBean` ignoring the singleton setting of the advice. ++ +You can append an interceptor name with an asterisk (`*`). Doing so results in the +application of all advisor beans with names that start with the part before the asterisk +to be applied. You can find an example of using this feature in <>. + +* singleton: Whether or not the factory should return a single object, no matter how + often the `getObject()` method is called. Several `FactoryBean` implementations offer + such a method. The default value is `true`. If you want to use stateful advice - for + example, for stateful mixins - use prototype advice along with a singleton value of + `false`. + + + +[[aop-pfb-proxy-types]] +== JDK- and CGLIB-based proxies + +This section serves as the definitive documentation on how the `ProxyFactoryBean` +chooses to create either a JDK-based proxy or a CGLIB-based proxy for a particular target +object (which is to be proxied). + +NOTE: The behavior of the `ProxyFactoryBean` with regard to creating JDK- or CGLIB-based +proxies changed between versions 1.2.x and 2.0 of Spring. The `ProxyFactoryBean` now +exhibits similar semantics with regard to auto-detecting interfaces as those of the +`TransactionProxyFactoryBean` class. + +If the class of a target object that is to be proxied (hereafter simply referred to as +the target class) does not implement any interfaces, a CGLIB-based proxy is +created. This is the easiest scenario, because JDK proxies are interface-based, and no +interfaces means JDK proxying is not even possible. You can plug in the target bean +and specify the list of interceptors by setting the `interceptorNames` property. Note that a +CGLIB-based proxy is created even if the `proxyTargetClass` property of the +`ProxyFactoryBean` has been set to `false`. (Doing so makes no sense and is best +removed from the bean definition, because it is, at best, redundant, and, at worst +confusing.) + +If the target class implements one (or more) interfaces, the type of proxy that is +created depends on the configuration of the `ProxyFactoryBean`. + +If the `proxyTargetClass` property of the `ProxyFactoryBean` has been set to `true`, +a CGLIB-based proxy is created. This makes sense and is in keeping with the +principle of least surprise. Even if the `proxyInterfaces` property of the +`ProxyFactoryBean` has been set to one or more fully qualified interface names, the fact +that the `proxyTargetClass` property is set to `true` causes CGLIB-based +proxying to be in effect. + +If the `proxyInterfaces` property of the `ProxyFactoryBean` has been set to one or more +fully qualified interface names, a JDK-based proxy is created. The created +proxy implements all of the interfaces that were specified in the `proxyInterfaces` +property. If the target class happens to implement a whole lot more interfaces than +those specified in the `proxyInterfaces` property, that is all well and good, but those +additional interfaces are not implemented by the returned proxy. + +If the `proxyInterfaces` property of the `ProxyFactoryBean` has not been set, but +the target class does implement one (or more) interfaces, the +`ProxyFactoryBean` auto-detects the fact that the target class does actually +implement at least one interface, and a JDK-based proxy is created. The interfaces +that are actually proxied are all of the interfaces that the target class +implements. In effect, this is the same as supplying a list of each and every +interface that the target class implements to the `proxyInterfaces` property. However, +it is significantly less work and less prone to typographical errors. + + + +[[aop-api-proxying-intf]] +== Proxying Interfaces + +Consider a simple example of `ProxyFactoryBean` in action. This example involves: + +* A target bean that is proxied. This is the `personTarget` bean definition in + the example. +* An `Advisor` and an `Interceptor` used to provide advice. +* An AOP proxy bean definition to specify the target object (the `personTarget` bean), + the interfaces to proxy, and the advice to apply. + +The following listing shows the example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + + + + myAdvisor + debugInterceptor + + + +---- + +Note that the `interceptorNames` property takes a list of `String`, which holds the bean names of the +interceptors or advisors in the current factory. You can use advisors, interceptors, before, after +returning, and throws advice objects. The ordering of advisors is significant. + +NOTE: You might be wondering why the list does not hold bean references. The reason for this is +that, if the singleton property of the `ProxyFactoryBean` is set to `false`, it must be able to +return independent proxy instances. If any of the advisors is itself a prototype, an +independent instance would need to be returned, so it is necessary to be able to obtain +an instance of the prototype from the factory. Holding a reference is not sufficient. + +The `person` bean definition shown earlier can be used in place of a `Person` implementation, as +follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Person person = (Person) factory.getBean("person"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val person = factory.getBean("person") as Person; +---- + +Other beans in the same IoC context can express a strongly typed dependency on it, as +with an ordinary Java object. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +The `PersonUser` class in this example exposes a property of type `Person`. As far as +it is concerned, the AOP proxy can be used transparently in place of a "`real`" person +implementation. However, its class would be a dynamic proxy class. It would be possible +to cast it to the `Advised` interface (discussed later). + +You can conceal the distinction between target and proxy by using an anonymous +inner bean. Only the `ProxyFactoryBean` definition is different. The +advice is included only for completeness. The following example shows how to use an +anonymous inner bean: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + + + myAdvisor + debugInterceptor + + + +---- + +Using an anonymous inner bean has the advantage that there is only one object of type `Person`. This is useful if we want +to prevent users of the application context from obtaining a reference to the un-advised +object or need to avoid any ambiguity with Spring IoC autowiring. There is also, +arguably, an advantage in that the `ProxyFactoryBean` definition is self-contained. +However, there are times when being able to obtain the un-advised target from the +factory might actually be an advantage (for example, in certain test scenarios). + + + +[[aop-api-proxying-class]] +== Proxying Classes + +What if you need to proxy a class, rather than one or more interfaces? + +Imagine that in our earlier example, there was no `Person` interface. We needed to advise +a class called `Person` that did not implement any business interface. In this case, you +can configure Spring to use CGLIB proxying rather than dynamic proxies. To do so, set the +`proxyTargetClass` property on the `ProxyFactoryBean` shown earlier to `true`. While it is best to +program to interfaces rather than classes, the ability to advise classes that do not +implement interfaces can be useful when working with legacy code. (In general, Spring +is not prescriptive. While it makes it easy to apply good practices, it avoids forcing a +particular approach.) + +If you want to, you can force the use of CGLIB in any case, even if you do have +interfaces. + +CGLIB proxying works by generating a subclass of the target class at runtime. Spring +configures this generated subclass to delegate method calls to the original target. The +subclass is used to implement the Decorator pattern, weaving in the advice. + +CGLIB proxying should generally be transparent to users. However, there are some issues +to consider: + +* `final` classes cannot be proxied, because they cannot be extended. +* `final` methods cannot be advised, because they cannot be overridden. +* `private` methods cannot be advised, because they cannot be overridden. + +NOTE: There is no need to add CGLIB to your classpath. CGLIB is repackaged and included +in the `spring-core` JAR. In other words, CGLIB-based AOP works "out of the box", as do +JDK dynamic proxies. + +There is little performance difference between CGLIB proxies and dynamic proxies. +Performance should not be a decisive consideration in this case. + + + +[[aop-global-advisors]] +== Using "`Global`" Advisors + +By appending an asterisk to an interceptor name, all advisors with bean names that match +the part before the asterisk are added to the advisor chain. This can come in handy +if you need to add a standard set of "`global`" advisors. The following example defines +two global advisors: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + global* + + + + + + +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc new file mode 100644 index 000000000000..334097228e2a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc @@ -0,0 +1,250 @@ +[[aop-api-pointcuts]] += Pointcut API in Spring + +This section describes how Spring handles the crucial pointcut concept. + + + +[[aop-api-concepts]] +== Concepts + +Spring's pointcut model enables pointcut reuse independent of advice types. You can +target different advice with the same pointcut. + +The `org.springframework.aop.Pointcut` interface is the central interface, used to +target advice to particular classes and methods. The complete interface follows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface Pointcut { + + ClassFilter getClassFilter(); + + MethodMatcher getMethodMatcher(); + } +---- + +Splitting the `Pointcut` interface into two parts allows reuse of class and method +matching parts and fine-grained composition operations (such as performing a "`union`" +with another method matcher). + +The `ClassFilter` interface is used to restrict the pointcut to a given set of target +classes. If the `matches()` method always returns true, all target classes are +matched. The following listing shows the `ClassFilter` interface definition: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface ClassFilter { + + boolean matches(Class clazz); + } +---- + +The `MethodMatcher` interface is normally more important. The complete interface follows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface MethodMatcher { + + boolean matches(Method m, Class targetClass); + + boolean isRuntime(); + + boolean matches(Method m, Class targetClass, Object... args); + } +---- + +The `matches(Method, Class)` method is used to test whether this pointcut ever +matches a given method on a target class. This evaluation can be performed when an AOP +proxy is created to avoid the need for a test on every method invocation. If the +two-argument `matches` method returns `true` for a given method, and the `isRuntime()` +method for the MethodMatcher returns `true`, the three-argument matches method is +invoked on every method invocation. This lets a pointcut look at the arguments passed +to the method invocation immediately before the target advice starts. + +Most `MethodMatcher` implementations are static, meaning that their `isRuntime()` method +returns `false`. In this case, the three-argument `matches` method is never invoked. + +TIP: If possible, try to make pointcuts static, allowing the AOP framework to cache the +results of pointcut evaluation when an AOP proxy is created. + + + +[[aop-api-pointcut-ops]] +== Operations on Pointcuts + +Spring supports operations (notably, union and intersection) on pointcuts. + +Union means the methods that either pointcut matches. +Intersection means the methods that both pointcuts match. +Union is usually more useful. +You can compose pointcuts by using the static methods in the +`org.springframework.aop.support.Pointcuts` class or by using the +`ComposablePointcut` class in the same package. However, using AspectJ pointcut +expressions is usually a simpler approach. + + + +[[aop-api-pointcuts-aspectj]] +== AspectJ Expression Pointcuts + +Since 2.0, the most important type of pointcut used by Spring is +`org.springframework.aop.aspectj.AspectJExpressionPointcut`. This is a pointcut that +uses an AspectJ-supplied library to parse an AspectJ pointcut expression string. + +See the <> for a discussion of supported AspectJ pointcut primitives. + + + +[[aop-api-pointcuts-impls]] +== Convenience Pointcut Implementations + +Spring provides several convenient pointcut implementations. You can use some of them +directly; others are intended to be subclassed in application-specific pointcuts. + + +[[aop-api-pointcuts-static]] +=== Static Pointcuts + +Static pointcuts are based on the method and the target class and cannot take into account +the method's arguments. Static pointcuts suffice -- and are best -- for most usages. +Spring can evaluate a static pointcut only once, when a method is first invoked. +After that, there is no need to evaluate the pointcut again with each method invocation. + +The rest of this section describes some of the static pointcut implementations that are +included with Spring. + +[[aop-api-pointcuts-regex]] +==== Regular Expression Pointcuts + +One obvious way to specify static pointcuts is regular expressions. Several AOP +frameworks besides Spring make this possible. +`org.springframework.aop.support.JdkRegexpMethodPointcut` is a generic regular +expression pointcut that uses the regular expression support in the JDK. + +With the `JdkRegexpMethodPointcut` class, you can provide a list of pattern strings. +If any of these is a match, the pointcut evaluates to `true`. (As a consequence, +the resulting pointcut is effectively the union of the specified patterns.) + +The following example shows how to use `JdkRegexpMethodPointcut`: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + .*set.* + .*absquatulate + + + +---- + +Spring provides a convenience class named `RegexpMethodPointcutAdvisor`, which lets us +also reference an `Advice` (remember that an `Advice` can be an interceptor, before advice, +throws advice, and others). Behind the scenes, Spring uses a `JdkRegexpMethodPointcut`. +Using `RegexpMethodPointcutAdvisor` simplifies wiring, as the one bean encapsulates both +pointcut and advice, as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + .*set.* + .*absquatulate + + + +---- + +You can use `RegexpMethodPointcutAdvisor` with any `Advice` type. + +[[aop-api-pointcuts-attribute-driven]] +==== Attribute-driven Pointcuts + +An important type of static pointcut is a metadata-driven pointcut. This uses the +values of metadata attributes (typically, source-level metadata). + + +[[aop-api-pointcuts-dynamic]] +=== Dynamic pointcuts + +Dynamic pointcuts are costlier to evaluate than static pointcuts. They take into account +method arguments as well as static information. This means that they must be +evaluated with every method invocation and that the result cannot be cached, as arguments will +vary. + +The main example is the `control flow` pointcut. + +[[aop-api-pointcuts-cflow]] +==== Control Flow Pointcuts + +Spring control flow pointcuts are conceptually similar to AspectJ `cflow` pointcuts, +although less powerful. (There is currently no way to specify that a pointcut runs +below a join point matched by another pointcut.) A control flow pointcut matches the +current call stack. For example, it might fire if the join point was invoked by a method +in the `com.mycompany.web` package or by the `SomeCaller` class. Control flow pointcuts +are specified by using the `org.springframework.aop.support.ControlFlowPointcut` class. + +NOTE: Control flow pointcuts are significantly more expensive to evaluate at runtime than even +other dynamic pointcuts. In Java 1.4, the cost is about five times that of other dynamic +pointcuts. + + + +[[aop-api-pointcuts-superclasses]] +== Pointcut Superclasses + +Spring provides useful pointcut superclasses to help you to implement your own pointcuts. + +Because static pointcuts are most useful, you should probably subclass +`StaticMethodMatcherPointcut`. This requires implementing only one +abstract method (although you can override other methods to customize behavior). The +following example shows how to subclass `StaticMethodMatcherPointcut`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + class TestStaticPointcut extends StaticMethodMatcherPointcut { + + public boolean matches(Method m, Class targetClass) { + // return true if custom criteria match + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class TestStaticPointcut : StaticMethodMatcherPointcut() { + + override fun matches(method: Method, targetClass: Class<*>): Boolean { + // return true if custom criteria match + } + } +---- + +There are also superclasses for dynamic pointcuts. +You can use custom pointcuts with any advice type. + + + +[[aop-api-pointcuts-custom]] +== Custom Pointcuts + +Because pointcuts in Spring AOP are Java classes rather than language features (as in +AspectJ), you can declare custom pointcuts, whether static or dynamic. Custom +pointcuts in Spring can be arbitrarily complex. However, we recommend using the AspectJ pointcut +expression language, if you can. + +NOTE: Later versions of Spring may offer support for "`semantic pointcuts`" as offered by JAC -- +for example, "`all methods that change instance variables in the target object.`" + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/prog.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/prog.adoc new file mode 100644 index 000000000000..51be4bf6995e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/prog.adoc @@ -0,0 +1,48 @@ +[[aop-prog]] += Creating AOP Proxies Programmatically with the `ProxyFactory` + +It is easy to create AOP proxies programmatically with Spring. This lets you use +Spring AOP without dependency on Spring IoC. + +The interfaces implemented by the target object are +automatically proxied. The following listing shows creation of a proxy for a target object, with one +interceptor and one advisor: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ProxyFactory factory = new ProxyFactory(myBusinessInterfaceImpl); + factory.addAdvice(myMethodInterceptor); + factory.addAdvisor(myAdvisor); + MyBusinessInterface tb = (MyBusinessInterface) factory.getProxy(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val factory = ProxyFactory(myBusinessInterfaceImpl) + factory.addAdvice(myMethodInterceptor) + factory.addAdvisor(myAdvisor) + val tb = factory.proxy as MyBusinessInterface +---- + +The first step is to construct an object of type +`org.springframework.aop.framework.ProxyFactory`. You can create this with a target +object, as in the preceding example, or specify the interfaces to be proxied in an alternate +constructor. + +You can add advice (with interceptors as a specialized kind of advice), advisors, or both +and manipulate them for the life of the `ProxyFactory`. If you add an +`IntroductionInterceptionAroundAdvisor`, you can cause the proxy to implement additional +interfaces. + +There are also convenience methods on `ProxyFactory` (inherited from `AdvisedSupport`) +that let you add other advice types, such as before and throws advice. +`AdvisedSupport` is the superclass of both `ProxyFactory` and `ProxyFactoryBean`. + +TIP: Integrating AOP proxy creation with the IoC framework is best practice in most +applications. We recommend that you externalize configuration from Java code with AOP, +as you should in general. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/targetsource.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/targetsource.adoc new file mode 100644 index 000000000000..91c1cf698ad4 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop-api/targetsource.adoc @@ -0,0 +1,220 @@ +[[aop-targetsource]] += Using `TargetSource` Implementations + +Spring offers the concept of a `TargetSource`, expressed in the +`org.springframework.aop.TargetSource` interface. This interface is responsible for +returning the "`target object`" that implements the join point. The `TargetSource` +implementation is asked for a target instance each time the AOP proxy handles a method +invocation. + +Developers who use Spring AOP do not normally need to work directly with `TargetSource` implementations, but +this provides a powerful means of supporting pooling, hot swappable, and other +sophisticated targets. For example, a pooling `TargetSource` can return a different target +instance for each invocation, by using a pool to manage instances. + +If you do not specify a `TargetSource`, a default implementation is used to wrap a +local object. The same target is returned for each invocation (as you would expect). + +The rest of this section describes the standard target sources provided with Spring and how you can use them. + +TIP: When using a custom target source, your target will usually need to be a prototype +rather than a singleton bean definition. This allows Spring to create a new target +instance when required. + + + +[[aop-ts-swap]] +== Hot-swappable Target Sources + +The `org.springframework.aop.target.HotSwappableTargetSource` exists to let the target +of an AOP proxy be switched while letting callers keep their references to it. + +Changing the target source's target takes effect immediately. The +`HotSwappableTargetSource` is thread-safe. + +You can change the target by using the `swap()` method on HotSwappableTargetSource, as the follow example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HotSwappableTargetSource swapper = (HotSwappableTargetSource) beanFactory.getBean("swapper"); + Object oldTarget = swapper.swap(newTarget); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val swapper = beanFactory.getBean("swapper") as HotSwappableTargetSource + val oldTarget = swapper.swap(newTarget) +---- + +The following example shows the required XML definitions: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + +---- + +The preceding `swap()` call changes the target of the swappable bean. Clients that hold a +reference to that bean are unaware of the change but immediately start hitting +the new target. + +Although this example does not add any advice (it is not necessary to add advice to +use a `TargetSource`), any `TargetSource` can be used in conjunction with +arbitrary advice. + + + +[[aop-ts-pool]] +== Pooling Target Sources + +Using a pooling target source provides a similar programming model to stateless session +EJBs, in which a pool of identical instances is maintained, with method invocations +going to free objects in the pool. + +A crucial difference between Spring pooling and SLSB pooling is that Spring pooling can +be applied to any POJO. As with Spring in general, this service can be applied in a +non-invasive way. + +Spring provides support for Commons Pool 2.2, which provides a +fairly efficient pooling implementation. You need the `commons-pool` Jar on your +application's classpath to use this feature. You can also subclass +`org.springframework.aop.target.AbstractPoolingTargetSource` to support any other +pooling API. + +NOTE: Commons Pool 1.5+ is also supported but is deprecated as of Spring Framework 4.2. + +The following listing shows an example configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + ... properties omitted + + + + + + + + + + + +---- + +Note that the target object (`businessObjectTarget` in the preceding example) must be a +prototype. This lets the `PoolingTargetSource` implementation create new instances +of the target to grow the pool as necessary. See the {api-spring-framework}/aop/target/AbstractPoolingTargetSource.html[javadoc of +`AbstractPoolingTargetSource`] and the concrete subclass you wish to use for information +about its properties. `maxSize` is the most basic and is always guaranteed to be present. + +In this case, `myInterceptor` is the name of an interceptor that would need to be +defined in the same IoC context. However, you need not specify interceptors to +use pooling. If you want only pooling and no other advice, do not set the +`interceptorNames` property at all. + +You can configure Spring to be able to cast any pooled object to the +`org.springframework.aop.target.PoolingConfig` interface, which exposes information +about the configuration and current size of the pool through an introduction. You +need to define an advisor similar to the following: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- + +This advisor is obtained by calling a convenience method on the +`AbstractPoolingTargetSource` class, hence the use of `MethodInvokingFactoryBean`. This +advisor's name (`poolConfigAdvisor`, here) must be in the list of interceptors names in +the `ProxyFactoryBean` that exposes the pooled object. + +The cast is defined as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + PoolingConfig conf = (PoolingConfig) beanFactory.getBean("businessObject"); + System.out.println("Max pool size is " + conf.getMaxSize()); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val conf = beanFactory.getBean("businessObject") as PoolingConfig + println("Max pool size is " + conf.maxSize) +---- + +NOTE: Pooling stateless service objects is not usually necessary. We do not believe it should +be the default choice, as most stateless objects are naturally thread safe, and instance +pooling is problematic if resources are cached. + +Simpler pooling is available by using auto-proxying. You can set the `TargetSource` implementations +used by any auto-proxy creator. + + + +[[aop-ts-prototype]] +== Prototype Target Sources + +Setting up a "`prototype`" target source is similar to setting up a pooling `TargetSource`. In this +case, a new instance of the target is created on every method invocation. Although +the cost of creating a new object is not high in a modern JVM, the cost of wiring up the +new object (satisfying its IoC dependencies) may be more expensive. Thus, you should not +use this approach without very good reason. + +To do this, you could modify the `poolTargetSource` definition shown earlier as follows +(we also changed the name, for clarity): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +The only property is the name of the target bean. Inheritance is used in the +`TargetSource` implementations to ensure consistent naming. As with the pooling target +source, the target bean must be a prototype bean definition. + + + +[[aop-ts-threadlocal]] +== `ThreadLocal` Target Sources + +`ThreadLocal` target sources are useful if you need an object to be created for each +incoming request (per thread that is). The concept of a `ThreadLocal` provides a JDK-wide +facility to transparently store a resource alongside a thread. Setting up a +`ThreadLocalTargetSource` is pretty much the same as was explained for the other types +of target source, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +NOTE: `ThreadLocal` instances come with serious issues (potentially resulting in memory leaks) when +incorrectly using them in multi-threaded and multi-classloader environments. You +should always consider wrapping a `ThreadLocal` in some other class and never directly use +the `ThreadLocal` itself (except in the wrapper class). Also, you should +always remember to correctly set and unset (where the latter simply involves a call to +`ThreadLocal.set(null)`) the resource local to the thread. Unsetting should be done in +any case, since not unsetting it might result in problematic behavior. Spring's +`ThreadLocal` support does this for you and should always be considered in favor of using +`ThreadLocal` instances without other proper handling code. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop.adoc b/framework-docs/modules/ROOT/pages/core/aop.adoc index be7e6b7d9630..1421a1bacdf9 100644 --- a/framework-docs/modules/ROOT/pages/core/aop.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop.adoc @@ -36,4295 +36,3 @@ Spring AOP, and can skip most of this chapter. -[[aop-introduction-defn]] -== AOP Concepts - -Let us begin by defining some central AOP concepts and terminology. These terms are not -Spring-specific. Unfortunately, AOP terminology is not particularly intuitive. -However, it would be even more confusing if Spring used its own terminology. - -* Aspect: A modularization of a concern that cuts across multiple classes. - Transaction management is a good example of a crosscutting concern in enterprise Java - applications. In Spring AOP, aspects are implemented by using regular classes - (the <>) or regular classes annotated with the - `@Aspect` annotation (the <>). -* Join point: A point during the execution of a program, such as the execution of a - method or the handling of an exception. In Spring AOP, a join point always - represents a method execution. -* Advice: Action taken by an aspect at a particular join point. Different types of - advice include "around", "before", and "after" advice. (Advice types are discussed - later.) Many AOP frameworks, including Spring, model an advice as an interceptor and - maintain a chain of interceptors around the join point. -* Pointcut: A predicate that matches join points. Advice is associated with a - pointcut expression and runs at any join point matched by the pointcut (for example, - the execution of a method with a certain name). The concept of join points as matched - by pointcut expressions is central to AOP, and Spring uses the AspectJ pointcut - expression language by default. -* Introduction: Declaring additional methods or fields on behalf of a type. Spring - AOP lets you introduce new interfaces (and a corresponding implementation) to any - advised object. For example, you could use an introduction to make a bean implement an - `IsModified` interface, to simplify caching. (An introduction is known as an - inter-type declaration in the AspectJ community.) -* Target object: An object being advised by one or more aspects. Also referred to as - the "advised object". Since Spring AOP is implemented by using runtime proxies, this - object is always a proxied object. -* AOP proxy: An object created by the AOP framework in order to implement the aspect - contracts (advise method executions and so on). In the Spring Framework, an AOP proxy - is a JDK dynamic proxy or a CGLIB proxy. -* Weaving: linking aspects with other application types or objects to create an - advised object. This can be done at compile time (using the AspectJ compiler, for - example), load time, or at runtime. Spring AOP, like other pure Java AOP frameworks, - performs weaving at runtime. - -Spring AOP includes the following types of advice: - -* Before advice: Advice that runs before a join point but that does not have - the ability to prevent execution flow proceeding to the join point (unless it throws - an exception). -* After returning advice: Advice to be run after a join point completes - normally (for example, if a method returns without throwing an exception). -* After throwing advice: Advice to be run if a method exits by throwing an - exception. -* After (finally) advice: Advice to be run regardless of the means by which a - join point exits (normal or exceptional return). -* Around advice: Advice that surrounds a join point such as a method invocation. - This is the most powerful kind of advice. Around advice can perform custom behavior - before and after the method invocation. It is also responsible for choosing whether to - proceed to the join point or to shortcut the advised method execution by returning its - own return value or throwing an exception. - -Around advice is the most general kind of advice. Since Spring AOP, like AspectJ, -provides a full range of advice types, we recommend that you use the least powerful -advice type that can implement the required behavior. For example, if you need only to -update a cache with the return value of a method, you are better off implementing an -after returning advice than an around advice, although an around advice can accomplish -the same thing. Using the most specific advice type provides a simpler programming model -with less potential for errors. For example, you do not need to invoke the `proceed()` -method on the `JoinPoint` used for around advice, and, hence, you cannot fail to invoke it. - -All advice parameters are statically typed so that you work with advice parameters of -the appropriate type (e.g. the type of the return value from a method execution) rather -than `Object` arrays. - -The concept of join points matched by pointcuts is the key to AOP, which distinguishes -it from older technologies offering only interception. Pointcuts enable advice to be -targeted independently of the object-oriented hierarchy. For example, you can apply an -around advice providing declarative transaction management to a set of methods that span -multiple objects (such as all business operations in the service layer). - - - - -[[aop-introduction-spring-defn]] -== Spring AOP Capabilities and Goals - -Spring AOP is implemented in pure Java. There is no need for a special compilation -process. Spring AOP does not need to control the class loader hierarchy and is thus -suitable for use in a servlet container or application server. - -Spring AOP currently supports only method execution join points (advising the execution -of methods on Spring beans). Field interception is not implemented, although support for -field interception could be added without breaking the core Spring AOP APIs. If you need -to advise field access and update join points, consider a language such as AspectJ. - -Spring AOP's approach to AOP differs from that of most other AOP frameworks. The aim is -not to provide the most complete AOP implementation (although Spring AOP is quite -capable). Rather, the aim is to provide a close integration between AOP implementation and -Spring IoC, to help solve common problems in enterprise applications. - -Thus, for example, the Spring Framework's AOP functionality is normally used in -conjunction with the Spring IoC container. Aspects are configured by using normal bean -definition syntax (although this allows powerful "auto-proxying" capabilities). This is a -crucial difference from other AOP implementations. You cannot do some things -easily or efficiently with Spring AOP, such as advise very fine-grained objects (typically, -domain objects). AspectJ is the best choice in such cases. However, our -experience is that Spring AOP provides an excellent solution to most problems in -enterprise Java applications that are amenable to AOP. - -Spring AOP never strives to compete with AspectJ to provide a comprehensive AOP -solution. We believe that both proxy-based frameworks such as Spring AOP and full-blown -frameworks such as AspectJ are valuable and that they are complementary, rather than in -competition. Spring seamlessly integrates Spring AOP and IoC with AspectJ, to enable -all uses of AOP within a consistent Spring-based application -architecture. This integration does not affect the Spring AOP API or the AOP Alliance -API. Spring AOP remains backward-compatible. See <> -for a discussion of the Spring AOP APIs. - -[NOTE] -==== -One of the central tenets of the Spring Framework is that of non-invasiveness. This -is the idea that you should not be forced to introduce framework-specific classes and -interfaces into your business or domain model. However, in some places, the Spring Framework -does give you the option to introduce Spring Framework-specific dependencies into your -codebase. The rationale in giving you such options is because, in certain scenarios, it -might be just plain easier to read or code some specific piece of functionality in such -a way. However, the Spring Framework (almost) always offers you the choice: You have the -freedom to make an informed decision as to which option best suits your particular use -case or scenario. - -One such choice that is relevant to this chapter is that of which AOP framework (and -which AOP style) to choose. You have the choice of AspectJ, Spring AOP, or both. You -also have the choice of either the @AspectJ annotation-style approach or the Spring XML -configuration-style approach. The fact that this chapter chooses to introduce the -@AspectJ-style approach first should not be taken as an indication that the Spring team -favors the @AspectJ annotation-style approach over the Spring XML configuration-style. - -See <> for a more complete discussion of the advantages and disadvantages of -each style. -==== - - - - -[[aop-introduction-proxies]] -== AOP Proxies - -Spring AOP defaults to using standard JDK dynamic proxies for AOP proxies. This -enables any interface (or set of interfaces) to be proxied. - -Spring AOP can also use CGLIB proxies. This is necessary to proxy classes rather than -interfaces. By default, CGLIB is used if a business object does not implement an -interface. As it is good practice to program to interfaces rather than classes, business -classes normally implement one or more business interfaces. It is possible to -<>, in those (hopefully rare) cases where you -need to advise a method that is not declared on an interface or where you need to -pass a proxied object to a method as a concrete type. - -It is important to grasp the fact that Spring AOP is proxy-based. See -<> for a thorough examination of exactly what this -implementation detail actually means. - - - - -[[aop-ataspectj]] -== @AspectJ support - -@AspectJ refers to a style of declaring aspects as regular Java classes annotated with -annotations. The @AspectJ style was introduced by the -https://www.eclipse.org/aspectj[AspectJ project] as part of the AspectJ 5 release. Spring -interprets the same annotations as AspectJ 5, using a library supplied by AspectJ -for pointcut parsing and matching. The AOP runtime is still pure Spring AOP, though, and -there is no dependency on the AspectJ compiler or weaver. - -NOTE: Using the AspectJ compiler and weaver enables use of the full AspectJ language and -is discussed in <>. - - - -[[aop-aspectj-support]] -=== Enabling @AspectJ Support - -To use @AspectJ aspects in a Spring configuration, you need to enable Spring support for -configuring Spring AOP based on @AspectJ aspects and auto-proxying beans based on -whether or not they are advised by those aspects. By auto-proxying, we mean that, if Spring -determines that a bean is advised by one or more aspects, it automatically generates -a proxy for that bean to intercept method invocations and ensures that advice is run -as needed. - -The @AspectJ support can be enabled with XML- or Java-style configuration. In either -case, you also need to ensure that AspectJ's `aspectjweaver.jar` library is on the -classpath of your application (version 1.9 or later). This library is available in the -`lib` directory of an AspectJ distribution or from the Maven Central repository. - - -[[aop-enable-aspectj-java]] -==== Enabling @AspectJ Support with Java Configuration - -To enable @AspectJ support with Java `@Configuration`, add the `@EnableAspectJAutoProxy` -annotation, as the following example shows: -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Configuration - @EnableAspectJAutoProxy - public class AppConfig { - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configuration - @EnableAspectJAutoProxy - class AppConfig ----- - -[[aop-enable-aspectj-xml]] -==== Enabling @AspectJ Support with XML Configuration - -To enable @AspectJ support with XML-based configuration, use the `aop:aspectj-autoproxy` -element, as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - ----- - -This assumes that you use schema support as described in -<>. -See <> for how to -import the tags in the `aop` namespace. - - - -[[aop-at-aspectj]] -=== Declaring an Aspect - -With @AspectJ support enabled, any bean defined in your application context with a -class that is an @AspectJ aspect (has the `@Aspect` annotation) is automatically -detected by Spring and used to configure Spring AOP. The next two examples show the -minimal steps required for a not-very-useful aspect. - -The first of the two examples shows a regular bean definition in the application context -that points to a bean class that is annotated with `@Aspect`: - -[source,xml,indent=0,subs="verbatim"] ----- - - - ----- - -The second of the two examples shows the `NotVeryUsefulAspect` class definition, which is -annotated with `@Aspect`: - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages",fold="none"] -.Java ----- - package com.xyz; - - import org.aspectj.lang.annotation.Aspect; - - @Aspect - public class NotVeryUsefulAspect { - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages",fold="none"] -.Kotlin ----- - package com.xyz - - import org.aspectj.lang.annotation.Aspect - - @Aspect - class NotVeryUsefulAspect ----- - -Aspects (classes annotated with `@Aspect`) can have methods and fields, the same as any -other class. They can also contain pointcut, advice, and introduction (inter-type) -declarations. - -.Autodetecting aspects through component scanning -NOTE: You can register aspect classes as regular beans in your Spring XML configuration, -via `@Bean` methods in `@Configuration` classes, or have Spring autodetect them through -classpath scanning -- the same as any other Spring-managed bean. However, note that the -`@Aspect` annotation is not sufficient for autodetection in the classpath. For that -purpose, you need to add a separate `@Component` annotation (or, alternatively, a custom -stereotype annotation that qualifies, as per the rules of Spring's component scanner). - -.Advising aspects with other aspects? -NOTE: In Spring AOP, aspects themselves cannot be the targets of advice from other -aspects. The `@Aspect` annotation on a class marks it as an aspect and, hence, excludes -it from auto-proxying. - - - -[[aop-pointcuts]] -=== Declaring a Pointcut - -Pointcuts determine join points of interest and thus enable us to control -when advice runs. Spring AOP only supports method execution join points for Spring -beans, so you can think of a pointcut as matching the execution of methods on Spring -beans. A pointcut declaration has two parts: a signature comprising a name and any -parameters and a pointcut expression that determines exactly which method -executions we are interested in. In the @AspectJ annotation-style of AOP, a pointcut -signature is provided by a regular method definition, and the pointcut expression is -indicated by using the `@Pointcut` annotation (the method serving as the pointcut signature -must have a `void` return type). - -An example may help make this distinction between a pointcut signature and a pointcut -expression clear. The following example defines a pointcut named `anyOldTransfer` that -matches the execution of any method named `transfer`: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Pointcut("execution(* transfer(..))") // the pointcut expression - private void anyOldTransfer() {} // the pointcut signature ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Pointcut("execution(* transfer(..))") // the pointcut expression - private fun anyOldTransfer() {} // the pointcut signature ----- - -The pointcut expression that forms the value of the `@Pointcut` annotation is a regular -AspectJ pointcut expression. For a full discussion of AspectJ's pointcut language, see -the https://www.eclipse.org/aspectj/doc/released/progguide/index.html[AspectJ -Programming Guide] (and, for extensions, the -https://www.eclipse.org/aspectj/doc/released/adk15notebook/index.html[AspectJ 5 -Developer's Notebook]) or one of the books on AspectJ (such as _Eclipse AspectJ_, by Colyer -et al., or _AspectJ in Action_, by Ramnivas Laddad). - - -[[aop-pointcuts-designators]] -==== Supported Pointcut Designators - -Spring AOP supports the following AspectJ pointcut designators (PCD) for use in pointcut -expressions: - -* `execution`: For matching method execution join points. This is the primary - pointcut designator to use when working with Spring AOP. -* `within`: Limits matching to join points within certain types (the execution - of a method declared within a matching type when using Spring AOP). -* `this`: Limits matching to join points (the execution of methods when using Spring - AOP) where the bean reference (Spring AOP proxy) is an instance of the given type. -* `target`: Limits matching to join points (the execution of methods when using - Spring AOP) where the target object (application object being proxied) is an instance - of the given type. -* `args`: Limits matching to join points (the execution of methods when using Spring - AOP) where the arguments are instances of the given types. -* `@target`: Limits matching to join points (the execution of methods when using - Spring AOP) where the class of the executing object has an annotation of the given type. -* `@args`: Limits matching to join points (the execution of methods when using Spring - AOP) where the runtime type of the actual arguments passed have annotations of the - given types. -* `@within`: Limits matching to join points within types that have the given - annotation (the execution of methods declared in types with the given annotation when - using Spring AOP). -* `@annotation`: Limits matching to join points where the subject of the join point - (the method being run in Spring AOP) has the given annotation. - -.Other pointcut types -**** -The full AspectJ pointcut language supports additional pointcut designators that are not -supported in Spring: `call`, `get`, `set`, `preinitialization`, -`staticinitialization`, `initialization`, `handler`, `adviceexecution`, `withincode`, `cflow`, -`cflowbelow`, `if`, `@this`, and `@withincode`. Use of these pointcut designators in pointcut -expressions interpreted by Spring AOP results in an `IllegalArgumentException` being -thrown. - -The set of pointcut designators supported by Spring AOP may be extended in future -releases to support more of the AspectJ pointcut designators. -**** - -Because Spring AOP limits matching to only method execution join points, the preceding discussion -of the pointcut designators gives a narrower definition than you can find in the -AspectJ programming guide. In addition, AspectJ itself has type-based semantics and, at -an execution join point, both `this` and `target` refer to the same object: the -object executing the method. Spring AOP is a proxy-based system and differentiates -between the proxy object itself (which is bound to `this`) and the target object behind the -proxy (which is bound to `target`). - -[NOTE] -==== -Due to the proxy-based nature of Spring's AOP framework, calls within the target object -are, by definition, not intercepted. For JDK proxies, only public interface method -calls on the proxy can be intercepted. With CGLIB, public and protected method calls on -the proxy are intercepted (and even package-visible methods, if necessary). However, -common interactions through proxies should always be designed through public signatures. - -Note that pointcut definitions are generally matched against any intercepted method. -If a pointcut is strictly meant to be public-only, even in a CGLIB proxy scenario with -potential non-public interactions through proxies, it needs to be defined accordingly. - -If your interception needs include method calls or even constructors within the target -class, consider the use of Spring-driven <> instead -of Spring's proxy-based AOP framework. This constitutes a different mode of AOP usage -with different characteristics, so be sure to make yourself familiar with weaving -before making a decision. -==== - -Spring AOP also supports an additional PCD named `bean`. This PCD lets you limit -the matching of join points to a particular named Spring bean or to a set of named -Spring beans (when using wildcards). The `bean` PCD has the following form: - -[source,indent=0,subs="verbatim"] ----- - bean(idOrNameOfBean) ----- - -The `idOrNameOfBean` token can be the name of any Spring bean. Limited wildcard -support that uses the `*` character is provided, so, if you establish some naming -conventions for your Spring beans, you can write a `bean` PCD expression -to select them. As is the case with other pointcut designators, the `bean` PCD can -be used with the `&&` (and), `||` (or), and `!` (negation) operators, too. - -[NOTE] -==== -The `bean` PCD is supported only in Spring AOP and not in -native AspectJ weaving. It is a Spring-specific extension to the standard PCDs that -AspectJ defines and is, therefore, not available for aspects declared in the `@Aspect` model. - -The `bean` PCD operates at the instance level (building on the Spring bean name -concept) rather than at the type level only (to which weaving-based AOP is limited). -Instance-based pointcut designators are a special capability of Spring's -proxy-based AOP framework and its close integration with the Spring bean factory, where -it is natural and straightforward to identify specific beans by name. -==== - - -[[aop-pointcuts-combining]] -==== Combining Pointcut Expressions - -You can combine pointcut expressions by using `&&,` `||` and `!`. You can also refer to -pointcut expressions by name. The following example shows three pointcut expressions: - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ----- - package com.xyz; - - @Aspect - public class Pointcuts { - - @Pointcut("execution(public * *(..))") - public void publicMethod() {} // <1> - - @Pointcut("within(com.xyz.trading..*)") - public void inTrading() {} // <2> - - @Pointcut("publicMethod() && inTrading()") - public void tradingOperation() {} // <3> - } ----- -<1> `publicMethod` matches if a method execution join point represents the execution -of any public method. -<2> `inTrading` matches if a method execution is in the trading module. -<3> `tradingOperation` matches if a method execution represents any public method in the -trading module. - -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.xyz - - @Aspect - class Pointcuts { - - @Pointcut("execution(public * *(..))") - fun publicMethod() {} // <1> - - @Pointcut("within(com.xyz.trading..*)") - fun inTrading() {} // <2> - - @Pointcut("publicMethod() && inTrading()") - fun tradingOperation() {} // <3> - } ----- -<1> `publicMethod` matches if a method execution join point represents the execution -of any public method. -<2> `inTrading` matches if a method execution is in the trading module. -<3> `tradingOperation` matches if a method execution represents any public method in the -trading module. - -It is a best practice to build more complex pointcut expressions out of smaller _named -pointcuts_, as shown above. When referring to pointcuts by name, normal Java visibility -rules apply (you can see `private` pointcuts in the same type, `protected` pointcuts in -the hierarchy, `public` pointcuts anywhere, and so on). Visibility does not affect -pointcut matching. - - -[[aop-common-pointcuts]] -==== Sharing Named Pointcut Definitions - -When working with enterprise applications, developers often have the need to refer to -modules of the application and particular sets of operations from within several aspects. -We recommend defining a dedicated aspect that captures commonly used _named pointcut_ -expressions for this purpose. Such an aspect typically resembles the following -`CommonPointcuts` example (though what you name the aspect is up to you): - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages",fold="none"] -.Java ----- - package com.xyz; - - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.Pointcut; - - @Aspect - public class CommonPointcuts { - - /** - * A join point is in the web layer if the method is defined - * in a type in the com.xyz.web package or any sub-package - * under that. - */ - @Pointcut("within(com.xyz.web..*)") - public void inWebLayer() {} - - /** - * A join point is in the service layer if the method is defined - * in a type in the com.xyz.service package or any sub-package - * under that. - */ - @Pointcut("within(com.xyz.service..*)") - public void inServiceLayer() {} - - /** - * A join point is in the data access layer if the method is defined - * in a type in the com.xyz.dao package or any sub-package - * under that. - */ - @Pointcut("within(com.xyz.dao..*)") - public void inDataAccessLayer() {} - - /** - * A business service is the execution of any method defined on a service - * interface. This definition assumes that interfaces are placed in the - * "service" package, and that implementation types are in sub-packages. - * - * If you group service interfaces by functional area (for example, - * in packages com.xyz.abc.service and com.xyz.def.service) then - * the pointcut expression "execution(* com.xyz..service.*.*(..))" - * could be used instead. - * - * Alternatively, you can write the expression using the 'bean' - * PCD, like so "bean(*Service)". (This assumes that you have - * named your Spring service beans in a consistent fashion.) - */ - @Pointcut("execution(* com.xyz..service.*.*(..))") - public void businessService() {} - - /** - * A data access operation is the execution of any method defined on a - * DAO interface. This definition assumes that interfaces are placed in the - * "dao" package, and that implementation types are in sub-packages. - */ - @Pointcut("execution(* com.xyz.dao.*.*(..))") - public void dataAccessOperation() {} - - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages",fold="none"] -.Kotlin ----- - package com.xyz - - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.Pointcut - - @Aspect - class CommonPointcuts { - - /** - * A join point is in the web layer if the method is defined - * in a type in the com.xyz.web package or any sub-package - * under that. - */ - @Pointcut("within(com.xyz.web..*)") - fun inWebLayer() {} - - /** - * A join point is in the service layer if the method is defined - * in a type in the com.xyz.service package or any sub-package - * under that. - */ - @Pointcut("within(com.xyz.service..*)") - fun inServiceLayer() {} - - /** - * A join point is in the data access layer if the method is defined - * in a type in the com.xyz.dao package or any sub-package - * under that. - */ - @Pointcut("within(com.xyz.dao..*)") - fun inDataAccessLayer() {} - - /** - * A business service is the execution of any method defined on a service - * interface. This definition assumes that interfaces are placed in the - * "service" package, and that implementation types are in sub-packages. - * - * If you group service interfaces by functional area (for example, - * in packages com.xyz.abc.service and com.xyz.def.service) then - * the pointcut expression "execution(* com.xyz..service.*.*(..))" - * could be used instead. - * - * Alternatively, you can write the expression using the 'bean' - * PCD, like so "bean(*Service)". (This assumes that you have - * named your Spring service beans in a consistent fashion.) - */ - @Pointcut("execution(* com.xyz..service.*.*(..))") - fun businessService() {} - - /** - * A data access operation is the execution of any method defined on a - * DAO interface. This definition assumes that interfaces are placed in the - * "dao" package, and that implementation types are in sub-packages. - */ - @Pointcut("execution(* com.xyz.dao.*.*(..))") - fun dataAccessOperation() {} - - } ----- - -You can refer to the pointcuts defined in such an aspect anywhere you need a pointcut -expression by referencing the fully-qualified name of the `@Aspect` class combined with -the `@Pointcut` method's name. For example, to make the service layer transactional, you -could write the following which references the -`com.xyz.CommonPointcuts.businessService()` _named pointcut_: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - ----- - -The `` and `` elements are discussed in <>. The -transaction elements are discussed in <>. - - -[[aop-pointcuts-examples]] -==== Examples - -Spring AOP users are likely to use the `execution` pointcut designator the most often. -The format of an execution expression follows: - -[literal,indent=0,subs="verbatim"] ----- - execution(modifiers-pattern? - ret-type-pattern - declaring-type-pattern?name-pattern(param-pattern) - throws-pattern?) ----- - -All parts except the returning type pattern (`ret-type-pattern` in the preceding snippet), -the name pattern, and the parameters pattern are optional. The returning type pattern determines -what the return type of the method must be in order for a join point to be matched. -`{asterisk}` is most frequently used as the returning type pattern. It matches any return -type. A fully-qualified type name matches only when the method returns the given -type. The name pattern matches the method name. You can use the `{asterisk}` wildcard as all or -part of a name pattern. If you specify a declaring type pattern, -include a trailing `.` to join it to the name pattern component. -The parameters pattern is slightly more complex: `()` matches a -method that takes no parameters, whereas `(..)` matches any number (zero or more) of parameters. -The `({asterisk})` pattern matches a method that takes one parameter of any type. -`(*,String)` matches a method that takes two parameters. The first can be of any type, while the -second must be a `String`. Consult the -https://www.eclipse.org/aspectj/doc/released/progguide/semantics-pointcuts.html[Language -Semantics] section of the AspectJ Programming Guide for more information. - -The following examples show some common pointcut expressions: - -* The execution of any public method: -+ -[literal,indent=0,subs="verbatim"] ----- - execution(public * *(..)) ----- - -* The execution of any method with a name that begins with `set`: -+ -[literal,indent=0,subs="verbatim"] ----- - execution(* set*(..)) ----- - -* The execution of any method defined by the `AccountService` interface: -+ -[literal,indent=0,subs="verbatim"] ----- - execution(* com.xyz.service.AccountService.*(..)) ----- - -* The execution of any method defined in the `service` package: -+ -[literal,indent=0,subs="verbatim"] ----- - execution(* com.xyz.service.*.*(..)) ----- - -* The execution of any method defined in the service package or one of its sub-packages: -+ -[literal,indent=0,subs="verbatim"] ----- - execution(* com.xyz.service..*.*(..)) ----- - -* Any join point (method execution only in Spring AOP) within the service package: -+ -[literal,indent=0,subs="verbatim"] ----- - within(com.xyz.service.*) ----- - -* Any join point (method execution only in Spring AOP) within the service package or one of its -sub-packages: -+ -[literal,indent=0,subs="verbatim"] ----- - within(com.xyz.service..*) ----- - -* Any join point (method execution only in Spring AOP) where the proxy implements the -`AccountService` interface: -+ -[literal,indent=0,subs="verbatim"] ----- - this(com.xyz.service.AccountService) ----- -+ -NOTE: `this` is more commonly used in a binding form. See the section on <> -for how to make the proxy object available in the advice body. - -* Any join point (method execution only in Spring AOP) where the target object -implements the `AccountService` interface: -+ -[literal,indent=0,subs="verbatim"] ----- - target(com.xyz.service.AccountService) ----- -+ -NOTE: `target` is more commonly used in a binding form. See the <> section -for how to make the target object available in the advice body. - -* Any join point (method execution only in Spring AOP) that takes a single parameter -and where the argument passed at runtime is `Serializable`: -+ -[literal,indent=0,subs="verbatim"] ----- - args(java.io.Serializable) ----- -+ -NOTE: `args` is more commonly used in a binding form. See the <> section -for how to make the method arguments available in the advice body. -+ -Note that the pointcut given in this example is different from `execution(* -*(java.io.Serializable))`. The args version matches if the argument passed at runtime is -`Serializable`, and the execution version matches if the method signature declares a single -parameter of type `Serializable`. - -* Any join point (method execution only in Spring AOP) where the target object has a -`@Transactional` annotation: -+ -[literal,indent=0,subs="verbatim"] ----- - @target(org.springframework.transaction.annotation.Transactional) ----- -+ -NOTE: You can also use `@target` in a binding form. See the <> section for -how to make the annotation object available in the advice body. - -* Any join point (method execution only in Spring AOP) where the declared type of the -target object has an `@Transactional` annotation: -+ -[literal,indent=0,subs="verbatim"] ----- - @within(org.springframework.transaction.annotation.Transactional) ----- -+ -NOTE: You can also use `@within` in a binding form. See the <> section for -how to make the annotation object available in the advice body. - -* Any join point (method execution only in Spring AOP) where the executing method has an -`@Transactional` annotation: -+ -[literal,indent=0,subs="verbatim"] ----- - @annotation(org.springframework.transaction.annotation.Transactional) ----- -+ -NOTE: You can also use `@annotation` in a binding form. See the <> section -for how to make the annotation object available in the advice body. - -* Any join point (method execution only in Spring AOP) which takes a single parameter, -and where the runtime type of the argument passed has the `@Classified` annotation: -+ -[literal,indent=0,subs="verbatim"] ----- - @args(com.xyz.security.Classified) ----- -+ -NOTE: You can also use `@args` in a binding form. See the <> section -how to make the annotation object(s) available in the advice body. - -* Any join point (method execution only in Spring AOP) on a Spring bean named -`tradeService`: -+ -[literal,indent=0,subs="verbatim"] ----- - bean(tradeService) ----- - -* Any join point (method execution only in Spring AOP) on Spring beans having names that -match the wildcard expression `*Service`: -+ -[literal,indent=0,subs="verbatim"] ----- - bean(*Service) ----- - - -[[writing-good-pointcuts]] -==== Writing Good Pointcuts - -During compilation, AspectJ processes pointcuts in order to optimize matching -performance. Examining code and determining if each join point matches (statically or -dynamically) a given pointcut is a costly process. (A dynamic match means the match -cannot be fully determined from static analysis and that a test is placed in the code to -determine if there is an actual match when the code is running). On first encountering a -pointcut declaration, AspectJ rewrites it into an optimal form for the matching -process. What does this mean? Basically, pointcuts are rewritten in DNF (Disjunctive -Normal Form) and the components of the pointcut are sorted such that those components -that are cheaper to evaluate are checked first. This means you do not have to worry -about understanding the performance of various pointcut designators and may supply them -in any order in a pointcut declaration. - -However, AspectJ can work only with what it is told. For optimal performance of -matching, you should think about what you are trying to achieve and narrow the search -space for matches as much as possible in the definition. The existing designators -naturally fall into one of three groups: kinded, scoping, and contextual: - -* Kinded designators select a particular kind of join point: -`execution`, `get`, `set`, `call`, and `handler`. -* Scoping designators select a group of join points of interest -(probably of many kinds): `within` and `withincode` -* Contextual designators match (and optionally bind) based on context: -`this`, `target`, and `@annotation` - -A well written pointcut should include at least the first two types (kinded and -scoping). You can include the contextual designators to match based on -join point context or bind that context for use in the advice. Supplying only a -kinded designator or only a contextual designator works but could affect weaving -performance (time and memory used), due to extra processing and analysis. Scoping -designators are very fast to match, and using them means AspectJ can very quickly -dismiss groups of join points that should not be further processed. A good -pointcut should always include one if possible. - - - -[[aop-advice]] -=== Declaring Advice - -Advice is associated with a pointcut expression and runs before, after, or around method -executions matched by the pointcut. The pointcut expression may be either an _inline -pointcut_ or a reference to a <>. - - -[[aop-advice-before]] -==== Before Advice - -You can declare before advice in an aspect by using the `@Before` annotation. - -The following example uses an inline pointcut expression. - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.Before; - - @Aspect - public class BeforeExample { - - @Before("execution(* com.xyz.dao.*.*(..))") - public void doAccessCheck() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.Before - - @Aspect - class BeforeExample { - - @Before("execution(* com.xyz.dao.*.*(..))") - fun doAccessCheck() { - // ... - } - } ----- - -If we use a <>, we can rewrite the preceding example -as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.Before; - - @Aspect - public class BeforeExample { - - @Before("com.xyz.CommonPointcuts.dataAccessOperation()") - public void doAccessCheck() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.Before - - @Aspect - class BeforeExample { - - @Before("com.xyz.CommonPointcuts.dataAccessOperation()") - fun doAccessCheck() { - // ... - } - } ----- - - -[[aop-advice-after-returning]] -==== After Returning Advice - -After returning advice runs when a matched method execution returns normally. -You can declare it by using the `@AfterReturning` annotation. - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.AfterReturning; - - @Aspect - public class AfterReturningExample { - - @AfterReturning("execution(* com.xyz.dao.*.*(..))") - public void doAccessCheck() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.AfterReturning - - @Aspect - class AfterReturningExample { - - @AfterReturning("execution(* com.xyz.dao.*.*(..))") - fun doAccessCheck() { - // ... - } - } ----- - -NOTE: You can have multiple advice declarations (and other members as well), -all inside the same aspect. We show only a single advice declaration in these -examples to focus the effect of each one. - -Sometimes, you need access in the advice body to the actual value that was returned. -You can use the form of `@AfterReturning` that binds the return value to get that -access, as the following example shows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.AfterReturning; - - @Aspect - public class AfterReturningExample { - - @AfterReturning( - pointcut="execution(* com.xyz.dao.*.*(..))", - returning="retVal") - public void doAccessCheck(Object retVal) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.AfterReturning - - @Aspect - class AfterReturningExample { - - @AfterReturning( - pointcut = "execution(* com.xyz.dao.*.*(..))", - returning = "retVal") - fun doAccessCheck(retVal: Any) { - // ... - } - } ----- - -The name used in the `returning` attribute must correspond to the name of a parameter -in the advice method. When a method execution returns, the return value is passed to -the advice method as the corresponding argument value. A `returning` clause also -restricts matching to only those method executions that return a value of the -specified type (in this case, `Object`, which matches any return value). - -Please note that it is not possible to return a totally different reference when -using after returning advice. - - -[[aop-advice-after-throwing]] -==== After Throwing Advice - -After throwing advice runs when a matched method execution exits by throwing an -exception. You can declare it by using the `@AfterThrowing` annotation, as the -following example shows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.AfterThrowing; - - @Aspect - public class AfterThrowingExample { - - @AfterThrowing("execution(* com.xyz.dao.*.*(..))") - public void doRecoveryActions() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.AfterThrowing - - @Aspect - class AfterThrowingExample { - - @AfterThrowing("execution(* com.xyz.dao.*.*(..))") - fun doRecoveryActions() { - // ... - } - } ----- - -Often, you want the advice to run only when exceptions of a given type are thrown, -and you also often need access to the thrown exception in the advice body. You can -use the `throwing` attribute to both restrict matching (if desired -- use `Throwable` -as the exception type otherwise) and bind the thrown exception to an advice parameter. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.AfterThrowing; - - @Aspect - public class AfterThrowingExample { - - @AfterThrowing( - pointcut="execution(* com.xyz.dao.*.*(..))", - throwing="ex") - public void doRecoveryActions(DataAccessException ex) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.AfterThrowing - - @Aspect - class AfterThrowingExample { - - @AfterThrowing( - pointcut = "execution(* com.xyz.dao.*.*(..))", - throwing = "ex") - fun doRecoveryActions(ex: DataAccessException) { - // ... - } - } ----- - -The name used in the `throwing` attribute must correspond to the name of a parameter in -the advice method. When a method execution exits by throwing an exception, the exception -is passed to the advice method as the corresponding argument value. A `throwing` clause -also restricts matching to only those method executions that throw an exception of the -specified type (`DataAccessException`, in this case). - -[NOTE] -==== -Note that `@AfterThrowing` does not indicate a general exception handling callback. -Specifically, an `@AfterThrowing` advice method is only supposed to receive exceptions -from the join point (user-declared target method) itself but not from an accompanying -`@After`/`@AfterReturning` method. -==== - - -[[aop-advice-after-finally]] -==== After (Finally) Advice - -After (finally) advice runs when a matched method execution exits. It is declared by -using the `@After` annotation. After advice must be prepared to handle both normal and -exception return conditions. It is typically used for releasing resources and similar -purposes. The following example shows how to use after finally advice: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.After; - - @Aspect - public class AfterFinallyExample { - - @After("execution(* com.xyz.dao.*.*(..))") - public void doReleaseLock() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.After - - @Aspect - class AfterFinallyExample { - - @After("execution(* com.xyz.dao.*.*(..))") - fun doReleaseLock() { - // ... - } - } ----- - -[NOTE] -==== -Note that `@After` advice in AspectJ is defined as "after finally advice", analogous -to a finally block in a try-catch statement. It will be invoked for any outcome, -normal return or exception thrown from the join point (user-declared target method), -in contrast to `@AfterReturning` which only applies to successful normal returns. -==== - - -[[aop-ataspectj-around-advice]] -==== Around Advice - -The last kind of advice is _around_ advice. Around advice runs "around" a matched -method's execution. It has the opportunity to do work both before and after the method -runs and to determine when, how, and even if the method actually gets to run at all. -Around advice is often used if you need to share state before and after a method -execution in a thread-safe manner – for example, starting and stopping a timer. - -[TIP] -==== -Always use the least powerful form of advice that meets your requirements. - -For example, do not use _around_ advice if _before_ advice is sufficient for your needs. -==== - -Around advice is declared by annotating a method with the `@Around` annotation. The -method should declare `Object` as its return type, and the first parameter of the method -must be of type `ProceedingJoinPoint`. Within the body of the advice method, you must -invoke `proceed()` on the `ProceedingJoinPoint` in order for the underlying method to -run. Invoking `proceed()` without arguments will result in the caller's original -arguments being supplied to the underlying method when it is invoked. For advanced use -cases, there is an overloaded variant of the `proceed()` method which accepts an array of -arguments (`Object[]`). The values in the array will be used as the arguments to the -underlying method when it is invoked. - -[NOTE] -==== -The behavior of `proceed` when called with an `Object[]` is a little different than the -behavior of `proceed` for around advice compiled by the AspectJ compiler. For around -advice written using the traditional AspectJ language, the number of arguments passed to -`proceed` must match the number of arguments passed to the around advice (not the number -of arguments taken by the underlying join point), and the value passed to proceed in a -given argument position supplants the original value at the join point for the entity the -value was bound to (do not worry if this does not make sense right now). - -The approach taken by Spring is simpler and a better match to its proxy-based, -execution-only semantics. You only need to be aware of this difference if you compile -`@AspectJ` aspects written for Spring and use `proceed` with arguments with the AspectJ -compiler and weaver. There is a way to write such aspects that is 100% compatible across -both Spring AOP and AspectJ, and this is discussed in the -<>. -==== - -The value returned by the around advice is the return value seen by the caller of the -method. For example, a simple caching aspect could return a value from a cache if it has -one or invoke `proceed()` (and return that value) if it does not. Note that `proceed` -may be invoked once, many times, or not at all within the body of the around advice. All -of these are legal. - -WARNING: If you declare the return type of your around advice method as `void`, `null` -will always be returned to the caller, effectively ignoring the result of any invocation -of `proceed()`. It is therefore recommended that an around advice method declare a return -type of `Object`. The advice method should typically return the value returned from an -invocation of `proceed()`, even if the underlying method has a `void` return type. -However, the advice may optionally return a cached value, a wrapped value, or some other -value depending on the use case. - -The following example shows how to use around advice: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.Around; - import org.aspectj.lang.ProceedingJoinPoint; - - @Aspect - public class AroundExample { - - @Around("execution(* com.xyz..service.*.*(..))") - public Object doBasicProfiling(ProceedingJoinPoint pjp) throws Throwable { - // start stopwatch - Object retVal = pjp.proceed(); - // stop stopwatch - return retVal; - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.Around - import org.aspectj.lang.ProceedingJoinPoint - - @Aspect - class AroundExample { - - @Around("execution(* com.xyz..service.*.*(..))") - fun doBasicProfiling(pjp: ProceedingJoinPoint): Any { - // start stopwatch - val retVal = pjp.proceed() - // stop stopwatch - return retVal - } - } ----- - -[[aop-ataspectj-advice-params]] -==== Advice Parameters - -Spring offers fully typed advice, meaning that you declare the parameters you need in the -advice signature (as we saw earlier for the returning and throwing examples) rather than -work with `Object[]` arrays all the time. We see how to make argument and other contextual -values available to the advice body later in this section. First, we take a look at how to -write generic advice that can find out about the method the advice is currently advising. - -[[aop-ataspectj-advice-params-the-joinpoint]] -===== Access to the Current `JoinPoint` - -Any advice method may declare, as its first parameter, a parameter of type -`org.aspectj.lang.JoinPoint`. Note that around advice is required to declare a first -parameter of type `ProceedingJoinPoint`, which is a subclass of `JoinPoint`. - -The `JoinPoint` interface provides a number of useful methods: - -* `getArgs()`: Returns the method arguments. -* `getThis()`: Returns the proxy object. -* `getTarget()`: Returns the target object. -* `getSignature()`: Returns a description of the method that is being advised. -* `toString()`: Prints a useful description of the method being advised. - -See the https://www.eclipse.org/aspectj/doc/released/runtime-api/org/aspectj/lang/JoinPoint.html[javadoc] for more detail. - -[[aop-ataspectj-advice-params-passing]] -===== Passing Parameters to Advice - -We have already seen how to bind the returned value or exception value (using after -returning and after throwing advice). To make argument values available to the advice -body, you can use the binding form of `args`. If you use a parameter name in place of a -type name in an `args` expression, the value of the corresponding argument is passed as -the parameter value when the advice is invoked. An example should make this clearer. -Suppose you want to advise the execution of DAO operations that take an `Account` -object as the first parameter, and you need access to the account in the advice body. -You could write the following: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Before("execution(* com.xyz.dao.*.*(..)) && args(account,..)") - public void validateAccount(Account account) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Before("execution(* com.xyz.dao.*.*(..)) && args(account,..)") - fun validateAccount(account: Account) { - // ... - } ----- - -The `args(account,..)` part of the pointcut expression serves two purposes. First, it -restricts matching to only those method executions where the method takes at least one -parameter, and the argument passed to that parameter is an instance of `Account`. -Second, it makes the actual `Account` object available to the advice through the `account` -parameter. - -Another way of writing this is to declare a pointcut that "provides" the `Account` -object value when it matches a join point, and then refer to the named pointcut -from the advice. This would look as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Pointcut("execution(* com.xyz.dao.*.*(..)) && args(account,..)") - private void accountDataAccessOperation(Account account) {} - - @Before("accountDataAccessOperation(account)") - public void validateAccount(Account account) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Pointcut("execution(* com.xyz.dao.*.*(..)) && args(account,..)") - private fun accountDataAccessOperation(account: Account) { - } - - @Before("accountDataAccessOperation(account)") - fun validateAccount(account: Account) { - // ... - } ----- - -See the AspectJ programming guide for more details. - -The proxy object (`this`), target object (`target`), and annotations (`@within`, -`@target`, `@annotation`, and `@args`) can all be bound in a similar fashion. The next -set of examples shows how to match the execution of methods annotated with an -`@Auditable` annotation and extract the audit code: - -The following shows the definition of the `@Auditable` annotation: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Retention(RetentionPolicy.RUNTIME) - @Target(ElementType.METHOD) - public @interface Auditable { - AuditCode value(); - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Retention(AnnotationRetention.RUNTIME) - @Target(AnnotationTarget.FUNCTION) - annotation class Auditable(val value: AuditCode) ----- - -The following shows the advice that matches the execution of `@Auditable` methods: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Before("com.xyz.Pointcuts.publicMethod() && @annotation(auditable)") // <1> - public void audit(Auditable auditable) { - AuditCode code = auditable.value(); - // ... - } ----- -<1> References the `publicMethod` named pointcut defined in <>. - -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Before("com.xyz.Pointcuts.publicMethod() && @annotation(auditable)") // <1> - fun audit(auditable: Auditable) { - val code = auditable.value() - // ... - } ----- -<1> References the `publicMethod` named pointcut defined in <>. - -[[aop-ataspectj-advice-params-generics]] -===== Advice Parameters and Generics - -Spring AOP can handle generics used in class declarations and method parameters. Suppose -you have a generic type like the following: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public interface Sample { - void sampleGenericMethod(T param); - void sampleGenericCollectionMethod(Collection param); - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - interface Sample { - fun sampleGenericMethod(param: T) - fun sampleGenericCollectionMethod(param: Collection) - } ----- - -You can restrict interception of method types to certain parameter types by -tying the advice parameter to the parameter type for which you want to intercept the method: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Before("execution(* ..Sample+.sampleGenericMethod(*)) && args(param)") - public void beforeSampleMethod(MyType param) { - // Advice implementation - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Before("execution(* ..Sample+.sampleGenericMethod(*)) && args(param)") - fun beforeSampleMethod(param: MyType) { - // Advice implementation - } ----- - -This approach does not work for generic collections. So you cannot define a -pointcut as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Before("execution(* ..Sample+.sampleGenericCollectionMethod(*)) && args(param)") - public void beforeSampleMethod(Collection param) { - // Advice implementation - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Before("execution(* ..Sample+.sampleGenericCollectionMethod(*)) && args(param)") - fun beforeSampleMethod(param: Collection) { - // Advice implementation - } ----- - -To make this work, we would have to inspect every element of the collection, which is not -reasonable, as we also cannot decide how to treat `null` values in general. To achieve -something similar to this, you have to type the parameter to `Collection` and manually -check the type of the elements. - -[[aop-ataspectj-advice-params-names]] -===== Determining Argument Names - -Parameter binding in advice invocations relies on matching the names used in pointcut -expressions to the parameter names declared in advice and pointcut method signatures. - -NOTE: This section uses the terms _argument_ and _parameter_ interchangeably, since -AspectJ APIs refer to parameter names as argument names. - -Spring AOP uses the following `ParameterNameDiscoverer` implementations to determine -parameter names. Each discoverer will be given a chance to discover parameter names, and -the first successful discoverer wins. If none of the registered discoverers is capable -of determining parameter names, an exception will be thrown. - -`AspectJAnnotationParameterNameDiscoverer` :: Uses parameter names that have been explicitly - specified by the user via the `argNames` attribute in the corresponding advice or - pointcut annotation. See <> for details. -`KotlinReflectionParameterNameDiscoverer` :: Uses Kotlin reflection APIs to determine - parameter names. This discoverer is only used if such APIs are present on the classpath. -`StandardReflectionParameterNameDiscoverer` :: Uses the standard `java.lang.reflect.Parameter` - API to determine parameter names. Requires that code be compiled with the `-parameters` - flag for `javac`. Recommended approach on Java 8+. -`LocalVariableTableParameterNameDiscoverer` :: Analyzes the local variable table available - in the byte code of the advice class to determine parameter names from debug information. - Requires that code be compiled with debug symbols (`-g:vars` at a minimum). Deprecated - as of Spring Framework 6.0 for removal in Spring Framework 6.1 in favor of compiling - code with `-parameters`. Not supported in a GraalVM native image. -`AspectJAdviceParameterNameDiscoverer` :: Deduces parameter names from the pointcut - expression, `returning`, and `throwing` clauses. See the - {api-spring-framework}/aop/aspectj/AspectJAdviceParameterNameDiscoverer.html[javadoc] - for details on the algorithm used. - -[[aop-ataspectj-advice-params-names-explicit]] -===== Explicit Argument Names - -@AspectJ advice and pointcut annotations have an optional `argNames` attribute that you -can use to specify the argument names of the annotated method. - -[TIP] -==== -If an @AspectJ aspect has been compiled by the AspectJ compiler (`ajc`) even without -debug information, you do not need to add the `argNames` attribute, since the compiler -retains the needed information. - -Similarly, if an @AspectJ aspect has been compiled with `javac` using the `-parameters` -flag, you do not need to add the `argNames` attribute, since the compiler retains the -needed information. -==== - -The following example shows how to use the `argNames` attribute: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Before( - value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> - argNames = "bean,auditable") // <2> - public void audit(Object bean, Auditable auditable) { - AuditCode code = auditable.value(); - // ... use code and bean - } ----- -<1> References the `publicMethod` named pointcut defined in <>. -<2> Declares `bean` and `auditable` as the argument names. - -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Before( - value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> - argNames = "bean,auditable") // <2> - fun audit(bean: Any, auditable: Auditable) { - val code = auditable.value() - // ... use code and bean - } ----- -<1> References the `publicMethod` named pointcut defined in <>. -<2> Declares `bean` and `auditable` as the argument names. - -If the first parameter is of type `JoinPoint`, `ProceedingJoinPoint`, or -`JoinPoint.StaticPart`, you can omit the name of the parameter from the value of the -`argNames` attribute. For example, if you modify the preceding advice to receive the join -point object, the `argNames` attribute does not need to include it: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Before( - value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> - argNames = "bean,auditable") // <2> - public void audit(JoinPoint jp, Object bean, Auditable auditable) { - AuditCode code = auditable.value(); - // ... use code, bean, and jp - } ----- -<1> References the `publicMethod` named pointcut defined in <>. -<2> Declares `bean` and `auditable` as the argument names. - -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Before( - value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> - argNames = "bean,auditable") // <2> - fun audit(jp: JoinPoint, bean: Any, auditable: Auditable) { - val code = auditable.value() - // ... use code, bean, and jp - } ----- -<1> References the `publicMethod` named pointcut defined in <>. -<2> Declares `bean` and `auditable` as the argument names. - -The special treatment given to the first parameter of type `JoinPoint`, -`ProceedingJoinPoint`, or `JoinPoint.StaticPart` is particularly convenient for advice -methods that do not collect any other join point context. In such situations, you may -omit the `argNames` attribute. For example, the following advice does not need to declare -the `argNames` attribute: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Before("com.xyz.Pointcuts.publicMethod()") // <1> - public void audit(JoinPoint jp) { - // ... use jp - } ----- -<1> References the `publicMethod` named pointcut defined in <>. - -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Before("com.xyz.Pointcuts.publicMethod()") // <1> - fun audit(jp: JoinPoint) { - // ... use jp - } ----- -<1> References the `publicMethod` named pointcut defined in <>. - - -[[aop-ataspectj-advice-proceeding-with-the-call]] -===== Proceeding with Arguments - -We remarked earlier that we would describe how to write a `proceed` call with -arguments that works consistently across Spring AOP and AspectJ. The solution is -to ensure that the advice signature binds each of the method parameters in order. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Around("execution(List find*(..)) && " + - "com.xyz.CommonPointcuts.inDataAccessLayer() && " + - "args(accountHolderNamePattern)") // <1> - public Object preProcessQueryPattern(ProceedingJoinPoint pjp, - String accountHolderNamePattern) throws Throwable { - String newPattern = preProcess(accountHolderNamePattern); - return pjp.proceed(new Object[] {newPattern}); - } ----- -<1> References the `inDataAccessLayer` named pointcut defined in <>. - -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Around("execution(List find*(..)) && " + - "com.xyz.CommonPointcuts.inDataAccessLayer() && " + - "args(accountHolderNamePattern)") // <1> - fun preProcessQueryPattern(pjp: ProceedingJoinPoint, - accountHolderNamePattern: String): Any { - val newPattern = preProcess(accountHolderNamePattern) - return pjp.proceed(arrayOf(newPattern)) - } ----- -<1> References the `inDataAccessLayer` named pointcut defined in <>. - -In many cases, you do this binding anyway (as in the preceding example). - - -[[aop-ataspectj-advice-ordering]] -==== Advice Ordering - -What happens when multiple pieces of advice all want to run at the same join point? -Spring AOP follows the same precedence rules as AspectJ to determine the order of advice -execution. The highest precedence advice runs first "on the way in" (so, given two pieces -of before advice, the one with highest precedence runs first). "On the way out" from a -join point, the highest precedence advice runs last (so, given two pieces of after -advice, the one with the highest precedence will run second). - -When two pieces of advice defined in different aspects both need to run at the same -join point, unless you specify otherwise, the order of execution is undefined. You can -control the order of execution by specifying precedence. This is done in the normal -Spring way by either implementing the `org.springframework.core.Ordered` interface in -the aspect class or annotating it with the `@Order` annotation. Given two aspects, the -aspect returning the lower value from `Ordered.getOrder()` (or the annotation value) has -the higher precedence. - -[NOTE] -==== -Each of the distinct advice types of a particular aspect is conceptually meant to apply -to the join point directly. As a consequence, an `@AfterThrowing` advice method is not -supposed to receive an exception from an accompanying `@After`/`@AfterReturning` method. - -As of Spring Framework 5.2.7, advice methods defined in the same `@Aspect` class that -need to run at the same join point are assigned precedence based on their advice type in -the following order, from highest to lowest precedence: `@Around`, `@Before`, `@After`, -`@AfterReturning`, `@AfterThrowing`. Note, however, that an `@After` advice method will -effectively be invoked after any `@AfterReturning` or `@AfterThrowing` advice methods -in the same aspect, following AspectJ's "after finally advice" semantics for `@After`. - -When two pieces of the same type of advice (for example, two `@After` advice methods) -defined in the same `@Aspect` class both need to run at the same join point, the ordering -is undefined (since there is no way to retrieve the source code declaration order through -reflection for javac-compiled classes). Consider collapsing such advice methods into one -advice method per join point in each `@Aspect` class or refactor the pieces of advice into -separate `@Aspect` classes that you can order at the aspect level via `Ordered` or `@Order`. -==== - - -[[aop-introductions]] -=== Introductions - -Introductions (known as inter-type declarations in AspectJ) enable an aspect to declare -that advised objects implement a given interface, and to provide an implementation of -that interface on behalf of those objects. - -You can make an introduction by using the `@DeclareParents` annotation. This annotation -is used to declare that matching types have a new parent (hence the name). For example, -given an interface named `UsageTracked` and an implementation of that interface named -`DefaultUsageTracked`, the following aspect declares that all implementors of service -interfaces also implement the `UsageTracked` interface (e.g. for statistics via JMX): - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Aspect - public class UsageTracking { - - @DeclareParents(value="com.xyz.service.*+", defaultImpl=DefaultUsageTracked.class) - public static UsageTracked mixin; - - @Before("execution(* com.xyz..service.*.*(..)) && this(usageTracked)") - public void recordUsage(UsageTracked usageTracked) { - usageTracked.incrementUseCount(); - } - - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Aspect - class UsageTracking { - - companion object { - @DeclareParents(value = "com.xyz.service.*+", - defaultImpl = DefaultUsageTracked::class) - lateinit var mixin: UsageTracked - } - - @Before("execution(* com.xyz..service.*.*(..)) && this(usageTracked)") - fun recordUsage(usageTracked: UsageTracked) { - usageTracked.incrementUseCount() - } - } ----- - -The interface to be implemented is determined by the type of the annotated field. The -`value` attribute of the `@DeclareParents` annotation is an AspectJ type pattern. Any -bean of a matching type implements the `UsageTracked` interface. Note that, in the -before advice of the preceding example, service beans can be directly used as -implementations of the `UsageTracked` interface. If accessing a bean programmatically, -you would write the following: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - UsageTracked usageTracked = context.getBean("myService", UsageTracked.class); ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - val usageTracked = context.getBean("myService", UsageTracked.class) ----- - - -[[aop-instantiation-models]] -=== Aspect Instantiation Models - -NOTE: This is an advanced topic. If you are just starting out with AOP, you can safely skip -it until later. - -By default, there is a single instance of each aspect within the application -context. AspectJ calls this the singleton instantiation model. It is possible to define -aspects with alternate lifecycles. Spring supports AspectJ's `perthis` and `pertarget` -instantiation models; `percflow`, `percflowbelow`, and `pertypewithin` are not currently -supported. - -You can declare a `perthis` aspect by specifying a `perthis` clause in the `@Aspect` -annotation. Consider the following example: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Aspect("perthis(execution(* com.xyz..service.*.*(..)))") - public class MyAspect { - - private int someState; - - @Before("execution(* com.xyz..service.*.*(..))") - public void recordServiceUsage() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Aspect("perthis(execution(* com.xyz..service.*.*(..)))") - class MyAspect { - - private val someState: Int = 0 - - @Before("execution(* com.xyz..service.*.*(..))") - fun recordServiceUsage() { - // ... - } - } ----- - -In the preceding example, the effect of the `perthis` clause is that one aspect instance -is created for each unique service object that performs a business service (each unique -object bound to `this` at join points matched by the pointcut expression). The aspect -instance is created the first time that a method is invoked on the service object. The -aspect goes out of scope when the service object goes out of scope. Before the aspect -instance is created, none of the advice within it runs. As soon as the aspect instance -has been created, the advice declared within it runs at matched join points, but only -when the service object is the one with which this aspect is associated. See the AspectJ -Programming Guide for more information on `per` clauses. - -The `pertarget` instantiation model works in exactly the same way as `perthis`, but it -creates one aspect instance for each unique target object at matched join points. - - - -[[aop-ataspectj-example]] -=== An AOP Example - -Now that you have seen how all the constituent parts work, we can put them together to do -something useful. - -The execution of business services can sometimes fail due to concurrency issues (for -example, a deadlock loser). If the operation is retried, it is likely to succeed -on the next try. For business services where it is appropriate to retry in such -conditions (idempotent operations that do not need to go back to the user for conflict -resolution), we want to transparently retry the operation to avoid the client seeing a -`PessimisticLockingFailureException`. This is a requirement that clearly cuts across -multiple services in the service layer and, hence, is ideal for implementing through an -aspect. - -Because we want to retry the operation, we need to use around advice so that we can -call `proceed` multiple times. The following listing shows the basic aspect implementation: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Aspect - public class ConcurrentOperationExecutor implements Ordered { - - private static final int DEFAULT_MAX_RETRIES = 2; - - private int maxRetries = DEFAULT_MAX_RETRIES; - private int order = 1; - - public void setMaxRetries(int maxRetries) { - this.maxRetries = maxRetries; - } - - public int getOrder() { - return this.order; - } - - public void setOrder(int order) { - this.order = order; - } - - @Around("com.xyz.CommonPointcuts.businessService()") // <1> - public Object doConcurrentOperation(ProceedingJoinPoint pjp) throws Throwable { - int numAttempts = 0; - PessimisticLockingFailureException lockFailureException; - do { - numAttempts++; - try { - return pjp.proceed(); - } - catch(PessimisticLockingFailureException ex) { - lockFailureException = ex; - } - } while(numAttempts <= this.maxRetries); - throw lockFailureException; - } - } ----- -<1> References the `businessService` named pointcut defined in <>. - -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Aspect - class ConcurrentOperationExecutor : Ordered { - - private val DEFAULT_MAX_RETRIES = 2 - private var maxRetries = DEFAULT_MAX_RETRIES - private var order = 1 - - fun setMaxRetries(maxRetries: Int) { - this.maxRetries = maxRetries - } - - override fun getOrder(): Int { - return this.order - } - - fun setOrder(order: Int) { - this.order = order - } - - @Around("com.xyz.CommonPointcuts.businessService()") // <1> - fun doConcurrentOperation(pjp: ProceedingJoinPoint): Any { - var numAttempts = 0 - var lockFailureException: PessimisticLockingFailureException - do { - numAttempts++ - try { - return pjp.proceed() - } catch (ex: PessimisticLockingFailureException) { - lockFailureException = ex - } - - } while (numAttempts <= this.maxRetries) - throw lockFailureException - } - } ----- -<1> References the `businessService` named pointcut defined in <>. - -Note that the aspect implements the `Ordered` interface so that we can set the precedence of -the aspect higher than the transaction advice (we want a fresh transaction each time we -retry). The `maxRetries` and `order` properties are both configured by Spring. The -main action happens in the `doConcurrentOperation` around advice. Notice that, for the -moment, we apply the retry logic to each `businessService`. We try to proceed, -and if we fail with a `PessimisticLockingFailureException`, we try again, unless -we have exhausted all of our retry attempts. - -The corresponding Spring configuration follows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - ----- - -To refine the aspect so that it retries only idempotent operations, we might define the following -`Idempotent` annotation: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Retention(RetentionPolicy.RUNTIME) - // marker annotation - public @interface Idempotent { - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Retention(AnnotationRetention.RUNTIME) - // marker annotation - annotation class Idempotent ----- - -We can then use the annotation to annotate the implementation of service operations. The change -to the aspect to retry only idempotent operations involves refining the pointcut -expression so that only `@Idempotent` operations match, as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Around("execution(* com.xyz..service.*.*(..)) && " + - "@annotation(com.xyz.service.Idempotent)") - public Object doConcurrentOperation(ProceedingJoinPoint pjp) throws Throwable { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Around("execution(* com.xyz..service.*.*(..)) && " + - "@annotation(com.xyz.service.Idempotent)") - fun doConcurrentOperation(pjp: ProceedingJoinPoint): Any { - // ... - } ----- - - - -[[aop-schema]] -== Schema-based AOP Support - -If you prefer an XML-based format, Spring also offers support for defining aspects -using the `aop` namespace tags. The exact same pointcut expressions and advice kinds -as when using the @AspectJ style are supported. Hence, in this section we focus on -that syntax and refer the reader to the discussion in the previous section -(<>) for an understanding of writing pointcut expressions and the binding -of advice parameters. - -To use the aop namespace tags described in this section, you need to import the -`spring-aop` schema, as described in <>. See <> -for how to import the tags in the `aop` namespace. - -Within your Spring configurations, all aspect and advisor elements must be placed within -an `` element (you can have more than one `` element in an -application context configuration). An `` element can contain pointcut, -advisor, and aspect elements (note that these must be declared in that order). - -WARNING: The `` style of configuration makes heavy use of Spring's -<> mechanism. This can cause issues (such as advice -not being woven) if you already use explicit auto-proxying through the use of -`BeanNameAutoProxyCreator` or something similar. The recommended usage pattern is to -use either only the `` style or only the `AutoProxyCreator` style and -never mix them. - - - -[[aop-schema-declaring-an-aspect]] -=== Declaring an Aspect - -When you use the schema support, an aspect is a regular Java object defined as a bean in -your Spring application context. The state and behavior are captured in the fields and -methods of the object, and the pointcut and advice information are captured in the XML. - -You can declare an aspect by using the `` element, and reference the backing bean -by using the `ref` attribute, as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - ... - - - - - ... - ----- - -The bean that backs the aspect (`aBean` in this case) can of course be configured and -dependency injected just like any other Spring bean. - - - -[[aop-schema-pointcuts]] -=== Declaring a Pointcut - -You can declare a _named pointcut_ inside an `` element, letting the pointcut -definition be shared across several aspects and advisors. - -A pointcut that represents the execution of any business service in the service layer can -be defined as follows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ----- - -Note that the pointcut expression itself uses the same AspectJ pointcut expression -language as described in <>. If you use the schema based declaration -style, you can also refer to _named pointcuts_ defined in `@Aspect` types within the -pointcut expression. Thus, another way of defining the above pointcut would be as follows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - <1> - - ----- -<1> References the `businessService` named pointcut defined in <>. - -Declaring a pointcut _inside_ an aspect is very similar to declaring a top-level pointcut, -as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - ... - - - ----- - -In much the same way as an @AspectJ aspect, pointcuts declared by using the schema based -definition style can collect join point context. For example, the following pointcut -collects the `this` object as the join point context and passes it to the advice: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - ... - - - ----- - -The advice must be declared to receive the collected join point context by including -parameters of the matching names, as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public void monitor(Object service) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - fun monitor(service: Any) { - // ... - } ----- - -When combining pointcut sub-expressions, `+&&+` is awkward within an XML -document, so you can use the `and`, `or`, and `not` keywords in place of `+&&+`, -`||`, and `!`, respectively. For example, the previous pointcut can be better written as -follows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - ... - - - ----- - -Note that pointcuts defined in this way are referred to by their XML `id` and cannot be -used as named pointcuts to form composite pointcuts. The named pointcut support in the -schema-based definition style is thus more limited than that offered by the @AspectJ -style. - - - -[[aop-schema-advice]] -=== Declaring Advice - -The schema-based AOP support uses the same five kinds of advice as the @AspectJ style, and they have -exactly the same semantics. - - -[[aop-schema-advice-before]] -==== Before Advice - -Before advice runs before a matched method execution. It is declared inside an -`` by using the `` element, as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ... - - ----- - -In the example above, `dataAccessOperation` is the `id` of a _named pointcut_ defined at -the top (``) level (see <>). - -NOTE: As we noted in the discussion of the @AspectJ style, using _named pointcuts_ can -significantly improve the readability of your code. See <> for -details. - -To define the pointcut inline instead, replace the `pointcut-ref` attribute with a -`pointcut` attribute, as follows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ... - - ----- - -The `method` attribute identifies a method (`doAccessCheck`) that provides the body of -the advice. This method must be defined for the bean referenced by the aspect element -that contains the advice. Before a data access operation is performed (a method execution -join point matched by the pointcut expression), the `doAccessCheck` method on the aspect -bean is invoked. - - -[[aop-schema-advice-after-returning]] -==== After Returning Advice - -After returning advice runs when a matched method execution completes normally. It is -declared inside an `` in the same way as before advice. The following example -shows how to declare it: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ... - ----- - -As in the @AspectJ style, you can get the return value within the advice body. -To do so, use the `returning` attribute to specify the name of the parameter to which -the return value should be passed, as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ... - ----- - -The `doAccessCheck` method must declare a parameter named `retVal`. The type of this -parameter constrains matching in the same way as described for `@AfterReturning`. For -example, you can declare the method signature as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public void doAccessCheck(Object retVal) {... ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - fun doAccessCheck(retVal: Any) {... ----- - - -[[aop-schema-advice-after-throwing]] -==== After Throwing Advice - -After throwing advice runs when a matched method execution exits by throwing an -exception. It is declared inside an `` by using the `after-throwing` element, -as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ... - ----- - -As in the @AspectJ style, you can get the thrown exception within the advice body. -To do so, use the `throwing` attribute to specify the name of the parameter to -which the exception should be passed as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ... - ----- - -The `doRecoveryActions` method must declare a parameter named `dataAccessEx`. -The type of this parameter constrains matching in the same way as described for -`@AfterThrowing`. For example, the method signature may be declared as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public void doRecoveryActions(DataAccessException dataAccessEx) {... ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - fun doRecoveryActions(dataAccessEx: DataAccessException) {... ----- - - -[[aop-schema-advice-after-finally]] -==== After (Finally) Advice - -After (finally) advice runs no matter how a matched method execution exits. -You can declare it by using the `after` element, as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ... - ----- - - -[[aop-schema-advice-around]] -==== Around Advice - -The last kind of advice is _around_ advice. Around advice runs "around" a matched -method's execution. It has the opportunity to do work both before and after the method -runs and to determine when, how, and even if the method actually gets to run at all. -Around advice is often used if you need to share state before and after a method -execution in a thread-safe manner – for example, starting and stopping a timer. - -[TIP] -==== -Always use the least powerful form of advice that meets your requirements. - -For example, do not use _around_ advice if _before_ advice is sufficient for your needs. -==== - -You can declare around advice by using the `aop:around` element. The advice method should -declare `Object` as its return type, and the first parameter of the method must be of -type `ProceedingJoinPoint`. Within the body of the advice method, you must invoke -`proceed()` on the `ProceedingJoinPoint` in order for the underlying method to run. -Invoking `proceed()` without arguments will result in the caller's original arguments -being supplied to the underlying method when it is invoked. For advanced use cases, there -is an overloaded variant of the `proceed()` method which accepts an array of arguments -(`Object[]`). The values in the array will be used as the arguments to the underlying -method when it is invoked. See <> for notes on calling -`proceed` with an `Object[]`. - -The following example shows how to declare around advice in XML: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ... - ----- - -The implementation of the `doBasicProfiling` advice can be exactly the same as in the -@AspectJ example (minus the annotation, of course), as the following example shows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public Object doBasicProfiling(ProceedingJoinPoint pjp) throws Throwable { - // start stopwatch - Object retVal = pjp.proceed(); - // stop stopwatch - return retVal; - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - fun doBasicProfiling(pjp: ProceedingJoinPoint): Any { - // start stopwatch - val retVal = pjp.proceed() - // stop stopwatch - return pjp.proceed() - } ----- - - -[[aop-schema-params]] -==== Advice Parameters - -The schema-based declaration style supports fully typed advice in the same way as -described for the @AspectJ support -- by matching pointcut parameters by name against -advice method parameters. See <> for details. If you wish -to explicitly specify argument names for the advice methods (not relying on the -detection strategies previously described), you can do so by using the `arg-names` -attribute of the advice element, which is treated in the same manner as the `argNames` -attribute in an advice annotation (as described in <>). -The following example shows how to specify an argument name in XML: - -[source,xml,indent=0,subs="verbatim"] ----- - - method="audit" - arg-names="auditable" /> ----- -<1> References the `publicMethod` named pointcut defined in <>. - -The `arg-names` attribute accepts a comma-delimited list of parameter names. - -The following slightly more involved example of the XSD-based approach shows -some around advice used in conjunction with a number of strongly typed parameters: - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ----- - package com.xyz.service; - - public interface PersonService { - - Person getPerson(String personName, int age); - } - - public class DefaultPersonService implements PersonService { - - public Person getPerson(String name, int age) { - return new Person(name, age); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.xyz.service - - interface PersonService { - - fun getPerson(personName: String, age: Int): Person - } - - class DefaultPersonService : PersonService { - - fun getPerson(name: String, age: Int): Person { - return Person(name, age) - } - } ----- - -Next up is the aspect. Notice the fact that the `profile(..)` method accepts a number of -strongly-typed parameters, the first of which happens to be the join point used to -proceed with the method call. The presence of this parameter is an indication that the -`profile(..)` is to be used as `around` advice, as the following example shows: - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ----- - package com.xyz; - - import org.aspectj.lang.ProceedingJoinPoint; - import org.springframework.util.StopWatch; - - public class SimpleProfiler { - - public Object profile(ProceedingJoinPoint call, String name, int age) throws Throwable { - StopWatch clock = new StopWatch("Profiling for '" + name + "' and '" + age + "'"); - try { - clock.start(call.toShortString()); - return call.proceed(); - } finally { - clock.stop(); - System.out.println(clock.prettyPrint()); - } - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.xyz - - import org.aspectj.lang.ProceedingJoinPoint - import org.springframework.util.StopWatch - - class SimpleProfiler { - - fun profile(call: ProceedingJoinPoint, name: String, age: Int): Any { - val clock = StopWatch("Profiling for '$name' and '$age'") - try { - clock.start(call.toShortString()) - return call.proceed() - } finally { - clock.stop() - println(clock.prettyPrint()) - } - } - } ----- - -Finally, the following example XML configuration effects the execution of the -preceding advice for a particular join point: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - - - - - - ----- - -Consider the following driver script: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public class Boot { - - public static void main(String[] args) { - ApplicationContext ctx = new ClassPathXmlApplicationContext("beans.xml"); - PersonService person = ctx.getBean(PersonService.class); - person.getPerson("Pengo", 12); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - fun main() { - val ctx = ClassPathXmlApplicationContext("beans.xml") - val person = ctx.getBean(PersonService.class) - person.getPerson("Pengo", 12) - } ----- - -With such a `Boot` class, we would get output similar to the following on standard output: - -[literal,subs="verbatim"] ----- -StopWatch 'Profiling for 'Pengo' and '12': running time (millis) = 0 ------------------------------------------ -ms % Task name ------------------------------------------ -00000 ? execution(getFoo) ----- - - -[[aop-ordering]] -==== Advice Ordering - -When multiple pieces of advice need to run at the same join point (executing method) -the ordering rules are as described in <>. The precedence -between aspects is determined via the `order` attribute in the `` element or -by either adding the `@Order` annotation to the bean that backs the aspect or by having -the bean implement the `Ordered` interface. - -[NOTE] -==== -In contrast to the precedence rules for advice methods defined in the same `@Aspect` -class, when two pieces of advice defined in the same `` element both need to -run at the same join point, the precedence is determined by the order in which the advice -elements are declared within the enclosing `` element, from highest to lowest -precedence. - -For example, given an `around` advice and a `before` advice defined in the same -`` element that apply to the same join point, to ensure that the `around` -advice has higher precedence than the `before` advice, the `` element must be -declared before the `` element. - -As a general rule of thumb, if you find that you have multiple pieces of advice defined -in the same `` element that apply to the same join point, consider collapsing -such advice methods into one advice method per join point in each `` element -or refactor the pieces of advice into separate `` elements that you can order -at the aspect level. -==== - - - -[[aop-schema-introductions]] -=== Introductions - -Introductions (known as inter-type declarations in AspectJ) let an aspect declare -that advised objects implement a given interface and provide an implementation of -that interface on behalf of those objects. - -You can make an introduction by using the `aop:declare-parents` element inside an `aop:aspect`. -You can use the `aop:declare-parents` element to declare that matching types have a new parent (hence the name). -For example, given an interface named `UsageTracked` and an implementation of that interface named -`DefaultUsageTracked`, the following aspect declares that all implementors of service -interfaces also implement the `UsageTracked` interface. (In order to expose statistics -through JMX for example.) - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - ----- - -The class that backs the `usageTracking` bean would then contain the following method: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public void recordUsage(UsageTracked usageTracked) { - usageTracked.incrementUseCount(); - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - fun recordUsage(usageTracked: UsageTracked) { - usageTracked.incrementUseCount() - } ----- - -The interface to be implemented is determined by the `implement-interface` attribute. The -value of the `types-matching` attribute is an AspectJ type pattern. Any bean of a -matching type implements the `UsageTracked` interface. Note that, in the before -advice of the preceding example, service beans can be directly used as implementations of -the `UsageTracked` interface. To access a bean programmatically, you could write the -following: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - UsageTracked usageTracked = context.getBean("myService", UsageTracked.class); ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - val usageTracked = context.getBean("myService", UsageTracked.class) ----- - - - -[[aop-schema-instantiation-models]] -=== Aspect Instantiation Models - -The only supported instantiation model for schema-defined aspects is the singleton -model. Other instantiation models may be supported in future releases. - - - -[[aop-schema-advisors]] -=== Advisors - -The concept of "advisors" comes from the AOP support defined in Spring -and does not have a direct equivalent in AspectJ. An advisor is like a small -self-contained aspect that has a single piece of advice. The advice itself is -represented by a bean and must implement one of the advice interfaces described in -<>. Advisors can take advantage of AspectJ pointcut expressions. - -Spring supports the advisor concept with the `` element. You most -commonly see it used in conjunction with transactional advice, which also has its own -namespace support in Spring. The following example shows an advisor: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - ----- - -As well as the `pointcut-ref` attribute used in the preceding example, you can also use the -`pointcut` attribute to define a pointcut expression inline. - -To define the precedence of an advisor so that the advice can participate in ordering, -use the `order` attribute to define the `Ordered` value of the advisor. - - - -[[aop-schema-example]] -=== An AOP Schema Example - -This section shows how the concurrent locking failure retry example from -<> looks when rewritten with the schema support. - -The execution of business services can sometimes fail due to concurrency issues (for -example, a deadlock loser). If the operation is retried, it is likely to succeed -on the next try. For business services where it is appropriate to retry in such -conditions (idempotent operations that do not need to go back to the user for conflict -resolution), we want to transparently retry the operation to avoid the client seeing a -`PessimisticLockingFailureException`. This is a requirement that clearly cuts across -multiple services in the service layer and, hence, is ideal for implementing through an -aspect. - -Because we want to retry the operation, we need to use around advice so that we can -call `proceed` multiple times. The following listing shows the basic aspect implementation -(which is a regular Java class that uses the schema support): - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public class ConcurrentOperationExecutor implements Ordered { - - private static final int DEFAULT_MAX_RETRIES = 2; - - private int maxRetries = DEFAULT_MAX_RETRIES; - private int order = 1; - - public void setMaxRetries(int maxRetries) { - this.maxRetries = maxRetries; - } - - public int getOrder() { - return this.order; - } - - public void setOrder(int order) { - this.order = order; - } - - public Object doConcurrentOperation(ProceedingJoinPoint pjp) throws Throwable { - int numAttempts = 0; - PessimisticLockingFailureException lockFailureException; - do { - numAttempts++; - try { - return pjp.proceed(); - } - catch(PessimisticLockingFailureException ex) { - lockFailureException = ex; - } - } while(numAttempts <= this.maxRetries); - throw lockFailureException; - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - class ConcurrentOperationExecutor : Ordered { - - private val DEFAULT_MAX_RETRIES = 2 - - private var maxRetries = DEFAULT_MAX_RETRIES - private var order = 1 - - fun setMaxRetries(maxRetries: Int) { - this.maxRetries = maxRetries - } - - override fun getOrder(): Int { - return this.order - } - - fun setOrder(order: Int) { - this.order = order - } - - fun doConcurrentOperation(pjp: ProceedingJoinPoint): Any { - var numAttempts = 0 - var lockFailureException: PessimisticLockingFailureException - do { - numAttempts++ - try { - return pjp.proceed() - } catch (ex: PessimisticLockingFailureException) { - lockFailureException = ex - } - - } while (numAttempts <= this.maxRetries) - throw lockFailureException - } - } ----- - -Note that the aspect implements the `Ordered` interface so that we can set the precedence of -the aspect higher than the transaction advice (we want a fresh transaction each time we -retry). The `maxRetries` and `order` properties are both configured by Spring. The -main action happens in the `doConcurrentOperation` around advice method. We try to -proceed. If we fail with a `PessimisticLockingFailureException`, we try again, -unless we have exhausted all of our retry attempts. - -NOTE: This class is identical to the one used in the @AspectJ example, but with the -annotations removed. - -The corresponding Spring configuration is as follows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - - - ----- - -Notice that, for the time being, we assume that all business services are idempotent. If -this is not the case, we can refine the aspect so that it retries only genuinely -idempotent operations, by introducing an `Idempotent` annotation and using the annotation -to annotate the implementation of service operations, as the following example shows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Retention(RetentionPolicy.RUNTIME) - // marker annotation - public @interface Idempotent { - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Retention(AnnotationRetention.RUNTIME) - // marker annotation - annotation class Idempotent ----- - -The -change to the aspect to retry only idempotent operations involves refining the -pointcut expression so that only `@Idempotent` operations match, as follows: - -[source,xml,indent=0,subs="verbatim"] ----- - ----- - - - - -[[aop-choosing]] -== Choosing which AOP Declaration Style to Use - -Once you have decided that an aspect is the best approach for implementing a given -requirement, how do you decide between using Spring AOP or AspectJ and between the -Aspect language (code) style, the @AspectJ annotation style, or the Spring XML style? These -decisions are influenced by a number of factors including application requirements, -development tools, and team familiarity with AOP. - - - -[[aop-spring-or-aspectj]] -=== Spring AOP or Full AspectJ? - -Use the simplest thing that can work. Spring AOP is simpler than using full AspectJ, as -there is no requirement to introduce the AspectJ compiler / weaver into your development -and build processes. If you only need to advise the execution of operations on Spring -beans, Spring AOP is the right choice. If you need to advise objects not managed by -the Spring container (such as domain objects, typically), you need to use -AspectJ. You also need to use AspectJ if you wish to advise join points other than -simple method executions (for example, field get or set join points and so on). - -When you use AspectJ, you have the choice of the AspectJ language syntax (also known as -the "code style") or the @AspectJ annotation style. If aspects play a large -role in your design, and you are able to use the https://www.eclipse.org/ajdt/[AspectJ -Development Tools (AJDT)] plugin for Eclipse, the AspectJ language syntax is the -preferred option. It is cleaner and simpler because the language was purposefully -designed for writing aspects. If you do not use Eclipse or have only a few aspects -that do not play a major role in your application, you may want to consider using -the @AspectJ style, sticking with regular Java compilation in your IDE, and adding -an aspect weaving phase to your build script. - - - -[[aop-ataspectj-or-xml]] -=== @AspectJ or XML for Spring AOP? - -If you have chosen to use Spring AOP, you have a choice of @AspectJ or XML style. -There are various tradeoffs to consider. - -The XML style may be most familiar to existing Spring users, and it is backed by genuine -POJOs. When using AOP as a tool to configure enterprise services, XML can be a good -choice (a good test is whether you consider the pointcut expression to be a part of your -configuration that you might want to change independently). With the XML style, it is -arguably clearer from your configuration which aspects are present in the system. - -The XML style has two disadvantages. First, it does not fully encapsulate the -implementation of the requirement it addresses in a single place. The DRY principle says -that there should be a single, unambiguous, authoritative representation of any piece of -knowledge within a system. When using the XML style, the knowledge of how a requirement -is implemented is split across the declaration of the backing bean class and the XML in -the configuration file. When you use the @AspectJ style, this information is encapsulated -in a single module: the aspect. Secondly, the XML style is slightly more limited in what -it can express than the @AspectJ style: Only the "singleton" aspect instantiation model -is supported, and it is not possible to combine named pointcuts declared in XML. -For example, in the @AspectJ style you can write something like the following: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Pointcut("execution(* get*())") - public void propertyAccess() {} - - @Pointcut("execution(com.xyz.Account+ *(..))") - public void operationReturningAnAccount() {} - - @Pointcut("propertyAccess() && operationReturningAnAccount()") - public void accountPropertyAccess() {} ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Pointcut("execution(* get*())") - fun propertyAccess() {} - - @Pointcut("execution(com.xyz.Account+ *(..))") - fun operationReturningAnAccount() {} - - @Pointcut("propertyAccess() && operationReturningAnAccount()") - fun accountPropertyAccess() {} ----- - -In the XML style you can declare the first two pointcuts: - -[source,xml,indent=0,subs="verbatim"] ----- - - - ----- - -The downside of the XML approach is that you cannot define the -`accountPropertyAccess` pointcut by combining these definitions. - -The @AspectJ style supports additional instantiation models and richer pointcut -composition. It has the advantage of keeping the aspect as a modular unit. It also has -the advantage that the @AspectJ aspects can be understood (and thus consumed) both by -Spring AOP and by AspectJ. So, if you later decide you need the capabilities of AspectJ -to implement additional requirements, you can easily migrate to a classic AspectJ setup. -In general, the Spring team prefers the @AspectJ style for custom aspects beyond simple -configuration of enterprise services. - - - - -[[aop-mixing-styles]] -== Mixing Aspect Types - -It is perfectly possible to mix @AspectJ style aspects by using the auto-proxying support, -schema-defined `` aspects, `` declared advisors, and even proxies -and interceptors in other styles in the same configuration. All of these are implemented -by using the same underlying support mechanism and can co-exist without any difficulty. - - - - -[[aop-proxying]] -== Proxying Mechanisms - -Spring AOP uses either JDK dynamic proxies or CGLIB to create the proxy for a given -target object. JDK dynamic proxies are built into the JDK, whereas CGLIB is a common -open-source class definition library (repackaged into `spring-core`). - -If the target object to be proxied implements at least one interface, a JDK dynamic -proxy is used. All of the interfaces implemented by the target type are proxied. -If the target object does not implement any interfaces, a CGLIB proxy is created. - -If you want to force the use of CGLIB proxying (for example, to proxy every method -defined for the target object, not only those implemented by its interfaces), -you can do so. However, you should consider the following issues: - -* With CGLIB, `final` methods cannot be advised, as they cannot be overridden in - runtime-generated subclasses. -* As of Spring 4.0, the constructor of your proxied object is NOT called twice anymore, - since the CGLIB proxy instance is created through Objenesis. Only if your JVM does - not allow for constructor bypassing, you might see double invocations and - corresponding debug log entries from Spring's AOP support. - -To force the use of CGLIB proxies, set the value of the `proxy-target-class` attribute -of the `` element to true, as follows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - ----- - -To force CGLIB proxying when you use the @AspectJ auto-proxy support, set the -`proxy-target-class` attribute of the `` element to `true`, -as follows: - -[source,xml,indent=0,subs="verbatim"] ----- - ----- - -[NOTE] -==== -Multiple `` sections are collapsed into a single unified auto-proxy creator -at runtime, which applies the _strongest_ proxy settings that any of the -`` sections (typically from different XML bean definition files) specified. -This also applies to the `` and `` -elements. - -To be clear, using `proxy-target-class="true"` on ``, -``, or `` elements forces the use of CGLIB -proxies _for all three of them_. -==== - - - -[[aop-understanding-aop-proxies]] -=== Understanding AOP Proxies - -Spring AOP is proxy-based. It is vitally important that you grasp the semantics of -what that last statement actually means before you write your own aspects or use any of -the Spring AOP-based aspects supplied with the Spring Framework. - -Consider first the scenario where you have a plain-vanilla, un-proxied, -nothing-special-about-it, straight object reference, as the following -code snippet shows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public class SimplePojo implements Pojo { - - public void foo() { - // this next method invocation is a direct call on the 'this' reference - this.bar(); - } - - public void bar() { - // some logic... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - class SimplePojo : Pojo { - - fun foo() { - // this next method invocation is a direct call on the 'this' reference - this.bar() - } - - fun bar() { - // some logic... - } - } ----- - -If you invoke a method on an object reference, the method is invoked directly on -that object reference, as the following image and listing show: - -image::aop-proxy-plain-pojo-call.png[] - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public class Main { - - public static void main(String[] args) { - Pojo pojo = new SimplePojo(); - // this is a direct method call on the 'pojo' reference - pojo.foo(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - fun main() { - val pojo = SimplePojo() - // this is a direct method call on the 'pojo' reference - pojo.foo() - } ----- - -Things change slightly when the reference that client code has is a proxy. Consider the -following diagram and code snippet: - -image::aop-proxy-call.png[] - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public class Main { - - public static void main(String[] args) { - ProxyFactory factory = new ProxyFactory(new SimplePojo()); - factory.addInterface(Pojo.class); - factory.addAdvice(new RetryAdvice()); - - Pojo pojo = (Pojo) factory.getProxy(); - // this is a method call on the proxy! - pojo.foo(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- -fun main() { - val factory = ProxyFactory(SimplePojo()) - factory.addInterface(Pojo::class.java) - factory.addAdvice(RetryAdvice()) - - val pojo = factory.proxy as Pojo - // this is a method call on the proxy! - pojo.foo() -} ----- - -The key thing to understand here is that the client code inside the `main(..)` method -of the `Main` class has a reference to the proxy. This means that method calls on that -object reference are calls on the proxy. As a result, the proxy can delegate to all of -the interceptors (advice) that are relevant to that particular method call. However, -once the call has finally reached the target object (the `SimplePojo` reference in -this case), any method calls that it may make on itself, such as `this.bar()` or -`this.foo()`, are going to be invoked against the `this` reference, and not the proxy. -This has important implications. It means that self-invocation is not going to result -in the advice associated with a method invocation getting a chance to run. - -Okay, so what is to be done about this? The best approach (the term "best" is used -loosely here) is to refactor your code such that the self-invocation does not happen. -This does entail some work on your part, but it is the best, least-invasive approach. -The next approach is absolutely horrendous, and we hesitate to point it out, precisely -because it is so horrendous. You can (painful as it is to us) totally tie the logic -within your class to Spring AOP, as the following example shows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public class SimplePojo implements Pojo { - - public void foo() { - // this works, but... gah! - ((Pojo) AopContext.currentProxy()).bar(); - } - - public void bar() { - // some logic... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - class SimplePojo : Pojo { - - fun foo() { - // this works, but... gah! - (AopContext.currentProxy() as Pojo).bar() - } - - fun bar() { - // some logic... - } - } ----- - -This totally couples your code to Spring AOP, and it makes the class itself aware of -the fact that it is being used in an AOP context, which flies in the face of AOP. It -also requires some additional configuration when the proxy is being created, as the -following example shows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - public class Main { - - public static void main(String[] args) { - ProxyFactory factory = new ProxyFactory(new SimplePojo()); - factory.addInterface(Pojo.class); - factory.addAdvice(new RetryAdvice()); - factory.setExposeProxy(true); - - Pojo pojo = (Pojo) factory.getProxy(); - // this is a method call on the proxy! - pojo.foo(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - fun main() { - val factory = ProxyFactory(SimplePojo()) - factory.addInterface(Pojo::class.java) - factory.addAdvice(RetryAdvice()) - factory.isExposeProxy = true - - val pojo = factory.proxy as Pojo - // this is a method call on the proxy! - pojo.foo() - } ----- - -Finally, it must be noted that AspectJ does not have this self-invocation issue because -it is not a proxy-based AOP framework. - - - - -[[aop-aspectj-programmatic]] -== Programmatic Creation of @AspectJ Proxies - -In addition to declaring aspects in your configuration by using either `` -or ``, it is also possible to programmatically create proxies -that advise target objects. For the full details of Spring's AOP API, see the -<>. Here, we want to focus on the ability to automatically -create proxies by using @AspectJ aspects. - -You can use the `org.springframework.aop.aspectj.annotation.AspectJProxyFactory` class -to create a proxy for a target object that is advised by one or more @AspectJ aspects. -The basic usage for this class is very simple, as the following example shows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - // create a factory that can generate a proxy for the given target object - AspectJProxyFactory factory = new AspectJProxyFactory(targetObject); - - // add an aspect, the class must be an @AspectJ aspect - // you can call this as many times as you need with different aspects - factory.addAspect(SecurityManager.class); - - // you can also add existing aspect instances, the type of the object supplied - // must be an @AspectJ aspect - factory.addAspect(usageTracker); - - // now get the proxy object... - MyInterfaceType proxy = factory.getProxy(); ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - // create a factory that can generate a proxy for the given target object - val factory = AspectJProxyFactory(targetObject) - - // add an aspect, the class must be an @AspectJ aspect - // you can call this as many times as you need with different aspects - factory.addAspect(SecurityManager::class.java) - - // you can also add existing aspect instances, the type of the object supplied - // must be an @AspectJ aspect - factory.addAspect(usageTracker) - - // now get the proxy object... - val proxy = factory.getProxy() ----- - -See the {api-spring-framework}/aop/aspectj/annotation/AspectJProxyFactory.html[javadoc] for more information. - - - - -[[aop-using-aspectj]] -== Using AspectJ with Spring Applications - -Everything we have covered so far in this chapter is pure Spring AOP. In this section, -we look at how you can use the AspectJ compiler or weaver instead of or in -addition to Spring AOP if your needs go beyond the facilities offered by Spring AOP -alone. - -Spring ships with a small AspectJ aspect library, which is available stand-alone in your -distribution as `spring-aspects.jar`. You need to add this to your classpath in order -to use the aspects in it. <> and <> discuss the -content of this library and how you can use it. <> discusses how to -dependency inject AspectJ aspects that are woven using the AspectJ compiler. Finally, -<> provides an introduction to load-time weaving for Spring applications -that use AspectJ. - - - -[[aop-atconfigurable]] -=== Using AspectJ to Dependency Inject Domain Objects with Spring - -The Spring container instantiates and configures beans defined in your application -context. It is also possible to ask a bean factory to configure a pre-existing -object, given the name of a bean definition that contains the configuration to be applied. -`spring-aspects.jar` contains an annotation-driven aspect that exploits this -capability to allow dependency injection of any object. The support is intended to -be used for objects created outside of the control of any container. Domain objects -often fall into this category because they are often created programmatically with the -`new` operator or by an ORM tool as a result of a database query. - -The `@Configurable` annotation marks a class as being eligible for Spring-driven -configuration. In the simplest case, you can use purely it as a marker annotation, as the -following example shows: - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ----- - package com.xyz.domain; - - import org.springframework.beans.factory.annotation.Configurable; - - @Configurable - public class Account { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.xyz.domain - - import org.springframework.beans.factory.annotation.Configurable - - @Configurable - class Account { - // ... - } ----- - -When used as a marker interface in this way, Spring configures new instances of the -annotated type (`Account`, in this case) by using a bean definition (typically -prototype-scoped) with the same name as the fully-qualified type name -(`com.xyz.domain.Account`). Since the default name for a bean is the -fully-qualified name of its type, a convenient way to declare the prototype definition -is to omit the `id` attribute, as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - ----- - -If you want to explicitly specify the name of the prototype bean definition to use, you -can do so directly in the annotation, as the following example shows: - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ----- - package com.xyz.domain; - - import org.springframework.beans.factory.annotation.Configurable; - - @Configurable("account") - public class Account { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.xyz.domain - - import org.springframework.beans.factory.annotation.Configurable - - @Configurable("account") - class Account { - // ... - } ----- - -Spring now looks for a bean definition named `account` and uses that as the -definition to configure new `Account` instances. - -You can also use autowiring to avoid having to specify a dedicated bean definition at -all. To have Spring apply autowiring, use the `autowire` property of the `@Configurable` -annotation. You can specify either `@Configurable(autowire=Autowire.BY_TYPE)` or -`@Configurable(autowire=Autowire.BY_NAME)` for autowiring by type or by name, -respectively. As an alternative, it is preferable to specify explicit, annotation-driven -dependency injection for your `@Configurable` beans through `@Autowired` or `@Inject` -at the field or method level (see <> for further details). - -Finally, you can enable Spring dependency checking for the object references in the newly -created and configured object by using the `dependencyCheck` attribute (for example, -`@Configurable(autowire=Autowire.BY_NAME,dependencyCheck=true)`). If this attribute is -set to `true`, Spring validates after configuration that all properties (which -are not primitives or collections) have been set. - -Note that using the annotation on its own does nothing. It is the -`AnnotationBeanConfigurerAspect` in `spring-aspects.jar` that acts on the presence of -the annotation. In essence, the aspect says, "after returning from the initialization of -a new object of a type annotated with `@Configurable`, configure the newly created object -using Spring in accordance with the properties of the annotation". In this context, -"initialization" refers to newly instantiated objects (for example, objects instantiated -with the `new` operator) as well as to `Serializable` objects that are undergoing -deserialization (for example, through -https://docs.oracle.com/javase/8/docs/api/java/io/Serializable.html[readResolve()]). - -[NOTE] -===== -One of the key phrases in the above paragraph is "in essence". For most cases, the -exact semantics of "after returning from the initialization of a new object" are -fine. In this context, "after initialization" means that the dependencies are -injected after the object has been constructed. This means that the dependencies -are not available for use in the constructor bodies of the class. If you want the -dependencies to be injected before the constructor bodies run and thus be -available for use in the body of the constructors, you need to define this on the -`@Configurable` declaration, as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Configurable(preConstruction = true) ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configurable(preConstruction = true) ----- - -You can find more information about the language semantics of the various pointcut -types in AspectJ -https://www.eclipse.org/aspectj/doc/next/progguide/semantics-joinPoints.html[in this -appendix] of the https://www.eclipse.org/aspectj/doc/next/progguide/index.html[AspectJ -Programming Guide]. -===== - -For this to work, the annotated types must be woven with the AspectJ weaver. You can -either use a build-time Ant or Maven task to do this (see, for example, the -https://www.eclipse.org/aspectj/doc/released/devguide/antTasks.html[AspectJ Development -Environment Guide]) or load-time weaving (see <>). The -`AnnotationBeanConfigurerAspect` itself needs to be configured by Spring (in order to obtain -a reference to the bean factory that is to be used to configure new objects). If you -use Java-based configuration, you can add `@EnableSpringConfigured` to any -`@Configuration` class, as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Configuration - @EnableSpringConfigured - public class AppConfig { - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configuration - @EnableSpringConfigured - class AppConfig { - } ----- - -If you prefer XML based configuration, the Spring -<> -defines a convenient `context:spring-configured` element, which you can use as follows: - -[source,xml,indent=0,subs="verbatim"] ----- - ----- - -Instances of `@Configurable` objects created before the aspect has been configured -result in a message being issued to the debug log and no configuration of the -object taking place. An example might be a bean in the Spring configuration that creates -domain objects when it is initialized by Spring. In this case, you can use the -`depends-on` bean attribute to manually specify that the bean depends on the -configuration aspect. The following example shows how to use the `depends-on` attribute: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ----- - -NOTE: Do not activate `@Configurable` processing through the bean configurer aspect unless you -really mean to rely on its semantics at runtime. In particular, make sure that you do -not use `@Configurable` on bean classes that are registered as regular Spring beans -with the container. Doing so results in double initialization, once through the -container and once through the aspect. - - -[[aop-configurable-testing]] -==== Unit Testing `@Configurable` Objects - -One of the goals of the `@Configurable` support is to enable independent unit testing -of domain objects without the difficulties associated with hard-coded lookups. -If `@Configurable` types have not been woven by AspectJ, the annotation has no affect -during unit testing. You can set mock or stub property references in the object under -test and proceed as normal. If `@Configurable` types have been woven by AspectJ, -you can still unit test outside of the container as normal, but you see a warning -message each time that you construct a `@Configurable` object indicating that it has -not been configured by Spring. - - -[[aop-configurable-container]] -==== Working with Multiple Application Contexts - -The `AnnotationBeanConfigurerAspect` that is used to implement the `@Configurable` support -is an AspectJ singleton aspect. The scope of a singleton aspect is the same as the scope -of `static` members: There is one aspect instance per `ClassLoader` that defines the type. -This means that, if you define multiple application contexts within the same `ClassLoader` -hierarchy, you need to consider where to define the `@EnableSpringConfigured` bean and -where to place `spring-aspects.jar` on the classpath. - -Consider a typical Spring web application configuration that has a shared parent application -context that defines common business services, everything needed to support those services, -and one child application context for each servlet (which contains definitions particular -to that servlet). All of these contexts co-exist within the same `ClassLoader` hierarchy, -and so the `AnnotationBeanConfigurerAspect` can hold a reference to only one of them. -In this case, we recommend defining the `@EnableSpringConfigured` bean in the shared -(parent) application context. This defines the services that you are likely to want to -inject into domain objects. A consequence is that you cannot configure domain objects -with references to beans defined in the child (servlet-specific) contexts by using the -@Configurable mechanism (which is probably not something you want to do anyway). - -When deploying multiple web applications within the same container, ensure that each -web application loads the types in `spring-aspects.jar` by using its own `ClassLoader` -(for example, by placing `spring-aspects.jar` in `WEB-INF/lib`). If `spring-aspects.jar` -is added only to the container-wide classpath (and hence loaded by the shared parent -`ClassLoader`), all web applications share the same aspect instance (which is probably -not what you want). - - - -[[aop-ajlib-other]] -=== Other Spring aspects for AspectJ - -In addition to the `@Configurable` aspect, `spring-aspects.jar` contains an AspectJ -aspect that you can use to drive Spring's transaction management for types and methods -annotated with the `@Transactional` annotation. This is primarily intended for users who -want to use the Spring Framework's transaction support outside of the Spring container. - -The aspect that interprets `@Transactional` annotations is the -`AnnotationTransactionAspect`. When you use this aspect, you must annotate the -implementation class (or methods within that class or both), not the interface (if -any) that the class implements. AspectJ follows Java's rule that annotations on -interfaces are not inherited. - -A `@Transactional` annotation on a class specifies the default transaction semantics for -the execution of any public operation in the class. - -A `@Transactional` annotation on a method within the class overrides the default -transaction semantics given by the class annotation (if present). Methods of any -visibility may be annotated, including private methods. Annotating non-public methods -directly is the only way to get transaction demarcation for the execution of such methods. - -TIP: Since Spring Framework 4.2, `spring-aspects` provides a similar aspect that offers the -exact same features for the standard `jakarta.transaction.Transactional` annotation. Check -`JtaAnnotationTransactionAspect` for more details. - -For AspectJ programmers who want to use the Spring configuration and transaction -management support but do not want to (or cannot) use annotations, `spring-aspects.jar` -also contains `abstract` aspects you can extend to provide your own pointcut -definitions. See the sources for the `AbstractBeanConfigurerAspect` and -`AbstractTransactionAspect` aspects for more information. As an example, the following -excerpt shows how you could write an aspect to configure all instances of objects -defined in the domain model by using prototype bean definitions that match the -fully qualified class names: - -[source,java,indent=0,subs="verbatim"] ----- - public aspect DomainObjectConfiguration extends AbstractBeanConfigurerAspect { - - public DomainObjectConfiguration() { - setBeanWiringInfoResolver(new ClassNameBeanWiringInfoResolver()); - } - - // the creation of a new bean (any object in the domain model) - protected pointcut beanCreation(Object beanInstance) : - initialization(new(..)) && - CommonPointcuts.inDomainModel() && - this(beanInstance); - } ----- - - - -[[aop-aj-configure]] -=== Configuring AspectJ Aspects by Using Spring IoC - -When you use AspectJ aspects with Spring applications, it is natural to both want and -expect to be able to configure such aspects with Spring. The AspectJ runtime itself is -responsible for aspect creation, and the means of configuring the AspectJ-created -aspects through Spring depends on the AspectJ instantiation model (the `per-xxx` clause) -used by the aspect. - -The majority of AspectJ aspects are singleton aspects. Configuration of these -aspects is easy. You can create a bean definition that references the aspect type as -normal and include the `factory-method="aspectOf"` bean attribute. This ensures that -Spring obtains the aspect instance by asking AspectJ for it rather than trying to create -an instance itself. The following example shows how to use the `factory-method="aspectOf"` attribute: - -[source,xml,indent=0,subs="verbatim"] ----- - <1> - - - ----- -<1> Note the `factory-method="aspectOf"` attribute - - -Non-singleton aspects are harder to configure. However, it is possible to do so by -creating prototype bean definitions and using the `@Configurable` support from -`spring-aspects.jar` to configure the aspect instances once they have bean created by -the AspectJ runtime. - -If you have some @AspectJ aspects that you want to weave with AspectJ (for example, -using load-time weaving for domain model types) and other @AspectJ aspects that you want -to use with Spring AOP, and these aspects are all configured in Spring, you -need to tell the Spring AOP @AspectJ auto-proxying support which exact subset of the -@AspectJ aspects defined in the configuration should be used for auto-proxying. You can -do this by using one or more `` elements inside the `` -declaration. Each `` element specifies a name pattern, and only beans with -names matched by at least one of the patterns are used for Spring AOP auto-proxy -configuration. The following example shows how to use `` elements: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - ----- - -NOTE: Do not be misled by the name of the `` element. Using it -results in the creation of Spring AOP proxies. The @AspectJ style of aspect -declaration is being used here, but the AspectJ runtime is not involved. - - - -[[aop-aj-ltw]] -=== Load-time Weaving with AspectJ in the Spring Framework - -Load-time weaving (LTW) refers to the process of weaving AspectJ aspects into an -application's class files as they are being loaded into the Java virtual machine (JVM). -The focus of this section is on configuring and using LTW in the specific context of the -Spring Framework. This section is not a general introduction to LTW. For full details on -the specifics of LTW and configuring LTW with only AspectJ (with Spring not being -involved at all), see the -https://www.eclipse.org/aspectj/doc/released/devguide/ltw.html[LTW section of the AspectJ -Development Environment Guide]. - -The value that the Spring Framework brings to AspectJ LTW is in enabling much -finer-grained control over the weaving process. 'Vanilla' AspectJ LTW is effected by using -a Java (5+) agent, which is switched on by specifying a VM argument when starting up a -JVM. It is, thus, a JVM-wide setting, which may be fine in some situations but is often a -little too coarse. Spring-enabled LTW lets you switch on LTW on a -per-`ClassLoader` basis, which is more fine-grained and which can make more -sense in a 'single-JVM-multiple-application' environment (such as is found in a typical -application server environment). - -Further, <>, this support enables -load-time weaving without making any modifications to the application server's launch -script that is needed to add `-javaagent:path/to/aspectjweaver.jar` or (as we describe -later in this section) `-javaagent:path/to/spring-instrument.jar`. Developers configure -the application context to enable load-time weaving instead of relying on administrators -who typically are in charge of the deployment configuration, such as the launch script. - -Now that the sales pitch is over, let us first walk through a quick example of AspectJ -LTW that uses Spring, followed by detailed specifics about elements introduced in the -example. For a complete example, see the -https://github.com/spring-projects/spring-petclinic[Petclinic sample application]. - - -[[aop-aj-ltw-first-example]] -==== A First Example - -Assume that you are an application developer who has been tasked with diagnosing -the cause of some performance problems in a system. Rather than break out a -profiling tool, we are going to switch on a simple profiling aspect that lets us -quickly get some performance metrics. We can then apply a finer-grained profiling -tool to that specific area immediately afterwards. - -NOTE: The example presented here uses XML configuration. You can also configure and -use @AspectJ with <>. Specifically, you can use the -`@EnableLoadTimeWeaving` annotation as an alternative to `` -(see <> for details). - -The following example shows the profiling aspect, which is not fancy. -It is a time-based profiler that uses the @AspectJ-style of aspect declaration: - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ----- - package com.xyz; - - import org.aspectj.lang.ProceedingJoinPoint; - import org.aspectj.lang.annotation.Aspect; - import org.aspectj.lang.annotation.Around; - import org.aspectj.lang.annotation.Pointcut; - import org.springframework.util.StopWatch; - import org.springframework.core.annotation.Order; - - @Aspect - public class ProfilingAspect { - - @Around("methodsToBeProfiled()") - public Object profile(ProceedingJoinPoint pjp) throws Throwable { - StopWatch sw = new StopWatch(getClass().getSimpleName()); - try { - sw.start(pjp.getSignature().getName()); - return pjp.proceed(); - } finally { - sw.stop(); - System.out.println(sw.prettyPrint()); - } - } - - @Pointcut("execution(public * com.xyz..*.*(..))") - public void methodsToBeProfiled(){} - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.xyz - - import org.aspectj.lang.ProceedingJoinPoint - import org.aspectj.lang.annotation.Aspect - import org.aspectj.lang.annotation.Around - import org.aspectj.lang.annotation.Pointcut - import org.springframework.util.StopWatch - import org.springframework.core.annotation.Order - - @Aspect - class ProfilingAspect { - - @Around("methodsToBeProfiled()") - fun profile(pjp: ProceedingJoinPoint): Any { - val sw = StopWatch(javaClass.simpleName) - try { - sw.start(pjp.getSignature().getName()) - return pjp.proceed() - } finally { - sw.stop() - println(sw.prettyPrint()) - } - } - - @Pointcut("execution(public * com.xyz..*.*(..))") - fun methodsToBeProfiled() { - } - } ----- - -We also need to create an `META-INF/aop.xml` file, to inform the AspectJ weaver that -we want to weave our `ProfilingAspect` into our classes. This file convention, namely -the presence of a file (or files) on the Java classpath called `META-INF/aop.xml` is -standard AspectJ. The following example shows the `aop.xml` file: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - ----- - -Now we can move on to the Spring-specific portion of the configuration. We need -to configure a `LoadTimeWeaver` (explained later). This load-time weaver is the -essential component responsible for weaving the aspect configuration in one or -more `META-INF/aop.xml` files into the classes in your application. The good -thing is that it does not require a lot of configuration (there are some more -options that you can specify, but these are detailed later), as can be seen in -the following example: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - ----- - -Now that all the required artifacts (the aspect, the `META-INF/aop.xml` -file, and the Spring configuration) are in place, we can create the following -driver class with a `main(..)` method to demonstrate the LTW in action: - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ----- - package com.xyz; - - // imports - - public class Main { - - public static void main(String[] args) { - ApplicationContext ctx = new ClassPathXmlApplicationContext("beans.xml"); - - EntitlementCalculationService service = - ctx.getBean(EntitlementCalculationService.class); - - // the profiling aspect is 'woven' around this method execution - service.calculateEntitlement(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.xyz - - // imports - - fun main() { - val ctx = ClassPathXmlApplicationContext("beans.xml") - - val service = ctx.getBean(EntitlementCalculationService.class) - - // the profiling aspect is 'woven' around this method execution - service.calculateEntitlement() - } ----- - -We have one last thing to do. The introduction to this section did say that one could -switch on LTW selectively on a per-`ClassLoader` basis with Spring, and this is true. -However, for this example, we use a Java agent (supplied with Spring) to switch on LTW. -We use the following command to run the `Main` class shown earlier: - -[literal,subs="verbatim"] ----- -java -javaagent:C:/projects/xyz/lib/spring-instrument.jar com.xyz.Main ----- - -The `-javaagent` is a flag for specifying and enabling -https://docs.oracle.com/javase/8/docs/api/java/lang/instrument/package-summary.html[agents -to instrument programs that run on the JVM]. The Spring Framework ships with such an -agent, the `InstrumentationSavingAgent`, which is packaged in the -`spring-instrument.jar` that was supplied as the value of the `-javaagent` argument in -the preceding example. - -The output from the execution of the `Main` program looks something like the next example. -(I have introduced a `Thread.sleep(..)` statement into the `calculateEntitlement()` -implementation so that the profiler actually captures something other than 0 -milliseconds (the `01234` milliseconds is not an overhead introduced by the AOP). -The following listing shows the output we got when we ran our profiler: - -[literal,subs="verbatim"] ----- -Calculating entitlement - -StopWatch 'ProfilingAspect': running time (millis) = 1234 ------- ----- ---------------------------- -ms % Task name ------- ----- ---------------------------- -01234 100% calculateEntitlement ----- - -Since this LTW is effected by using full-blown AspectJ, we are not limited only to advising -Spring beans. The following slight variation on the `Main` program yields the same -result: - -[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ----- - package com.xyz; - - // imports - - public class Main { - - public static void main(String[] args) { - new ClassPathXmlApplicationContext("beans.xml"); - - EntitlementCalculationService service = - new StubEntitlementCalculationService(); - - // the profiling aspect will be 'woven' around this method execution - service.calculateEntitlement(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.xyz - - // imports - - fun main(args: Array) { - ClassPathXmlApplicationContext("beans.xml") - - val service = StubEntitlementCalculationService() - - // the profiling aspect will be 'woven' around this method execution - service.calculateEntitlement() - } ----- - -Notice how, in the preceding program, we bootstrap the Spring container and -then create a new instance of the `StubEntitlementCalculationService` totally outside -the context of Spring. The profiling advice still gets woven in. - -Admittedly, the example is simplistic. However, the basics of the LTW support in Spring -have all been introduced in the earlier example, and the rest of this section explains -the "why" behind each bit of configuration and usage in detail. - -NOTE: The `ProfilingAspect` used in this example may be basic, but it is quite useful. It is a -nice example of a development-time aspect that developers can use during development -and then easily exclude from builds of the application being deployed -into UAT or production. - - -[[aop-aj-ltw-the-aspects]] -==== Aspects - -The aspects that you use in LTW have to be AspectJ aspects. You can write them in -either the AspectJ language itself, or you can write your aspects in the @AspectJ-style. -Your aspects are then both valid AspectJ and Spring AOP aspects. -Furthermore, the compiled aspect classes need to be available on the classpath. - - -[[aop-aj-ltw-aop_dot_xml]] -==== 'META-INF/aop.xml' - -The AspectJ LTW infrastructure is configured by using one or more `META-INF/aop.xml` -files that are on the Java classpath (either directly or, more typically, in jar files). - -The structure and contents of this file is detailed in the LTW part of the -https://www.eclipse.org/aspectj/doc/released/devguide/ltw-configuration.html[AspectJ reference -documentation]. Because the `aop.xml` file is 100% AspectJ, we do not describe it further here. - - -[[aop-aj-ltw-libraries]] -==== Required libraries (JARS) - -At minimum, you need the following libraries to use the Spring Framework's support -for AspectJ LTW: - -* `spring-aop.jar` -* `aspectjweaver.jar` - -If you use the <>, you also need: - -* `spring-instrument.jar` - - -[[aop-aj-ltw-spring]] -==== Spring Configuration - -The key component in Spring's LTW support is the `LoadTimeWeaver` interface (in the -`org.springframework.instrument.classloading` package), and the numerous implementations -of it that ship with the Spring distribution. A `LoadTimeWeaver` is responsible for -adding one or more `java.lang.instrument.ClassFileTransformers` to a `ClassLoader` at -runtime, which opens the door to all manner of interesting applications, one of which -happens to be the LTW of aspects. - -TIP: If you are unfamiliar with the idea of runtime class file transformation, see the -javadoc API documentation for the `java.lang.instrument` package before continuing. -While that documentation is not comprehensive, at least you can see the key interfaces -and classes (for reference as you read through this section). - -Configuring a `LoadTimeWeaver` for a particular `ApplicationContext` can be as easy as -adding one line. (Note that you almost certainly need to use an -`ApplicationContext` as your Spring container -- typically, a `BeanFactory` is not -enough because the LTW support uses `BeanFactoryPostProcessors`.) - -To enable the Spring Framework's LTW support, you need to configure a `LoadTimeWeaver`, -which typically is done by using the `@EnableLoadTimeWeaving` annotation, as follows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Configuration - @EnableLoadTimeWeaving - public class AppConfig { - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configuration - @EnableLoadTimeWeaving - class AppConfig { - } ----- - -Alternatively, if you prefer XML-based configuration, use the -`` element. Note that the element is defined in the -`context` namespace. The following example shows how to use ``: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - ----- - -The preceding configuration automatically defines and registers a number of LTW-specific -infrastructure beans, such as a `LoadTimeWeaver` and an `AspectJWeavingEnabler`, for you. -The default `LoadTimeWeaver` is the `DefaultContextLoadTimeWeaver` class, which attempts -to decorate an automatically detected `LoadTimeWeaver`. The exact type of `LoadTimeWeaver` -that is "automatically detected" is dependent upon your runtime environment. -The following table summarizes various `LoadTimeWeaver` implementations: - -[[aop-aj-ltw-spring-env-impls]] -.DefaultContextLoadTimeWeaver LoadTimeWeavers -|=== -| Runtime Environment| `LoadTimeWeaver` implementation - -| Running in https://tomcat.apache.org/[Apache Tomcat] -| `TomcatLoadTimeWeaver` - -| Running in https://eclipse-ee4j.github.io/glassfish/[GlassFish] (limited to EAR deployments) -| `GlassFishLoadTimeWeaver` - -| Running in Red Hat's https://www.jboss.org/jbossas/[JBoss AS] or https://www.wildfly.org/[WildFly] -| `JBossLoadTimeWeaver` - -| Running in IBM's https://www-01.ibm.com/software/webservers/appserv/was/[WebSphere] -| `WebSphereLoadTimeWeaver` - -| Running in Oracle's - https://www.oracle.com/technetwork/middleware/weblogic/overview/index-085209.html[WebLogic] -| `WebLogicLoadTimeWeaver` - -| JVM started with Spring `InstrumentationSavingAgent` - (`java -javaagent:path/to/spring-instrument.jar`) -| `InstrumentationLoadTimeWeaver` - -| Fallback, expecting the underlying ClassLoader to follow common conventions - (namely `addTransformer` and optionally a `getThrowawayClassLoader` method) -| `ReflectiveLoadTimeWeaver` -|=== - -Note that the table lists only the `LoadTimeWeavers` that are autodetected when you -use the `DefaultContextLoadTimeWeaver`. You can specify exactly which `LoadTimeWeaver` -implementation to use. - -To specify a specific `LoadTimeWeaver` with Java configuration, implement the -`LoadTimeWeavingConfigurer` interface and override the `getLoadTimeWeaver()` method. -The following example specifies a `ReflectiveLoadTimeWeaver`: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Configuration - @EnableLoadTimeWeaving - public class AppConfig implements LoadTimeWeavingConfigurer { - - @Override - public LoadTimeWeaver getLoadTimeWeaver() { - return new ReflectiveLoadTimeWeaver(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configuration - @EnableLoadTimeWeaving - class AppConfig : LoadTimeWeavingConfigurer { - - override fun getLoadTimeWeaver(): LoadTimeWeaver { - return ReflectiveLoadTimeWeaver() - } - } ----- - -If you use XML-based configuration, you can specify the fully qualified class name -as the value of the `weaver-class` attribute on the `` -element. Again, the following example specifies a `ReflectiveLoadTimeWeaver`: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - ----- - -The `LoadTimeWeaver` that is defined and registered by the configuration can be later -retrieved from the Spring container by using the well known name, `loadTimeWeaver`. -Remember that the `LoadTimeWeaver` exists only as a mechanism for Spring's LTW -infrastructure to add one or more `ClassFileTransformers`. The actual -`ClassFileTransformer` that does the LTW is the `ClassPreProcessorAgentAdapter` (from -the `org.aspectj.weaver.loadtime` package) class. See the class-level javadoc of the -`ClassPreProcessorAgentAdapter` class for further details, because the specifics of how -the weaving is actually effected is beyond the scope of this document. - -There is one final attribute of the configuration left to discuss: the `aspectjWeaving` -attribute (or `aspectj-weaving` if you use XML). This attribute controls whether LTW -is enabled or not. It accepts one of three possible values, with the default value being -`autodetect` if the attribute is not present. The following table summarizes the three -possible values: - -[[aop-aj-ltw-ltw-tag-attrs]] -.AspectJ weaving attribute values -|=== -| Annotation Value| XML Value| Explanation - -| `ENABLED` -| `on` -| AspectJ weaving is on, and aspects are woven at load-time as appropriate. - -| `DISABLED` -| `off` -| LTW is off. No aspect is woven at load-time. - -| `AUTODETECT` -| `autodetect` -| If the Spring LTW infrastructure can find at least one `META-INF/aop.xml` file, - then AspectJ weaving is on. Otherwise, it is off. This is the default value. -|=== - - -[[aop-aj-ltw-environments]] -==== Environment-specific Configuration - -This last section contains any additional settings and configuration that you need -when you use Spring's LTW support in environments such as application servers and web -containers. - -[[aop-aj-ltw-environments-tomcat-jboss-etc]] -===== Tomcat, JBoss, WebSphere, WebLogic - -Tomcat, JBoss/WildFly, IBM WebSphere Application Server and Oracle WebLogic Server all -provide a general app `ClassLoader` that is capable of local instrumentation. Spring's -native LTW may leverage those ClassLoader implementations to provide AspectJ weaving. -You can simply enable load-time weaving, as <>. -Specifically, you do not need to modify the JVM launch script to add -`-javaagent:path/to/spring-instrument.jar`. - -Note that on JBoss, you may need to disable the app server scanning to prevent it from -loading the classes before the application actually starts. A quick workaround is to add -to your artifact a file named `WEB-INF/jboss-scanning.xml` with the following content: - -[source,xml,indent=0,subs="verbatim"] ----- - ----- - -[[aop-aj-ltw-environments-generic]] -===== Generic Java Applications - -When class instrumentation is required in environments that are not supported by -specific `LoadTimeWeaver` implementations, a JVM agent is the general solution. -For such cases, Spring provides `InstrumentationLoadTimeWeaver` which requires a -Spring-specific (but very general) JVM agent, `spring-instrument.jar`, autodetected -by common `@EnableLoadTimeWeaving` and `` setups. - -To use it, you must start the virtual machine with the Spring agent by supplying -the following JVM options: - -[literal] -[subs="verbatim"] ----- --javaagent:/path/to/spring-instrument.jar ----- - -Note that this requires modification of the JVM launch script, which may prevent you -from using this in application server environments (depending on your server and your -operation policies). That said, for one-app-per-JVM deployments such as standalone -Spring Boot applications, you typically control the entire JVM setup in any case. - - - - -[[aop-resources]] -== Further Resources - -More information on AspectJ can be found on the https://www.eclipse.org/aspectj[AspectJ website]. - -_Eclipse AspectJ_ by Adrian Colyer et. al. (Addison-Wesley, 2005) provides a -comprehensive introduction and reference for the AspectJ language. - -_AspectJ in Action_, Second Edition by Ramnivas Laddad (Manning, 2009) comes highly -recommended. The focus of the book is on AspectJ, but a lot of general AOP themes are -explored (in some depth). diff --git a/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc b/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc new file mode 100644 index 000000000000..8e76aadb60eb --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc @@ -0,0 +1,53 @@ +[[aop-aspectj-programmatic]] += Programmatic Creation of @AspectJ Proxies + +In addition to declaring aspects in your configuration by using either `` +or ``, it is also possible to programmatically create proxies +that advise target objects. For the full details of Spring's AOP API, see the +<>. Here, we want to focus on the ability to automatically +create proxies by using @AspectJ aspects. + +You can use the `org.springframework.aop.aspectj.annotation.AspectJProxyFactory` class +to create a proxy for a target object that is advised by one or more @AspectJ aspects. +The basic usage for this class is very simple, as the following example shows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + // create a factory that can generate a proxy for the given target object + AspectJProxyFactory factory = new AspectJProxyFactory(targetObject); + + // add an aspect, the class must be an @AspectJ aspect + // you can call this as many times as you need with different aspects + factory.addAspect(SecurityManager.class); + + // you can also add existing aspect instances, the type of the object supplied + // must be an @AspectJ aspect + factory.addAspect(usageTracker); + + // now get the proxy object... + MyInterfaceType proxy = factory.getProxy(); +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + // create a factory that can generate a proxy for the given target object + val factory = AspectJProxyFactory(targetObject) + + // add an aspect, the class must be an @AspectJ aspect + // you can call this as many times as you need with different aspects + factory.addAspect(SecurityManager::class.java) + + // you can also add existing aspect instances, the type of the object supplied + // must be an @AspectJ aspect + factory.addAspect(usageTracker) + + // now get the proxy object... + val proxy = factory.getProxy() +---- + +See the {api-spring-framework}/aop/aspectj/annotation/AspectJProxyFactory.html[javadoc] for more information. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc new file mode 100644 index 000000000000..bcda90151581 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc @@ -0,0 +1,15 @@ +[[aop-ataspectj]] += @AspectJ support + +@AspectJ refers to a style of declaring aspects as regular Java classes annotated with +annotations. The @AspectJ style was introduced by the +https://www.eclipse.org/aspectj[AspectJ project] as part of the AspectJ 5 release. Spring +interprets the same annotations as AspectJ 5, using a library supplied by AspectJ +for pointcut parsing and matching. The AOP runtime is still pure Spring AOP, though, and +there is no dependency on the AspectJ compiler or weaver. + +NOTE: Using the AspectJ compiler and weaver enables use of the full AspectJ language and +is discussed in <>. + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc new file mode 100644 index 000000000000..0b1f36c11acc --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc @@ -0,0 +1,837 @@ +[[aop-advice]] += Declaring Advice + +Advice is associated with a pointcut expression and runs before, after, or around method +executions matched by the pointcut. The pointcut expression may be either an _inline +pointcut_ or a reference to a <>. + + +[[aop-advice-before]] +== Before Advice + +You can declare before advice in an aspect by using the `@Before` annotation. + +The following example uses an inline pointcut expression. + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.Before; + + @Aspect + public class BeforeExample { + + @Before("execution(* com.xyz.dao.*.*(..))") + public void doAccessCheck() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.Before + + @Aspect + class BeforeExample { + + @Before("execution(* com.xyz.dao.*.*(..))") + fun doAccessCheck() { + // ... + } + } +---- + +If we use a <>, we can rewrite the preceding example +as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.Before; + + @Aspect + public class BeforeExample { + + @Before("com.xyz.CommonPointcuts.dataAccessOperation()") + public void doAccessCheck() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.Before + + @Aspect + class BeforeExample { + + @Before("com.xyz.CommonPointcuts.dataAccessOperation()") + fun doAccessCheck() { + // ... + } + } +---- + + +[[aop-advice-after-returning]] +== After Returning Advice + +After returning advice runs when a matched method execution returns normally. +You can declare it by using the `@AfterReturning` annotation. + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.AfterReturning; + + @Aspect + public class AfterReturningExample { + + @AfterReturning("execution(* com.xyz.dao.*.*(..))") + public void doAccessCheck() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.AfterReturning + + @Aspect + class AfterReturningExample { + + @AfterReturning("execution(* com.xyz.dao.*.*(..))") + fun doAccessCheck() { + // ... + } + } +---- + +NOTE: You can have multiple advice declarations (and other members as well), +all inside the same aspect. We show only a single advice declaration in these +examples to focus the effect of each one. + +Sometimes, you need access in the advice body to the actual value that was returned. +You can use the form of `@AfterReturning` that binds the return value to get that +access, as the following example shows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.AfterReturning; + + @Aspect + public class AfterReturningExample { + + @AfterReturning( + pointcut="execution(* com.xyz.dao.*.*(..))", + returning="retVal") + public void doAccessCheck(Object retVal) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.AfterReturning + + @Aspect + class AfterReturningExample { + + @AfterReturning( + pointcut = "execution(* com.xyz.dao.*.*(..))", + returning = "retVal") + fun doAccessCheck(retVal: Any) { + // ... + } + } +---- + +The name used in the `returning` attribute must correspond to the name of a parameter +in the advice method. When a method execution returns, the return value is passed to +the advice method as the corresponding argument value. A `returning` clause also +restricts matching to only those method executions that return a value of the +specified type (in this case, `Object`, which matches any return value). + +Please note that it is not possible to return a totally different reference when +using after returning advice. + + +[[aop-advice-after-throwing]] +== After Throwing Advice + +After throwing advice runs when a matched method execution exits by throwing an +exception. You can declare it by using the `@AfterThrowing` annotation, as the +following example shows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.AfterThrowing; + + @Aspect + public class AfterThrowingExample { + + @AfterThrowing("execution(* com.xyz.dao.*.*(..))") + public void doRecoveryActions() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.AfterThrowing + + @Aspect + class AfterThrowingExample { + + @AfterThrowing("execution(* com.xyz.dao.*.*(..))") + fun doRecoveryActions() { + // ... + } + } +---- + +Often, you want the advice to run only when exceptions of a given type are thrown, +and you also often need access to the thrown exception in the advice body. You can +use the `throwing` attribute to both restrict matching (if desired -- use `Throwable` +as the exception type otherwise) and bind the thrown exception to an advice parameter. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.AfterThrowing; + + @Aspect + public class AfterThrowingExample { + + @AfterThrowing( + pointcut="execution(* com.xyz.dao.*.*(..))", + throwing="ex") + public void doRecoveryActions(DataAccessException ex) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.AfterThrowing + + @Aspect + class AfterThrowingExample { + + @AfterThrowing( + pointcut = "execution(* com.xyz.dao.*.*(..))", + throwing = "ex") + fun doRecoveryActions(ex: DataAccessException) { + // ... + } + } +---- + +The name used in the `throwing` attribute must correspond to the name of a parameter in +the advice method. When a method execution exits by throwing an exception, the exception +is passed to the advice method as the corresponding argument value. A `throwing` clause +also restricts matching to only those method executions that throw an exception of the +specified type (`DataAccessException`, in this case). + +[NOTE] +==== +Note that `@AfterThrowing` does not indicate a general exception handling callback. +Specifically, an `@AfterThrowing` advice method is only supposed to receive exceptions +from the join point (user-declared target method) itself but not from an accompanying +`@After`/`@AfterReturning` method. +==== + + +[[aop-advice-after-finally]] +== After (Finally) Advice + +After (finally) advice runs when a matched method execution exits. It is declared by +using the `@After` annotation. After advice must be prepared to handle both normal and +exception return conditions. It is typically used for releasing resources and similar +purposes. The following example shows how to use after finally advice: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.After; + + @Aspect + public class AfterFinallyExample { + + @After("execution(* com.xyz.dao.*.*(..))") + public void doReleaseLock() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.After + + @Aspect + class AfterFinallyExample { + + @After("execution(* com.xyz.dao.*.*(..))") + fun doReleaseLock() { + // ... + } + } +---- + +[NOTE] +==== +Note that `@After` advice in AspectJ is defined as "after finally advice", analogous +to a finally block in a try-catch statement. It will be invoked for any outcome, +normal return or exception thrown from the join point (user-declared target method), +in contrast to `@AfterReturning` which only applies to successful normal returns. +==== + + +[[aop-ataspectj-around-advice]] +== Around Advice + +The last kind of advice is _around_ advice. Around advice runs "around" a matched +method's execution. It has the opportunity to do work both before and after the method +runs and to determine when, how, and even if the method actually gets to run at all. +Around advice is often used if you need to share state before and after a method +execution in a thread-safe manner – for example, starting and stopping a timer. + +[TIP] +==== +Always use the least powerful form of advice that meets your requirements. + +For example, do not use _around_ advice if _before_ advice is sufficient for your needs. +==== + +Around advice is declared by annotating a method with the `@Around` annotation. The +method should declare `Object` as its return type, and the first parameter of the method +must be of type `ProceedingJoinPoint`. Within the body of the advice method, you must +invoke `proceed()` on the `ProceedingJoinPoint` in order for the underlying method to +run. Invoking `proceed()` without arguments will result in the caller's original +arguments being supplied to the underlying method when it is invoked. For advanced use +cases, there is an overloaded variant of the `proceed()` method which accepts an array of +arguments (`Object[]`). The values in the array will be used as the arguments to the +underlying method when it is invoked. + +[NOTE] +==== +The behavior of `proceed` when called with an `Object[]` is a little different than the +behavior of `proceed` for around advice compiled by the AspectJ compiler. For around +advice written using the traditional AspectJ language, the number of arguments passed to +`proceed` must match the number of arguments passed to the around advice (not the number +of arguments taken by the underlying join point), and the value passed to proceed in a +given argument position supplants the original value at the join point for the entity the +value was bound to (do not worry if this does not make sense right now). + +The approach taken by Spring is simpler and a better match to its proxy-based, +execution-only semantics. You only need to be aware of this difference if you compile +`@AspectJ` aspects written for Spring and use `proceed` with arguments with the AspectJ +compiler and weaver. There is a way to write such aspects that is 100% compatible across +both Spring AOP and AspectJ, and this is discussed in the +<>. +==== + +The value returned by the around advice is the return value seen by the caller of the +method. For example, a simple caching aspect could return a value from a cache if it has +one or invoke `proceed()` (and return that value) if it does not. Note that `proceed` +may be invoked once, many times, or not at all within the body of the around advice. All +of these are legal. + +WARNING: If you declare the return type of your around advice method as `void`, `null` +will always be returned to the caller, effectively ignoring the result of any invocation +of `proceed()`. It is therefore recommended that an around advice method declare a return +type of `Object`. The advice method should typically return the value returned from an +invocation of `proceed()`, even if the underlying method has a `void` return type. +However, the advice may optionally return a cached value, a wrapped value, or some other +value depending on the use case. + +The following example shows how to use around advice: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.Around; + import org.aspectj.lang.ProceedingJoinPoint; + + @Aspect + public class AroundExample { + + @Around("execution(* com.xyz..service.*.*(..))") + public Object doBasicProfiling(ProceedingJoinPoint pjp) throws Throwable { + // start stopwatch + Object retVal = pjp.proceed(); + // stop stopwatch + return retVal; + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.Around + import org.aspectj.lang.ProceedingJoinPoint + + @Aspect + class AroundExample { + + @Around("execution(* com.xyz..service.*.*(..))") + fun doBasicProfiling(pjp: ProceedingJoinPoint): Any { + // start stopwatch + val retVal = pjp.proceed() + // stop stopwatch + return retVal + } + } +---- + +[[aop-ataspectj-advice-params]] +== Advice Parameters + +Spring offers fully typed advice, meaning that you declare the parameters you need in the +advice signature (as we saw earlier for the returning and throwing examples) rather than +work with `Object[]` arrays all the time. We see how to make argument and other contextual +values available to the advice body later in this section. First, we take a look at how to +write generic advice that can find out about the method the advice is currently advising. + +[[aop-ataspectj-advice-params-the-joinpoint]] +=== Access to the Current `JoinPoint` + +Any advice method may declare, as its first parameter, a parameter of type +`org.aspectj.lang.JoinPoint`. Note that around advice is required to declare a first +parameter of type `ProceedingJoinPoint`, which is a subclass of `JoinPoint`. + +The `JoinPoint` interface provides a number of useful methods: + +* `getArgs()`: Returns the method arguments. +* `getThis()`: Returns the proxy object. +* `getTarget()`: Returns the target object. +* `getSignature()`: Returns a description of the method that is being advised. +* `toString()`: Prints a useful description of the method being advised. + +See the https://www.eclipse.org/aspectj/doc/released/runtime-api/org/aspectj/lang/JoinPoint.html[javadoc] for more detail. + +[[aop-ataspectj-advice-params-passing]] +=== Passing Parameters to Advice + +We have already seen how to bind the returned value or exception value (using after +returning and after throwing advice). To make argument values available to the advice +body, you can use the binding form of `args`. If you use a parameter name in place of a +type name in an `args` expression, the value of the corresponding argument is passed as +the parameter value when the advice is invoked. An example should make this clearer. +Suppose you want to advise the execution of DAO operations that take an `Account` +object as the first parameter, and you need access to the account in the advice body. +You could write the following: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Before("execution(* com.xyz.dao.*.*(..)) && args(account,..)") + public void validateAccount(Account account) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Before("execution(* com.xyz.dao.*.*(..)) && args(account,..)") + fun validateAccount(account: Account) { + // ... + } +---- + +The `args(account,..)` part of the pointcut expression serves two purposes. First, it +restricts matching to only those method executions where the method takes at least one +parameter, and the argument passed to that parameter is an instance of `Account`. +Second, it makes the actual `Account` object available to the advice through the `account` +parameter. + +Another way of writing this is to declare a pointcut that "provides" the `Account` +object value when it matches a join point, and then refer to the named pointcut +from the advice. This would look as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Pointcut("execution(* com.xyz.dao.*.*(..)) && args(account,..)") + private void accountDataAccessOperation(Account account) {} + + @Before("accountDataAccessOperation(account)") + public void validateAccount(Account account) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Pointcut("execution(* com.xyz.dao.*.*(..)) && args(account,..)") + private fun accountDataAccessOperation(account: Account) { + } + + @Before("accountDataAccessOperation(account)") + fun validateAccount(account: Account) { + // ... + } +---- + +See the AspectJ programming guide for more details. + +The proxy object (`this`), target object (`target`), and annotations (`@within`, +`@target`, `@annotation`, and `@args`) can all be bound in a similar fashion. The next +set of examples shows how to match the execution of methods annotated with an +`@Auditable` annotation and extract the audit code: + +The following shows the definition of the `@Auditable` annotation: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Retention(RetentionPolicy.RUNTIME) + @Target(ElementType.METHOD) + public @interface Auditable { + AuditCode value(); + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Retention(AnnotationRetention.RUNTIME) + @Target(AnnotationTarget.FUNCTION) + annotation class Auditable(val value: AuditCode) +---- + +The following shows the advice that matches the execution of `@Auditable` methods: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Before("com.xyz.Pointcuts.publicMethod() && @annotation(auditable)") // <1> + public void audit(Auditable auditable) { + AuditCode code = auditable.value(); + // ... + } +---- +<1> References the `publicMethod` named pointcut defined in <>. + +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Before("com.xyz.Pointcuts.publicMethod() && @annotation(auditable)") // <1> + fun audit(auditable: Auditable) { + val code = auditable.value() + // ... + } +---- +<1> References the `publicMethod` named pointcut defined in <>. + +[[aop-ataspectj-advice-params-generics]] +=== Advice Parameters and Generics + +Spring AOP can handle generics used in class declarations and method parameters. Suppose +you have a generic type like the following: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public interface Sample { + void sampleGenericMethod(T param); + void sampleGenericCollectionMethod(Collection param); + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + interface Sample { + fun sampleGenericMethod(param: T) + fun sampleGenericCollectionMethod(param: Collection) + } +---- + +You can restrict interception of method types to certain parameter types by +tying the advice parameter to the parameter type for which you want to intercept the method: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Before("execution(* ..Sample+.sampleGenericMethod(*)) && args(param)") + public void beforeSampleMethod(MyType param) { + // Advice implementation + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Before("execution(* ..Sample+.sampleGenericMethod(*)) && args(param)") + fun beforeSampleMethod(param: MyType) { + // Advice implementation + } +---- + +This approach does not work for generic collections. So you cannot define a +pointcut as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Before("execution(* ..Sample+.sampleGenericCollectionMethod(*)) && args(param)") + public void beforeSampleMethod(Collection param) { + // Advice implementation + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Before("execution(* ..Sample+.sampleGenericCollectionMethod(*)) && args(param)") + fun beforeSampleMethod(param: Collection) { + // Advice implementation + } +---- + +To make this work, we would have to inspect every element of the collection, which is not +reasonable, as we also cannot decide how to treat `null` values in general. To achieve +something similar to this, you have to type the parameter to `Collection` and manually +check the type of the elements. + +[[aop-ataspectj-advice-params-names]] +=== Determining Argument Names + +Parameter binding in advice invocations relies on matching the names used in pointcut +expressions to the parameter names declared in advice and pointcut method signatures. + +NOTE: This section uses the terms _argument_ and _parameter_ interchangeably, since +AspectJ APIs refer to parameter names as argument names. + +Spring AOP uses the following `ParameterNameDiscoverer` implementations to determine +parameter names. Each discoverer will be given a chance to discover parameter names, and +the first successful discoverer wins. If none of the registered discoverers is capable +of determining parameter names, an exception will be thrown. + +`AspectJAnnotationParameterNameDiscoverer` :: Uses parameter names that have been explicitly + specified by the user via the `argNames` attribute in the corresponding advice or + pointcut annotation. See <> for details. +`KotlinReflectionParameterNameDiscoverer` :: Uses Kotlin reflection APIs to determine + parameter names. This discoverer is only used if such APIs are present on the classpath. +`StandardReflectionParameterNameDiscoverer` :: Uses the standard `java.lang.reflect.Parameter` + API to determine parameter names. Requires that code be compiled with the `-parameters` + flag for `javac`. Recommended approach on Java 8+. +`LocalVariableTableParameterNameDiscoverer` :: Analyzes the local variable table available + in the byte code of the advice class to determine parameter names from debug information. + Requires that code be compiled with debug symbols (`-g:vars` at a minimum). Deprecated + as of Spring Framework 6.0 for removal in Spring Framework 6.1 in favor of compiling + code with `-parameters`. Not supported in a GraalVM native image. +`AspectJAdviceParameterNameDiscoverer` :: Deduces parameter names from the pointcut + expression, `returning`, and `throwing` clauses. See the + {api-spring-framework}/aop/aspectj/AspectJAdviceParameterNameDiscoverer.html[javadoc] + for details on the algorithm used. + +[[aop-ataspectj-advice-params-names-explicit]] +=== Explicit Argument Names + +@AspectJ advice and pointcut annotations have an optional `argNames` attribute that you +can use to specify the argument names of the annotated method. + +[TIP] +==== +If an @AspectJ aspect has been compiled by the AspectJ compiler (`ajc`) even without +debug information, you do not need to add the `argNames` attribute, since the compiler +retains the needed information. + +Similarly, if an @AspectJ aspect has been compiled with `javac` using the `-parameters` +flag, you do not need to add the `argNames` attribute, since the compiler retains the +needed information. +==== + +The following example shows how to use the `argNames` attribute: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Before( + value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> + argNames = "bean,auditable") // <2> + public void audit(Object bean, Auditable auditable) { + AuditCode code = auditable.value(); + // ... use code and bean + } +---- +<1> References the `publicMethod` named pointcut defined in <>. +<2> Declares `bean` and `auditable` as the argument names. + +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Before( + value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> + argNames = "bean,auditable") // <2> + fun audit(bean: Any, auditable: Auditable) { + val code = auditable.value() + // ... use code and bean + } +---- +<1> References the `publicMethod` named pointcut defined in <>. +<2> Declares `bean` and `auditable` as the argument names. + +If the first parameter is of type `JoinPoint`, `ProceedingJoinPoint`, or +`JoinPoint.StaticPart`, you can omit the name of the parameter from the value of the +`argNames` attribute. For example, if you modify the preceding advice to receive the join +point object, the `argNames` attribute does not need to include it: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Before( + value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> + argNames = "bean,auditable") // <2> + public void audit(JoinPoint jp, Object bean, Auditable auditable) { + AuditCode code = auditable.value(); + // ... use code, bean, and jp + } +---- +<1> References the `publicMethod` named pointcut defined in <>. +<2> Declares `bean` and `auditable` as the argument names. + +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Before( + value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> + argNames = "bean,auditable") // <2> + fun audit(jp: JoinPoint, bean: Any, auditable: Auditable) { + val code = auditable.value() + // ... use code, bean, and jp + } +---- +<1> References the `publicMethod` named pointcut defined in <>. +<2> Declares `bean` and `auditable` as the argument names. + +The special treatment given to the first parameter of type `JoinPoint`, +`ProceedingJoinPoint`, or `JoinPoint.StaticPart` is particularly convenient for advice +methods that do not collect any other join point context. In such situations, you may +omit the `argNames` attribute. For example, the following advice does not need to declare +the `argNames` attribute: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Before("com.xyz.Pointcuts.publicMethod()") // <1> + public void audit(JoinPoint jp) { + // ... use jp + } +---- +<1> References the `publicMethod` named pointcut defined in <>. + +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Before("com.xyz.Pointcuts.publicMethod()") // <1> + fun audit(jp: JoinPoint) { + // ... use jp + } +---- +<1> References the `publicMethod` named pointcut defined in <>. + + +[[aop-ataspectj-advice-proceeding-with-the-call]] +=== Proceeding with Arguments + +We remarked earlier that we would describe how to write a `proceed` call with +arguments that works consistently across Spring AOP and AspectJ. The solution is +to ensure that the advice signature binds each of the method parameters in order. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Around("execution(List find*(..)) && " + + "com.xyz.CommonPointcuts.inDataAccessLayer() && " + + "args(accountHolderNamePattern)") // <1> + public Object preProcessQueryPattern(ProceedingJoinPoint pjp, + String accountHolderNamePattern) throws Throwable { + String newPattern = preProcess(accountHolderNamePattern); + return pjp.proceed(new Object[] {newPattern}); + } +---- +<1> References the `inDataAccessLayer` named pointcut defined in <>. + +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Around("execution(List find*(..)) && " + + "com.xyz.CommonPointcuts.inDataAccessLayer() && " + + "args(accountHolderNamePattern)") // <1> + fun preProcessQueryPattern(pjp: ProceedingJoinPoint, + accountHolderNamePattern: String): Any { + val newPattern = preProcess(accountHolderNamePattern) + return pjp.proceed(arrayOf(newPattern)) + } +---- +<1> References the `inDataAccessLayer` named pointcut defined in <>. + +In many cases, you do this binding anyway (as in the preceding example). + + +[[aop-ataspectj-advice-ordering]] +== Advice Ordering + +What happens when multiple pieces of advice all want to run at the same join point? +Spring AOP follows the same precedence rules as AspectJ to determine the order of advice +execution. The highest precedence advice runs first "on the way in" (so, given two pieces +of before advice, the one with highest precedence runs first). "On the way out" from a +join point, the highest precedence advice runs last (so, given two pieces of after +advice, the one with the highest precedence will run second). + +When two pieces of advice defined in different aspects both need to run at the same +join point, unless you specify otherwise, the order of execution is undefined. You can +control the order of execution by specifying precedence. This is done in the normal +Spring way by either implementing the `org.springframework.core.Ordered` interface in +the aspect class or annotating it with the `@Order` annotation. Given two aspects, the +aspect returning the lower value from `Ordered.getOrder()` (or the annotation value) has +the higher precedence. + +[NOTE] +==== +Each of the distinct advice types of a particular aspect is conceptually meant to apply +to the join point directly. As a consequence, an `@AfterThrowing` advice method is not +supposed to receive an exception from an accompanying `@After`/`@AfterReturning` method. + +As of Spring Framework 5.2.7, advice methods defined in the same `@Aspect` class that +need to run at the same join point are assigned precedence based on their advice type in +the following order, from highest to lowest precedence: `@Around`, `@Before`, `@After`, +`@AfterReturning`, `@AfterThrowing`. Note, however, that an `@After` advice method will +effectively be invoked after any `@AfterReturning` or `@AfterThrowing` advice methods +in the same aspect, following AspectJ's "after finally advice" semantics for `@After`. + +When two pieces of the same type of advice (for example, two `@After` advice methods) +defined in the same `@Aspect` class both need to run at the same join point, the ordering +is undefined (since there is no way to retrieve the source code declaration order through +reflection for javac-compiled classes). Consider collapsing such advice methods into one +advice method per join point in each `@Aspect` class or refactor the pieces of advice into +separate `@Aspect` classes that you can order at the aspect level via `Ordered` or `@Order`. +==== + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc new file mode 100644 index 000000000000..e0725013ea03 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc @@ -0,0 +1,55 @@ +[[aop-aspectj-support]] += Enabling @AspectJ Support + +To use @AspectJ aspects in a Spring configuration, you need to enable Spring support for +configuring Spring AOP based on @AspectJ aspects and auto-proxying beans based on +whether or not they are advised by those aspects. By auto-proxying, we mean that, if Spring +determines that a bean is advised by one or more aspects, it automatically generates +a proxy for that bean to intercept method invocations and ensures that advice is run +as needed. + +The @AspectJ support can be enabled with XML- or Java-style configuration. In either +case, you also need to ensure that AspectJ's `aspectjweaver.jar` library is on the +classpath of your application (version 1.9 or later). This library is available in the +`lib` directory of an AspectJ distribution or from the Maven Central repository. + + +[[aop-enable-aspectj-java]] +== Enabling @AspectJ Support with Java Configuration + +To enable @AspectJ support with Java `@Configuration`, add the `@EnableAspectJAutoProxy` +annotation, as the following example shows: +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Configuration + @EnableAspectJAutoProxy + public class AppConfig { + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configuration + @EnableAspectJAutoProxy + class AppConfig +---- + +[[aop-enable-aspectj-xml]] +== Enabling @AspectJ Support with XML Configuration + +To enable @AspectJ support with XML-based configuration, use the `aop:aspectj-autoproxy` +element, as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + +---- + +This assumes that you use schema support as described in +<>. +See <> for how to +import the tags in the `aop` namespace. + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/at-aspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/at-aspectj.adoc new file mode 100644 index 000000000000..c50f8aba6c3e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/at-aspectj.adoc @@ -0,0 +1,62 @@ +[[aop-at-aspectj]] += Declaring an Aspect + +With @AspectJ support enabled, any bean defined in your application context with a +class that is an @AspectJ aspect (has the `@Aspect` annotation) is automatically +detected by Spring and used to configure Spring AOP. The next two examples show the +minimal steps required for a not-very-useful aspect. + +The first of the two examples shows a regular bean definition in the application context +that points to a bean class that is annotated with `@Aspect`: + +[source,xml,indent=0,subs="verbatim"] +---- + + + +---- + +The second of the two examples shows the `NotVeryUsefulAspect` class definition, which is +annotated with `@Aspect`: + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages",fold="none"] +.Java +---- + package com.xyz; + + import org.aspectj.lang.annotation.Aspect; + + @Aspect + public class NotVeryUsefulAspect { + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages",fold="none"] +.Kotlin +---- + package com.xyz + + import org.aspectj.lang.annotation.Aspect + + @Aspect + class NotVeryUsefulAspect +---- + +Aspects (classes annotated with `@Aspect`) can have methods and fields, the same as any +other class. They can also contain pointcut, advice, and introduction (inter-type) +declarations. + +.Autodetecting aspects through component scanning +NOTE: You can register aspect classes as regular beans in your Spring XML configuration, +via `@Bean` methods in `@Configuration` classes, or have Spring autodetect them through +classpath scanning -- the same as any other Spring-managed bean. However, note that the +`@Aspect` annotation is not sufficient for autodetection in the classpath. For that +purpose, you need to add a separate `@Component` annotation (or, alternatively, a custom +stereotype annotation that qualifies, as per the rules of Spring's component scanner). + +.Advising aspects with other aspects? +NOTE: In Spring AOP, aspects themselves cannot be the targets of advice from other +aspects. The `@Aspect` annotation on a class marks it as an aspect and, hence, excludes +it from auto-proxying. + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc new file mode 100644 index 000000000000..46507ec9ff11 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc @@ -0,0 +1,166 @@ +[[aop-ataspectj-example]] += An AOP Example + +Now that you have seen how all the constituent parts work, we can put them together to do +something useful. + +The execution of business services can sometimes fail due to concurrency issues (for +example, a deadlock loser). If the operation is retried, it is likely to succeed +on the next try. For business services where it is appropriate to retry in such +conditions (idempotent operations that do not need to go back to the user for conflict +resolution), we want to transparently retry the operation to avoid the client seeing a +`PessimisticLockingFailureException`. This is a requirement that clearly cuts across +multiple services in the service layer and, hence, is ideal for implementing through an +aspect. + +Because we want to retry the operation, we need to use around advice so that we can +call `proceed` multiple times. The following listing shows the basic aspect implementation: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Aspect + public class ConcurrentOperationExecutor implements Ordered { + + private static final int DEFAULT_MAX_RETRIES = 2; + + private int maxRetries = DEFAULT_MAX_RETRIES; + private int order = 1; + + public void setMaxRetries(int maxRetries) { + this.maxRetries = maxRetries; + } + + public int getOrder() { + return this.order; + } + + public void setOrder(int order) { + this.order = order; + } + + @Around("com.xyz.CommonPointcuts.businessService()") // <1> + public Object doConcurrentOperation(ProceedingJoinPoint pjp) throws Throwable { + int numAttempts = 0; + PessimisticLockingFailureException lockFailureException; + do { + numAttempts++; + try { + return pjp.proceed(); + } + catch(PessimisticLockingFailureException ex) { + lockFailureException = ex; + } + } while(numAttempts <= this.maxRetries); + throw lockFailureException; + } + } +---- +<1> References the `businessService` named pointcut defined in <>. + +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Aspect + class ConcurrentOperationExecutor : Ordered { + + private val DEFAULT_MAX_RETRIES = 2 + private var maxRetries = DEFAULT_MAX_RETRIES + private var order = 1 + + fun setMaxRetries(maxRetries: Int) { + this.maxRetries = maxRetries + } + + override fun getOrder(): Int { + return this.order + } + + fun setOrder(order: Int) { + this.order = order + } + + @Around("com.xyz.CommonPointcuts.businessService()") // <1> + fun doConcurrentOperation(pjp: ProceedingJoinPoint): Any { + var numAttempts = 0 + var lockFailureException: PessimisticLockingFailureException + do { + numAttempts++ + try { + return pjp.proceed() + } catch (ex: PessimisticLockingFailureException) { + lockFailureException = ex + } + + } while (numAttempts <= this.maxRetries) + throw lockFailureException + } + } +---- +<1> References the `businessService` named pointcut defined in <>. + +Note that the aspect implements the `Ordered` interface so that we can set the precedence of +the aspect higher than the transaction advice (we want a fresh transaction each time we +retry). The `maxRetries` and `order` properties are both configured by Spring. The +main action happens in the `doConcurrentOperation` around advice. Notice that, for the +moment, we apply the retry logic to each `businessService`. We try to proceed, +and if we fail with a `PessimisticLockingFailureException`, we try again, unless +we have exhausted all of our retry attempts. + +The corresponding Spring configuration follows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + +---- + +To refine the aspect so that it retries only idempotent operations, we might define the following +`Idempotent` annotation: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Retention(RetentionPolicy.RUNTIME) + // marker annotation + public @interface Idempotent { + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Retention(AnnotationRetention.RUNTIME) + // marker annotation + annotation class Idempotent +---- + +We can then use the annotation to annotate the implementation of service operations. The change +to the aspect to retry only idempotent operations involves refining the pointcut +expression so that only `@Idempotent` operations match, as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Around("execution(* com.xyz..service.*.*(..)) && " + + "@annotation(com.xyz.service.Idempotent)") + public Object doConcurrentOperation(ProceedingJoinPoint pjp) throws Throwable { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Around("execution(* com.xyz..service.*.*(..)) && " + + "@annotation(com.xyz.service.Idempotent)") + fun doConcurrentOperation(pjp: ProceedingJoinPoint): Any { + // ... + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/instantiation-models.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/instantiation-models.adoc new file mode 100644 index 000000000000..75c985d8112e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/instantiation-models.adoc @@ -0,0 +1,59 @@ +[[aop-instantiation-models]] += Aspect Instantiation Models + +NOTE: This is an advanced topic. If you are just starting out with AOP, you can safely skip +it until later. + +By default, there is a single instance of each aspect within the application +context. AspectJ calls this the singleton instantiation model. It is possible to define +aspects with alternate lifecycles. Spring supports AspectJ's `perthis` and `pertarget` +instantiation models; `percflow`, `percflowbelow`, and `pertypewithin` are not currently +supported. + +You can declare a `perthis` aspect by specifying a `perthis` clause in the `@Aspect` +annotation. Consider the following example: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Aspect("perthis(execution(* com.xyz..service.*.*(..)))") + public class MyAspect { + + private int someState; + + @Before("execution(* com.xyz..service.*.*(..))") + public void recordServiceUsage() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Aspect("perthis(execution(* com.xyz..service.*.*(..)))") + class MyAspect { + + private val someState: Int = 0 + + @Before("execution(* com.xyz..service.*.*(..))") + fun recordServiceUsage() { + // ... + } + } +---- + +In the preceding example, the effect of the `perthis` clause is that one aspect instance +is created for each unique service object that performs a business service (each unique +object bound to `this` at join points matched by the pointcut expression). The aspect +instance is created the first time that a method is invoked on the service object. The +aspect goes out of scope when the service object goes out of scope. Before the aspect +instance is created, none of the advice within it runs. As soon as the aspect instance +has been created, the advice declared within it runs at matched join points, but only +when the service object is the one with which this aspect is associated. See the AspectJ +Programming Guide for more information on `per` clauses. + +The `pertarget` instantiation model works in exactly the same way as `perthis`, but it +creates one aspect instance for each unique target object at matched join points. + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/introductions.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/introductions.adoc new file mode 100644 index 000000000000..d535ade9f49a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/introductions.adoc @@ -0,0 +1,67 @@ +[[aop-introductions]] += Introductions + +Introductions (known as inter-type declarations in AspectJ) enable an aspect to declare +that advised objects implement a given interface, and to provide an implementation of +that interface on behalf of those objects. + +You can make an introduction by using the `@DeclareParents` annotation. This annotation +is used to declare that matching types have a new parent (hence the name). For example, +given an interface named `UsageTracked` and an implementation of that interface named +`DefaultUsageTracked`, the following aspect declares that all implementors of service +interfaces also implement the `UsageTracked` interface (e.g. for statistics via JMX): + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Aspect + public class UsageTracking { + + @DeclareParents(value="com.xyz.service.*+", defaultImpl=DefaultUsageTracked.class) + public static UsageTracked mixin; + + @Before("execution(* com.xyz..service.*.*(..)) && this(usageTracked)") + public void recordUsage(UsageTracked usageTracked) { + usageTracked.incrementUseCount(); + } + + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Aspect + class UsageTracking { + + companion object { + @DeclareParents(value = "com.xyz.service.*+", + defaultImpl = DefaultUsageTracked::class) + lateinit var mixin: UsageTracked + } + + @Before("execution(* com.xyz..service.*.*(..)) && this(usageTracked)") + fun recordUsage(usageTracked: UsageTracked) { + usageTracked.incrementUseCount() + } + } +---- + +The interface to be implemented is determined by the type of the annotated field. The +`value` attribute of the `@DeclareParents` annotation is an AspectJ type pattern. Any +bean of a matching type implements the `UsageTracked` interface. Note that, in the +before advice of the preceding example, service beans can be directly used as +implementations of the `UsageTracked` interface. If accessing a bean programmatically, +you would write the following: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + UsageTracked usageTracked = context.getBean("myService", UsageTracked.class); +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + val usageTracked = context.getBean("myService", UsageTracked.class) +---- + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc new file mode 100644 index 000000000000..4ddddf4fb893 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc @@ -0,0 +1,575 @@ +[[aop-pointcuts]] += Declaring a Pointcut + +Pointcuts determine join points of interest and thus enable us to control +when advice runs. Spring AOP only supports method execution join points for Spring +beans, so you can think of a pointcut as matching the execution of methods on Spring +beans. A pointcut declaration has two parts: a signature comprising a name and any +parameters and a pointcut expression that determines exactly which method +executions we are interested in. In the @AspectJ annotation-style of AOP, a pointcut +signature is provided by a regular method definition, and the pointcut expression is +indicated by using the `@Pointcut` annotation (the method serving as the pointcut signature +must have a `void` return type). + +An example may help make this distinction between a pointcut signature and a pointcut +expression clear. The following example defines a pointcut named `anyOldTransfer` that +matches the execution of any method named `transfer`: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Pointcut("execution(* transfer(..))") // the pointcut expression + private void anyOldTransfer() {} // the pointcut signature +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Pointcut("execution(* transfer(..))") // the pointcut expression + private fun anyOldTransfer() {} // the pointcut signature +---- + +The pointcut expression that forms the value of the `@Pointcut` annotation is a regular +AspectJ pointcut expression. For a full discussion of AspectJ's pointcut language, see +the https://www.eclipse.org/aspectj/doc/released/progguide/index.html[AspectJ +Programming Guide] (and, for extensions, the +https://www.eclipse.org/aspectj/doc/released/adk15notebook/index.html[AspectJ 5 +Developer's Notebook]) or one of the books on AspectJ (such as _Eclipse AspectJ_, by Colyer +et al., or _AspectJ in Action_, by Ramnivas Laddad). + + +[[aop-pointcuts-designators]] +== Supported Pointcut Designators + +Spring AOP supports the following AspectJ pointcut designators (PCD) for use in pointcut +expressions: + +* `execution`: For matching method execution join points. This is the primary + pointcut designator to use when working with Spring AOP. +* `within`: Limits matching to join points within certain types (the execution + of a method declared within a matching type when using Spring AOP). +* `this`: Limits matching to join points (the execution of methods when using Spring + AOP) where the bean reference (Spring AOP proxy) is an instance of the given type. +* `target`: Limits matching to join points (the execution of methods when using + Spring AOP) where the target object (application object being proxied) is an instance + of the given type. +* `args`: Limits matching to join points (the execution of methods when using Spring + AOP) where the arguments are instances of the given types. +* `@target`: Limits matching to join points (the execution of methods when using + Spring AOP) where the class of the executing object has an annotation of the given type. +* `@args`: Limits matching to join points (the execution of methods when using Spring + AOP) where the runtime type of the actual arguments passed have annotations of the + given types. +* `@within`: Limits matching to join points within types that have the given + annotation (the execution of methods declared in types with the given annotation when + using Spring AOP). +* `@annotation`: Limits matching to join points where the subject of the join point + (the method being run in Spring AOP) has the given annotation. + +.Other pointcut types +**** +The full AspectJ pointcut language supports additional pointcut designators that are not +supported in Spring: `call`, `get`, `set`, `preinitialization`, +`staticinitialization`, `initialization`, `handler`, `adviceexecution`, `withincode`, `cflow`, +`cflowbelow`, `if`, `@this`, and `@withincode`. Use of these pointcut designators in pointcut +expressions interpreted by Spring AOP results in an `IllegalArgumentException` being +thrown. + +The set of pointcut designators supported by Spring AOP may be extended in future +releases to support more of the AspectJ pointcut designators. +**** + +Because Spring AOP limits matching to only method execution join points, the preceding discussion +of the pointcut designators gives a narrower definition than you can find in the +AspectJ programming guide. In addition, AspectJ itself has type-based semantics and, at +an execution join point, both `this` and `target` refer to the same object: the +object executing the method. Spring AOP is a proxy-based system and differentiates +between the proxy object itself (which is bound to `this`) and the target object behind the +proxy (which is bound to `target`). + +[NOTE] +==== +Due to the proxy-based nature of Spring's AOP framework, calls within the target object +are, by definition, not intercepted. For JDK proxies, only public interface method +calls on the proxy can be intercepted. With CGLIB, public and protected method calls on +the proxy are intercepted (and even package-visible methods, if necessary). However, +common interactions through proxies should always be designed through public signatures. + +Note that pointcut definitions are generally matched against any intercepted method. +If a pointcut is strictly meant to be public-only, even in a CGLIB proxy scenario with +potential non-public interactions through proxies, it needs to be defined accordingly. + +If your interception needs include method calls or even constructors within the target +class, consider the use of Spring-driven <> instead +of Spring's proxy-based AOP framework. This constitutes a different mode of AOP usage +with different characteristics, so be sure to make yourself familiar with weaving +before making a decision. +==== + +Spring AOP also supports an additional PCD named `bean`. This PCD lets you limit +the matching of join points to a particular named Spring bean or to a set of named +Spring beans (when using wildcards). The `bean` PCD has the following form: + +[source,indent=0,subs="verbatim"] +---- + bean(idOrNameOfBean) +---- + +The `idOrNameOfBean` token can be the name of any Spring bean. Limited wildcard +support that uses the `*` character is provided, so, if you establish some naming +conventions for your Spring beans, you can write a `bean` PCD expression +to select them. As is the case with other pointcut designators, the `bean` PCD can +be used with the `&&` (and), `||` (or), and `!` (negation) operators, too. + +[NOTE] +==== +The `bean` PCD is supported only in Spring AOP and not in +native AspectJ weaving. It is a Spring-specific extension to the standard PCDs that +AspectJ defines and is, therefore, not available for aspects declared in the `@Aspect` model. + +The `bean` PCD operates at the instance level (building on the Spring bean name +concept) rather than at the type level only (to which weaving-based AOP is limited). +Instance-based pointcut designators are a special capability of Spring's +proxy-based AOP framework and its close integration with the Spring bean factory, where +it is natural and straightforward to identify specific beans by name. +==== + + +[[aop-pointcuts-combining]] +== Combining Pointcut Expressions + +You can combine pointcut expressions by using `&&,` `||` and `!`. You can also refer to +pointcut expressions by name. The following example shows three pointcut expressions: + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] +.Java +---- + package com.xyz; + + @Aspect + public class Pointcuts { + + @Pointcut("execution(public * *(..))") + public void publicMethod() {} // <1> + + @Pointcut("within(com.xyz.trading..*)") + public void inTrading() {} // <2> + + @Pointcut("publicMethod() && inTrading()") + public void tradingOperation() {} // <3> + } +---- +<1> `publicMethod` matches if a method execution join point represents the execution +of any public method. +<2> `inTrading` matches if a method execution is in the trading module. +<3> `tradingOperation` matches if a method execution represents any public method in the +trading module. + +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.xyz + + @Aspect + class Pointcuts { + + @Pointcut("execution(public * *(..))") + fun publicMethod() {} // <1> + + @Pointcut("within(com.xyz.trading..*)") + fun inTrading() {} // <2> + + @Pointcut("publicMethod() && inTrading()") + fun tradingOperation() {} // <3> + } +---- +<1> `publicMethod` matches if a method execution join point represents the execution +of any public method. +<2> `inTrading` matches if a method execution is in the trading module. +<3> `tradingOperation` matches if a method execution represents any public method in the +trading module. + +It is a best practice to build more complex pointcut expressions out of smaller _named +pointcuts_, as shown above. When referring to pointcuts by name, normal Java visibility +rules apply (you can see `private` pointcuts in the same type, `protected` pointcuts in +the hierarchy, `public` pointcuts anywhere, and so on). Visibility does not affect +pointcut matching. + + +[[aop-common-pointcuts]] +== Sharing Named Pointcut Definitions + +When working with enterprise applications, developers often have the need to refer to +modules of the application and particular sets of operations from within several aspects. +We recommend defining a dedicated aspect that captures commonly used _named pointcut_ +expressions for this purpose. Such an aspect typically resembles the following +`CommonPointcuts` example (though what you name the aspect is up to you): + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages",fold="none"] +.Java +---- + package com.xyz; + + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.Pointcut; + + @Aspect + public class CommonPointcuts { + + /** + * A join point is in the web layer if the method is defined + * in a type in the com.xyz.web package or any sub-package + * under that. + */ + @Pointcut("within(com.xyz.web..*)") + public void inWebLayer() {} + + /** + * A join point is in the service layer if the method is defined + * in a type in the com.xyz.service package or any sub-package + * under that. + */ + @Pointcut("within(com.xyz.service..*)") + public void inServiceLayer() {} + + /** + * A join point is in the data access layer if the method is defined + * in a type in the com.xyz.dao package or any sub-package + * under that. + */ + @Pointcut("within(com.xyz.dao..*)") + public void inDataAccessLayer() {} + + /** + * A business service is the execution of any method defined on a service + * interface. This definition assumes that interfaces are placed in the + * "service" package, and that implementation types are in sub-packages. + * + * If you group service interfaces by functional area (for example, + * in packages com.xyz.abc.service and com.xyz.def.service) then + * the pointcut expression "execution(* com.xyz..service.*.*(..))" + * could be used instead. + * + * Alternatively, you can write the expression using the 'bean' + * PCD, like so "bean(*Service)". (This assumes that you have + * named your Spring service beans in a consistent fashion.) + */ + @Pointcut("execution(* com.xyz..service.*.*(..))") + public void businessService() {} + + /** + * A data access operation is the execution of any method defined on a + * DAO interface. This definition assumes that interfaces are placed in the + * "dao" package, and that implementation types are in sub-packages. + */ + @Pointcut("execution(* com.xyz.dao.*.*(..))") + public void dataAccessOperation() {} + + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages",fold="none"] +.Kotlin +---- + package com.xyz + + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.Pointcut + + @Aspect + class CommonPointcuts { + + /** + * A join point is in the web layer if the method is defined + * in a type in the com.xyz.web package or any sub-package + * under that. + */ + @Pointcut("within(com.xyz.web..*)") + fun inWebLayer() {} + + /** + * A join point is in the service layer if the method is defined + * in a type in the com.xyz.service package or any sub-package + * under that. + */ + @Pointcut("within(com.xyz.service..*)") + fun inServiceLayer() {} + + /** + * A join point is in the data access layer if the method is defined + * in a type in the com.xyz.dao package or any sub-package + * under that. + */ + @Pointcut("within(com.xyz.dao..*)") + fun inDataAccessLayer() {} + + /** + * A business service is the execution of any method defined on a service + * interface. This definition assumes that interfaces are placed in the + * "service" package, and that implementation types are in sub-packages. + * + * If you group service interfaces by functional area (for example, + * in packages com.xyz.abc.service and com.xyz.def.service) then + * the pointcut expression "execution(* com.xyz..service.*.*(..))" + * could be used instead. + * + * Alternatively, you can write the expression using the 'bean' + * PCD, like so "bean(*Service)". (This assumes that you have + * named your Spring service beans in a consistent fashion.) + */ + @Pointcut("execution(* com.xyz..service.*.*(..))") + fun businessService() {} + + /** + * A data access operation is the execution of any method defined on a + * DAO interface. This definition assumes that interfaces are placed in the + * "dao" package, and that implementation types are in sub-packages. + */ + @Pointcut("execution(* com.xyz.dao.*.*(..))") + fun dataAccessOperation() {} + + } +---- + +You can refer to the pointcuts defined in such an aspect anywhere you need a pointcut +expression by referencing the fully-qualified name of the `@Aspect` class combined with +the `@Pointcut` method's name. For example, to make the service layer transactional, you +could write the following which references the +`com.xyz.CommonPointcuts.businessService()` _named pointcut_: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + +---- + +The `` and `` elements are discussed in <>. The +transaction elements are discussed in <>. + + +[[aop-pointcuts-examples]] +== Examples + +Spring AOP users are likely to use the `execution` pointcut designator the most often. +The format of an execution expression follows: + +[literal,indent=0,subs="verbatim"] +---- + execution(modifiers-pattern? + ret-type-pattern + declaring-type-pattern?name-pattern(param-pattern) + throws-pattern?) +---- + +All parts except the returning type pattern (`ret-type-pattern` in the preceding snippet), +the name pattern, and the parameters pattern are optional. The returning type pattern determines +what the return type of the method must be in order for a join point to be matched. +`{asterisk}` is most frequently used as the returning type pattern. It matches any return +type. A fully-qualified type name matches only when the method returns the given +type. The name pattern matches the method name. You can use the `{asterisk}` wildcard as all or +part of a name pattern. If you specify a declaring type pattern, +include a trailing `.` to join it to the name pattern component. +The parameters pattern is slightly more complex: `()` matches a +method that takes no parameters, whereas `(..)` matches any number (zero or more) of parameters. +The `({asterisk})` pattern matches a method that takes one parameter of any type. +`(*,String)` matches a method that takes two parameters. The first can be of any type, while the +second must be a `String`. Consult the +https://www.eclipse.org/aspectj/doc/released/progguide/semantics-pointcuts.html[Language +Semantics] section of the AspectJ Programming Guide for more information. + +The following examples show some common pointcut expressions: + +* The execution of any public method: ++ +[literal,indent=0,subs="verbatim"] +---- + execution(public * *(..)) +---- + +* The execution of any method with a name that begins with `set`: ++ +[literal,indent=0,subs="verbatim"] +---- + execution(* set*(..)) +---- + +* The execution of any method defined by the `AccountService` interface: ++ +[literal,indent=0,subs="verbatim"] +---- + execution(* com.xyz.service.AccountService.*(..)) +---- + +* The execution of any method defined in the `service` package: ++ +[literal,indent=0,subs="verbatim"] +---- + execution(* com.xyz.service.*.*(..)) +---- + +* The execution of any method defined in the service package or one of its sub-packages: ++ +[literal,indent=0,subs="verbatim"] +---- + execution(* com.xyz.service..*.*(..)) +---- + +* Any join point (method execution only in Spring AOP) within the service package: ++ +[literal,indent=0,subs="verbatim"] +---- + within(com.xyz.service.*) +---- + +* Any join point (method execution only in Spring AOP) within the service package or one of its +sub-packages: ++ +[literal,indent=0,subs="verbatim"] +---- + within(com.xyz.service..*) +---- + +* Any join point (method execution only in Spring AOP) where the proxy implements the +`AccountService` interface: ++ +[literal,indent=0,subs="verbatim"] +---- + this(com.xyz.service.AccountService) +---- ++ +NOTE: `this` is more commonly used in a binding form. See the section on <> +for how to make the proxy object available in the advice body. + +* Any join point (method execution only in Spring AOP) where the target object +implements the `AccountService` interface: ++ +[literal,indent=0,subs="verbatim"] +---- + target(com.xyz.service.AccountService) +---- ++ +NOTE: `target` is more commonly used in a binding form. See the <> section +for how to make the target object available in the advice body. + +* Any join point (method execution only in Spring AOP) that takes a single parameter +and where the argument passed at runtime is `Serializable`: ++ +[literal,indent=0,subs="verbatim"] +---- + args(java.io.Serializable) +---- ++ +NOTE: `args` is more commonly used in a binding form. See the <> section +for how to make the method arguments available in the advice body. ++ +Note that the pointcut given in this example is different from `execution(* +*(java.io.Serializable))`. The args version matches if the argument passed at runtime is +`Serializable`, and the execution version matches if the method signature declares a single +parameter of type `Serializable`. + +* Any join point (method execution only in Spring AOP) where the target object has a +`@Transactional` annotation: ++ +[literal,indent=0,subs="verbatim"] +---- + @target(org.springframework.transaction.annotation.Transactional) +---- ++ +NOTE: You can also use `@target` in a binding form. See the <> section for +how to make the annotation object available in the advice body. + +* Any join point (method execution only in Spring AOP) where the declared type of the +target object has an `@Transactional` annotation: ++ +[literal,indent=0,subs="verbatim"] +---- + @within(org.springframework.transaction.annotation.Transactional) +---- ++ +NOTE: You can also use `@within` in a binding form. See the <> section for +how to make the annotation object available in the advice body. + +* Any join point (method execution only in Spring AOP) where the executing method has an +`@Transactional` annotation: ++ +[literal,indent=0,subs="verbatim"] +---- + @annotation(org.springframework.transaction.annotation.Transactional) +---- ++ +NOTE: You can also use `@annotation` in a binding form. See the <> section +for how to make the annotation object available in the advice body. + +* Any join point (method execution only in Spring AOP) which takes a single parameter, +and where the runtime type of the argument passed has the `@Classified` annotation: ++ +[literal,indent=0,subs="verbatim"] +---- + @args(com.xyz.security.Classified) +---- ++ +NOTE: You can also use `@args` in a binding form. See the <> section +how to make the annotation object(s) available in the advice body. + +* Any join point (method execution only in Spring AOP) on a Spring bean named +`tradeService`: ++ +[literal,indent=0,subs="verbatim"] +---- + bean(tradeService) +---- + +* Any join point (method execution only in Spring AOP) on Spring beans having names that +match the wildcard expression `*Service`: ++ +[literal,indent=0,subs="verbatim"] +---- + bean(*Service) +---- + + +[[writing-good-pointcuts]] +== Writing Good Pointcuts + +During compilation, AspectJ processes pointcuts in order to optimize matching +performance. Examining code and determining if each join point matches (statically or +dynamically) a given pointcut is a costly process. (A dynamic match means the match +cannot be fully determined from static analysis and that a test is placed in the code to +determine if there is an actual match when the code is running). On first encountering a +pointcut declaration, AspectJ rewrites it into an optimal form for the matching +process. What does this mean? Basically, pointcuts are rewritten in DNF (Disjunctive +Normal Form) and the components of the pointcut are sorted such that those components +that are cheaper to evaluate are checked first. This means you do not have to worry +about understanding the performance of various pointcut designators and may supply them +in any order in a pointcut declaration. + +However, AspectJ can work only with what it is told. For optimal performance of +matching, you should think about what you are trying to achieve and narrow the search +space for matches as much as possible in the definition. The existing designators +naturally fall into one of three groups: kinded, scoping, and contextual: + +* Kinded designators select a particular kind of join point: +`execution`, `get`, `set`, `call`, and `handler`. +* Scoping designators select a group of join points of interest +(probably of many kinds): `within` and `withincode` +* Contextual designators match (and optionally bind) based on context: +`this`, `target`, and `@annotation` + +A well written pointcut should include at least the first two types (kinded and +scoping). You can include the contextual designators to match based on +join point context or bind that context for use in the advice. Supplying only a +kinded designator or only a contextual designator works but could affect weaving +performance (time and memory used), due to extra processing and analysis. Scoping +designators are very fast to match, and using them means AspectJ can very quickly +dismiss groups of join points that should not be further processed. A good +pointcut should always include one if possible. + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/choosing.adoc b/framework-docs/modules/ROOT/pages/core/aop/choosing.adoc new file mode 100644 index 000000000000..aed62baa1b1e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/choosing.adoc @@ -0,0 +1,107 @@ +[[aop-choosing]] += Choosing which AOP Declaration Style to Use + +Once you have decided that an aspect is the best approach for implementing a given +requirement, how do you decide between using Spring AOP or AspectJ and between the +Aspect language (code) style, the @AspectJ annotation style, or the Spring XML style? These +decisions are influenced by a number of factors including application requirements, +development tools, and team familiarity with AOP. + + + +[[aop-spring-or-aspectj]] +== Spring AOP or Full AspectJ? + +Use the simplest thing that can work. Spring AOP is simpler than using full AspectJ, as +there is no requirement to introduce the AspectJ compiler / weaver into your development +and build processes. If you only need to advise the execution of operations on Spring +beans, Spring AOP is the right choice. If you need to advise objects not managed by +the Spring container (such as domain objects, typically), you need to use +AspectJ. You also need to use AspectJ if you wish to advise join points other than +simple method executions (for example, field get or set join points and so on). + +When you use AspectJ, you have the choice of the AspectJ language syntax (also known as +the "code style") or the @AspectJ annotation style. If aspects play a large +role in your design, and you are able to use the https://www.eclipse.org/ajdt/[AspectJ +Development Tools (AJDT)] plugin for Eclipse, the AspectJ language syntax is the +preferred option. It is cleaner and simpler because the language was purposefully +designed for writing aspects. If you do not use Eclipse or have only a few aspects +that do not play a major role in your application, you may want to consider using +the @AspectJ style, sticking with regular Java compilation in your IDE, and adding +an aspect weaving phase to your build script. + + + +[[aop-ataspectj-or-xml]] +== @AspectJ or XML for Spring AOP? + +If you have chosen to use Spring AOP, you have a choice of @AspectJ or XML style. +There are various tradeoffs to consider. + +The XML style may be most familiar to existing Spring users, and it is backed by genuine +POJOs. When using AOP as a tool to configure enterprise services, XML can be a good +choice (a good test is whether you consider the pointcut expression to be a part of your +configuration that you might want to change independently). With the XML style, it is +arguably clearer from your configuration which aspects are present in the system. + +The XML style has two disadvantages. First, it does not fully encapsulate the +implementation of the requirement it addresses in a single place. The DRY principle says +that there should be a single, unambiguous, authoritative representation of any piece of +knowledge within a system. When using the XML style, the knowledge of how a requirement +is implemented is split across the declaration of the backing bean class and the XML in +the configuration file. When you use the @AspectJ style, this information is encapsulated +in a single module: the aspect. Secondly, the XML style is slightly more limited in what +it can express than the @AspectJ style: Only the "singleton" aspect instantiation model +is supported, and it is not possible to combine named pointcuts declared in XML. +For example, in the @AspectJ style you can write something like the following: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Pointcut("execution(* get*())") + public void propertyAccess() {} + + @Pointcut("execution(com.xyz.Account+ *(..))") + public void operationReturningAnAccount() {} + + @Pointcut("propertyAccess() && operationReturningAnAccount()") + public void accountPropertyAccess() {} +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Pointcut("execution(* get*())") + fun propertyAccess() {} + + @Pointcut("execution(com.xyz.Account+ *(..))") + fun operationReturningAnAccount() {} + + @Pointcut("propertyAccess() && operationReturningAnAccount()") + fun accountPropertyAccess() {} +---- + +In the XML style you can declare the first two pointcuts: + +[source,xml,indent=0,subs="verbatim"] +---- + + + +---- + +The downside of the XML approach is that you cannot define the +`accountPropertyAccess` pointcut by combining these definitions. + +The @AspectJ style supports additional instantiation models and richer pointcut +composition. It has the advantage of keeping the aspect as a modular unit. It also has +the advantage that the @AspectJ aspects can be understood (and thus consumed) both by +Spring AOP and by AspectJ. So, if you later decide you need the capabilities of AspectJ +to implement additional requirements, you can easily migrate to a classic AspectJ setup. +In general, the Spring team prefers the @AspectJ style for custom aspects beyond simple +configuration of enterprise services. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc new file mode 100644 index 000000000000..55ec9db45e31 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc @@ -0,0 +1,79 @@ +[[aop-introduction-defn]] += AOP Concepts + +Let us begin by defining some central AOP concepts and terminology. These terms are not +Spring-specific. Unfortunately, AOP terminology is not particularly intuitive. +However, it would be even more confusing if Spring used its own terminology. + +* Aspect: A modularization of a concern that cuts across multiple classes. + Transaction management is a good example of a crosscutting concern in enterprise Java + applications. In Spring AOP, aspects are implemented by using regular classes + (the <>) or regular classes annotated with the + `@Aspect` annotation (the <>). +* Join point: A point during the execution of a program, such as the execution of a + method or the handling of an exception. In Spring AOP, a join point always + represents a method execution. +* Advice: Action taken by an aspect at a particular join point. Different types of + advice include "around", "before", and "after" advice. (Advice types are discussed + later.) Many AOP frameworks, including Spring, model an advice as an interceptor and + maintain a chain of interceptors around the join point. +* Pointcut: A predicate that matches join points. Advice is associated with a + pointcut expression and runs at any join point matched by the pointcut (for example, + the execution of a method with a certain name). The concept of join points as matched + by pointcut expressions is central to AOP, and Spring uses the AspectJ pointcut + expression language by default. +* Introduction: Declaring additional methods or fields on behalf of a type. Spring + AOP lets you introduce new interfaces (and a corresponding implementation) to any + advised object. For example, you could use an introduction to make a bean implement an + `IsModified` interface, to simplify caching. (An introduction is known as an + inter-type declaration in the AspectJ community.) +* Target object: An object being advised by one or more aspects. Also referred to as + the "advised object". Since Spring AOP is implemented by using runtime proxies, this + object is always a proxied object. +* AOP proxy: An object created by the AOP framework in order to implement the aspect + contracts (advise method executions and so on). In the Spring Framework, an AOP proxy + is a JDK dynamic proxy or a CGLIB proxy. +* Weaving: linking aspects with other application types or objects to create an + advised object. This can be done at compile time (using the AspectJ compiler, for + example), load time, or at runtime. Spring AOP, like other pure Java AOP frameworks, + performs weaving at runtime. + +Spring AOP includes the following types of advice: + +* Before advice: Advice that runs before a join point but that does not have + the ability to prevent execution flow proceeding to the join point (unless it throws + an exception). +* After returning advice: Advice to be run after a join point completes + normally (for example, if a method returns without throwing an exception). +* After throwing advice: Advice to be run if a method exits by throwing an + exception. +* After (finally) advice: Advice to be run regardless of the means by which a + join point exits (normal or exceptional return). +* Around advice: Advice that surrounds a join point such as a method invocation. + This is the most powerful kind of advice. Around advice can perform custom behavior + before and after the method invocation. It is also responsible for choosing whether to + proceed to the join point or to shortcut the advised method execution by returning its + own return value or throwing an exception. + +Around advice is the most general kind of advice. Since Spring AOP, like AspectJ, +provides a full range of advice types, we recommend that you use the least powerful +advice type that can implement the required behavior. For example, if you need only to +update a cache with the return value of a method, you are better off implementing an +after returning advice than an around advice, although an around advice can accomplish +the same thing. Using the most specific advice type provides a simpler programming model +with less potential for errors. For example, you do not need to invoke the `proceed()` +method on the `JoinPoint` used for around advice, and, hence, you cannot fail to invoke it. + +All advice parameters are statically typed so that you work with advice parameters of +the appropriate type (e.g. the type of the return value from a method execution) rather +than `Object` arrays. + +The concept of join points matched by pointcuts is the key to AOP, which distinguishes +it from older technologies offering only interception. Pointcuts enable advice to be +targeted independently of the object-oriented hierarchy. For example, you can apply an +around advice providing declarative transaction management to a set of methods that span +multiple objects (such as all business operations in the service layer). + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc new file mode 100644 index 000000000000..872673dbf4de --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc @@ -0,0 +1,21 @@ +[[aop-introduction-proxies]] += AOP Proxies + +Spring AOP defaults to using standard JDK dynamic proxies for AOP proxies. This +enables any interface (or set of interfaces) to be proxied. + +Spring AOP can also use CGLIB proxies. This is necessary to proxy classes rather than +interfaces. By default, CGLIB is used if a business object does not implement an +interface. As it is good practice to program to interfaces rather than classes, business +classes normally implement one or more business interfaces. It is possible to +<>, in those (hopefully rare) cases where you +need to advise a method that is not declared on an interface or where you need to +pass a proxied object to a method as a concrete type. + +It is important to grasp the fact that Spring AOP is proxy-based. See +<> for a thorough examination of exactly what this +implementation detail actually means. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc new file mode 100644 index 000000000000..48110b52cde9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc @@ -0,0 +1,61 @@ +[[aop-introduction-spring-defn]] += Spring AOP Capabilities and Goals + +Spring AOP is implemented in pure Java. There is no need for a special compilation +process. Spring AOP does not need to control the class loader hierarchy and is thus +suitable for use in a servlet container or application server. + +Spring AOP currently supports only method execution join points (advising the execution +of methods on Spring beans). Field interception is not implemented, although support for +field interception could be added without breaking the core Spring AOP APIs. If you need +to advise field access and update join points, consider a language such as AspectJ. + +Spring AOP's approach to AOP differs from that of most other AOP frameworks. The aim is +not to provide the most complete AOP implementation (although Spring AOP is quite +capable). Rather, the aim is to provide a close integration between AOP implementation and +Spring IoC, to help solve common problems in enterprise applications. + +Thus, for example, the Spring Framework's AOP functionality is normally used in +conjunction with the Spring IoC container. Aspects are configured by using normal bean +definition syntax (although this allows powerful "auto-proxying" capabilities). This is a +crucial difference from other AOP implementations. You cannot do some things +easily or efficiently with Spring AOP, such as advise very fine-grained objects (typically, +domain objects). AspectJ is the best choice in such cases. However, our +experience is that Spring AOP provides an excellent solution to most problems in +enterprise Java applications that are amenable to AOP. + +Spring AOP never strives to compete with AspectJ to provide a comprehensive AOP +solution. We believe that both proxy-based frameworks such as Spring AOP and full-blown +frameworks such as AspectJ are valuable and that they are complementary, rather than in +competition. Spring seamlessly integrates Spring AOP and IoC with AspectJ, to enable +all uses of AOP within a consistent Spring-based application +architecture. This integration does not affect the Spring AOP API or the AOP Alliance +API. Spring AOP remains backward-compatible. See <> +for a discussion of the Spring AOP APIs. + +[NOTE] +==== +One of the central tenets of the Spring Framework is that of non-invasiveness. This +is the idea that you should not be forced to introduce framework-specific classes and +interfaces into your business or domain model. However, in some places, the Spring Framework +does give you the option to introduce Spring Framework-specific dependencies into your +codebase. The rationale in giving you such options is because, in certain scenarios, it +might be just plain easier to read or code some specific piece of functionality in such +a way. However, the Spring Framework (almost) always offers you the choice: You have the +freedom to make an informed decision as to which option best suits your particular use +case or scenario. + +One such choice that is relevant to this chapter is that of which AOP framework (and +which AOP style) to choose. You have the choice of AspectJ, Spring AOP, or both. You +also have the choice of either the @AspectJ annotation-style approach or the Spring XML +configuration-style approach. The fact that this chapter chooses to introduce the +@AspectJ-style approach first should not be taken as an indication that the Spring team +favors the @AspectJ annotation-style approach over the Spring XML configuration-style. + +See <> for a more complete discussion of the advantages and disadvantages of +each style. +==== + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/mixing-styles.adoc b/framework-docs/modules/ROOT/pages/core/aop/mixing-styles.adoc new file mode 100644 index 000000000000..5b1bb3201882 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/mixing-styles.adoc @@ -0,0 +1,11 @@ +[[aop-mixing-styles]] += Mixing Aspect Types + +It is perfectly possible to mix @AspectJ style aspects by using the auto-proxying support, +schema-defined `` aspects, `` declared advisors, and even proxies +and interceptors in other styles in the same configuration. All of these are implemented +by using the same underlying support mechanism and can co-exist without any difficulty. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/proxying.adoc b/framework-docs/modules/ROOT/pages/core/aop/proxying.adoc new file mode 100644 index 000000000000..4ec0ae914520 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/proxying.adoc @@ -0,0 +1,251 @@ +[[aop-proxying]] += Proxying Mechanisms + +Spring AOP uses either JDK dynamic proxies or CGLIB to create the proxy for a given +target object. JDK dynamic proxies are built into the JDK, whereas CGLIB is a common +open-source class definition library (repackaged into `spring-core`). + +If the target object to be proxied implements at least one interface, a JDK dynamic +proxy is used. All of the interfaces implemented by the target type are proxied. +If the target object does not implement any interfaces, a CGLIB proxy is created. + +If you want to force the use of CGLIB proxying (for example, to proxy every method +defined for the target object, not only those implemented by its interfaces), +you can do so. However, you should consider the following issues: + +* With CGLIB, `final` methods cannot be advised, as they cannot be overridden in + runtime-generated subclasses. +* As of Spring 4.0, the constructor of your proxied object is NOT called twice anymore, + since the CGLIB proxy instance is created through Objenesis. Only if your JVM does + not allow for constructor bypassing, you might see double invocations and + corresponding debug log entries from Spring's AOP support. + +To force the use of CGLIB proxies, set the value of the `proxy-target-class` attribute +of the `` element to true, as follows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + +---- + +To force CGLIB proxying when you use the @AspectJ auto-proxy support, set the +`proxy-target-class` attribute of the `` element to `true`, +as follows: + +[source,xml,indent=0,subs="verbatim"] +---- + +---- + +[NOTE] +==== +Multiple `` sections are collapsed into a single unified auto-proxy creator +at runtime, which applies the _strongest_ proxy settings that any of the +`` sections (typically from different XML bean definition files) specified. +This also applies to the `` and `` +elements. + +To be clear, using `proxy-target-class="true"` on ``, +``, or `` elements forces the use of CGLIB +proxies _for all three of them_. +==== + + + +[[aop-understanding-aop-proxies]] +== Understanding AOP Proxies + +Spring AOP is proxy-based. It is vitally important that you grasp the semantics of +what that last statement actually means before you write your own aspects or use any of +the Spring AOP-based aspects supplied with the Spring Framework. + +Consider first the scenario where you have a plain-vanilla, un-proxied, +nothing-special-about-it, straight object reference, as the following +code snippet shows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public class SimplePojo implements Pojo { + + public void foo() { + // this next method invocation is a direct call on the 'this' reference + this.bar(); + } + + public void bar() { + // some logic... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + class SimplePojo : Pojo { + + fun foo() { + // this next method invocation is a direct call on the 'this' reference + this.bar() + } + + fun bar() { + // some logic... + } + } +---- + +If you invoke a method on an object reference, the method is invoked directly on +that object reference, as the following image and listing show: + +image::aop-proxy-plain-pojo-call.png[] + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public class Main { + + public static void main(String[] args) { + Pojo pojo = new SimplePojo(); + // this is a direct method call on the 'pojo' reference + pojo.foo(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + fun main() { + val pojo = SimplePojo() + // this is a direct method call on the 'pojo' reference + pojo.foo() + } +---- + +Things change slightly when the reference that client code has is a proxy. Consider the +following diagram and code snippet: + +image::aop-proxy-call.png[] + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public class Main { + + public static void main(String[] args) { + ProxyFactory factory = new ProxyFactory(new SimplePojo()); + factory.addInterface(Pojo.class); + factory.addAdvice(new RetryAdvice()); + + Pojo pojo = (Pojo) factory.getProxy(); + // this is a method call on the proxy! + pojo.foo(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- +fun main() { + val factory = ProxyFactory(SimplePojo()) + factory.addInterface(Pojo::class.java) + factory.addAdvice(RetryAdvice()) + + val pojo = factory.proxy as Pojo + // this is a method call on the proxy! + pojo.foo() +} +---- + +The key thing to understand here is that the client code inside the `main(..)` method +of the `Main` class has a reference to the proxy. This means that method calls on that +object reference are calls on the proxy. As a result, the proxy can delegate to all of +the interceptors (advice) that are relevant to that particular method call. However, +once the call has finally reached the target object (the `SimplePojo` reference in +this case), any method calls that it may make on itself, such as `this.bar()` or +`this.foo()`, are going to be invoked against the `this` reference, and not the proxy. +This has important implications. It means that self-invocation is not going to result +in the advice associated with a method invocation getting a chance to run. + +Okay, so what is to be done about this? The best approach (the term "best" is used +loosely here) is to refactor your code such that the self-invocation does not happen. +This does entail some work on your part, but it is the best, least-invasive approach. +The next approach is absolutely horrendous, and we hesitate to point it out, precisely +because it is so horrendous. You can (painful as it is to us) totally tie the logic +within your class to Spring AOP, as the following example shows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public class SimplePojo implements Pojo { + + public void foo() { + // this works, but... gah! + ((Pojo) AopContext.currentProxy()).bar(); + } + + public void bar() { + // some logic... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + class SimplePojo : Pojo { + + fun foo() { + // this works, but... gah! + (AopContext.currentProxy() as Pojo).bar() + } + + fun bar() { + // some logic... + } + } +---- + +This totally couples your code to Spring AOP, and it makes the class itself aware of +the fact that it is being used in an AOP context, which flies in the face of AOP. It +also requires some additional configuration when the proxy is being created, as the +following example shows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public class Main { + + public static void main(String[] args) { + ProxyFactory factory = new ProxyFactory(new SimplePojo()); + factory.addInterface(Pojo.class); + factory.addAdvice(new RetryAdvice()); + factory.setExposeProxy(true); + + Pojo pojo = (Pojo) factory.getProxy(); + // this is a method call on the proxy! + pojo.foo(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + fun main() { + val factory = ProxyFactory(SimplePojo()) + factory.addInterface(Pojo::class.java) + factory.addAdvice(RetryAdvice()) + factory.isExposeProxy = true + + val pojo = factory.proxy as Pojo + // this is a method call on the proxy! + pojo.foo() + } +---- + +Finally, it must be noted that AspectJ does not have this self-invocation issue because +it is not a proxy-based AOP framework. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/resources.adoc b/framework-docs/modules/ROOT/pages/core/aop/resources.adoc new file mode 100644 index 000000000000..8de6cc35808a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/resources.adoc @@ -0,0 +1,11 @@ +[[aop-resources]] += Further Resources + +More information on AspectJ can be found on the https://www.eclipse.org/aspectj[AspectJ website]. + +_Eclipse AspectJ_ by Adrian Colyer et. al. (Addison-Wesley, 2005) provides a +comprehensive introduction and reference for the AspectJ language. + +_AspectJ in Action_, Second Edition by Ramnivas Laddad (Manning, 2009) comes highly +recommended. The focus of the book is on AspectJ, but a lot of general AOP themes are +explored (in some depth). diff --git a/framework-docs/modules/ROOT/pages/core/aop/schema.adoc b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc new file mode 100644 index 000000000000..a0fe4a24746f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc @@ -0,0 +1,921 @@ +[[aop-schema]] += Schema-based AOP Support + +If you prefer an XML-based format, Spring also offers support for defining aspects +using the `aop` namespace tags. The exact same pointcut expressions and advice kinds +as when using the @AspectJ style are supported. Hence, in this section we focus on +that syntax and refer the reader to the discussion in the previous section +(<>) for an understanding of writing pointcut expressions and the binding +of advice parameters. + +To use the aop namespace tags described in this section, you need to import the +`spring-aop` schema, as described in <>. See <> +for how to import the tags in the `aop` namespace. + +Within your Spring configurations, all aspect and advisor elements must be placed within +an `` element (you can have more than one `` element in an +application context configuration). An `` element can contain pointcut, +advisor, and aspect elements (note that these must be declared in that order). + +WARNING: The `` style of configuration makes heavy use of Spring's +<> mechanism. This can cause issues (such as advice +not being woven) if you already use explicit auto-proxying through the use of +`BeanNameAutoProxyCreator` or something similar. The recommended usage pattern is to +use either only the `` style or only the `AutoProxyCreator` style and +never mix them. + + + +[[aop-schema-declaring-an-aspect]] +== Declaring an Aspect + +When you use the schema support, an aspect is a regular Java object defined as a bean in +your Spring application context. The state and behavior are captured in the fields and +methods of the object, and the pointcut and advice information are captured in the XML. + +You can declare an aspect by using the `` element, and reference the backing bean +by using the `ref` attribute, as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + ... + + + + + ... + +---- + +The bean that backs the aspect (`aBean` in this case) can of course be configured and +dependency injected just like any other Spring bean. + + + +[[aop-schema-pointcuts]] +== Declaring a Pointcut + +You can declare a _named pointcut_ inside an `` element, letting the pointcut +definition be shared across several aspects and advisors. + +A pointcut that represents the execution of any business service in the service layer can +be defined as follows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + +---- + +Note that the pointcut expression itself uses the same AspectJ pointcut expression +language as described in <>. If you use the schema based declaration +style, you can also refer to _named pointcuts_ defined in `@Aspect` types within the +pointcut expression. Thus, another way of defining the above pointcut would be as follows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + <1> + + +---- +<1> References the `businessService` named pointcut defined in <>. + +Declaring a pointcut _inside_ an aspect is very similar to declaring a top-level pointcut, +as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + ... + + + +---- + +In much the same way as an @AspectJ aspect, pointcuts declared by using the schema based +definition style can collect join point context. For example, the following pointcut +collects the `this` object as the join point context and passes it to the advice: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + ... + + + +---- + +The advice must be declared to receive the collected join point context by including +parameters of the matching names, as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public void monitor(Object service) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + fun monitor(service: Any) { + // ... + } +---- + +When combining pointcut sub-expressions, `+&&+` is awkward within an XML +document, so you can use the `and`, `or`, and `not` keywords in place of `+&&+`, +`||`, and `!`, respectively. For example, the previous pointcut can be better written as +follows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + ... + + + +---- + +Note that pointcuts defined in this way are referred to by their XML `id` and cannot be +used as named pointcuts to form composite pointcuts. The named pointcut support in the +schema-based definition style is thus more limited than that offered by the @AspectJ +style. + + + +[[aop-schema-advice]] +== Declaring Advice + +The schema-based AOP support uses the same five kinds of advice as the @AspectJ style, and they have +exactly the same semantics. + + +[[aop-schema-advice-before]] +=== Before Advice + +Before advice runs before a matched method execution. It is declared inside an +`` by using the `` element, as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + ... + + +---- + +In the example above, `dataAccessOperation` is the `id` of a _named pointcut_ defined at +the top (``) level (see <>). + +NOTE: As we noted in the discussion of the @AspectJ style, using _named pointcuts_ can +significantly improve the readability of your code. See <> for +details. + +To define the pointcut inline instead, replace the `pointcut-ref` attribute with a +`pointcut` attribute, as follows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + ... + + +---- + +The `method` attribute identifies a method (`doAccessCheck`) that provides the body of +the advice. This method must be defined for the bean referenced by the aspect element +that contains the advice. Before a data access operation is performed (a method execution +join point matched by the pointcut expression), the `doAccessCheck` method on the aspect +bean is invoked. + + +[[aop-schema-advice-after-returning]] +=== After Returning Advice + +After returning advice runs when a matched method execution completes normally. It is +declared inside an `` in the same way as before advice. The following example +shows how to declare it: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + ... + +---- + +As in the @AspectJ style, you can get the return value within the advice body. +To do so, use the `returning` attribute to specify the name of the parameter to which +the return value should be passed, as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + ... + +---- + +The `doAccessCheck` method must declare a parameter named `retVal`. The type of this +parameter constrains matching in the same way as described for `@AfterReturning`. For +example, you can declare the method signature as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public void doAccessCheck(Object retVal) {... +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + fun doAccessCheck(retVal: Any) {... +---- + + +[[aop-schema-advice-after-throwing]] +=== After Throwing Advice + +After throwing advice runs when a matched method execution exits by throwing an +exception. It is declared inside an `` by using the `after-throwing` element, +as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + ... + +---- + +As in the @AspectJ style, you can get the thrown exception within the advice body. +To do so, use the `throwing` attribute to specify the name of the parameter to +which the exception should be passed as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + ... + +---- + +The `doRecoveryActions` method must declare a parameter named `dataAccessEx`. +The type of this parameter constrains matching in the same way as described for +`@AfterThrowing`. For example, the method signature may be declared as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public void doRecoveryActions(DataAccessException dataAccessEx) {... +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + fun doRecoveryActions(dataAccessEx: DataAccessException) {... +---- + + +[[aop-schema-advice-after-finally]] +=== After (Finally) Advice + +After (finally) advice runs no matter how a matched method execution exits. +You can declare it by using the `after` element, as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + ... + +---- + + +[[aop-schema-advice-around]] +=== Around Advice + +The last kind of advice is _around_ advice. Around advice runs "around" a matched +method's execution. It has the opportunity to do work both before and after the method +runs and to determine when, how, and even if the method actually gets to run at all. +Around advice is often used if you need to share state before and after a method +execution in a thread-safe manner – for example, starting and stopping a timer. + +[TIP] +==== +Always use the least powerful form of advice that meets your requirements. + +For example, do not use _around_ advice if _before_ advice is sufficient for your needs. +==== + +You can declare around advice by using the `aop:around` element. The advice method should +declare `Object` as its return type, and the first parameter of the method must be of +type `ProceedingJoinPoint`. Within the body of the advice method, you must invoke +`proceed()` on the `ProceedingJoinPoint` in order for the underlying method to run. +Invoking `proceed()` without arguments will result in the caller's original arguments +being supplied to the underlying method when it is invoked. For advanced use cases, there +is an overloaded variant of the `proceed()` method which accepts an array of arguments +(`Object[]`). The values in the array will be used as the arguments to the underlying +method when it is invoked. See <> for notes on calling +`proceed` with an `Object[]`. + +The following example shows how to declare around advice in XML: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + ... + +---- + +The implementation of the `doBasicProfiling` advice can be exactly the same as in the +@AspectJ example (minus the annotation, of course), as the following example shows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public Object doBasicProfiling(ProceedingJoinPoint pjp) throws Throwable { + // start stopwatch + Object retVal = pjp.proceed(); + // stop stopwatch + return retVal; + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + fun doBasicProfiling(pjp: ProceedingJoinPoint): Any { + // start stopwatch + val retVal = pjp.proceed() + // stop stopwatch + return pjp.proceed() + } +---- + + +[[aop-schema-params]] +=== Advice Parameters + +The schema-based declaration style supports fully typed advice in the same way as +described for the @AspectJ support -- by matching pointcut parameters by name against +advice method parameters. See <> for details. If you wish +to explicitly specify argument names for the advice methods (not relying on the +detection strategies previously described), you can do so by using the `arg-names` +attribute of the advice element, which is treated in the same manner as the `argNames` +attribute in an advice annotation (as described in <>). +The following example shows how to specify an argument name in XML: + +[source,xml,indent=0,subs="verbatim"] +---- + + method="audit" + arg-names="auditable" /> +---- +<1> References the `publicMethod` named pointcut defined in <>. + +The `arg-names` attribute accepts a comma-delimited list of parameter names. + +The following slightly more involved example of the XSD-based approach shows +some around advice used in conjunction with a number of strongly typed parameters: + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] +.Java +---- + package com.xyz.service; + + public interface PersonService { + + Person getPerson(String personName, int age); + } + + public class DefaultPersonService implements PersonService { + + public Person getPerson(String name, int age) { + return new Person(name, age); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.xyz.service + + interface PersonService { + + fun getPerson(personName: String, age: Int): Person + } + + class DefaultPersonService : PersonService { + + fun getPerson(name: String, age: Int): Person { + return Person(name, age) + } + } +---- + +Next up is the aspect. Notice the fact that the `profile(..)` method accepts a number of +strongly-typed parameters, the first of which happens to be the join point used to +proceed with the method call. The presence of this parameter is an indication that the +`profile(..)` is to be used as `around` advice, as the following example shows: + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] +.Java +---- + package com.xyz; + + import org.aspectj.lang.ProceedingJoinPoint; + import org.springframework.util.StopWatch; + + public class SimpleProfiler { + + public Object profile(ProceedingJoinPoint call, String name, int age) throws Throwable { + StopWatch clock = new StopWatch("Profiling for '" + name + "' and '" + age + "'"); + try { + clock.start(call.toShortString()); + return call.proceed(); + } finally { + clock.stop(); + System.out.println(clock.prettyPrint()); + } + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.xyz + + import org.aspectj.lang.ProceedingJoinPoint + import org.springframework.util.StopWatch + + class SimpleProfiler { + + fun profile(call: ProceedingJoinPoint, name: String, age: Int): Any { + val clock = StopWatch("Profiling for '$name' and '$age'") + try { + clock.start(call.toShortString()) + return call.proceed() + } finally { + clock.stop() + println(clock.prettyPrint()) + } + } + } +---- + +Finally, the following example XML configuration effects the execution of the +preceding advice for a particular join point: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + + + + + + + + + + + +---- + +Consider the following driver script: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public class Boot { + + public static void main(String[] args) { + ApplicationContext ctx = new ClassPathXmlApplicationContext("beans.xml"); + PersonService person = ctx.getBean(PersonService.class); + person.getPerson("Pengo", 12); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + fun main() { + val ctx = ClassPathXmlApplicationContext("beans.xml") + val person = ctx.getBean(PersonService.class) + person.getPerson("Pengo", 12) + } +---- + +With such a `Boot` class, we would get output similar to the following on standard output: + +[literal,subs="verbatim"] +---- +StopWatch 'Profiling for 'Pengo' and '12': running time (millis) = 0 +----------------------------------------- +ms % Task name +----------------------------------------- +00000 ? execution(getFoo) +---- + + +[[aop-ordering]] +=== Advice Ordering + +When multiple pieces of advice need to run at the same join point (executing method) +the ordering rules are as described in <>. The precedence +between aspects is determined via the `order` attribute in the `` element or +by either adding the `@Order` annotation to the bean that backs the aspect or by having +the bean implement the `Ordered` interface. + +[NOTE] +==== +In contrast to the precedence rules for advice methods defined in the same `@Aspect` +class, when two pieces of advice defined in the same `` element both need to +run at the same join point, the precedence is determined by the order in which the advice +elements are declared within the enclosing `` element, from highest to lowest +precedence. + +For example, given an `around` advice and a `before` advice defined in the same +`` element that apply to the same join point, to ensure that the `around` +advice has higher precedence than the `before` advice, the `` element must be +declared before the `` element. + +As a general rule of thumb, if you find that you have multiple pieces of advice defined +in the same `` element that apply to the same join point, consider collapsing +such advice methods into one advice method per join point in each `` element +or refactor the pieces of advice into separate `` elements that you can order +at the aspect level. +==== + + + +[[aop-schema-introductions]] +== Introductions + +Introductions (known as inter-type declarations in AspectJ) let an aspect declare +that advised objects implement a given interface and provide an implementation of +that interface on behalf of those objects. + +You can make an introduction by using the `aop:declare-parents` element inside an `aop:aspect`. +You can use the `aop:declare-parents` element to declare that matching types have a new parent (hence the name). +For example, given an interface named `UsageTracked` and an implementation of that interface named +`DefaultUsageTracked`, the following aspect declares that all implementors of service +interfaces also implement the `UsageTracked` interface. (In order to expose statistics +through JMX for example.) + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + +---- + +The class that backs the `usageTracking` bean would then contain the following method: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public void recordUsage(UsageTracked usageTracked) { + usageTracked.incrementUseCount(); + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + fun recordUsage(usageTracked: UsageTracked) { + usageTracked.incrementUseCount() + } +---- + +The interface to be implemented is determined by the `implement-interface` attribute. The +value of the `types-matching` attribute is an AspectJ type pattern. Any bean of a +matching type implements the `UsageTracked` interface. Note that, in the before +advice of the preceding example, service beans can be directly used as implementations of +the `UsageTracked` interface. To access a bean programmatically, you could write the +following: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + UsageTracked usageTracked = context.getBean("myService", UsageTracked.class); +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + val usageTracked = context.getBean("myService", UsageTracked.class) +---- + + + +[[aop-schema-instantiation-models]] +== Aspect Instantiation Models + +The only supported instantiation model for schema-defined aspects is the singleton +model. Other instantiation models may be supported in future releases. + + + +[[aop-schema-advisors]] +== Advisors + +The concept of "advisors" comes from the AOP support defined in Spring +and does not have a direct equivalent in AspectJ. An advisor is like a small +self-contained aspect that has a single piece of advice. The advice itself is +represented by a bean and must implement one of the advice interfaces described in +<>. Advisors can take advantage of AspectJ pointcut expressions. + +Spring supports the advisor concept with the `` element. You most +commonly see it used in conjunction with transactional advice, which also has its own +namespace support in Spring. The following example shows an advisor: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + + + + + +---- + +As well as the `pointcut-ref` attribute used in the preceding example, you can also use the +`pointcut` attribute to define a pointcut expression inline. + +To define the precedence of an advisor so that the advice can participate in ordering, +use the `order` attribute to define the `Ordered` value of the advisor. + + + +[[aop-schema-example]] +== An AOP Schema Example + +This section shows how the concurrent locking failure retry example from +<> looks when rewritten with the schema support. + +The execution of business services can sometimes fail due to concurrency issues (for +example, a deadlock loser). If the operation is retried, it is likely to succeed +on the next try. For business services where it is appropriate to retry in such +conditions (idempotent operations that do not need to go back to the user for conflict +resolution), we want to transparently retry the operation to avoid the client seeing a +`PessimisticLockingFailureException`. This is a requirement that clearly cuts across +multiple services in the service layer and, hence, is ideal for implementing through an +aspect. + +Because we want to retry the operation, we need to use around advice so that we can +call `proceed` multiple times. The following listing shows the basic aspect implementation +(which is a regular Java class that uses the schema support): + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + public class ConcurrentOperationExecutor implements Ordered { + + private static final int DEFAULT_MAX_RETRIES = 2; + + private int maxRetries = DEFAULT_MAX_RETRIES; + private int order = 1; + + public void setMaxRetries(int maxRetries) { + this.maxRetries = maxRetries; + } + + public int getOrder() { + return this.order; + } + + public void setOrder(int order) { + this.order = order; + } + + public Object doConcurrentOperation(ProceedingJoinPoint pjp) throws Throwable { + int numAttempts = 0; + PessimisticLockingFailureException lockFailureException; + do { + numAttempts++; + try { + return pjp.proceed(); + } + catch(PessimisticLockingFailureException ex) { + lockFailureException = ex; + } + } while(numAttempts <= this.maxRetries); + throw lockFailureException; + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + class ConcurrentOperationExecutor : Ordered { + + private val DEFAULT_MAX_RETRIES = 2 + + private var maxRetries = DEFAULT_MAX_RETRIES + private var order = 1 + + fun setMaxRetries(maxRetries: Int) { + this.maxRetries = maxRetries + } + + override fun getOrder(): Int { + return this.order + } + + fun setOrder(order: Int) { + this.order = order + } + + fun doConcurrentOperation(pjp: ProceedingJoinPoint): Any { + var numAttempts = 0 + var lockFailureException: PessimisticLockingFailureException + do { + numAttempts++ + try { + return pjp.proceed() + } catch (ex: PessimisticLockingFailureException) { + lockFailureException = ex + } + + } while (numAttempts <= this.maxRetries) + throw lockFailureException + } + } +---- + +Note that the aspect implements the `Ordered` interface so that we can set the precedence of +the aspect higher than the transaction advice (we want a fresh transaction each time we +retry). The `maxRetries` and `order` properties are both configured by Spring. The +main action happens in the `doConcurrentOperation` around advice method. We try to +proceed. If we fail with a `PessimisticLockingFailureException`, we try again, +unless we have exhausted all of our retry attempts. + +NOTE: This class is identical to the one used in the @AspectJ example, but with the +annotations removed. + +The corresponding Spring configuration is as follows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + + + + + + + + +---- + +Notice that, for the time being, we assume that all business services are idempotent. If +this is not the case, we can refine the aspect so that it retries only genuinely +idempotent operations, by introducing an `Idempotent` annotation and using the annotation +to annotate the implementation of service operations, as the following example shows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Retention(RetentionPolicy.RUNTIME) + // marker annotation + public @interface Idempotent { + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Retention(AnnotationRetention.RUNTIME) + // marker annotation + annotation class Idempotent +---- + +The +change to the aspect to retry only idempotent operations involves refining the +pointcut expression so that only `@Idempotent` operations match, as follows: + +[source,xml,indent=0,subs="verbatim"] +---- + +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc new file mode 100644 index 000000000000..d0c65500d049 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc @@ -0,0 +1,941 @@ +[[aop-using-aspectj]] += Using AspectJ with Spring Applications + +Everything we have covered so far in this chapter is pure Spring AOP. In this section, +we look at how you can use the AspectJ compiler or weaver instead of or in +addition to Spring AOP if your needs go beyond the facilities offered by Spring AOP +alone. + +Spring ships with a small AspectJ aspect library, which is available stand-alone in your +distribution as `spring-aspects.jar`. You need to add this to your classpath in order +to use the aspects in it. <> and <> discuss the +content of this library and how you can use it. <> discusses how to +dependency inject AspectJ aspects that are woven using the AspectJ compiler. Finally, +<> provides an introduction to load-time weaving for Spring applications +that use AspectJ. + + + +[[aop-atconfigurable]] +== Using AspectJ to Dependency Inject Domain Objects with Spring + +The Spring container instantiates and configures beans defined in your application +context. It is also possible to ask a bean factory to configure a pre-existing +object, given the name of a bean definition that contains the configuration to be applied. +`spring-aspects.jar` contains an annotation-driven aspect that exploits this +capability to allow dependency injection of any object. The support is intended to +be used for objects created outside of the control of any container. Domain objects +often fall into this category because they are often created programmatically with the +`new` operator or by an ORM tool as a result of a database query. + +The `@Configurable` annotation marks a class as being eligible for Spring-driven +configuration. In the simplest case, you can use purely it as a marker annotation, as the +following example shows: + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] +.Java +---- + package com.xyz.domain; + + import org.springframework.beans.factory.annotation.Configurable; + + @Configurable + public class Account { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.xyz.domain + + import org.springframework.beans.factory.annotation.Configurable + + @Configurable + class Account { + // ... + } +---- + +When used as a marker interface in this way, Spring configures new instances of the +annotated type (`Account`, in this case) by using a bean definition (typically +prototype-scoped) with the same name as the fully-qualified type name +(`com.xyz.domain.Account`). Since the default name for a bean is the +fully-qualified name of its type, a convenient way to declare the prototype definition +is to omit the `id` attribute, as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + +---- + +If you want to explicitly specify the name of the prototype bean definition to use, you +can do so directly in the annotation, as the following example shows: + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] +.Java +---- + package com.xyz.domain; + + import org.springframework.beans.factory.annotation.Configurable; + + @Configurable("account") + public class Account { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.xyz.domain + + import org.springframework.beans.factory.annotation.Configurable + + @Configurable("account") + class Account { + // ... + } +---- + +Spring now looks for a bean definition named `account` and uses that as the +definition to configure new `Account` instances. + +You can also use autowiring to avoid having to specify a dedicated bean definition at +all. To have Spring apply autowiring, use the `autowire` property of the `@Configurable` +annotation. You can specify either `@Configurable(autowire=Autowire.BY_TYPE)` or +`@Configurable(autowire=Autowire.BY_NAME)` for autowiring by type or by name, +respectively. As an alternative, it is preferable to specify explicit, annotation-driven +dependency injection for your `@Configurable` beans through `@Autowired` or `@Inject` +at the field or method level (see <> for further details). + +Finally, you can enable Spring dependency checking for the object references in the newly +created and configured object by using the `dependencyCheck` attribute (for example, +`@Configurable(autowire=Autowire.BY_NAME,dependencyCheck=true)`). If this attribute is +set to `true`, Spring validates after configuration that all properties (which +are not primitives or collections) have been set. + +Note that using the annotation on its own does nothing. It is the +`AnnotationBeanConfigurerAspect` in `spring-aspects.jar` that acts on the presence of +the annotation. In essence, the aspect says, "after returning from the initialization of +a new object of a type annotated with `@Configurable`, configure the newly created object +using Spring in accordance with the properties of the annotation". In this context, +"initialization" refers to newly instantiated objects (for example, objects instantiated +with the `new` operator) as well as to `Serializable` objects that are undergoing +deserialization (for example, through +https://docs.oracle.com/javase/8/docs/api/java/io/Serializable.html[readResolve()]). + +[NOTE] +===== +One of the key phrases in the above paragraph is "in essence". For most cases, the +exact semantics of "after returning from the initialization of a new object" are +fine. In this context, "after initialization" means that the dependencies are +injected after the object has been constructed. This means that the dependencies +are not available for use in the constructor bodies of the class. If you want the +dependencies to be injected before the constructor bodies run and thus be +available for use in the body of the constructors, you need to define this on the +`@Configurable` declaration, as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Configurable(preConstruction = true) +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configurable(preConstruction = true) +---- + +You can find more information about the language semantics of the various pointcut +types in AspectJ +https://www.eclipse.org/aspectj/doc/next/progguide/semantics-joinPoints.html[in this +appendix] of the https://www.eclipse.org/aspectj/doc/next/progguide/index.html[AspectJ +Programming Guide]. +===== + +For this to work, the annotated types must be woven with the AspectJ weaver. You can +either use a build-time Ant or Maven task to do this (see, for example, the +https://www.eclipse.org/aspectj/doc/released/devguide/antTasks.html[AspectJ Development +Environment Guide]) or load-time weaving (see <>). The +`AnnotationBeanConfigurerAspect` itself needs to be configured by Spring (in order to obtain +a reference to the bean factory that is to be used to configure new objects). If you +use Java-based configuration, you can add `@EnableSpringConfigured` to any +`@Configuration` class, as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Configuration + @EnableSpringConfigured + public class AppConfig { + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configuration + @EnableSpringConfigured + class AppConfig { + } +---- + +If you prefer XML based configuration, the Spring +<> +defines a convenient `context:spring-configured` element, which you can use as follows: + +[source,xml,indent=0,subs="verbatim"] +---- + +---- + +Instances of `@Configurable` objects created before the aspect has been configured +result in a message being issued to the debug log and no configuration of the +object taking place. An example might be a bean in the Spring configuration that creates +domain objects when it is initialized by Spring. In this case, you can use the +`depends-on` bean attribute to manually specify that the bean depends on the +configuration aspect. The following example shows how to use the `depends-on` attribute: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + +---- + +NOTE: Do not activate `@Configurable` processing through the bean configurer aspect unless you +really mean to rely on its semantics at runtime. In particular, make sure that you do +not use `@Configurable` on bean classes that are registered as regular Spring beans +with the container. Doing so results in double initialization, once through the +container and once through the aspect. + + +[[aop-configurable-testing]] +=== Unit Testing `@Configurable` Objects + +One of the goals of the `@Configurable` support is to enable independent unit testing +of domain objects without the difficulties associated with hard-coded lookups. +If `@Configurable` types have not been woven by AspectJ, the annotation has no affect +during unit testing. You can set mock or stub property references in the object under +test and proceed as normal. If `@Configurable` types have been woven by AspectJ, +you can still unit test outside of the container as normal, but you see a warning +message each time that you construct a `@Configurable` object indicating that it has +not been configured by Spring. + + +[[aop-configurable-container]] +=== Working with Multiple Application Contexts + +The `AnnotationBeanConfigurerAspect` that is used to implement the `@Configurable` support +is an AspectJ singleton aspect. The scope of a singleton aspect is the same as the scope +of `static` members: There is one aspect instance per `ClassLoader` that defines the type. +This means that, if you define multiple application contexts within the same `ClassLoader` +hierarchy, you need to consider where to define the `@EnableSpringConfigured` bean and +where to place `spring-aspects.jar` on the classpath. + +Consider a typical Spring web application configuration that has a shared parent application +context that defines common business services, everything needed to support those services, +and one child application context for each servlet (which contains definitions particular +to that servlet). All of these contexts co-exist within the same `ClassLoader` hierarchy, +and so the `AnnotationBeanConfigurerAspect` can hold a reference to only one of them. +In this case, we recommend defining the `@EnableSpringConfigured` bean in the shared +(parent) application context. This defines the services that you are likely to want to +inject into domain objects. A consequence is that you cannot configure domain objects +with references to beans defined in the child (servlet-specific) contexts by using the +@Configurable mechanism (which is probably not something you want to do anyway). + +When deploying multiple web applications within the same container, ensure that each +web application loads the types in `spring-aspects.jar` by using its own `ClassLoader` +(for example, by placing `spring-aspects.jar` in `WEB-INF/lib`). If `spring-aspects.jar` +is added only to the container-wide classpath (and hence loaded by the shared parent +`ClassLoader`), all web applications share the same aspect instance (which is probably +not what you want). + + + +[[aop-ajlib-other]] +== Other Spring aspects for AspectJ + +In addition to the `@Configurable` aspect, `spring-aspects.jar` contains an AspectJ +aspect that you can use to drive Spring's transaction management for types and methods +annotated with the `@Transactional` annotation. This is primarily intended for users who +want to use the Spring Framework's transaction support outside of the Spring container. + +The aspect that interprets `@Transactional` annotations is the +`AnnotationTransactionAspect`. When you use this aspect, you must annotate the +implementation class (or methods within that class or both), not the interface (if +any) that the class implements. AspectJ follows Java's rule that annotations on +interfaces are not inherited. + +A `@Transactional` annotation on a class specifies the default transaction semantics for +the execution of any public operation in the class. + +A `@Transactional` annotation on a method within the class overrides the default +transaction semantics given by the class annotation (if present). Methods of any +visibility may be annotated, including private methods. Annotating non-public methods +directly is the only way to get transaction demarcation for the execution of such methods. + +TIP: Since Spring Framework 4.2, `spring-aspects` provides a similar aspect that offers the +exact same features for the standard `jakarta.transaction.Transactional` annotation. Check +`JtaAnnotationTransactionAspect` for more details. + +For AspectJ programmers who want to use the Spring configuration and transaction +management support but do not want to (or cannot) use annotations, `spring-aspects.jar` +also contains `abstract` aspects you can extend to provide your own pointcut +definitions. See the sources for the `AbstractBeanConfigurerAspect` and +`AbstractTransactionAspect` aspects for more information. As an example, the following +excerpt shows how you could write an aspect to configure all instances of objects +defined in the domain model by using prototype bean definitions that match the +fully qualified class names: + +[source,java,indent=0,subs="verbatim"] +---- + public aspect DomainObjectConfiguration extends AbstractBeanConfigurerAspect { + + public DomainObjectConfiguration() { + setBeanWiringInfoResolver(new ClassNameBeanWiringInfoResolver()); + } + + // the creation of a new bean (any object in the domain model) + protected pointcut beanCreation(Object beanInstance) : + initialization(new(..)) && + CommonPointcuts.inDomainModel() && + this(beanInstance); + } +---- + + + +[[aop-aj-configure]] +== Configuring AspectJ Aspects by Using Spring IoC + +When you use AspectJ aspects with Spring applications, it is natural to both want and +expect to be able to configure such aspects with Spring. The AspectJ runtime itself is +responsible for aspect creation, and the means of configuring the AspectJ-created +aspects through Spring depends on the AspectJ instantiation model (the `per-xxx` clause) +used by the aspect. + +The majority of AspectJ aspects are singleton aspects. Configuration of these +aspects is easy. You can create a bean definition that references the aspect type as +normal and include the `factory-method="aspectOf"` bean attribute. This ensures that +Spring obtains the aspect instance by asking AspectJ for it rather than trying to create +an instance itself. The following example shows how to use the `factory-method="aspectOf"` attribute: + +[source,xml,indent=0,subs="verbatim"] +---- + <1> + + + +---- +<1> Note the `factory-method="aspectOf"` attribute + + +Non-singleton aspects are harder to configure. However, it is possible to do so by +creating prototype bean definitions and using the `@Configurable` support from +`spring-aspects.jar` to configure the aspect instances once they have bean created by +the AspectJ runtime. + +If you have some @AspectJ aspects that you want to weave with AspectJ (for example, +using load-time weaving for domain model types) and other @AspectJ aspects that you want +to use with Spring AOP, and these aspects are all configured in Spring, you +need to tell the Spring AOP @AspectJ auto-proxying support which exact subset of the +@AspectJ aspects defined in the configuration should be used for auto-proxying. You can +do this by using one or more `` elements inside the `` +declaration. Each `` element specifies a name pattern, and only beans with +names matched by at least one of the patterns are used for Spring AOP auto-proxy +configuration. The following example shows how to use `` elements: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + +---- + +NOTE: Do not be misled by the name of the `` element. Using it +results in the creation of Spring AOP proxies. The @AspectJ style of aspect +declaration is being used here, but the AspectJ runtime is not involved. + + + +[[aop-aj-ltw]] +== Load-time Weaving with AspectJ in the Spring Framework + +Load-time weaving (LTW) refers to the process of weaving AspectJ aspects into an +application's class files as they are being loaded into the Java virtual machine (JVM). +The focus of this section is on configuring and using LTW in the specific context of the +Spring Framework. This section is not a general introduction to LTW. For full details on +the specifics of LTW and configuring LTW with only AspectJ (with Spring not being +involved at all), see the +https://www.eclipse.org/aspectj/doc/released/devguide/ltw.html[LTW section of the AspectJ +Development Environment Guide]. + +The value that the Spring Framework brings to AspectJ LTW is in enabling much +finer-grained control over the weaving process. 'Vanilla' AspectJ LTW is effected by using +a Java (5+) agent, which is switched on by specifying a VM argument when starting up a +JVM. It is, thus, a JVM-wide setting, which may be fine in some situations but is often a +little too coarse. Spring-enabled LTW lets you switch on LTW on a +per-`ClassLoader` basis, which is more fine-grained and which can make more +sense in a 'single-JVM-multiple-application' environment (such as is found in a typical +application server environment). + +Further, <>, this support enables +load-time weaving without making any modifications to the application server's launch +script that is needed to add `-javaagent:path/to/aspectjweaver.jar` or (as we describe +later in this section) `-javaagent:path/to/spring-instrument.jar`. Developers configure +the application context to enable load-time weaving instead of relying on administrators +who typically are in charge of the deployment configuration, such as the launch script. + +Now that the sales pitch is over, let us first walk through a quick example of AspectJ +LTW that uses Spring, followed by detailed specifics about elements introduced in the +example. For a complete example, see the +https://github.com/spring-projects/spring-petclinic[Petclinic sample application]. + + +[[aop-aj-ltw-first-example]] +=== A First Example + +Assume that you are an application developer who has been tasked with diagnosing +the cause of some performance problems in a system. Rather than break out a +profiling tool, we are going to switch on a simple profiling aspect that lets us +quickly get some performance metrics. We can then apply a finer-grained profiling +tool to that specific area immediately afterwards. + +NOTE: The example presented here uses XML configuration. You can also configure and +use @AspectJ with <>. Specifically, you can use the +`@EnableLoadTimeWeaving` annotation as an alternative to `` +(see <> for details). + +The following example shows the profiling aspect, which is not fancy. +It is a time-based profiler that uses the @AspectJ-style of aspect declaration: + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] +.Java +---- + package com.xyz; + + import org.aspectj.lang.ProceedingJoinPoint; + import org.aspectj.lang.annotation.Aspect; + import org.aspectj.lang.annotation.Around; + import org.aspectj.lang.annotation.Pointcut; + import org.springframework.util.StopWatch; + import org.springframework.core.annotation.Order; + + @Aspect + public class ProfilingAspect { + + @Around("methodsToBeProfiled()") + public Object profile(ProceedingJoinPoint pjp) throws Throwable { + StopWatch sw = new StopWatch(getClass().getSimpleName()); + try { + sw.start(pjp.getSignature().getName()); + return pjp.proceed(); + } finally { + sw.stop(); + System.out.println(sw.prettyPrint()); + } + } + + @Pointcut("execution(public * com.xyz..*.*(..))") + public void methodsToBeProfiled(){} + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.xyz + + import org.aspectj.lang.ProceedingJoinPoint + import org.aspectj.lang.annotation.Aspect + import org.aspectj.lang.annotation.Around + import org.aspectj.lang.annotation.Pointcut + import org.springframework.util.StopWatch + import org.springframework.core.annotation.Order + + @Aspect + class ProfilingAspect { + + @Around("methodsToBeProfiled()") + fun profile(pjp: ProceedingJoinPoint): Any { + val sw = StopWatch(javaClass.simpleName) + try { + sw.start(pjp.getSignature().getName()) + return pjp.proceed() + } finally { + sw.stop() + println(sw.prettyPrint()) + } + } + + @Pointcut("execution(public * com.xyz..*.*(..))") + fun methodsToBeProfiled() { + } + } +---- + +We also need to create an `META-INF/aop.xml` file, to inform the AspectJ weaver that +we want to weave our `ProfilingAspect` into our classes. This file convention, namely +the presence of a file (or files) on the Java classpath called `META-INF/aop.xml` is +standard AspectJ. The following example shows the `aop.xml` file: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + + + + + + +---- + +Now we can move on to the Spring-specific portion of the configuration. We need +to configure a `LoadTimeWeaver` (explained later). This load-time weaver is the +essential component responsible for weaving the aspect configuration in one or +more `META-INF/aop.xml` files into the classes in your application. The good +thing is that it does not require a lot of configuration (there are some more +options that you can specify, but these are detailed later), as can be seen in +the following example: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + +---- + +Now that all the required artifacts (the aspect, the `META-INF/aop.xml` +file, and the Spring configuration) are in place, we can create the following +driver class with a `main(..)` method to demonstrate the LTW in action: + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] +.Java +---- + package com.xyz; + + // imports + + public class Main { + + public static void main(String[] args) { + ApplicationContext ctx = new ClassPathXmlApplicationContext("beans.xml"); + + EntitlementCalculationService service = + ctx.getBean(EntitlementCalculationService.class); + + // the profiling aspect is 'woven' around this method execution + service.calculateEntitlement(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.xyz + + // imports + + fun main() { + val ctx = ClassPathXmlApplicationContext("beans.xml") + + val service = ctx.getBean(EntitlementCalculationService.class) + + // the profiling aspect is 'woven' around this method execution + service.calculateEntitlement() + } +---- + +We have one last thing to do. The introduction to this section did say that one could +switch on LTW selectively on a per-`ClassLoader` basis with Spring, and this is true. +However, for this example, we use a Java agent (supplied with Spring) to switch on LTW. +We use the following command to run the `Main` class shown earlier: + +[literal,subs="verbatim"] +---- +java -javaagent:C:/projects/xyz/lib/spring-instrument.jar com.xyz.Main +---- + +The `-javaagent` is a flag for specifying and enabling +https://docs.oracle.com/javase/8/docs/api/java/lang/instrument/package-summary.html[agents +to instrument programs that run on the JVM]. The Spring Framework ships with such an +agent, the `InstrumentationSavingAgent`, which is packaged in the +`spring-instrument.jar` that was supplied as the value of the `-javaagent` argument in +the preceding example. + +The output from the execution of the `Main` program looks something like the next example. +(I have introduced a `Thread.sleep(..)` statement into the `calculateEntitlement()` +implementation so that the profiler actually captures something other than 0 +milliseconds (the `01234` milliseconds is not an overhead introduced by the AOP). +The following listing shows the output we got when we ran our profiler: + +[literal,subs="verbatim"] +---- +Calculating entitlement + +StopWatch 'ProfilingAspect': running time (millis) = 1234 +------ ----- ---------------------------- +ms % Task name +------ ----- ---------------------------- +01234 100% calculateEntitlement +---- + +Since this LTW is effected by using full-blown AspectJ, we are not limited only to advising +Spring beans. The following slight variation on the `Main` program yields the same +result: + +[source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] +.Java +---- + package com.xyz; + + // imports + + public class Main { + + public static void main(String[] args) { + new ClassPathXmlApplicationContext("beans.xml"); + + EntitlementCalculationService service = + new StubEntitlementCalculationService(); + + // the profiling aspect will be 'woven' around this method execution + service.calculateEntitlement(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.xyz + + // imports + + fun main(args: Array) { + ClassPathXmlApplicationContext("beans.xml") + + val service = StubEntitlementCalculationService() + + // the profiling aspect will be 'woven' around this method execution + service.calculateEntitlement() + } +---- + +Notice how, in the preceding program, we bootstrap the Spring container and +then create a new instance of the `StubEntitlementCalculationService` totally outside +the context of Spring. The profiling advice still gets woven in. + +Admittedly, the example is simplistic. However, the basics of the LTW support in Spring +have all been introduced in the earlier example, and the rest of this section explains +the "why" behind each bit of configuration and usage in detail. + +NOTE: The `ProfilingAspect` used in this example may be basic, but it is quite useful. It is a +nice example of a development-time aspect that developers can use during development +and then easily exclude from builds of the application being deployed +into UAT or production. + + +[[aop-aj-ltw-the-aspects]] +=== Aspects + +The aspects that you use in LTW have to be AspectJ aspects. You can write them in +either the AspectJ language itself, or you can write your aspects in the @AspectJ-style. +Your aspects are then both valid AspectJ and Spring AOP aspects. +Furthermore, the compiled aspect classes need to be available on the classpath. + + +[[aop-aj-ltw-aop_dot_xml]] +=== 'META-INF/aop.xml' + +The AspectJ LTW infrastructure is configured by using one or more `META-INF/aop.xml` +files that are on the Java classpath (either directly or, more typically, in jar files). + +The structure and contents of this file is detailed in the LTW part of the +https://www.eclipse.org/aspectj/doc/released/devguide/ltw-configuration.html[AspectJ reference +documentation]. Because the `aop.xml` file is 100% AspectJ, we do not describe it further here. + + +[[aop-aj-ltw-libraries]] +=== Required libraries (JARS) + +At minimum, you need the following libraries to use the Spring Framework's support +for AspectJ LTW: + +* `spring-aop.jar` +* `aspectjweaver.jar` + +If you use the <>, you also need: + +* `spring-instrument.jar` + + +[[aop-aj-ltw-spring]] +=== Spring Configuration + +The key component in Spring's LTW support is the `LoadTimeWeaver` interface (in the +`org.springframework.instrument.classloading` package), and the numerous implementations +of it that ship with the Spring distribution. A `LoadTimeWeaver` is responsible for +adding one or more `java.lang.instrument.ClassFileTransformers` to a `ClassLoader` at +runtime, which opens the door to all manner of interesting applications, one of which +happens to be the LTW of aspects. + +TIP: If you are unfamiliar with the idea of runtime class file transformation, see the +javadoc API documentation for the `java.lang.instrument` package before continuing. +While that documentation is not comprehensive, at least you can see the key interfaces +and classes (for reference as you read through this section). + +Configuring a `LoadTimeWeaver` for a particular `ApplicationContext` can be as easy as +adding one line. (Note that you almost certainly need to use an +`ApplicationContext` as your Spring container -- typically, a `BeanFactory` is not +enough because the LTW support uses `BeanFactoryPostProcessors`.) + +To enable the Spring Framework's LTW support, you need to configure a `LoadTimeWeaver`, +which typically is done by using the `@EnableLoadTimeWeaving` annotation, as follows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Configuration + @EnableLoadTimeWeaving + public class AppConfig { + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configuration + @EnableLoadTimeWeaving + class AppConfig { + } +---- + +Alternatively, if you prefer XML-based configuration, use the +`` element. Note that the element is defined in the +`context` namespace. The following example shows how to use ``: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + +---- + +The preceding configuration automatically defines and registers a number of LTW-specific +infrastructure beans, such as a `LoadTimeWeaver` and an `AspectJWeavingEnabler`, for you. +The default `LoadTimeWeaver` is the `DefaultContextLoadTimeWeaver` class, which attempts +to decorate an automatically detected `LoadTimeWeaver`. The exact type of `LoadTimeWeaver` +that is "automatically detected" is dependent upon your runtime environment. +The following table summarizes various `LoadTimeWeaver` implementations: + +[[aop-aj-ltw-spring-env-impls]] +.DefaultContextLoadTimeWeaver LoadTimeWeavers +|=== +| Runtime Environment| `LoadTimeWeaver` implementation + +| Running in https://tomcat.apache.org/[Apache Tomcat] +| `TomcatLoadTimeWeaver` + +| Running in https://eclipse-ee4j.github.io/glassfish/[GlassFish] (limited to EAR deployments) +| `GlassFishLoadTimeWeaver` + +| Running in Red Hat's https://www.jboss.org/jbossas/[JBoss AS] or https://www.wildfly.org/[WildFly] +| `JBossLoadTimeWeaver` + +| Running in IBM's https://www-01.ibm.com/software/webservers/appserv/was/[WebSphere] +| `WebSphereLoadTimeWeaver` + +| Running in Oracle's + https://www.oracle.com/technetwork/middleware/weblogic/overview/index-085209.html[WebLogic] +| `WebLogicLoadTimeWeaver` + +| JVM started with Spring `InstrumentationSavingAgent` + (`java -javaagent:path/to/spring-instrument.jar`) +| `InstrumentationLoadTimeWeaver` + +| Fallback, expecting the underlying ClassLoader to follow common conventions + (namely `addTransformer` and optionally a `getThrowawayClassLoader` method) +| `ReflectiveLoadTimeWeaver` +|=== + +Note that the table lists only the `LoadTimeWeavers` that are autodetected when you +use the `DefaultContextLoadTimeWeaver`. You can specify exactly which `LoadTimeWeaver` +implementation to use. + +To specify a specific `LoadTimeWeaver` with Java configuration, implement the +`LoadTimeWeavingConfigurer` interface and override the `getLoadTimeWeaver()` method. +The following example specifies a `ReflectiveLoadTimeWeaver`: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Configuration + @EnableLoadTimeWeaving + public class AppConfig implements LoadTimeWeavingConfigurer { + + @Override + public LoadTimeWeaver getLoadTimeWeaver() { + return new ReflectiveLoadTimeWeaver(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configuration + @EnableLoadTimeWeaving + class AppConfig : LoadTimeWeavingConfigurer { + + override fun getLoadTimeWeaver(): LoadTimeWeaver { + return ReflectiveLoadTimeWeaver() + } + } +---- + +If you use XML-based configuration, you can specify the fully qualified class name +as the value of the `weaver-class` attribute on the `` +element. Again, the following example specifies a `ReflectiveLoadTimeWeaver`: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + +---- + +The `LoadTimeWeaver` that is defined and registered by the configuration can be later +retrieved from the Spring container by using the well known name, `loadTimeWeaver`. +Remember that the `LoadTimeWeaver` exists only as a mechanism for Spring's LTW +infrastructure to add one or more `ClassFileTransformers`. The actual +`ClassFileTransformer` that does the LTW is the `ClassPreProcessorAgentAdapter` (from +the `org.aspectj.weaver.loadtime` package) class. See the class-level javadoc of the +`ClassPreProcessorAgentAdapter` class for further details, because the specifics of how +the weaving is actually effected is beyond the scope of this document. + +There is one final attribute of the configuration left to discuss: the `aspectjWeaving` +attribute (or `aspectj-weaving` if you use XML). This attribute controls whether LTW +is enabled or not. It accepts one of three possible values, with the default value being +`autodetect` if the attribute is not present. The following table summarizes the three +possible values: + +[[aop-aj-ltw-ltw-tag-attrs]] +.AspectJ weaving attribute values +|=== +| Annotation Value| XML Value| Explanation + +| `ENABLED` +| `on` +| AspectJ weaving is on, and aspects are woven at load-time as appropriate. + +| `DISABLED` +| `off` +| LTW is off. No aspect is woven at load-time. + +| `AUTODETECT` +| `autodetect` +| If the Spring LTW infrastructure can find at least one `META-INF/aop.xml` file, + then AspectJ weaving is on. Otherwise, it is off. This is the default value. +|=== + + +[[aop-aj-ltw-environments]] +=== Environment-specific Configuration + +This last section contains any additional settings and configuration that you need +when you use Spring's LTW support in environments such as application servers and web +containers. + +[[aop-aj-ltw-environments-tomcat-jboss-etc]] +==== Tomcat, JBoss, WebSphere, WebLogic + +Tomcat, JBoss/WildFly, IBM WebSphere Application Server and Oracle WebLogic Server all +provide a general app `ClassLoader` that is capable of local instrumentation. Spring's +native LTW may leverage those ClassLoader implementations to provide AspectJ weaving. +You can simply enable load-time weaving, as <>. +Specifically, you do not need to modify the JVM launch script to add +`-javaagent:path/to/spring-instrument.jar`. + +Note that on JBoss, you may need to disable the app server scanning to prevent it from +loading the classes before the application actually starts. A quick workaround is to add +to your artifact a file named `WEB-INF/jboss-scanning.xml` with the following content: + +[source,xml,indent=0,subs="verbatim"] +---- + +---- + +[[aop-aj-ltw-environments-generic]] +==== Generic Java Applications + +When class instrumentation is required in environments that are not supported by +specific `LoadTimeWeaver` implementations, a JVM agent is the general solution. +For such cases, Spring provides `InstrumentationLoadTimeWeaver` which requires a +Spring-specific (but very general) JVM agent, `spring-instrument.jar`, autodetected +by common `@EnableLoadTimeWeaving` and `` setups. + +To use it, you must start the virtual machine with the Spring agent by supplying +the following JVM options: + +[literal] +[subs="verbatim"] +---- +-javaagent:/path/to/spring-instrument.jar +---- + +Note that this requires modification of the JVM launch script, which may prevent you +from using this in application server environments (depending on your server and your +operation policies). That said, for one-app-per-JVM deployments such as standalone +Spring Boot applications, you typically control the entire JVM setup in any case. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/appendix.adoc b/framework-docs/modules/ROOT/pages/core/appendix.adoc index 094ec6a11ee4..5993dea520cc 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix.adoc @@ -4,1667 +4,3 @@ -[[core.appendix.xsd-schemas]] -== XML Schemas - -This part of the appendix lists XML schemas related to the core container. - - - -[[core.appendix.xsd-schemas-util]] -=== The `util` Schema - -As the name implies, the `util` tags deal with common, utility configuration -issues, such as configuring collections, referencing constants, and so forth. -To use the tags in the `util` schema, you need to have the following preamble at the top -of your Spring XML configuration file (the text in the snippet references the -correct schema so that the tags in the `util` namespace are available to you): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - - -[[core.appendix.xsd-schemas-util-constant]] -==== Using `` - -Consider the following bean definition: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - -The preceding configuration uses a Spring `FactoryBean` implementation (the -`FieldRetrievingFactoryBean`) to set the value of the `isolation` property on a bean -to the value of the `java.sql.Connection.TRANSACTION_SERIALIZABLE` constant. This is -all well and good, but it is verbose and (unnecessarily) exposes Spring's internal -plumbing to the end user. - -The following XML Schema-based version is more concise, clearly expresses the -developer's intent ("`inject this constant value`"), and it reads better: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - -[[core.appendix.xsd-schemas-util-frfb]] -===== Setting a Bean Property or Constructor Argument from a Field Value - -{api-spring-framework}/beans/factory/config/FieldRetrievingFactoryBean.html[`FieldRetrievingFactoryBean`] -is a `FactoryBean` that retrieves a `static` or non-static field value. It is typically -used for retrieving `public` `static` `final` constants, which may then be used to set a -property value or constructor argument for another bean. - -The following example shows how a `static` field is exposed, by using the -{api-spring-framework}/beans/factory/config/FieldRetrievingFactoryBean.html#setStaticField(java.lang.String)[`staticField`] -property: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -There is also a convenience usage form where the `static` field is specified as the bean -name, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -This does mean that there is no longer any choice in what the bean `id` is (so any other -bean that refers to it also has to use this longer name), but this form is very -concise to define and very convenient to use as an inner bean since the `id` does not have -to be specified for the bean reference, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - -You can also access a non-static (instance) field of another bean, as -described in the API documentation for the -{api-spring-framework}/beans/factory/config/FieldRetrievingFactoryBean.html[`FieldRetrievingFactoryBean`] -class. - -Injecting enumeration values into beans as either property or constructor arguments is -easy to do in Spring. You do not actually have to do anything or know anything about -the Spring internals (or even about classes such as the `FieldRetrievingFactoryBean`). -The following example enumeration shows how easy injecting an enum value is: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package jakarta.persistence; - - public enum PersistenceContextType { - - TRANSACTION, - EXTENDED - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package jakarta.persistence - - enum class PersistenceContextType { - - TRANSACTION, - EXTENDED - } ----- - -Now consider the following setter of type `PersistenceContextType` and the corresponding bean definition: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package example; - - public class Client { - - private PersistenceContextType persistenceContextType; - - public void setPersistenceContextType(PersistenceContextType type) { - this.persistenceContextType = type; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package example - - class Client { - - lateinit var persistenceContextType: PersistenceContextType - } ----- - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - - -[[core.appendix.xsd-schemas-util-property-path]] -==== Using `` - -Consider the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - ----- - -The preceding configuration uses a Spring `FactoryBean` implementation (the -`PropertyPathFactoryBean`) to create a bean (of type `int`) called `testBean.age` that -has a value equal to the `age` property of the `testBean` bean. - -Now consider the following example, which adds a `` element: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - ----- - -The value of the `path` attribute of the `` element follows the form of -`beanName.beanProperty`. In this case, it picks up the `age` property of the bean named -`testBean`. The value of that `age` property is `10`. - -[[core.appendix.xsd-schemas-util-property-path-dependency]] -===== Using `` to Set a Bean Property or Constructor Argument - -`PropertyPathFactoryBean` is a `FactoryBean` that evaluates a property path on a given -target object. The target object can be specified directly or by a bean name. You can then use this -value in another bean definition as a property value or constructor -argument. - -The following example shows a path being used against another bean, by name: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - ----- - -In the following example, a path is evaluated against an inner bean: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - ----- - -There is also a shortcut form, where the bean name is the property path. -The following example shows the shortcut form: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ----- - -This form does mean that there is no choice in the name of the bean. Any reference to it -also has to use the same `id`, which is the path. If used as an inner -bean, there is no need to refer to it at all, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - -You can specifically set the result type in the actual definition. This is not necessary -for most use cases, but it can sometimes be useful. See the javadoc for more info on -this feature. - - -[[core.appendix.xsd-schemas-util-properties]] -==== Using `` - -Consider the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - -The preceding configuration uses a Spring `FactoryBean` implementation (the -`PropertiesFactoryBean`) to instantiate a `java.util.Properties` instance with values -loaded from the supplied <> location). - -The following example uses a `util:properties` element to make a more concise representation: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ----- - - -[[core.appendix.xsd-schemas-util-list]] -==== Using `` - -Consider the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - pechorin@hero.org - raskolnikov@slums.org - stavrogin@gov.org - porfiry@gov.org - - - ----- - -The preceding configuration uses a Spring `FactoryBean` implementation (the -`ListFactoryBean`) to create a `java.util.List` instance and initialize it with values taken -from the supplied `sourceList`. - -The following example uses a `` element to make a more concise representation: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - pechorin@hero.org - raskolnikov@slums.org - stavrogin@gov.org - porfiry@gov.org - ----- - -You can also explicitly control the exact type of `List` that is instantiated and -populated by using the `list-class` attribute on the `` element. For -example, if we really need a `java.util.LinkedList` to be instantiated, we could use the -following configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - jackshaftoe@vagabond.org - eliza@thinkingmanscrumpet.org - vanhoek@pirate.org - d'Arcachon@nemesis.org - ----- - -If no `list-class` attribute is supplied, the container chooses a `List` implementation. - - -[[core.appendix.xsd-schemas-util-map]] -==== Using `` - -Consider the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - ----- - -The preceding configuration uses a Spring `FactoryBean` implementation (the -`MapFactoryBean`) to create a `java.util.Map` instance initialized with key-value pairs -taken from the supplied `'sourceMap'`. - -The following example uses a `` element to make a more concise representation: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -You can also explicitly control the exact type of `Map` that is instantiated and -populated by using the `'map-class'` attribute on the `` element. For -example, if we really need a `java.util.TreeMap` to be instantiated, we could use the -following configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -If no `'map-class'` attribute is supplied, the container chooses a `Map` implementation. - - -[[core.appendix.xsd-schemas-util-set]] -==== Using `` - -Consider the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - pechorin@hero.org - raskolnikov@slums.org - stavrogin@gov.org - porfiry@gov.org - - - ----- - -The preceding configuration uses a Spring `FactoryBean` implementation (the -`SetFactoryBean`) to create a `java.util.Set` instance initialized with values taken -from the supplied `sourceSet`. - -The following example uses a `` element to make a more concise representation: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - pechorin@hero.org - raskolnikov@slums.org - stavrogin@gov.org - porfiry@gov.org - ----- - -You can also explicitly control the exact type of `Set` that is instantiated and -populated by using the `set-class` attribute on the `` element. For -example, if we really need a `java.util.TreeSet` to be instantiated, we could use the -following configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - pechorin@hero.org - raskolnikov@slums.org - stavrogin@gov.org - porfiry@gov.org - ----- - -If no `set-class` attribute is supplied, the container chooses a `Set` implementation. - - - -[[core.appendix.xsd-schemas-aop]] -=== The `aop` Schema - -The `aop` tags deal with configuring all things AOP in Spring, including Spring's -own proxy-based AOP framework and Spring's integration with the AspectJ AOP framework. -These tags are comprehensively covered in the chapter entitled <>. - -In the interest of completeness, to use the tags in the `aop` schema, you need to have -the following preamble at the top of your Spring XML configuration file (the text in the -snippet references the correct schema so that the tags in the `aop` namespace -are available to you): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - - - -[[core.appendix.xsd-schemas-context]] -=== The `context` Schema - -The `context` tags deal with `ApplicationContext` configuration that relates to plumbing --- that is, not usually beans that are important to an end-user but rather beans that do -a lot of the "`grunt`" work in Spring, such as `BeanfactoryPostProcessors`. The following -snippet references the correct schema so that the elements in the `context` namespace are -available to you: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - - -[[core.appendix.xsd-schemas-context-pphc]] -==== Using `` - -This element activates the replacement of `${...}` placeholders, which are resolved against a -specified properties file (as a <>). This element -is a convenience mechanism that sets up a <> for you. If you need more control over the specific -`PropertySourcesPlaceholderConfigurer` setup, you can explicitly define it as a bean yourself. - - -[[core.appendix.xsd-schemas-context-ac]] -==== Using `` - -This element activates the Spring infrastructure to detect annotations in bean classes: - -* Spring's <> model -* <>, `@Value`, and `@Lookup` -* JSR-250's `@Resource`, `@PostConstruct`, and `@PreDestroy` (if available) -* JAX-WS's `@WebServiceRef` and EJB 3's `@EJB` (if available) -* JPA's `@PersistenceContext` and `@PersistenceUnit` (if available) -* Spring's <> - -Alternatively, you can choose to explicitly activate the individual `BeanPostProcessors` -for those annotations. - -NOTE: This element does not activate processing of Spring's -<> annotation; -you can use the <`>> -element for that purpose. Similarly, Spring's -<> need to be explicitly -<> as well. - - -[[core.appendix.xsd-schemas-context-component-scan]] -==== Using `` - -This element is detailed in the section on <>. - - -[[core.appendix.xsd-schemas-context-ltw]] -==== Using `` - -This element is detailed in the section on <>. - - -[[core.appendix.xsd-schemas-context-sc]] -==== Using `` - -This element is detailed in the section on <>. - - -[[core.appendix.xsd-schemas-context-mbe]] -==== Using `` - -This element is detailed in the section on <>. - - - -[[core.appendix.xsd-schemas-beans]] -=== The Beans Schema - -Last but not least, we have the elements in the `beans` schema. These elements -have been in Spring since the very dawn of the framework. Examples of the various elements -in the `beans` schema are not shown here because they are quite comprehensively covered -in <> -(and, indeed, in that entire <>). - -Note that you can add zero or more key-value pairs to `` XML definitions. -What, if anything, is done with this extra metadata is totally up to your own custom -logic (and so is typically only of use if you write your own custom elements as described -in the appendix entitled <>). - -The following example shows the `` element in the context of a surrounding `` -(note that, without any logic to interpret it, the metadata is effectively useless -as it stands). - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - <1> - - - - ----- -<1> This is the example `meta` element - -In the case of the preceding example, you could assume that there is some logic that consumes -the bean definition and sets up some caching infrastructure that uses the supplied metadata. - - - - -[[core.appendix.xml-custom]] -== XML Schema Authoring - -[[core.appendix.xsd-custom-introduction]] -Since version 2.0, Spring has featured a mechanism for adding schema-based extensions to the -basic Spring XML format for defining and configuring beans. This section covers -how to write your own custom XML bean definition parsers and -integrate such parsers into the Spring IoC container. - -To facilitate authoring configuration files that use a schema-aware XML editor, -Spring's extensible XML configuration mechanism is based on XML Schema. If you are not -familiar with Spring's current XML configuration extensions that come with the standard -Spring distribution, you should first read the previous section on <>. - - -To create new XML configuration extensions: - -. <> an XML schema to describe your custom element(s). -. <> a custom `NamespaceHandler` implementation. -. <> one or more `BeanDefinitionParser` implementations - (this is where the real work is done). -. <> your new artifacts with Spring. - -For a unified example, we create an -XML extension (a custom XML element) that lets us configure objects of the type -`SimpleDateFormat` (from the `java.text` package). When we are done, -we will be able to define bean definitions of type `SimpleDateFormat` as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -(We include much more detailed -examples follow later in this appendix. The intent of this first simple example is to walk you -through the basic steps of making a custom extension.) - - - -[[core.appendix.xsd-custom-schema]] -=== Authoring the Schema - -Creating an XML configuration extension for use with Spring's IoC container starts with -authoring an XML Schema to describe the extension. For our example, we use the following schema -to configure `SimpleDateFormat` objects: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - <1> - - - - - - - ----- -<1> The indicated line contains an extension base for all identifiable tags -(meaning they have an `id` attribute that we can use as the bean identifier in the -container). We can use this attribute because we imported the Spring-provided -`beans` namespace. - - -The preceding schema lets us configure `SimpleDateFormat` objects directly in an -XML application context file by using the `` element, as the following -example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -Note that, after we have created the infrastructure classes, the preceding snippet of XML is -essentially the same as the following XML snippet: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - -The second of the two preceding snippets -creates a bean in the container (identified by the name `dateFormat` of type -`SimpleDateFormat`) with a couple of properties set. - -NOTE: The schema-based approach to creating configuration format allows for tight integration -with an IDE that has a schema-aware XML editor. By using a properly authored schema, you -can use autocompletion to let a user choose between several configuration options -defined in the enumeration. - - - -[[core.appendix.xsd-custom-namespacehandler]] -=== Coding a `NamespaceHandler` - -In addition to the schema, we need a `NamespaceHandler` to parse all elements of -this specific namespace that Spring encounters while parsing configuration files. For this example, the -`NamespaceHandler` should take care of the parsing of the `myns:dateformat` -element. - -The `NamespaceHandler` interface features three methods: - -* `init()`: Allows for initialization of the `NamespaceHandler` and is called by - Spring before the handler is used. -* `BeanDefinition parse(Element, ParserContext)`: Called when Spring encounters a - top-level element (not nested inside a bean definition or a different namespace). - This method can itself register bean definitions, return a bean definition, or both. -* `BeanDefinitionHolder decorate(Node, BeanDefinitionHolder, ParserContext)`: Called - when Spring encounters an attribute or nested element of a different namespace. - The decoration of one or more bean definitions is used (for example) with the - <>. - We start by highlighting a simple example, without using decoration, after which - we show decoration in a somewhat more advanced example. - -Although you can code your own `NamespaceHandler` for the entire -namespace (and hence provide code that parses each and every element in the namespace), -it is often the case that each top-level XML element in a Spring XML configuration file -results in a single bean definition (as in our case, where a single `` -element results in a single `SimpleDateFormat` bean definition). Spring features a -number of convenience classes that support this scenario. In the following example, we -use the `NamespaceHandlerSupport` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package org.springframework.samples.xml; - - import org.springframework.beans.factory.xml.NamespaceHandlerSupport; - - public class MyNamespaceHandler extends NamespaceHandlerSupport { - - public void init() { - registerBeanDefinitionParser("dateformat", new SimpleDateFormatBeanDefinitionParser()); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package org.springframework.samples.xml - - import org.springframework.beans.factory.xml.NamespaceHandlerSupport - - class MyNamespaceHandler : NamespaceHandlerSupport { - - override fun init() { - registerBeanDefinitionParser("dateformat", SimpleDateFormatBeanDefinitionParser()) - } - } ----- - -You may notice that there is not actually a whole lot of parsing logic -in this class. Indeed, the `NamespaceHandlerSupport` class has a built-in notion of -delegation. It supports the registration of any number of `BeanDefinitionParser` -instances, to which it delegates to when it needs to parse an element in its -namespace. This clean separation of concerns lets a `NamespaceHandler` handle the -orchestration of the parsing of all of the custom elements in its namespace while -delegating to `BeanDefinitionParsers` to do the grunt work of the XML parsing. This -means that each `BeanDefinitionParser` contains only the logic for parsing a single -custom element, as we can see in the next step. - - - -[[core.appendix.xsd-custom-parser]] -=== Using `BeanDefinitionParser` - -A `BeanDefinitionParser` is used if the `NamespaceHandler` encounters an XML -element of the type that has been mapped to the specific bean definition parser -(`dateformat` in this case). In other words, the `BeanDefinitionParser` is -responsible for parsing one distinct top-level XML element defined in the schema. In -the parser, we' have access to the XML element (and thus to its subelements, too) so that -we can parse our custom XML content, as you can see in the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package org.springframework.samples.xml; - - import org.springframework.beans.factory.support.BeanDefinitionBuilder; - import org.springframework.beans.factory.xml.AbstractSingleBeanDefinitionParser; - import org.springframework.util.StringUtils; - import org.w3c.dom.Element; - - import java.text.SimpleDateFormat; - - public class SimpleDateFormatBeanDefinitionParser extends AbstractSingleBeanDefinitionParser { // <1> - - protected Class getBeanClass(Element element) { - return SimpleDateFormat.class; // <2> - } - - protected void doParse(Element element, BeanDefinitionBuilder bean) { - // this will never be null since the schema explicitly requires that a value be supplied - String pattern = element.getAttribute("pattern"); - bean.addConstructorArgValue(pattern); - - // this however is an optional property - String lenient = element.getAttribute("lenient"); - if (StringUtils.hasText(lenient)) { - bean.addPropertyValue("lenient", Boolean.valueOf(lenient)); - } - } - - } ----- -<1> We use the Spring-provided `AbstractSingleBeanDefinitionParser` to handle a lot of -the basic grunt work of creating a single `BeanDefinition`. -<2> We supply the `AbstractSingleBeanDefinitionParser` superclass with the type that our -single `BeanDefinition` represents. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package org.springframework.samples.xml - - import org.springframework.beans.factory.support.BeanDefinitionBuilder - import org.springframework.beans.factory.xml.AbstractSingleBeanDefinitionParser - import org.springframework.util.StringUtils - import org.w3c.dom.Element - - import java.text.SimpleDateFormat - - class SimpleDateFormatBeanDefinitionParser : AbstractSingleBeanDefinitionParser() { // <1> - - override fun getBeanClass(element: Element): Class<*>? { // <2> - return SimpleDateFormat::class.java - } - - override fun doParse(element: Element, bean: BeanDefinitionBuilder) { - // this will never be null since the schema explicitly requires that a value be supplied - val pattern = element.getAttribute("pattern") - bean.addConstructorArgValue(pattern) - - // this however is an optional property - val lenient = element.getAttribute("lenient") - if (StringUtils.hasText(lenient)) { - bean.addPropertyValue("lenient", java.lang.Boolean.valueOf(lenient)) - } - } - } ----- -<1> We use the Spring-provided `AbstractSingleBeanDefinitionParser` to handle a lot of -the basic grunt work of creating a single `BeanDefinition`. -<2> We supply the `AbstractSingleBeanDefinitionParser` superclass with the type that our -single `BeanDefinition` represents. - - -In this simple case, this is all that we need to do. The creation of our single -`BeanDefinition` is handled by the `AbstractSingleBeanDefinitionParser` superclass, as -is the extraction and setting of the bean definition's unique identifier. - - - -[[core.appendix.xsd-custom-registration]] -=== Registering the Handler and the Schema - -The coding is finished. All that remains to be done is to make the Spring XML -parsing infrastructure aware of our custom element. We do so by registering our custom -`namespaceHandler` and custom XSD file in two special-purpose properties files. These -properties files are both placed in a `META-INF` directory in your application and -can, for example, be distributed alongside your binary classes in a JAR file. The Spring -XML parsing infrastructure automatically picks up your new extension by consuming -these special properties files, the formats of which are detailed in the next two sections. - - -[[core.appendix.xsd-custom-registration-spring-handlers]] -==== Writing `META-INF/spring.handlers` - -The properties file called `spring.handlers` contains a mapping of XML Schema URIs to -namespace handler classes. For our example, we need to write the following: - -[literal,subs="verbatim,quotes"] ----- -http\://www.mycompany.example/schema/myns=org.springframework.samples.xml.MyNamespaceHandler ----- - -(The `:` character is a valid delimiter in the Java properties format, so -`:` character in the URI needs to be escaped with a backslash.) - -The first part (the key) of the key-value pair is the URI associated with your custom -namespace extension and needs to exactly match exactly the value of the `targetNamespace` -attribute, as specified in your custom XSD schema. - - -[[core.appendix.xsd-custom-registration-spring-schemas]] -==== Writing 'META-INF/spring.schemas' - -The properties file called `spring.schemas` contains a mapping of XML Schema locations -(referred to, along with the schema declaration, in XML files that use the schema as part -of the `xsi:schemaLocation` attribute) to classpath resources. This file is needed -to prevent Spring from absolutely having to use a default `EntityResolver` that requires -Internet access to retrieve the schema file. If you specify the mapping in this -properties file, Spring searches for the schema (in this case, -`myns.xsd` in the `org.springframework.samples.xml` package) on the classpath. -The following snippet shows the line we need to add for our custom schema: - -[literal,subs="verbatim,quotes"] ----- -http\://www.mycompany.example/schema/myns/myns.xsd=org/springframework/samples/xml/myns.xsd ----- - -(Remember that the `:` character must be escaped.) - -You are encouraged to deploy your XSD file (or files) right alongside -the `NamespaceHandler` and `BeanDefinitionParser` classes on the classpath. - - - -[[core.appendix.xsd-custom-using]] -=== Using a Custom Extension in Your Spring XML Configuration - -Using a custom extension that you yourself have implemented is no different from using -one of the "`custom`" extensions that Spring provides. The following -example uses the custom `` element developed in the previous steps -in a Spring XML configuration file: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - <1> - - - - - - - - - ----- -<1> Our custom bean. - - - -[[core.appendix.xsd-custom-meat]] -=== More Detailed Examples - -This section presents some more detailed examples of custom XML extensions. - - -[[core.appendix.xsd-custom-custom-nested]] -==== Nesting Custom Elements within Custom Elements - -The example presented in this section shows how you to write the various artifacts required -to satisfy a target of the following configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - ----- - -The preceding configuration nests custom extensions within each other. The class -that is actually configured by the `` element is the `Component` -class (shown in the next example). Notice how the `Component` class does not expose a -setter method for the `components` property. This makes it hard (or rather impossible) -to configure a bean definition for the `Component` class by using setter injection. -The following listing shows the `Component` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package com.foo; - - import java.util.ArrayList; - import java.util.List; - - public class Component { - - private String name; - private List components = new ArrayList (); - - // there is no setter method for the 'components' - public void addComponent(Component component) { - this.components.add(component); - } - - public List getComponents() { - return components; - } - - public String getName() { - return name; - } - - public void setName(String name) { - this.name = name; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.foo - - import java.util.ArrayList - - class Component { - - var name: String? = null - private val components = ArrayList() - - // there is no setter method for the 'components' - fun addComponent(component: Component) { - this.components.add(component) - } - - fun getComponents(): List { - return components - } - } ----- - -The typical solution to this issue is to create a custom `FactoryBean` that exposes a -setter property for the `components` property. The following listing shows such a custom -`FactoryBean`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package com.foo; - - import org.springframework.beans.factory.FactoryBean; - - import java.util.List; - - public class ComponentFactoryBean implements FactoryBean { - - private Component parent; - private List children; - - public void setParent(Component parent) { - this.parent = parent; - } - - public void setChildren(List children) { - this.children = children; - } - - public Component getObject() throws Exception { - if (this.children != null && this.children.size() > 0) { - for (Component child : children) { - this.parent.addComponent(child); - } - } - return this.parent; - } - - public Class getObjectType() { - return Component.class; - } - - public boolean isSingleton() { - return true; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.foo - - import org.springframework.beans.factory.FactoryBean - import org.springframework.stereotype.Component - - class ComponentFactoryBean : FactoryBean { - - private var parent: Component? = null - private var children: List? = null - - fun setParent(parent: Component) { - this.parent = parent - } - - fun setChildren(children: List) { - this.children = children - } - - override fun getObject(): Component? { - if (this.children != null && this.children!!.isNotEmpty()) { - for (child in children!!) { - this.parent!!.addComponent(child) - } - } - return this.parent - } - - override fun getObjectType(): Class? { - return Component::class.java - } - - override fun isSingleton(): Boolean { - return true - } - } ----- - -This works nicely, but it exposes a lot of Spring plumbing to the end user. What we are -going to do is write a custom extension that hides away all of this Spring plumbing. -If we stick to <>, we start off -by creating the XSD schema to define the structure of our custom tag, as the following -listing shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - ----- - -Again following <>, -we then create a custom `NamespaceHandler`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package com.foo; - - import org.springframework.beans.factory.xml.NamespaceHandlerSupport; - - public class ComponentNamespaceHandler extends NamespaceHandlerSupport { - - public void init() { - registerBeanDefinitionParser("component", new ComponentBeanDefinitionParser()); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.foo - - import org.springframework.beans.factory.xml.NamespaceHandlerSupport - - class ComponentNamespaceHandler : NamespaceHandlerSupport() { - - override fun init() { - registerBeanDefinitionParser("component", ComponentBeanDefinitionParser()) - } - } ----- - -Next up is the custom `BeanDefinitionParser`. Remember that we are creating -a `BeanDefinition` that describes a `ComponentFactoryBean`. The following -listing shows our custom `BeanDefinitionParser` implementation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package com.foo; - - import org.springframework.beans.factory.config.BeanDefinition; - import org.springframework.beans.factory.support.AbstractBeanDefinition; - import org.springframework.beans.factory.support.BeanDefinitionBuilder; - import org.springframework.beans.factory.support.ManagedList; - import org.springframework.beans.factory.xml.AbstractBeanDefinitionParser; - import org.springframework.beans.factory.xml.ParserContext; - import org.springframework.util.xml.DomUtils; - import org.w3c.dom.Element; - - import java.util.List; - - public class ComponentBeanDefinitionParser extends AbstractBeanDefinitionParser { - - protected AbstractBeanDefinition parseInternal(Element element, ParserContext parserContext) { - return parseComponentElement(element); - } - - private static AbstractBeanDefinition parseComponentElement(Element element) { - BeanDefinitionBuilder factory = BeanDefinitionBuilder.rootBeanDefinition(ComponentFactoryBean.class); - factory.addPropertyValue("parent", parseComponent(element)); - - List childElements = DomUtils.getChildElementsByTagName(element, "component"); - if (childElements != null && childElements.size() > 0) { - parseChildComponents(childElements, factory); - } - - return factory.getBeanDefinition(); - } - - private static BeanDefinition parseComponent(Element element) { - BeanDefinitionBuilder component = BeanDefinitionBuilder.rootBeanDefinition(Component.class); - component.addPropertyValue("name", element.getAttribute("name")); - return component.getBeanDefinition(); - } - - private static void parseChildComponents(List childElements, BeanDefinitionBuilder factory) { - ManagedList children = new ManagedList<>(childElements.size()); - for (Element element : childElements) { - children.add(parseComponentElement(element)); - } - factory.addPropertyValue("children", children); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.foo - - import org.springframework.beans.factory.config.BeanDefinition - import org.springframework.beans.factory.support.AbstractBeanDefinition - import org.springframework.beans.factory.support.BeanDefinitionBuilder - import org.springframework.beans.factory.support.ManagedList - import org.springframework.beans.factory.xml.AbstractBeanDefinitionParser - import org.springframework.beans.factory.xml.ParserContext - import org.springframework.util.xml.DomUtils - import org.w3c.dom.Element - - import java.util.List - - class ComponentBeanDefinitionParser : AbstractBeanDefinitionParser() { - - override fun parseInternal(element: Element, parserContext: ParserContext): AbstractBeanDefinition? { - return parseComponentElement(element) - } - - private fun parseComponentElement(element: Element): AbstractBeanDefinition { - val factory = BeanDefinitionBuilder.rootBeanDefinition(ComponentFactoryBean::class.java) - factory.addPropertyValue("parent", parseComponent(element)) - - val childElements = DomUtils.getChildElementsByTagName(element, "component") - if (childElements != null && childElements.size > 0) { - parseChildComponents(childElements, factory) - } - - return factory.getBeanDefinition() - } - - private fun parseComponent(element: Element): BeanDefinition { - val component = BeanDefinitionBuilder.rootBeanDefinition(Component::class.java) - component.addPropertyValue("name", element.getAttribute("name")) - return component.beanDefinition - } - - private fun parseChildComponents(childElements: List, factory: BeanDefinitionBuilder) { - val children = ManagedList(childElements.size) - for (element in childElements) { - children.add(parseComponentElement(element)) - } - factory.addPropertyValue("children", children) - } - } ----- - -Finally, the various artifacts need to be registered with the Spring XML infrastructure, -by modifying the `META-INF/spring.handlers` and `META-INF/spring.schemas` files, as follows: - -[literal,subs="verbatim,quotes"] ----- -# in 'META-INF/spring.handlers' -http\://www.foo.example/schema/component=com.foo.ComponentNamespaceHandler ----- - -[literal,subs="verbatim,quotes"] ----- -# in 'META-INF/spring.schemas' -http\://www.foo.example/schema/component/component.xsd=com/foo/component.xsd ----- - - -[[core.appendix.xsd-custom-custom-just-attributes]] -==== Custom Attributes on "`Normal`" Elements - -Writing your own custom parser and the associated artifacts is not hard. However, -it is sometimes not the right thing to do. Consider a scenario where you need to -add metadata to already existing bean definitions. In this case, you certainly -do not want to have to write your own entire custom extension. Rather, you merely -want to add an additional attribute to the existing bean definition element. - -By way of another example, suppose that you define a bean definition for a -service object that (unknown to it) accesses a clustered -https://jcp.org/en/jsr/detail?id=107[JCache], and you want to ensure that the -named JCache instance is eagerly started within the surrounding cluster. -The following listing shows such a definition: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -We can then create another `BeanDefinition` when the -`'jcache:cache-name'` attribute is parsed. This `BeanDefinition` then initializes -the named JCache for us. We can also modify the existing `BeanDefinition` for the -`'checkingAccountService'` so that it has a dependency on this new -JCache-initializing `BeanDefinition`. The following listing shows our `JCacheInitializer`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package com.foo; - - public class JCacheInitializer { - - private final String name; - - public JCacheInitializer(String name) { - this.name = name; - } - - public void initialize() { - // lots of JCache API calls to initialize the named cache... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.foo - - class JCacheInitializer(private val name: String) { - - fun initialize() { - // lots of JCache API calls to initialize the named cache... - } - } ----- - -Now we can move onto the custom extension. First, we need to author -the XSD schema that describes the custom attribute, as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -Next, we need to create the associated `NamespaceHandler`, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package com.foo; - - import org.springframework.beans.factory.xml.NamespaceHandlerSupport; - - public class JCacheNamespaceHandler extends NamespaceHandlerSupport { - - public void init() { - super.registerBeanDefinitionDecoratorForAttribute("cache-name", - new JCacheInitializingBeanDefinitionDecorator()); - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.foo - - import org.springframework.beans.factory.xml.NamespaceHandlerSupport - - class JCacheNamespaceHandler : NamespaceHandlerSupport() { - - override fun init() { - super.registerBeanDefinitionDecoratorForAttribute("cache-name", - JCacheInitializingBeanDefinitionDecorator()) - } - - } ----- - -Next, we need to create the parser. Note that, in this case, because we are going to parse -an XML attribute, we write a `BeanDefinitionDecorator` rather than a `BeanDefinitionParser`. -The following listing shows our `BeanDefinitionDecorator` implementation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package com.foo; - - import org.springframework.beans.factory.config.BeanDefinitionHolder; - import org.springframework.beans.factory.support.AbstractBeanDefinition; - import org.springframework.beans.factory.support.BeanDefinitionBuilder; - import org.springframework.beans.factory.xml.BeanDefinitionDecorator; - import org.springframework.beans.factory.xml.ParserContext; - import org.w3c.dom.Attr; - import org.w3c.dom.Node; - - import java.util.ArrayList; - import java.util.Arrays; - import java.util.List; - - public class JCacheInitializingBeanDefinitionDecorator implements BeanDefinitionDecorator { - - private static final String[] EMPTY_STRING_ARRAY = new String[0]; - - public BeanDefinitionHolder decorate(Node source, BeanDefinitionHolder holder, - ParserContext ctx) { - String initializerBeanName = registerJCacheInitializer(source, ctx); - createDependencyOnJCacheInitializer(holder, initializerBeanName); - return holder; - } - - private void createDependencyOnJCacheInitializer(BeanDefinitionHolder holder, - String initializerBeanName) { - AbstractBeanDefinition definition = ((AbstractBeanDefinition) holder.getBeanDefinition()); - String[] dependsOn = definition.getDependsOn(); - if (dependsOn == null) { - dependsOn = new String[]{initializerBeanName}; - } else { - List dependencies = new ArrayList(Arrays.asList(dependsOn)); - dependencies.add(initializerBeanName); - dependsOn = (String[]) dependencies.toArray(EMPTY_STRING_ARRAY); - } - definition.setDependsOn(dependsOn); - } - - private String registerJCacheInitializer(Node source, ParserContext ctx) { - String cacheName = ((Attr) source).getValue(); - String beanName = cacheName + "-initializer"; - if (!ctx.getRegistry().containsBeanDefinition(beanName)) { - BeanDefinitionBuilder initializer = BeanDefinitionBuilder.rootBeanDefinition(JCacheInitializer.class); - initializer.addConstructorArg(cacheName); - ctx.getRegistry().registerBeanDefinition(beanName, initializer.getBeanDefinition()); - } - return beanName; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.foo - - import org.springframework.beans.factory.config.BeanDefinitionHolder - import org.springframework.beans.factory.support.AbstractBeanDefinition - import org.springframework.beans.factory.support.BeanDefinitionBuilder - import org.springframework.beans.factory.xml.BeanDefinitionDecorator - import org.springframework.beans.factory.xml.ParserContext - import org.w3c.dom.Attr - import org.w3c.dom.Node - - import java.util.ArrayList - - class JCacheInitializingBeanDefinitionDecorator : BeanDefinitionDecorator { - - override fun decorate(source: Node, holder: BeanDefinitionHolder, - ctx: ParserContext): BeanDefinitionHolder { - val initializerBeanName = registerJCacheInitializer(source, ctx) - createDependencyOnJCacheInitializer(holder, initializerBeanName) - return holder - } - - private fun createDependencyOnJCacheInitializer(holder: BeanDefinitionHolder, - initializerBeanName: String) { - val definition = holder.beanDefinition as AbstractBeanDefinition - var dependsOn = definition.dependsOn - dependsOn = if (dependsOn == null) { - arrayOf(initializerBeanName) - } else { - val dependencies = ArrayList(listOf(*dependsOn)) - dependencies.add(initializerBeanName) - dependencies.toTypedArray() - } - definition.setDependsOn(*dependsOn) - } - - private fun registerJCacheInitializer(source: Node, ctx: ParserContext): String { - val cacheName = (source as Attr).value - val beanName = "$cacheName-initializer" - if (!ctx.registry.containsBeanDefinition(beanName)) { - val initializer = BeanDefinitionBuilder.rootBeanDefinition(JCacheInitializer::class.java) - initializer.addConstructorArg(cacheName) - ctx.registry.registerBeanDefinition(beanName, initializer.getBeanDefinition()) - } - return beanName - } - } ----- - -Finally, we need to register the various artifacts with the Spring XML infrastructure -by modifying the `META-INF/spring.handlers` and `META-INF/spring.schemas` files, as follows: - -[literal,subs="verbatim,quotes"] ----- -# in 'META-INF/spring.handlers' -http\://www.foo.example/schema/jcache=com.foo.JCacheNamespaceHandler ----- - -[literal,subs="verbatim,quotes"] ----- -# in 'META-INF/spring.schemas' -http\://www.foo.example/schema/jcache/jcache.xsd=com/foo/jcache.xsd ----- - - -[[core.appendix.application-startup-steps]] -== Application Startup Steps - -This part of the appendix lists the existing `StartupSteps` that the core container is instrumented with. - -WARNING: The name and detailed information about each startup step is not part of the public contract and -is subject to change; this is considered as an implementation detail of the core container and will follow -its behavior changes. - -.Application startup steps defined in the core container -|=== -| Name| Description| Tags - -| `spring.beans.instantiate` -| Instantiation of a bean and its dependencies. -| `beanName` the name of the bean, `beanType` the type required at the injection point. - -| `spring.beans.smart-initialize` -| Initialization of `SmartInitializingSingleton` beans. -| `beanName` the name of the bean. - -| `spring.context.annotated-bean-reader.create` -| Creation of the `AnnotatedBeanDefinitionReader`. -| - -| `spring.context.base-packages.scan` -| Scanning of base packages. -| `packages` array of base packages for scanning. - -| `spring.context.beans.post-process` -| Beans post-processing phase. -| - -| `spring.context.bean-factory.post-process` -| Invocation of the `BeanFactoryPostProcessor` beans. -| `postProcessor` the current post-processor. - -| `spring.context.beandef-registry.post-process` -| Invocation of the `BeanDefinitionRegistryPostProcessor` beans. -| `postProcessor` the current post-processor. - -| `spring.context.component-classes.register` -| Registration of component classes through `AnnotationConfigApplicationContext#register`. -| `classes` array of given classes for registration. - -| `spring.context.config-classes.enhance` -| Enhancement of configuration classes with CGLIB proxies. -| `classCount` count of enhanced classes. - -| `spring.context.config-classes.parse` -| Configuration classes parsing phase with the `ConfigurationClassPostProcessor`. -| `classCount` count of processed classes. - -| `spring.context.refresh` -| Application context refresh phase. -| -|=== diff --git a/framework-docs/modules/ROOT/pages/core/appendix/application-startup-steps.adoc b/framework-docs/modules/ROOT/pages/core/appendix/application-startup-steps.adoc new file mode 100644 index 000000000000..df05df7f7c70 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/appendix/application-startup-steps.adoc @@ -0,0 +1,57 @@ +[[core.appendix.application-startup-steps]] += Application Startup Steps + +This part of the appendix lists the existing `StartupSteps` that the core container is instrumented with. + +WARNING: The name and detailed information about each startup step is not part of the public contract and +is subject to change; this is considered as an implementation detail of the core container and will follow +its behavior changes. + +.Application startup steps defined in the core container +|=== +| Name| Description| Tags + +| `spring.beans.instantiate` +| Instantiation of a bean and its dependencies. +| `beanName` the name of the bean, `beanType` the type required at the injection point. + +| `spring.beans.smart-initialize` +| Initialization of `SmartInitializingSingleton` beans. +| `beanName` the name of the bean. + +| `spring.context.annotated-bean-reader.create` +| Creation of the `AnnotatedBeanDefinitionReader`. +| + +| `spring.context.base-packages.scan` +| Scanning of base packages. +| `packages` array of base packages for scanning. + +| `spring.context.beans.post-process` +| Beans post-processing phase. +| + +| `spring.context.bean-factory.post-process` +| Invocation of the `BeanFactoryPostProcessor` beans. +| `postProcessor` the current post-processor. + +| `spring.context.beandef-registry.post-process` +| Invocation of the `BeanDefinitionRegistryPostProcessor` beans. +| `postProcessor` the current post-processor. + +| `spring.context.component-classes.register` +| Registration of component classes through `AnnotationConfigApplicationContext#register`. +| `classes` array of given classes for registration. + +| `spring.context.config-classes.enhance` +| Enhancement of configuration classes with CGLIB proxies. +| `classCount` count of enhanced classes. + +| `spring.context.config-classes.parse` +| Configuration classes parsing phase with the `ConfigurationClassPostProcessor`. +| `classCount` count of processed classes. + +| `spring.context.refresh` +| Application context refresh phase. +| +|=== diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc new file mode 100644 index 000000000000..8ae321e2b491 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc @@ -0,0 +1,958 @@ +[[core.appendix.xml-custom]] += XML Schema Authoring + +[[core.appendix.xsd-custom-introduction]] +Since version 2.0, Spring has featured a mechanism for adding schema-based extensions to the +basic Spring XML format for defining and configuring beans. This section covers +how to write your own custom XML bean definition parsers and +integrate such parsers into the Spring IoC container. + +To facilitate authoring configuration files that use a schema-aware XML editor, +Spring's extensible XML configuration mechanism is based on XML Schema. If you are not +familiar with Spring's current XML configuration extensions that come with the standard +Spring distribution, you should first read the previous section on <>. + + +To create new XML configuration extensions: + +. <> an XML schema to describe your custom element(s). +. <> a custom `NamespaceHandler` implementation. +. <> one or more `BeanDefinitionParser` implementations + (this is where the real work is done). +. <> your new artifacts with Spring. + +For a unified example, we create an +XML extension (a custom XML element) that lets us configure objects of the type +`SimpleDateFormat` (from the `java.text` package). When we are done, +we will be able to define bean definitions of type `SimpleDateFormat` as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +(We include much more detailed +examples follow later in this appendix. The intent of this first simple example is to walk you +through the basic steps of making a custom extension.) + + + +[[core.appendix.xsd-custom-schema]] +== Authoring the Schema + +Creating an XML configuration extension for use with Spring's IoC container starts with +authoring an XML Schema to describe the extension. For our example, we use the following schema +to configure `SimpleDateFormat` objects: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + <1> + + + + + + + +---- +<1> The indicated line contains an extension base for all identifiable tags +(meaning they have an `id` attribute that we can use as the bean identifier in the +container). We can use this attribute because we imported the Spring-provided +`beans` namespace. + + +The preceding schema lets us configure `SimpleDateFormat` objects directly in an +XML application context file by using the `` element, as the following +example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +Note that, after we have created the infrastructure classes, the preceding snippet of XML is +essentially the same as the following XML snippet: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- + +The second of the two preceding snippets +creates a bean in the container (identified by the name `dateFormat` of type +`SimpleDateFormat`) with a couple of properties set. + +NOTE: The schema-based approach to creating configuration format allows for tight integration +with an IDE that has a schema-aware XML editor. By using a properly authored schema, you +can use autocompletion to let a user choose between several configuration options +defined in the enumeration. + + + +[[core.appendix.xsd-custom-namespacehandler]] +== Coding a `NamespaceHandler` + +In addition to the schema, we need a `NamespaceHandler` to parse all elements of +this specific namespace that Spring encounters while parsing configuration files. For this example, the +`NamespaceHandler` should take care of the parsing of the `myns:dateformat` +element. + +The `NamespaceHandler` interface features three methods: + +* `init()`: Allows for initialization of the `NamespaceHandler` and is called by + Spring before the handler is used. +* `BeanDefinition parse(Element, ParserContext)`: Called when Spring encounters a + top-level element (not nested inside a bean definition or a different namespace). + This method can itself register bean definitions, return a bean definition, or both. +* `BeanDefinitionHolder decorate(Node, BeanDefinitionHolder, ParserContext)`: Called + when Spring encounters an attribute or nested element of a different namespace. + The decoration of one or more bean definitions is used (for example) with the + <>. + We start by highlighting a simple example, without using decoration, after which + we show decoration in a somewhat more advanced example. + +Although you can code your own `NamespaceHandler` for the entire +namespace (and hence provide code that parses each and every element in the namespace), +it is often the case that each top-level XML element in a Spring XML configuration file +results in a single bean definition (as in our case, where a single `` +element results in a single `SimpleDateFormat` bean definition). Spring features a +number of convenience classes that support this scenario. In the following example, we +use the `NamespaceHandlerSupport` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package org.springframework.samples.xml; + + import org.springframework.beans.factory.xml.NamespaceHandlerSupport; + + public class MyNamespaceHandler extends NamespaceHandlerSupport { + + public void init() { + registerBeanDefinitionParser("dateformat", new SimpleDateFormatBeanDefinitionParser()); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package org.springframework.samples.xml + + import org.springframework.beans.factory.xml.NamespaceHandlerSupport + + class MyNamespaceHandler : NamespaceHandlerSupport { + + override fun init() { + registerBeanDefinitionParser("dateformat", SimpleDateFormatBeanDefinitionParser()) + } + } +---- + +You may notice that there is not actually a whole lot of parsing logic +in this class. Indeed, the `NamespaceHandlerSupport` class has a built-in notion of +delegation. It supports the registration of any number of `BeanDefinitionParser` +instances, to which it delegates to when it needs to parse an element in its +namespace. This clean separation of concerns lets a `NamespaceHandler` handle the +orchestration of the parsing of all of the custom elements in its namespace while +delegating to `BeanDefinitionParsers` to do the grunt work of the XML parsing. This +means that each `BeanDefinitionParser` contains only the logic for parsing a single +custom element, as we can see in the next step. + + + +[[core.appendix.xsd-custom-parser]] +== Using `BeanDefinitionParser` + +A `BeanDefinitionParser` is used if the `NamespaceHandler` encounters an XML +element of the type that has been mapped to the specific bean definition parser +(`dateformat` in this case). In other words, the `BeanDefinitionParser` is +responsible for parsing one distinct top-level XML element defined in the schema. In +the parser, we' have access to the XML element (and thus to its subelements, too) so that +we can parse our custom XML content, as you can see in the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package org.springframework.samples.xml; + + import org.springframework.beans.factory.support.BeanDefinitionBuilder; + import org.springframework.beans.factory.xml.AbstractSingleBeanDefinitionParser; + import org.springframework.util.StringUtils; + import org.w3c.dom.Element; + + import java.text.SimpleDateFormat; + + public class SimpleDateFormatBeanDefinitionParser extends AbstractSingleBeanDefinitionParser { // <1> + + protected Class getBeanClass(Element element) { + return SimpleDateFormat.class; // <2> + } + + protected void doParse(Element element, BeanDefinitionBuilder bean) { + // this will never be null since the schema explicitly requires that a value be supplied + String pattern = element.getAttribute("pattern"); + bean.addConstructorArgValue(pattern); + + // this however is an optional property + String lenient = element.getAttribute("lenient"); + if (StringUtils.hasText(lenient)) { + bean.addPropertyValue("lenient", Boolean.valueOf(lenient)); + } + } + + } +---- +<1> We use the Spring-provided `AbstractSingleBeanDefinitionParser` to handle a lot of +the basic grunt work of creating a single `BeanDefinition`. +<2> We supply the `AbstractSingleBeanDefinitionParser` superclass with the type that our +single `BeanDefinition` represents. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package org.springframework.samples.xml + + import org.springframework.beans.factory.support.BeanDefinitionBuilder + import org.springframework.beans.factory.xml.AbstractSingleBeanDefinitionParser + import org.springframework.util.StringUtils + import org.w3c.dom.Element + + import java.text.SimpleDateFormat + + class SimpleDateFormatBeanDefinitionParser : AbstractSingleBeanDefinitionParser() { // <1> + + override fun getBeanClass(element: Element): Class<*>? { // <2> + return SimpleDateFormat::class.java + } + + override fun doParse(element: Element, bean: BeanDefinitionBuilder) { + // this will never be null since the schema explicitly requires that a value be supplied + val pattern = element.getAttribute("pattern") + bean.addConstructorArgValue(pattern) + + // this however is an optional property + val lenient = element.getAttribute("lenient") + if (StringUtils.hasText(lenient)) { + bean.addPropertyValue("lenient", java.lang.Boolean.valueOf(lenient)) + } + } + } +---- +<1> We use the Spring-provided `AbstractSingleBeanDefinitionParser` to handle a lot of +the basic grunt work of creating a single `BeanDefinition`. +<2> We supply the `AbstractSingleBeanDefinitionParser` superclass with the type that our +single `BeanDefinition` represents. + + +In this simple case, this is all that we need to do. The creation of our single +`BeanDefinition` is handled by the `AbstractSingleBeanDefinitionParser` superclass, as +is the extraction and setting of the bean definition's unique identifier. + + + +[[core.appendix.xsd-custom-registration]] +== Registering the Handler and the Schema + +The coding is finished. All that remains to be done is to make the Spring XML +parsing infrastructure aware of our custom element. We do so by registering our custom +`namespaceHandler` and custom XSD file in two special-purpose properties files. These +properties files are both placed in a `META-INF` directory in your application and +can, for example, be distributed alongside your binary classes in a JAR file. The Spring +XML parsing infrastructure automatically picks up your new extension by consuming +these special properties files, the formats of which are detailed in the next two sections. + + +[[core.appendix.xsd-custom-registration-spring-handlers]] +=== Writing `META-INF/spring.handlers` + +The properties file called `spring.handlers` contains a mapping of XML Schema URIs to +namespace handler classes. For our example, we need to write the following: + +[literal,subs="verbatim,quotes"] +---- +http\://www.mycompany.example/schema/myns=org.springframework.samples.xml.MyNamespaceHandler +---- + +(The `:` character is a valid delimiter in the Java properties format, so +`:` character in the URI needs to be escaped with a backslash.) + +The first part (the key) of the key-value pair is the URI associated with your custom +namespace extension and needs to exactly match exactly the value of the `targetNamespace` +attribute, as specified in your custom XSD schema. + + +[[core.appendix.xsd-custom-registration-spring-schemas]] +=== Writing 'META-INF/spring.schemas' + +The properties file called `spring.schemas` contains a mapping of XML Schema locations +(referred to, along with the schema declaration, in XML files that use the schema as part +of the `xsi:schemaLocation` attribute) to classpath resources. This file is needed +to prevent Spring from absolutely having to use a default `EntityResolver` that requires +Internet access to retrieve the schema file. If you specify the mapping in this +properties file, Spring searches for the schema (in this case, +`myns.xsd` in the `org.springframework.samples.xml` package) on the classpath. +The following snippet shows the line we need to add for our custom schema: + +[literal,subs="verbatim,quotes"] +---- +http\://www.mycompany.example/schema/myns/myns.xsd=org/springframework/samples/xml/myns.xsd +---- + +(Remember that the `:` character must be escaped.) + +You are encouraged to deploy your XSD file (or files) right alongside +the `NamespaceHandler` and `BeanDefinitionParser` classes on the classpath. + + + +[[core.appendix.xsd-custom-using]] +== Using a Custom Extension in Your Spring XML Configuration + +Using a custom extension that you yourself have implemented is no different from using +one of the "`custom`" extensions that Spring provides. The following +example uses the custom `` element developed in the previous steps +in a Spring XML configuration file: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + <1> + + + + + + + + + +---- +<1> Our custom bean. + + + +[[core.appendix.xsd-custom-meat]] +== More Detailed Examples + +This section presents some more detailed examples of custom XML extensions. + + +[[core.appendix.xsd-custom-custom-nested]] +=== Nesting Custom Elements within Custom Elements + +The example presented in this section shows how you to write the various artifacts required +to satisfy a target of the following configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + +---- + +The preceding configuration nests custom extensions within each other. The class +that is actually configured by the `` element is the `Component` +class (shown in the next example). Notice how the `Component` class does not expose a +setter method for the `components` property. This makes it hard (or rather impossible) +to configure a bean definition for the `Component` class by using setter injection. +The following listing shows the `Component` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package com.foo; + + import java.util.ArrayList; + import java.util.List; + + public class Component { + + private String name; + private List components = new ArrayList (); + + // there is no setter method for the 'components' + public void addComponent(Component component) { + this.components.add(component); + } + + public List getComponents() { + return components; + } + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.foo + + import java.util.ArrayList + + class Component { + + var name: String? = null + private val components = ArrayList() + + // there is no setter method for the 'components' + fun addComponent(component: Component) { + this.components.add(component) + } + + fun getComponents(): List { + return components + } + } +---- + +The typical solution to this issue is to create a custom `FactoryBean` that exposes a +setter property for the `components` property. The following listing shows such a custom +`FactoryBean`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package com.foo; + + import org.springframework.beans.factory.FactoryBean; + + import java.util.List; + + public class ComponentFactoryBean implements FactoryBean { + + private Component parent; + private List children; + + public void setParent(Component parent) { + this.parent = parent; + } + + public void setChildren(List children) { + this.children = children; + } + + public Component getObject() throws Exception { + if (this.children != null && this.children.size() > 0) { + for (Component child : children) { + this.parent.addComponent(child); + } + } + return this.parent; + } + + public Class getObjectType() { + return Component.class; + } + + public boolean isSingleton() { + return true; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.foo + + import org.springframework.beans.factory.FactoryBean + import org.springframework.stereotype.Component + + class ComponentFactoryBean : FactoryBean { + + private var parent: Component? = null + private var children: List? = null + + fun setParent(parent: Component) { + this.parent = parent + } + + fun setChildren(children: List) { + this.children = children + } + + override fun getObject(): Component? { + if (this.children != null && this.children!!.isNotEmpty()) { + for (child in children!!) { + this.parent!!.addComponent(child) + } + } + return this.parent + } + + override fun getObjectType(): Class? { + return Component::class.java + } + + override fun isSingleton(): Boolean { + return true + } + } +---- + +This works nicely, but it exposes a lot of Spring plumbing to the end user. What we are +going to do is write a custom extension that hides away all of this Spring plumbing. +If we stick to <>, we start off +by creating the XSD schema to define the structure of our custom tag, as the following +listing shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + +---- + +Again following <>, +we then create a custom `NamespaceHandler`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package com.foo; + + import org.springframework.beans.factory.xml.NamespaceHandlerSupport; + + public class ComponentNamespaceHandler extends NamespaceHandlerSupport { + + public void init() { + registerBeanDefinitionParser("component", new ComponentBeanDefinitionParser()); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.foo + + import org.springframework.beans.factory.xml.NamespaceHandlerSupport + + class ComponentNamespaceHandler : NamespaceHandlerSupport() { + + override fun init() { + registerBeanDefinitionParser("component", ComponentBeanDefinitionParser()) + } + } +---- + +Next up is the custom `BeanDefinitionParser`. Remember that we are creating +a `BeanDefinition` that describes a `ComponentFactoryBean`. The following +listing shows our custom `BeanDefinitionParser` implementation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package com.foo; + + import org.springframework.beans.factory.config.BeanDefinition; + import org.springframework.beans.factory.support.AbstractBeanDefinition; + import org.springframework.beans.factory.support.BeanDefinitionBuilder; + import org.springframework.beans.factory.support.ManagedList; + import org.springframework.beans.factory.xml.AbstractBeanDefinitionParser; + import org.springframework.beans.factory.xml.ParserContext; + import org.springframework.util.xml.DomUtils; + import org.w3c.dom.Element; + + import java.util.List; + + public class ComponentBeanDefinitionParser extends AbstractBeanDefinitionParser { + + protected AbstractBeanDefinition parseInternal(Element element, ParserContext parserContext) { + return parseComponentElement(element); + } + + private static AbstractBeanDefinition parseComponentElement(Element element) { + BeanDefinitionBuilder factory = BeanDefinitionBuilder.rootBeanDefinition(ComponentFactoryBean.class); + factory.addPropertyValue("parent", parseComponent(element)); + + List childElements = DomUtils.getChildElementsByTagName(element, "component"); + if (childElements != null && childElements.size() > 0) { + parseChildComponents(childElements, factory); + } + + return factory.getBeanDefinition(); + } + + private static BeanDefinition parseComponent(Element element) { + BeanDefinitionBuilder component = BeanDefinitionBuilder.rootBeanDefinition(Component.class); + component.addPropertyValue("name", element.getAttribute("name")); + return component.getBeanDefinition(); + } + + private static void parseChildComponents(List childElements, BeanDefinitionBuilder factory) { + ManagedList children = new ManagedList<>(childElements.size()); + for (Element element : childElements) { + children.add(parseComponentElement(element)); + } + factory.addPropertyValue("children", children); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.foo + + import org.springframework.beans.factory.config.BeanDefinition + import org.springframework.beans.factory.support.AbstractBeanDefinition + import org.springframework.beans.factory.support.BeanDefinitionBuilder + import org.springframework.beans.factory.support.ManagedList + import org.springframework.beans.factory.xml.AbstractBeanDefinitionParser + import org.springframework.beans.factory.xml.ParserContext + import org.springframework.util.xml.DomUtils + import org.w3c.dom.Element + + import java.util.List + + class ComponentBeanDefinitionParser : AbstractBeanDefinitionParser() { + + override fun parseInternal(element: Element, parserContext: ParserContext): AbstractBeanDefinition? { + return parseComponentElement(element) + } + + private fun parseComponentElement(element: Element): AbstractBeanDefinition { + val factory = BeanDefinitionBuilder.rootBeanDefinition(ComponentFactoryBean::class.java) + factory.addPropertyValue("parent", parseComponent(element)) + + val childElements = DomUtils.getChildElementsByTagName(element, "component") + if (childElements != null && childElements.size > 0) { + parseChildComponents(childElements, factory) + } + + return factory.getBeanDefinition() + } + + private fun parseComponent(element: Element): BeanDefinition { + val component = BeanDefinitionBuilder.rootBeanDefinition(Component::class.java) + component.addPropertyValue("name", element.getAttribute("name")) + return component.beanDefinition + } + + private fun parseChildComponents(childElements: List, factory: BeanDefinitionBuilder) { + val children = ManagedList(childElements.size) + for (element in childElements) { + children.add(parseComponentElement(element)) + } + factory.addPropertyValue("children", children) + } + } +---- + +Finally, the various artifacts need to be registered with the Spring XML infrastructure, +by modifying the `META-INF/spring.handlers` and `META-INF/spring.schemas` files, as follows: + +[literal,subs="verbatim,quotes"] +---- +# in 'META-INF/spring.handlers' +http\://www.foo.example/schema/component=com.foo.ComponentNamespaceHandler +---- + +[literal,subs="verbatim,quotes"] +---- +# in 'META-INF/spring.schemas' +http\://www.foo.example/schema/component/component.xsd=com/foo/component.xsd +---- + + +[[core.appendix.xsd-custom-custom-just-attributes]] +=== Custom Attributes on "`Normal`" Elements + +Writing your own custom parser and the associated artifacts is not hard. However, +it is sometimes not the right thing to do. Consider a scenario where you need to +add metadata to already existing bean definitions. In this case, you certainly +do not want to have to write your own entire custom extension. Rather, you merely +want to add an additional attribute to the existing bean definition element. + +By way of another example, suppose that you define a bean definition for a +service object that (unknown to it) accesses a clustered +https://jcp.org/en/jsr/detail?id=107[JCache], and you want to ensure that the +named JCache instance is eagerly started within the surrounding cluster. +The following listing shows such a definition: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +We can then create another `BeanDefinition` when the +`'jcache:cache-name'` attribute is parsed. This `BeanDefinition` then initializes +the named JCache for us. We can also modify the existing `BeanDefinition` for the +`'checkingAccountService'` so that it has a dependency on this new +JCache-initializing `BeanDefinition`. The following listing shows our `JCacheInitializer`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package com.foo; + + public class JCacheInitializer { + + private final String name; + + public JCacheInitializer(String name) { + this.name = name; + } + + public void initialize() { + // lots of JCache API calls to initialize the named cache... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.foo + + class JCacheInitializer(private val name: String) { + + fun initialize() { + // lots of JCache API calls to initialize the named cache... + } + } +---- + +Now we can move onto the custom extension. First, we need to author +the XSD schema that describes the custom attribute, as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +Next, we need to create the associated `NamespaceHandler`, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package com.foo; + + import org.springframework.beans.factory.xml.NamespaceHandlerSupport; + + public class JCacheNamespaceHandler extends NamespaceHandlerSupport { + + public void init() { + super.registerBeanDefinitionDecoratorForAttribute("cache-name", + new JCacheInitializingBeanDefinitionDecorator()); + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.foo + + import org.springframework.beans.factory.xml.NamespaceHandlerSupport + + class JCacheNamespaceHandler : NamespaceHandlerSupport() { + + override fun init() { + super.registerBeanDefinitionDecoratorForAttribute("cache-name", + JCacheInitializingBeanDefinitionDecorator()) + } + + } +---- + +Next, we need to create the parser. Note that, in this case, because we are going to parse +an XML attribute, we write a `BeanDefinitionDecorator` rather than a `BeanDefinitionParser`. +The following listing shows our `BeanDefinitionDecorator` implementation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package com.foo; + + import org.springframework.beans.factory.config.BeanDefinitionHolder; + import org.springframework.beans.factory.support.AbstractBeanDefinition; + import org.springframework.beans.factory.support.BeanDefinitionBuilder; + import org.springframework.beans.factory.xml.BeanDefinitionDecorator; + import org.springframework.beans.factory.xml.ParserContext; + import org.w3c.dom.Attr; + import org.w3c.dom.Node; + + import java.util.ArrayList; + import java.util.Arrays; + import java.util.List; + + public class JCacheInitializingBeanDefinitionDecorator implements BeanDefinitionDecorator { + + private static final String[] EMPTY_STRING_ARRAY = new String[0]; + + public BeanDefinitionHolder decorate(Node source, BeanDefinitionHolder holder, + ParserContext ctx) { + String initializerBeanName = registerJCacheInitializer(source, ctx); + createDependencyOnJCacheInitializer(holder, initializerBeanName); + return holder; + } + + private void createDependencyOnJCacheInitializer(BeanDefinitionHolder holder, + String initializerBeanName) { + AbstractBeanDefinition definition = ((AbstractBeanDefinition) holder.getBeanDefinition()); + String[] dependsOn = definition.getDependsOn(); + if (dependsOn == null) { + dependsOn = new String[]{initializerBeanName}; + } else { + List dependencies = new ArrayList(Arrays.asList(dependsOn)); + dependencies.add(initializerBeanName); + dependsOn = (String[]) dependencies.toArray(EMPTY_STRING_ARRAY); + } + definition.setDependsOn(dependsOn); + } + + private String registerJCacheInitializer(Node source, ParserContext ctx) { + String cacheName = ((Attr) source).getValue(); + String beanName = cacheName + "-initializer"; + if (!ctx.getRegistry().containsBeanDefinition(beanName)) { + BeanDefinitionBuilder initializer = BeanDefinitionBuilder.rootBeanDefinition(JCacheInitializer.class); + initializer.addConstructorArg(cacheName); + ctx.getRegistry().registerBeanDefinition(beanName, initializer.getBeanDefinition()); + } + return beanName; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.foo + + import org.springframework.beans.factory.config.BeanDefinitionHolder + import org.springframework.beans.factory.support.AbstractBeanDefinition + import org.springframework.beans.factory.support.BeanDefinitionBuilder + import org.springframework.beans.factory.xml.BeanDefinitionDecorator + import org.springframework.beans.factory.xml.ParserContext + import org.w3c.dom.Attr + import org.w3c.dom.Node + + import java.util.ArrayList + + class JCacheInitializingBeanDefinitionDecorator : BeanDefinitionDecorator { + + override fun decorate(source: Node, holder: BeanDefinitionHolder, + ctx: ParserContext): BeanDefinitionHolder { + val initializerBeanName = registerJCacheInitializer(source, ctx) + createDependencyOnJCacheInitializer(holder, initializerBeanName) + return holder + } + + private fun createDependencyOnJCacheInitializer(holder: BeanDefinitionHolder, + initializerBeanName: String) { + val definition = holder.beanDefinition as AbstractBeanDefinition + var dependsOn = definition.dependsOn + dependsOn = if (dependsOn == null) { + arrayOf(initializerBeanName) + } else { + val dependencies = ArrayList(listOf(*dependsOn)) + dependencies.add(initializerBeanName) + dependencies.toTypedArray() + } + definition.setDependsOn(*dependsOn) + } + + private fun registerJCacheInitializer(source: Node, ctx: ParserContext): String { + val cacheName = (source as Attr).value + val beanName = "$cacheName-initializer" + if (!ctx.registry.containsBeanDefinition(beanName)) { + val initializer = BeanDefinitionBuilder.rootBeanDefinition(JCacheInitializer::class.java) + initializer.addConstructorArg(cacheName) + ctx.registry.registerBeanDefinition(beanName, initializer.getBeanDefinition()) + } + return beanName + } + } +---- + +Finally, we need to register the various artifacts with the Spring XML infrastructure +by modifying the `META-INF/spring.handlers` and `META-INF/spring.schemas` files, as follows: + +[literal,subs="verbatim,quotes"] +---- +# in 'META-INF/spring.handlers' +http\://www.foo.example/schema/jcache=com.foo.JCacheNamespaceHandler +---- + +[literal,subs="verbatim,quotes"] +---- +# in 'META-INF/spring.schemas' +http\://www.foo.example/schema/jcache/jcache.xsd=com/foo/jcache.xsd +---- + + diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc new file mode 100644 index 000000000000..c5ab44c73adc --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc @@ -0,0 +1,649 @@ +[[core.appendix.xsd-schemas]] += XML Schemas + +This part of the appendix lists XML schemas related to the core container. + + + +[[core.appendix.xsd-schemas-util]] +== The `util` Schema + +As the name implies, the `util` tags deal with common, utility configuration +issues, such as configuring collections, referencing constants, and so forth. +To use the tags in the `util` schema, you need to have the following preamble at the top +of your Spring XML configuration file (the text in the snippet references the +correct schema so that the tags in the `util` namespace are available to you): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + + +[[core.appendix.xsd-schemas-util-constant]] +=== Using `` + +Consider the following bean definition: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + +---- + +The preceding configuration uses a Spring `FactoryBean` implementation (the +`FieldRetrievingFactoryBean`) to set the value of the `isolation` property on a bean +to the value of the `java.sql.Connection.TRANSACTION_SERIALIZABLE` constant. This is +all well and good, but it is verbose and (unnecessarily) exposes Spring's internal +plumbing to the end user. + +The following XML Schema-based version is more concise, clearly expresses the +developer's intent ("`inject this constant value`"), and it reads better: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + +---- + +[[core.appendix.xsd-schemas-util-frfb]] +==== Setting a Bean Property or Constructor Argument from a Field Value + +{api-spring-framework}/beans/factory/config/FieldRetrievingFactoryBean.html[`FieldRetrievingFactoryBean`] +is a `FactoryBean` that retrieves a `static` or non-static field value. It is typically +used for retrieving `public` `static` `final` constants, which may then be used to set a +property value or constructor argument for another bean. + +The following example shows how a `static` field is exposed, by using the +{api-spring-framework}/beans/factory/config/FieldRetrievingFactoryBean.html#setStaticField(java.lang.String)[`staticField`] +property: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +There is also a convenience usage form where the `static` field is specified as the bean +name, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +This does mean that there is no longer any choice in what the bean `id` is (so any other +bean that refers to it also has to use this longer name), but this form is very +concise to define and very convenient to use as an inner bean since the `id` does not have +to be specified for the bean reference, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + +---- + +You can also access a non-static (instance) field of another bean, as +described in the API documentation for the +{api-spring-framework}/beans/factory/config/FieldRetrievingFactoryBean.html[`FieldRetrievingFactoryBean`] +class. + +Injecting enumeration values into beans as either property or constructor arguments is +easy to do in Spring. You do not actually have to do anything or know anything about +the Spring internals (or even about classes such as the `FieldRetrievingFactoryBean`). +The following example enumeration shows how easy injecting an enum value is: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package jakarta.persistence; + + public enum PersistenceContextType { + + TRANSACTION, + EXTENDED + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package jakarta.persistence + + enum class PersistenceContextType { + + TRANSACTION, + EXTENDED + } +---- + +Now consider the following setter of type `PersistenceContextType` and the corresponding bean definition: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package example; + + public class Client { + + private PersistenceContextType persistenceContextType; + + public void setPersistenceContextType(PersistenceContextType type) { + this.persistenceContextType = type; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package example + + class Client { + + lateinit var persistenceContextType: PersistenceContextType + } +---- + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + + +[[core.appendix.xsd-schemas-util-property-path]] +=== Using `` + +Consider the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + +---- + +The preceding configuration uses a Spring `FactoryBean` implementation (the +`PropertyPathFactoryBean`) to create a bean (of type `int`) called `testBean.age` that +has a value equal to the `age` property of the `testBean` bean. + +Now consider the following example, which adds a `` element: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + +---- + +The value of the `path` attribute of the `` element follows the form of +`beanName.beanProperty`. In this case, it picks up the `age` property of the bean named +`testBean`. The value of that `age` property is `10`. + +[[core.appendix.xsd-schemas-util-property-path-dependency]] +==== Using `` to Set a Bean Property or Constructor Argument + +`PropertyPathFactoryBean` is a `FactoryBean` that evaluates a property path on a given +target object. The target object can be specified directly or by a bean name. You can then use this +value in another bean definition as a property value or constructor +argument. + +The following example shows a path being used against another bean, by name: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + +---- + +In the following example, a path is evaluated against an inner bean: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + +---- + +There is also a shortcut form, where the bean name is the property path. +The following example shows the shortcut form: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + +---- + +This form does mean that there is no choice in the name of the bean. Any reference to it +also has to use the same `id`, which is the path. If used as an inner +bean, there is no need to refer to it at all, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + +---- + +You can specifically set the result type in the actual definition. This is not necessary +for most use cases, but it can sometimes be useful. See the javadoc for more info on +this feature. + + +[[core.appendix.xsd-schemas-util-properties]] +=== Using `` + +Consider the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- + +The preceding configuration uses a Spring `FactoryBean` implementation (the +`PropertiesFactoryBean`) to instantiate a `java.util.Properties` instance with values +loaded from the supplied <> location). + +The following example uses a `util:properties` element to make a more concise representation: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + +---- + + +[[core.appendix.xsd-schemas-util-list]] +=== Using `` + +Consider the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + pechorin@hero.org + raskolnikov@slums.org + stavrogin@gov.org + porfiry@gov.org + + + +---- + +The preceding configuration uses a Spring `FactoryBean` implementation (the +`ListFactoryBean`) to create a `java.util.List` instance and initialize it with values taken +from the supplied `sourceList`. + +The following example uses a `` element to make a more concise representation: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + pechorin@hero.org + raskolnikov@slums.org + stavrogin@gov.org + porfiry@gov.org + +---- + +You can also explicitly control the exact type of `List` that is instantiated and +populated by using the `list-class` attribute on the `` element. For +example, if we really need a `java.util.LinkedList` to be instantiated, we could use the +following configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + jackshaftoe@vagabond.org + eliza@thinkingmanscrumpet.org + vanhoek@pirate.org + d'Arcachon@nemesis.org + +---- + +If no `list-class` attribute is supplied, the container chooses a `List` implementation. + + +[[core.appendix.xsd-schemas-util-map]] +=== Using `` + +Consider the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + +---- + +The preceding configuration uses a Spring `FactoryBean` implementation (the +`MapFactoryBean`) to create a `java.util.Map` instance initialized with key-value pairs +taken from the supplied `'sourceMap'`. + +The following example uses a `` element to make a more concise representation: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +You can also explicitly control the exact type of `Map` that is instantiated and +populated by using the `'map-class'` attribute on the `` element. For +example, if we really need a `java.util.TreeMap` to be instantiated, we could use the +following configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + +If no `'map-class'` attribute is supplied, the container chooses a `Map` implementation. + + +[[core.appendix.xsd-schemas-util-set]] +=== Using `` + +Consider the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + pechorin@hero.org + raskolnikov@slums.org + stavrogin@gov.org + porfiry@gov.org + + + +---- + +The preceding configuration uses a Spring `FactoryBean` implementation (the +`SetFactoryBean`) to create a `java.util.Set` instance initialized with values taken +from the supplied `sourceSet`. + +The following example uses a `` element to make a more concise representation: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + pechorin@hero.org + raskolnikov@slums.org + stavrogin@gov.org + porfiry@gov.org + +---- + +You can also explicitly control the exact type of `Set` that is instantiated and +populated by using the `set-class` attribute on the `` element. For +example, if we really need a `java.util.TreeSet` to be instantiated, we could use the +following configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + pechorin@hero.org + raskolnikov@slums.org + stavrogin@gov.org + porfiry@gov.org + +---- + +If no `set-class` attribute is supplied, the container chooses a `Set` implementation. + + + +[[core.appendix.xsd-schemas-aop]] +== The `aop` Schema + +The `aop` tags deal with configuring all things AOP in Spring, including Spring's +own proxy-based AOP framework and Spring's integration with the AspectJ AOP framework. +These tags are comprehensively covered in the chapter entitled <>. + +In the interest of completeness, to use the tags in the `aop` schema, you need to have +the following preamble at the top of your Spring XML configuration file (the text in the +snippet references the correct schema so that the tags in the `aop` namespace +are available to you): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + + + +[[core.appendix.xsd-schemas-context]] +== The `context` Schema + +The `context` tags deal with `ApplicationContext` configuration that relates to plumbing +-- that is, not usually beans that are important to an end-user but rather beans that do +a lot of the "`grunt`" work in Spring, such as `BeanfactoryPostProcessors`. The following +snippet references the correct schema so that the elements in the `context` namespace are +available to you: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + + +[[core.appendix.xsd-schemas-context-pphc]] +=== Using `` + +This element activates the replacement of `${...}` placeholders, which are resolved against a +specified properties file (as a <>). This element +is a convenience mechanism that sets up a <> for you. If you need more control over the specific +`PropertySourcesPlaceholderConfigurer` setup, you can explicitly define it as a bean yourself. + + +[[core.appendix.xsd-schemas-context-ac]] +=== Using `` + +This element activates the Spring infrastructure to detect annotations in bean classes: + +* Spring's <> model +* <>, `@Value`, and `@Lookup` +* JSR-250's `@Resource`, `@PostConstruct`, and `@PreDestroy` (if available) +* JAX-WS's `@WebServiceRef` and EJB 3's `@EJB` (if available) +* JPA's `@PersistenceContext` and `@PersistenceUnit` (if available) +* Spring's <> + +Alternatively, you can choose to explicitly activate the individual `BeanPostProcessors` +for those annotations. + +NOTE: This element does not activate processing of Spring's +<> annotation; +you can use the <`>> +element for that purpose. Similarly, Spring's +<> need to be explicitly +<> as well. + + +[[core.appendix.xsd-schemas-context-component-scan]] +=== Using `` + +This element is detailed in the section on <>. + + +[[core.appendix.xsd-schemas-context-ltw]] +=== Using `` + +This element is detailed in the section on <>. + + +[[core.appendix.xsd-schemas-context-sc]] +=== Using `` + +This element is detailed in the section on <>. + + +[[core.appendix.xsd-schemas-context-mbe]] +=== Using `` + +This element is detailed in the section on <>. + + + +[[core.appendix.xsd-schemas-beans]] +== The Beans Schema + +Last but not least, we have the elements in the `beans` schema. These elements +have been in Spring since the very dawn of the framework. Examples of the various elements +in the `beans` schema are not shown here because they are quite comprehensively covered +in <> +(and, indeed, in that entire <>). + +Note that you can add zero or more key-value pairs to `` XML definitions. +What, if anything, is done with this extra metadata is totally up to your own custom +logic (and so is typically only of use if you write your own custom elements as described +in the appendix entitled <>). + +The following example shows the `` element in the context of a surrounding `` +(note that, without any logic to interpret it, the metadata is effectively useless +as it stands). + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + <1> + + + + +---- +<1> This is the example `meta` element + +In the case of the preceding example, you could assume that there is some logic that consumes +the bean definition and sets up some caching infrastructure that uses the supplied metadata. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans.adoc b/framework-docs/modules/ROOT/pages/core/beans.adoc index 064d8376332e..f5b17d5fe462 100644 --- a/framework-docs/modules/ROOT/pages/core/beans.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans.adoc @@ -6,11293 +6,3 @@ This chapter covers Spring's Inversion of Control (IoC) container. -[[beans-introduction]] -== Introduction to the Spring IoC Container and Beans - -This chapter covers the Spring Framework implementation of the Inversion of Control -(IoC) principle. IoC is also known as dependency injection (DI). It is a process whereby -objects define their dependencies (that is, the other objects they work with) only through -constructor arguments, arguments to a factory method, or properties that are set on the -object instance after it is constructed or returned from a factory method. The container -then injects those dependencies when it creates the bean. This process is fundamentally -the inverse (hence the name, Inversion of Control) of the bean itself -controlling the instantiation or location of its dependencies by using direct -construction of classes or a mechanism such as the Service Locator pattern. - -The `org.springframework.beans` and `org.springframework.context` packages are the basis -for Spring Framework's IoC container. The -{api-spring-framework}/beans/factory/BeanFactory.html[`BeanFactory`] -interface provides an advanced configuration mechanism capable of managing any type of -object. -{api-spring-framework}/context/ApplicationContext.html[`ApplicationContext`] -is a sub-interface of `BeanFactory`. It adds: - -* Easier integration with Spring's AOP features -* Message resource handling (for use in internationalization) -* Event publication -* Application-layer specific contexts such as the `WebApplicationContext` -for use in web applications. - -In short, the `BeanFactory` provides the configuration framework and basic functionality, -and the `ApplicationContext` adds more enterprise-specific functionality. The -`ApplicationContext` is a complete superset of the `BeanFactory` and is used exclusively -in this chapter in descriptions of Spring's IoC container. For more information on using -the `BeanFactory` instead of the `ApplicationContext,` see the section covering the -<>. - -In Spring, the objects that form the backbone of your application and that are managed -by the Spring IoC container are called beans. A bean is an object that is -instantiated, assembled, and managed by a Spring IoC container. Otherwise, a -bean is simply one of many objects in your application. Beans, and the dependencies -among them, are reflected in the configuration metadata used by a container. - - - - -[[beans-basics]] -== Container Overview - -The `org.springframework.context.ApplicationContext` interface represents the Spring IoC -container and is responsible for instantiating, configuring, and assembling the -beans. The container gets its instructions on what objects to -instantiate, configure, and assemble by reading configuration metadata. The -configuration metadata is represented in XML, Java annotations, or Java code. It lets -you express the objects that compose your application and the rich interdependencies -between those objects. - -Several implementations of the `ApplicationContext` interface are supplied -with Spring. In stand-alone applications, it is common to create an -instance of -{api-spring-framework}/context/support/ClassPathXmlApplicationContext.html[`ClassPathXmlApplicationContext`] -or {api-spring-framework}/context/support/FileSystemXmlApplicationContext.html[`FileSystemXmlApplicationContext`]. -While XML has been the traditional format for defining configuration metadata, you can -instruct the container to use Java annotations or code as the metadata format by -providing a small amount of XML configuration to declaratively enable support for these -additional metadata formats. - -In most application scenarios, explicit user code is not required to instantiate one or -more instances of a Spring IoC container. For example, in a web application scenario, a -simple eight (or so) lines of boilerplate web descriptor XML in the `web.xml` file -of the application typically suffices (see <>). If you use the -https://spring.io/tools[Spring Tools for Eclipse] (an Eclipse-powered development -environment), you can easily create this boilerplate configuration with a few mouse clicks or -keystrokes. - -The following diagram shows a high-level view of how Spring works. Your application classes -are combined with configuration metadata so that, after the `ApplicationContext` is -created and initialized, you have a fully configured and executable system or -application. - -.The Spring IoC container -image::container-magic.png[] - - - -[[beans-factory-metadata]] -=== Configuration Metadata - -As the preceding diagram shows, the Spring IoC container consumes a form of -configuration metadata. This configuration metadata represents how you, as an -application developer, tell the Spring container to instantiate, configure, and assemble -the objects in your application. - -Configuration metadata is traditionally supplied in a simple and intuitive XML format, -which is what most of this chapter uses to convey key concepts and features of the -Spring IoC container. - -NOTE: XML-based metadata is not the only allowed form of configuration metadata. -The Spring IoC container itself is totally decoupled from the format in which this -configuration metadata is actually written. These days, many developers choose -<> for their Spring applications. - -For information about using other forms of metadata with the Spring container, see: - -* <>: define beans using - annotation-based configuration metadata. -* <>: define beans external to your application - classes by using Java rather than XML files. To use these features, see the - {api-spring-framework}/context/annotation/Configuration.html[`@Configuration`], - {api-spring-framework}/context/annotation/Bean.html[`@Bean`], - {api-spring-framework}/context/annotation/Import.html[`@Import`], - and {api-spring-framework}/context/annotation/DependsOn.html[`@DependsOn`] annotations. - -Spring configuration consists of at least one and typically more than one bean -definition that the container must manage. XML-based configuration metadata configures these -beans as `` elements inside a top-level `` element. Java -configuration typically uses `@Bean`-annotated methods within a `@Configuration` class. - -These bean definitions correspond to the actual objects that make up your application. -Typically, you define service layer objects, persistence layer objects such as -repositories or data access objects (DAOs), presentation objects such as Web controllers, -infrastructure objects such as a JPA `EntityManagerFactory`, JMS queues, and so forth. -Typically, one does not configure fine-grained domain objects in the container, because -it is usually the responsibility of repositories and business logic to create and load -domain objects. - -The following example shows the basic structure of XML-based configuration metadata: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - <1> <2> - - - - - - - - - - ----- - -<1> The `id` attribute is a string that identifies the individual bean definition. -<2> The `class` attribute defines the type of the bean and uses the fully qualified -class name. - -The value of the `id` attribute can be used to refer to collaborating objects. The XML -for referring to collaborating objects is not shown in this example. See -<> for more information. - - - -[[beans-factory-instantiation]] -=== Instantiating a Container - -The location path or paths -supplied to an `ApplicationContext` constructor are resource strings that let -the container load configuration metadata from a variety of external resources, such -as the local file system, the Java `CLASSPATH`, and so on. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ApplicationContext context = new ClassPathXmlApplicationContext("services.xml", "daos.xml"); ----- -.Kotlin -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] ----- - val context = ClassPathXmlApplicationContext("services.xml", "daos.xml") ----- - -[NOTE] -==== -After you learn about Spring's IoC container, you may want to know more about Spring's -`Resource` abstraction (as described in <>), which provides a convenient -mechanism for reading an InputStream from locations defined in a URI syntax. In particular, -`Resource` paths are used to construct applications contexts, as described in <>. -==== - -The following example shows the service layer objects `(services.xml)` configuration file: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - ----- - -The following example shows the data access objects `daos.xml` file: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - ----- - -In the preceding example, the service layer consists of the `PetStoreServiceImpl` class -and two data access objects of the types `JpaAccountDao` and `JpaItemDao` (based -on the JPA Object-Relational Mapping standard). The `property name` element refers to the -name of the JavaBean property, and the `ref` element refers to the name of another bean -definition. This linkage between `id` and `ref` elements expresses the dependency between -collaborating objects. For details of configuring an object's dependencies, see -<>. - - -[[beans-factory-xml-import]] -==== Composing XML-based Configuration Metadata - -It can be useful to have bean definitions span multiple XML files. Often, each individual -XML configuration file represents a logical layer or module in your architecture. - -You can use the application context constructor to load bean definitions from all these -XML fragments. This constructor takes multiple `Resource` locations, as was shown in the -<>. Alternatively, use one or more -occurrences of the `` element to load bean definitions from another file or -files. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -In the preceding example, external bean definitions are loaded from three files: -`services.xml`, `messageSource.xml`, and `themeSource.xml`. All location paths are -relative to the definition file doing the importing, so `services.xml` must be in the -same directory or classpath location as the file doing the importing, while -`messageSource.xml` and `themeSource.xml` must be in a `resources` location below the -location of the importing file. As you can see, a leading slash is ignored. However, given -that these paths are relative, it is better form not to use the slash at all. The -contents of the files being imported, including the top level `` element, must -be valid XML bean definitions, according to the Spring Schema. - -[NOTE] -==== -It is possible, but not recommended, to reference files in parent directories using a -relative "../" path. Doing so creates a dependency on a file that is outside the current -application. In particular, this reference is not recommended for `classpath:` URLs (for -example, `classpath:../services.xml`), where the runtime resolution process chooses the -"`nearest`" classpath root and then looks into its parent directory. Classpath -configuration changes may lead to the choice of a different, incorrect directory. - -You can always use fully qualified resource locations instead of relative paths: for -example, `file:C:/config/services.xml` or `classpath:/config/services.xml`. However, be -aware that you are coupling your application's configuration to specific absolute -locations. It is generally preferable to keep an indirection for such absolute -locations -- for example, through "${...}" placeholders that are resolved against JVM -system properties at runtime. -==== - -The namespace itself provides the import directive feature. Further -configuration features beyond plain bean definitions are available in a selection -of XML namespaces provided by Spring -- for example, the `context` and `util` namespaces. - - -[[groovy-bean-definition-dsl]] -==== The Groovy Bean Definition DSL - -As a further example for externalized configuration metadata, bean definitions can also -be expressed in Spring's Groovy Bean Definition DSL, as known from the Grails framework. -Typically, such configuration live in a ".groovy" file with the structure shown in the -following example: - -[source,groovy,indent=0,subs="verbatim,quotes"] ----- - beans { - dataSource(BasicDataSource) { - driverClassName = "org.hsqldb.jdbcDriver" - url = "jdbc:hsqldb:mem:grailsDB" - username = "sa" - password = "" - settings = [mynew:"setting"] - } - sessionFactory(SessionFactory) { - dataSource = dataSource - } - myService(MyService) { - nestedBean = { AnotherBean bean -> - dataSource = dataSource - } - } - } ----- - -This configuration style is largely equivalent to XML bean definitions and even -supports Spring's XML configuration namespaces. It also allows for importing XML -bean definition files through an `importBeans` directive. - - - -[[beans-factory-client]] -=== Using the Container - -The `ApplicationContext` is the interface for an advanced factory capable of maintaining -a registry of different beans and their dependencies. By using the method -`T getBean(String name, Class requiredType)`, you can retrieve instances of your beans. - -The `ApplicationContext` lets you read bean definitions and access them, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // create and configure beans - ApplicationContext context = new ClassPathXmlApplicationContext("services.xml", "daos.xml"); - - // retrieve configured instance - PetStoreService service = context.getBean("petStore", PetStoreService.class); - - // use configured instance - List userList = service.getUsernameList(); ----- -.Kotlin -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] ----- - import org.springframework.beans.factory.getBean - - // create and configure beans - val context = ClassPathXmlApplicationContext("services.xml", "daos.xml") - - // retrieve configured instance - val service = context.getBean("petStore") - - // use configured instance - var userList = service.getUsernameList() ----- - -With Groovy configuration, bootstrapping looks very similar. It has a different context -implementation class which is Groovy-aware (but also understands XML bean definitions). -The following example shows Groovy configuration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ApplicationContext context = new GenericGroovyApplicationContext("services.groovy", "daos.groovy"); ----- -.Kotlin -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] ----- -val context = GenericGroovyApplicationContext("services.groovy", "daos.groovy") ----- - -The most flexible variant is `GenericApplicationContext` in combination with reader -delegates -- for example, with `XmlBeanDefinitionReader` for XML files, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - GenericApplicationContext context = new GenericApplicationContext(); - new XmlBeanDefinitionReader(context).loadBeanDefinitions("services.xml", "daos.xml"); - context.refresh(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val context = GenericApplicationContext() - XmlBeanDefinitionReader(context).loadBeanDefinitions("services.xml", "daos.xml") - context.refresh() ----- - -You can also use the `GroovyBeanDefinitionReader` for Groovy files, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - GenericApplicationContext context = new GenericApplicationContext(); - new GroovyBeanDefinitionReader(context).loadBeanDefinitions("services.groovy", "daos.groovy"); - context.refresh(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val context = GenericApplicationContext() - GroovyBeanDefinitionReader(context).loadBeanDefinitions("services.groovy", "daos.groovy") - context.refresh() ----- - -You can mix and match such reader delegates on the same `ApplicationContext`, -reading bean definitions from diverse configuration sources. - -You can then use `getBean` to retrieve instances of your beans. The `ApplicationContext` -interface has a few other methods for retrieving beans, but, ideally, your application -code should never use them. Indeed, your application code should have no calls to the -`getBean()` method at all and thus have no dependency on Spring APIs at all. For example, -Spring's integration with web frameworks provides dependency injection for various web -framework components such as controllers and JSF-managed beans, letting you declare -a dependency on a specific bean through metadata (such as an autowiring annotation). - - - - -[[beans-definition]] -== Bean Overview - -A Spring IoC container manages one or more beans. These beans are created with the -configuration metadata that you supply to the container (for example, in the form of XML -`` definitions). - -Within the container itself, these bean definitions are represented as `BeanDefinition` -objects, which contain (among other information) the following metadata: - -* A package-qualified class name: typically, the actual implementation class of the - bean being defined. -* Bean behavioral configuration elements, which state how the bean should behave in the - container (scope, lifecycle callbacks, and so forth). -* References to other beans that are needed for the bean to do its work. These - references are also called collaborators or dependencies. -* Other configuration settings to set in the newly created object -- for example, the size - limit of the pool or the number of connections to use in a bean that manages a - connection pool. - -This metadata translates to a set of properties that make up each bean definition. -The following table describes these properties: - -[[beans-factory-bean-definition-tbl]] -.The bean definition -|=== -| Property| Explained in... - -| Class -| <> - -| Name -| <> - -| Scope -| <> - -| Constructor arguments -| <> - -| Properties -| <> - -| Autowiring mode -| <> - -| Lazy initialization mode -| <> - -| Initialization method -| <> - -| Destruction method -| <> -|=== - -In addition to bean definitions that contain information on how to create a specific -bean, the `ApplicationContext` implementations also permit the registration of existing -objects that are created outside the container (by users). This is done by accessing the -ApplicationContext's `BeanFactory` through the `getBeanFactory()` method, which returns -the `DefaultListableBeanFactory` implementation. `DefaultListableBeanFactory` supports -this registration through the `registerSingleton(..)` and `registerBeanDefinition(..)` -methods. However, typical applications work solely with beans defined through regular -bean definition metadata. - -[NOTE] -==== -Bean metadata and manually supplied singleton instances need to be registered as early -as possible, in order for the container to properly reason about them during autowiring -and other introspection steps. While overriding existing metadata and existing -singleton instances is supported to some degree, the registration of new beans at -runtime (concurrently with live access to the factory) is not officially supported and may -lead to concurrent access exceptions, inconsistent state in the bean container, or both. -==== - - - -[[beans-beanname]] -=== Naming Beans - -Every bean has one or more identifiers. These identifiers must be unique within the -container that hosts the bean. A bean usually has only one identifier. However, if it -requires more than one, the extra ones can be considered aliases. - -In XML-based configuration metadata, you use the `id` attribute, the `name` attribute, or -both to specify bean identifiers. The `id` attribute lets you specify exactly one `id`. -Conventionally, these names are alphanumeric ('myBean', 'someService', etc.), but they -can contain special characters as well. If you want to introduce other aliases for the -bean, you can also specify them in the `name` attribute, separated by a comma (`,`), -semicolon (`;`), or white space. Although the `id` attribute is defined as an -`xsd:string` type, bean `id` uniqueness is enforced by the container, though not by XML -parsers. - -You are not required to supply a `name` or an `id` for a bean. If you do not supply a -`name` or `id` explicitly, the container generates a unique name for that bean. However, -if you want to refer to that bean by name, through the use of the `ref` element or a -Service Locator style lookup, you must provide a name. -Motivations for not supplying a name are related to using <> and <>. - -.Bean Naming Conventions -**** -The convention is to use the standard Java convention for instance field names when -naming beans. That is, bean names start with a lowercase letter and are camel-cased -from there. Examples of such names include `accountManager`, -`accountService`, `userDao`, `loginController`, and so forth. - -Naming beans consistently makes your configuration easier to read and understand. -Also, if you use Spring AOP, it helps a lot when applying advice to a set of beans -related by name. -**** - -NOTE: With component scanning in the classpath, Spring generates bean names for unnamed -components, following the rules described earlier: essentially, taking the simple class name -and turning its initial character to lower-case. However, in the (unusual) special -case when there is more than one character and both the first and second characters -are upper case, the original casing gets preserved. These are the same rules as -defined by `java.beans.Introspector.decapitalize` (which Spring uses here). - - -[[beans-beanname-alias]] -==== Aliasing a Bean outside the Bean Definition - -In a bean definition itself, you can supply more than one name for the bean, by using a -combination of up to one name specified by the `id` attribute and any number of other -names in the `name` attribute. These names can be equivalent aliases to the same bean -and are useful for some situations, such as letting each component in an application -refer to a common dependency by using a bean name that is specific to that component -itself. - -Specifying all aliases where the bean is actually defined is not always adequate, -however. It is sometimes desirable to introduce an alias for a bean that is defined -elsewhere. This is commonly the case in large systems where configuration is split -amongst each subsystem, with each subsystem having its own set of object definitions. -In XML-based configuration metadata, you can use the `` element to accomplish -this. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -In this case, a bean (in the same container) named `fromName` may also, -after the use of this alias definition, be referred to as `toName`. - -For example, the configuration metadata for subsystem A may refer to a DataSource by the -name of `subsystemA-dataSource`. The configuration metadata for subsystem B may refer to -a DataSource by the name of `subsystemB-dataSource`. When composing the main application -that uses both these subsystems, the main application refers to the DataSource by the -name of `myApp-dataSource`. To have all three names refer to the same object, you can -add the following alias definitions to the configuration metadata: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ----- - -Now each component and the main application can refer to the dataSource through a name -that is unique and guaranteed not to clash with any other definition (effectively -creating a namespace), yet they refer to the same bean. - -.Java-configuration -**** -If you use Java Configuration, the `@Bean` annotation can be used to provide aliases. -See <> for details. -**** - - - -[[beans-factory-class]] -=== Instantiating Beans - -A bean definition is essentially a recipe for creating one or more objects. The -container looks at the recipe for a named bean when asked and uses the configuration -metadata encapsulated by that bean definition to create (or acquire) an actual object. - -If you use XML-based configuration metadata, you specify the type (or class) of object -that is to be instantiated in the `class` attribute of the `` element. This -`class` attribute (which, internally, is a `Class` property on a `BeanDefinition` -instance) is usually mandatory. (For exceptions, see -<> and <>.) -You can use the `Class` property in one of two ways: - -* Typically, to specify the bean class to be constructed in the case where the container - itself directly creates the bean by calling its constructor reflectively, somewhat - equivalent to Java code with the `new` operator. -* To specify the actual class containing the `static` factory method that is - invoked to create the object, in the less common case where the container invokes a - `static` factory method on a class to create the bean. The object type returned - from the invocation of the `static` factory method may be the same class or another - class entirely. - -.Nested class names -**** -If you want to configure a bean definition for a nested class, you may use either the -binary name or the source name of the nested class. - -For example, if you have a class called `SomeThing` in the `com.example` package, and -this `SomeThing` class has a `static` nested class called `OtherThing`, they can be -separated by a dollar sign (`$`) or a dot (`.`). So the value of the `class` attribute in -a bean definition would be `com.example.SomeThing$OtherThing` or -`com.example.SomeThing.OtherThing`. -**** - - -[[beans-factory-class-ctor]] -==== Instantiation with a Constructor - -When you create a bean by the constructor approach, all normal classes are usable by and -compatible with Spring. That is, the class being developed does not need to implement -any specific interfaces or to be coded in a specific fashion. Simply specifying the bean -class should suffice. However, depending on what type of IoC you use for that specific -bean, you may need a default (empty) constructor. - -The Spring IoC container can manage virtually any class you want it to manage. It is -not limited to managing true JavaBeans. Most Spring users prefer actual JavaBeans with -only a default (no-argument) constructor and appropriate setters and getters modeled -after the properties in the container. You can also have more exotic non-bean-style -classes in your container. If, for example, you need to use a legacy connection pool -that absolutely does not adhere to the JavaBean specification, Spring can manage it as -well. - -With XML-based configuration metadata you can specify your bean class as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -For details about the mechanism for supplying arguments to the constructor (if required) -and setting object instance properties after the object is constructed, see -<>. - - -[[beans-factory-class-static-factory-method]] -==== Instantiation with a Static Factory Method - -When defining a bean that you create with a static factory method, use the `class` -attribute to specify the class that contains the `static` factory method and an attribute -named `factory-method` to specify the name of the factory method itself. You should be -able to call this method (with optional arguments, as described later) and return a live -object, which subsequently is treated as if it had been created through a constructor. -One use for such a bean definition is to call `static` factories in legacy code. - -The following bean definition specifies that the bean will be created by calling a -factory method. The definition does not specify the type (class) of the returned object, -but rather the class containing the factory method. In this example, the -`createInstance()` method must be a `static` method. The following example shows how to -specify a factory method: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -The following example shows a class that would work with the preceding bean definition: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ClientService { - private static ClientService clientService = new ClientService(); - private ClientService() {} - - public static ClientService createInstance() { - return clientService; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ClientService private constructor() { - companion object { - private val clientService = ClientService() - @JvmStatic - fun createInstance() = clientService - } - } ----- - -For details about the mechanism for supplying (optional) arguments to the factory method -and setting object instance properties after the object is returned from the factory, -see <>. - - -[[beans-factory-class-instance-factory-method]] -==== Instantiation by Using an Instance Factory Method - -Similar to instantiation through a <>, instantiation with an instance factory method invokes a non-static -method of an existing bean from the container to create a new bean. To use this -mechanism, leave the `class` attribute empty and, in the `factory-bean` attribute, -specify the name of a bean in the current (or parent or ancestor) container that contains -the instance method that is to be invoked to create the object. Set the name of the -factory method itself with the `factory-method` attribute. The following example shows -how to configure such a bean: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -The following example shows the corresponding class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class DefaultServiceLocator { - - private static ClientService clientService = new ClientServiceImpl(); - - public ClientService createClientServiceInstance() { - return clientService; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class DefaultServiceLocator { - companion object { - private val clientService = ClientServiceImpl() - } - fun createClientServiceInstance(): ClientService { - return clientService - } - } ----- - -One factory class can also hold more than one factory method, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -The following example shows the corresponding class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class DefaultServiceLocator { - - private static ClientService clientService = new ClientServiceImpl(); - - private static AccountService accountService = new AccountServiceImpl(); - - public ClientService createClientServiceInstance() { - return clientService; - } - - public AccountService createAccountServiceInstance() { - return accountService; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class DefaultServiceLocator { - companion object { - private val clientService = ClientServiceImpl() - private val accountService = AccountServiceImpl() - } - - fun createClientServiceInstance(): ClientService { - return clientService - } - - fun createAccountServiceInstance(): AccountService { - return accountService - } - } ----- - -This approach shows that the factory bean itself can be managed and configured through -dependency injection (DI). See <>. - -NOTE: In Spring documentation, "factory bean" refers to a bean that is configured in the -Spring container and that creates objects through an -<> or -<> factory method. By contrast, -`FactoryBean` (notice the capitalization) refers to a Spring-specific -<> implementation class. - - -[[beans-factory-type-determination]] -==== Determining a Bean's Runtime Type - -The runtime type of a specific bean is non-trivial to determine. A specified class in -the bean metadata definition is just an initial class reference, potentially combined -with a declared factory method or being a `FactoryBean` class which may lead to a -different runtime type of the bean, or not being set at all in case of an instance-level -factory method (which is resolved via the specified `factory-bean` name instead). -Additionally, AOP proxying may wrap a bean instance with an interface-based proxy with -limited exposure of the target bean's actual type (just its implemented interfaces). - -The recommended way to find out about the actual runtime type of a particular bean is -a `BeanFactory.getType` call for the specified bean name. This takes all of the above -cases into account and returns the type of object that a `BeanFactory.getBean` call is -going to return for the same bean name. - - - - -[[beans-dependencies]] -== Dependencies - -A typical enterprise application does not consist of a single object (or bean in the -Spring parlance). Even the simplest application has a few objects that work together to -present what the end-user sees as a coherent application. This next section explains how -you go from defining a number of bean definitions that stand alone to a fully realized -application where objects collaborate to achieve a goal. - - - -[[beans-factory-collaborators]] -=== Dependency Injection - -Dependency injection (DI) is a process whereby objects define their dependencies -(that is, the other objects with which they work) only through constructor arguments, -arguments to a factory method, or properties that are set on the object instance after -it is constructed or returned from a factory method. The container then injects those -dependencies when it creates the bean. This process is fundamentally the inverse (hence -the name, Inversion of Control) of the bean itself controlling the instantiation -or location of its dependencies on its own by using direct construction of classes or -the Service Locator pattern. - -Code is cleaner with the DI principle, and decoupling is more effective when objects are -provided with their dependencies. The object does not look up its dependencies and does -not know the location or class of the dependencies. As a result, your classes become easier -to test, particularly when the dependencies are on interfaces or abstract base classes, -which allow for stub or mock implementations to be used in unit tests. - -DI exists in two major variants: <> and <>. - - -[[beans-constructor-injection]] -==== Constructor-based Dependency Injection - -Constructor-based DI is accomplished by the container invoking a constructor with a -number of arguments, each representing a dependency. Calling a `static` factory method -with specific arguments to construct the bean is nearly equivalent, and this discussion -treats arguments to a constructor and to a `static` factory method similarly. The -following example shows a class that can only be dependency-injected with constructor -injection: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleMovieLister { - - // the SimpleMovieLister has a dependency on a MovieFinder - private final MovieFinder movieFinder; - - // a constructor so that the Spring container can inject a MovieFinder - public SimpleMovieLister(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - - // business logic that actually uses the injected MovieFinder is omitted... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // a constructor so that the Spring container can inject a MovieFinder - class SimpleMovieLister(private val movieFinder: MovieFinder) { - // business logic that actually uses the injected MovieFinder is omitted... - } ----- - -Notice that there is nothing special about this class. It is a POJO that -has no dependencies on container specific interfaces, base classes, or annotations. - -[[beans-factory-ctor-arguments-resolution]] -===== Constructor Argument Resolution - -Constructor argument resolution matching occurs by using the argument's type. If no -potential ambiguity exists in the constructor arguments of a bean definition, the -order in which the constructor arguments are defined in a bean definition is the order -in which those arguments are supplied to the appropriate constructor when the bean is -being instantiated. Consider the following class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package x.y; - - public class ThingOne { - - public ThingOne(ThingTwo thingTwo, ThingThree thingThree) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package x.y - - class ThingOne(thingTwo: ThingTwo, thingThree: ThingThree) ----- - -Assuming that the `ThingTwo` and `ThingThree` classes are not related by inheritance, no -potential ambiguity exists. Thus, the following configuration works fine, and you do not -need to specify the constructor argument indexes or types explicitly in the -`` element. - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - ----- - -When another bean is referenced, the type is known, and matching can occur (as was the -case with the preceding example). When a simple type is used, such as -`true`, Spring cannot determine the type of the value, and so cannot match -by type without help. Consider the following class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package examples; - - public class ExampleBean { - - // Number of years to calculate the Ultimate Answer - private final int years; - - // The Answer to Life, the Universe, and Everything - private final String ultimateAnswer; - - public ExampleBean(int years, String ultimateAnswer) { - this.years = years; - this.ultimateAnswer = ultimateAnswer; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package examples - - class ExampleBean( - private val years: Int, // Number of years to calculate the Ultimate Answer - private val ultimateAnswer: String // The Answer to Life, the Universe, and Everything - ) ----- - -.[[beans-factory-ctor-arguments-type]]Constructor argument type matching --- -In the preceding scenario, the container can use type matching with simple types if -you explicitly specify the type of the constructor argument by using the `type` attribute, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- --- - -.[[beans-factory-ctor-arguments-index]]Constructor argument index --- -You can use the `index` attribute to specify explicitly the index of constructor arguments, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - -In addition to resolving the ambiguity of multiple simple values, specifying an index -resolves ambiguity where a constructor has two arguments of the same type. - -NOTE: The index is 0-based. --- - -.[[beans-factory-ctor-arguments-name]]Constructor argument name --- -You can also use the constructor parameter name for value disambiguation, as the following -example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - -Keep in mind that, to make this work out of the box, your code must be compiled with the -debug flag enabled so that Spring can look up the parameter name from the constructor. -If you cannot or do not want to compile your code with the debug flag, you can use the -https://download.oracle.com/javase/8/docs/api/java/beans/ConstructorProperties.html[@ConstructorProperties] -JDK annotation to explicitly name your constructor arguments. The sample class would -then have to look as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package examples; - - public class ExampleBean { - - // Fields omitted - - @ConstructorProperties({"years", "ultimateAnswer"}) - public ExampleBean(int years, String ultimateAnswer) { - this.years = years; - this.ultimateAnswer = ultimateAnswer; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package examples - - class ExampleBean - @ConstructorProperties("years", "ultimateAnswer") - constructor(val years: Int, val ultimateAnswer: String) ----- --- - - -[[beans-setter-injection]] -==== Setter-based Dependency Injection - -Setter-based DI is accomplished by the container calling setter methods on your -beans after invoking a no-argument constructor or a no-argument `static` factory method to -instantiate your bean. - -The following example shows a class that can only be dependency-injected by using pure -setter injection. This class is conventional Java. It is a POJO that has no dependencies -on container specific interfaces, base classes, or annotations. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleMovieLister { - - // the SimpleMovieLister has a dependency on the MovieFinder - private MovieFinder movieFinder; - - // a setter method so that the Spring container can inject a MovieFinder - public void setMovieFinder(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - - // business logic that actually uses the injected MovieFinder is omitted... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -class SimpleMovieLister { - - // a late-initialized property so that the Spring container can inject a MovieFinder - lateinit var movieFinder: MovieFinder - - // business logic that actually uses the injected MovieFinder is omitted... -} ----- - - -The `ApplicationContext` supports constructor-based and setter-based DI for the beans it -manages. It also supports setter-based DI after some dependencies have already been -injected through the constructor approach. You configure the dependencies in the form of -a `BeanDefinition`, which you use in conjunction with `PropertyEditor` instances to -convert properties from one format to another. However, most Spring users do not work -with these classes directly (that is, programmatically) but rather with XML `bean` -definitions, annotated components (that is, classes annotated with `@Component`, -`@Controller`, and so forth), or `@Bean` methods in Java-based `@Configuration` classes. -These sources are then converted internally into instances of `BeanDefinition` and used to -load an entire Spring IoC container instance. - -[[beans-constructor-vs-setter-injection]] -.Constructor-based or setter-based DI? -**** -Since you can mix constructor-based and setter-based DI, it is a good rule of thumb to -use constructors for mandatory dependencies and setter methods or configuration methods -for optional dependencies. Note that use of the <> -annotation on a setter method can be used to make the property be a required dependency; -however, constructor injection with programmatic validation of arguments is preferable. - -The Spring team generally advocates constructor injection, as it lets you implement -application components as immutable objects and ensures that required dependencies -are not `null`. Furthermore, constructor-injected components are always returned to the client -(calling) code in a fully initialized state. As a side note, a large number of constructor -arguments is a bad code smell, implying that the class likely has too many -responsibilities and should be refactored to better address proper separation of concerns. - -Setter injection should primarily only be used for optional dependencies that can be -assigned reasonable default values within the class. Otherwise, not-null checks must be -performed everywhere the code uses the dependency. One benefit of setter injection is that -setter methods make objects of that class amenable to reconfiguration or re-injection -later. Management through <> is therefore a compelling -use case for setter injection. - -Use the DI style that makes the most sense for a particular class. Sometimes, when dealing -with third-party classes for which you do not have the source, the choice is made for you. -For example, if a third-party class does not expose any setter methods, then constructor -injection may be the only available form of DI. -**** - - -[[beans-dependency-resolution]] -==== Dependency Resolution Process - -The container performs bean dependency resolution as follows: - -* The `ApplicationContext` is created and initialized with configuration metadata that - describes all the beans. Configuration metadata can be specified by XML, Java code, or - annotations. -* For each bean, its dependencies are expressed in the form of properties, constructor - arguments, or arguments to the static-factory method (if you use that instead of a - normal constructor). These dependencies are provided to the bean, when the bean is - actually created. -* Each property or constructor argument is an actual definition of the value to set, or - a reference to another bean in the container. -* Each property or constructor argument that is a value is converted from its specified - format to the actual type of that property or constructor argument. By default, Spring - can convert a value supplied in string format to all built-in types, such as `int`, - `long`, `String`, `boolean`, and so forth. - -The Spring container validates the configuration of each bean as the container is created. -However, the bean properties themselves are not set until the bean is actually created. -Beans that are singleton-scoped and set to be pre-instantiated (the default) are created -when the container is created. Scopes are defined in <>. Otherwise, -the bean is created only when it is requested. Creation of a bean potentially causes a -graph of beans to be created, as the bean's dependencies and its dependencies' -dependencies (and so on) are created and assigned. Note that resolution mismatches among -those dependencies may show up late -- that is, on first creation of the affected bean. - -.Circular dependencies -**** -If you use predominantly constructor injection, it is possible to create an unresolvable -circular dependency scenario. - -For example: Class A requires an instance of class B through constructor injection, and -class B requires an instance of class A through constructor injection. If you configure -beans for classes A and B to be injected into each other, the Spring IoC container -detects this circular reference at runtime, and throws a -`BeanCurrentlyInCreationException`. - -One possible solution is to edit the source code of some classes to be configured by -setters rather than constructors. Alternatively, avoid constructor injection and use -setter injection only. In other words, although it is not recommended, you can configure -circular dependencies with setter injection. - -Unlike the typical case (with no circular dependencies), a circular dependency -between bean A and bean B forces one of the beans to be injected into the other prior to -being fully initialized itself (a classic chicken-and-egg scenario). -**** - -You can generally trust Spring to do the right thing. It detects configuration problems, -such as references to non-existent beans and circular dependencies, at container -load-time. Spring sets properties and resolves dependencies as late as possible, when -the bean is actually created. This means that a Spring container that has loaded -correctly can later generate an exception when you request an object if there is a -problem creating that object or one of its dependencies -- for example, the bean throws an -exception as a result of a missing or invalid property. This potentially delayed -visibility of some configuration issues is why `ApplicationContext` implementations by -default pre-instantiate singleton beans. At the cost of some upfront time and memory to -create these beans before they are actually needed, you discover configuration issues -when the `ApplicationContext` is created, not later. You can still override this default -behavior so that singleton beans initialize lazily, rather than being eagerly -pre-instantiated. - -If no circular dependencies exist, when one or more collaborating beans are being -injected into a dependent bean, each collaborating bean is totally configured prior -to being injected into the dependent bean. This means that, if bean A has a dependency on -bean B, the Spring IoC container completely configures bean B prior to invoking the -setter method on bean A. In other words, the bean is instantiated (if it is not a -pre-instantiated singleton), its dependencies are set, and the relevant lifecycle -methods (such as a <> -or the <>) -are invoked. - - -[[beans-some-examples]] -==== Examples of Dependency Injection - -The following example uses XML-based configuration metadata for setter-based DI. A small -part of a Spring XML configuration file specifies some bean definitions as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - ----- - -The following example shows the corresponding `ExampleBean` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ExampleBean { - - private AnotherBean beanOne; - - private YetAnotherBean beanTwo; - - private int i; - - public void setBeanOne(AnotherBean beanOne) { - this.beanOne = beanOne; - } - - public void setBeanTwo(YetAnotherBean beanTwo) { - this.beanTwo = beanTwo; - } - - public void setIntegerProperty(int i) { - this.i = i; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -class ExampleBean { - lateinit var beanOne: AnotherBean - lateinit var beanTwo: YetAnotherBean - var i: Int = 0 -} ----- - -In the preceding example, setters are declared to match against the properties specified -in the XML file. The following example uses constructor-based DI: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - ----- - -The following example shows the corresponding `ExampleBean` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ExampleBean { - - private AnotherBean beanOne; - - private YetAnotherBean beanTwo; - - private int i; - - public ExampleBean( - AnotherBean anotherBean, YetAnotherBean yetAnotherBean, int i) { - this.beanOne = anotherBean; - this.beanTwo = yetAnotherBean; - this.i = i; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -class ExampleBean( - private val beanOne: AnotherBean, - private val beanTwo: YetAnotherBean, - private val i: Int) ----- - -The constructor arguments specified in the bean definition are used as arguments to -the constructor of the `ExampleBean`. - -Now consider a variant of this example, where, instead of using a constructor, Spring is -told to call a `static` factory method to return an instance of the object: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -The following example shows the corresponding `ExampleBean` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ExampleBean { - - // a private constructor - private ExampleBean(...) { - ... - } - - // a static factory method; the arguments to this method can be - // considered the dependencies of the bean that is returned, - // regardless of how those arguments are actually used. - public static ExampleBean createInstance ( - AnotherBean anotherBean, YetAnotherBean yetAnotherBean, int i) { - - ExampleBean eb = new ExampleBean (...); - // some other operations... - return eb; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ExampleBean private constructor() { - companion object { - // a static factory method; the arguments to this method can be - // considered the dependencies of the bean that is returned, - // regardless of how those arguments are actually used. - @JvmStatic - fun createInstance(anotherBean: AnotherBean, yetAnotherBean: YetAnotherBean, i: Int): ExampleBean { - val eb = ExampleBean (...) - // some other operations... - return eb - } - } - } ----- - -Arguments to the `static` factory method are supplied by `` elements, -exactly the same as if a constructor had actually been used. The type of the class being -returned by the factory method does not have to be of the same type as the class that -contains the `static` factory method (although, in this example, it is). An instance -(non-static) factory method can be used in an essentially identical fashion (aside -from the use of the `factory-bean` attribute instead of the `class` attribute), so we -do not discuss those details here. - - - -[[beans-factory-properties-detailed]] -=== Dependencies and Configuration in Detail - -As mentioned in the <>, you can define bean -properties and constructor arguments as references to other managed beans (collaborators) -or as values defined inline. Spring's XML-based configuration metadata supports -sub-element types within its `` and `` elements for this -purpose. - - -[[beans-value-element]] -==== Straight Values (Primitives, Strings, and so on) - -The `value` attribute of the `` element specifies a property or constructor -argument as a human-readable string representation. Spring's -<> is used to convert these -values from a `String` to the actual type of the property or argument. -The following example shows various values being set: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -The following example uses the <> for even more succinct -XML configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - -The preceding XML is more succinct. However, typos are discovered at runtime rather than -design time, unless you use an IDE (such as https://www.jetbrains.com/idea/[IntelliJ -IDEA] or the https://spring.io/tools[Spring Tools for Eclipse]) -that supports automatic property completion when you create bean definitions. Such IDE -assistance is highly recommended. - -You can also configure a `java.util.Properties` instance, as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - jdbc.driver.className=com.mysql.jdbc.Driver - jdbc.url=jdbc:mysql://localhost:3306/mydb - - - ----- - -The Spring container converts the text inside the `` element into a -`java.util.Properties` instance by using the JavaBeans `PropertyEditor` mechanism. This -is a nice shortcut, and is one of a few places where the Spring team do favor the use of -the nested `` element over the `value` attribute style. - -[[beans-idref-element]] -===== The `idref` element - -The `idref` element is simply an error-proof way to pass the `id` (a string value - not -a reference) of another bean in the container to a `` or `` -element. The following example shows how to use it: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -The preceding bean definition snippet is exactly equivalent (at runtime) to the -following snippet: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - -The first form is preferable to the second, because using the `idref` tag lets the -container validate at deployment time that the referenced, named bean actually -exists. In the second variation, no validation is performed on the value that is passed -to the `targetName` property of the `client` bean. Typos are only discovered (with most -likely fatal results) when the `client` bean is actually instantiated. If the `client` -bean is a <> bean, this typo and the resulting exception -may only be discovered long after the container is deployed. - -NOTE: The `local` attribute on the `idref` element is no longer supported in the 4.0 beans -XSD, since it does not provide value over a regular `bean` reference any more. Change -your existing `idref local` references to `idref bean` when upgrading to the 4.0 schema. - -A common place (at least in versions earlier than Spring 2.0) where the `` element -brings value is in the configuration of <> in a -`ProxyFactoryBean` bean definition. Using `` elements when you specify the -interceptor names prevents you from misspelling an interceptor ID. - - -[[beans-ref-element]] -==== References to Other Beans (Collaborators) - -The `ref` element is the final element inside a `` or `` -definition element. Here, you set the value of the specified property of a bean to be a -reference to another bean (a collaborator) managed by the container. The referenced bean -is a dependency of the bean whose property is to be set, and it is initialized on demand -as needed before the property is set. (If the collaborator is a singleton bean, it may -already be initialized by the container.) All references are ultimately a reference to -another object. Scoping and validation depend on whether you specify the ID or name of the -other object through the `bean` or `parent` attribute. - -Specifying the target bean through the `bean` attribute of the `` tag is the most -general form and allows creation of a reference to any bean in the same container or -parent container, regardless of whether it is in the same XML file. The value of the -`bean` attribute may be the same as the `id` attribute of the target bean or be the same -as one of the values in the `name` attribute of the target bean. The following example -shows how to use a `ref` element: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -Specifying the target bean through the `parent` attribute creates a reference to a bean -that is in a parent container of the current container. The value of the `parent` -attribute may be the same as either the `id` attribute of the target bean or one of the -values in the `name` attribute of the target bean. The target bean must be in a -parent container of the current one. You should use this bean reference variant mainly -when you have a hierarchy of containers and you want to wrap an existing bean in a parent -container with a proxy that has the same name as the parent bean. The following pair of -listings shows how to use the `parent` attribute: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - class="org.springframework.aop.framework.ProxyFactoryBean"> - - - - - ----- - -NOTE: The `local` attribute on the `ref` element is no longer supported in the 4.0 beans -XSD, since it does not provide value over a regular `bean` reference any more. Change -your existing `ref local` references to `ref bean` when upgrading to the 4.0 schema. - - -[[beans-inner-beans]] -==== Inner Beans - -A `` element inside the `` or `` elements defines an -inner bean, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - ----- - -An inner bean definition does not require a defined ID or name. If specified, the container -does not use such a value as an identifier. The container also ignores the `scope` flag on -creation, because inner beans are always anonymous and are always created with the outer -bean. It is not possible to access inner beans independently or to inject them into -collaborating beans other than into the enclosing bean. - -As a corner case, it is possible to receive destruction callbacks from a custom scope -- -for example, for a request-scoped inner bean contained within a singleton bean. The creation -of the inner bean instance is tied to its containing bean, but destruction callbacks let it -participate in the request scope's lifecycle. This is not a common scenario. Inner beans -typically simply share their containing bean's scope. - - -[[beans-collection-elements]] -==== Collections - -The ``, ``, ``, and `` elements set the properties -and arguments of the Java `Collection` types `List`, `Set`, `Map`, and `Properties`, -respectively. The following example shows how to use them: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - administrator@example.org - support@example.org - development@example.org - - - - - - a list element followed by a reference - - - - - - - - - - - - - - just some string - - - - ----- - -The value of a map key or value, or a set value, can also be any of the -following elements: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - bean | ref | idref | list | set | map | props | value | null ----- - -[[beans-collection-elements-merging]] -===== Collection Merging - -The Spring container also supports merging collections. An application -developer can define a parent ``, ``, `` or `` element -and have child ``, ``, `` or `` elements inherit and -override values from the parent collection. That is, the child collection's values are -the result of merging the elements of the parent and child collections, with the child's -collection elements overriding values specified in the parent collection. - -This section on merging discusses the parent-child bean mechanism. Readers unfamiliar -with parent and child bean definitions may wish to read the -<> before continuing. - -The following example demonstrates collection merging: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - administrator@example.com - support@example.com - - - - - - - - sales@example.com - support@example.co.uk - - - - ----- - -Notice the use of the `merge=true` attribute on the `` element of the -`adminEmails` property of the `child` bean definition. When the `child` bean is resolved -and instantiated by the container, the resulting instance has an `adminEmails` -`Properties` collection that contains the result of merging the child's -`adminEmails` collection with the parent's `adminEmails` collection. The following listing -shows the result: - -[literal,subs="verbatim,quotes"] ----- -administrator=administrator@example.com -sales=sales@example.com -support=support@example.co.uk ----- - -The child `Properties` collection's value set inherits all property elements from the -parent ``, and the child's value for the `support` value overrides the value in -the parent collection. - -This merging behavior applies similarly to the ``, ``, and `` -collection types. In the specific case of the `` element, the semantics -associated with the `List` collection type (that is, the notion of an `ordered` -collection of values) is maintained. The parent's values precede all of the child list's -values. In the case of the `Map`, `Set`, and `Properties` collection types, no ordering -exists. Hence, no ordering semantics are in effect for the collection types that underlie -the associated `Map`, `Set`, and `Properties` implementation types that the container -uses internally. - -[[beans-collection-merge-limitations]] -===== Limitations of Collection Merging - -You cannot merge different collection types (such as a `Map` and a `List`). If you -do attempt to do so, an appropriate `Exception` is thrown. The `merge` attribute must be -specified on the lower, inherited, child definition. Specifying the `merge` attribute on -a parent collection definition is redundant and does not result in the desired merging. - -[[beans-collection-elements-strongly-typed]] -===== Strongly-typed collection - -Thanks to Java's support for generic types, you can use strongly typed collections. -That is, it is possible to declare a `Collection` type such that it can only contain -(for example) `String` elements. If you use Spring to dependency-inject a -strongly-typed `Collection` into a bean, you can take advantage of Spring's -type-conversion support such that the elements of your strongly-typed `Collection` -instances are converted to the appropriate type prior to being added to the `Collection`. -The following Java class and bean definition show how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SomeClass { - - private Map accounts; - - public void setAccounts(Map accounts) { - this.accounts = accounts; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -class SomeClass { - lateinit var accounts: Map -} ----- - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - ----- - -When the `accounts` property of the `something` bean is prepared for injection, the generics -information about the element type of the strongly-typed `Map` is -available by reflection. Thus, Spring's type conversion infrastructure recognizes the -various value elements as being of type `Float`, and the string values (`9.99`, `2.75`, and -`3.99`) are converted into an actual `Float` type. - - -[[beans-null-element]] -==== Null and Empty String Values - -Spring treats empty arguments for properties and the like as empty `Strings`. The -following XML-based configuration metadata snippet sets the `email` property to the empty -`String` value (""). - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -The preceding example is equivalent to the following Java code: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - exampleBean.setEmail(""); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - exampleBean.email = "" ----- - - -The `` element handles `null` values. The following listing shows an example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - -The preceding configuration is equivalent to the following Java code: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - exampleBean.setEmail(null); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - exampleBean.email = null ----- - - -[[beans-p-namespace]] -==== XML Shortcut with the p-namespace - -The p-namespace lets you use the `bean` element's attributes (instead of nested -`` elements) to describe your property values collaborating beans, or both. - -Spring supports extensible configuration formats <>, -which are based on an XML Schema definition. The `beans` configuration format discussed in -this chapter is defined in an XML Schema document. However, the p-namespace is not defined -in an XSD file and exists only in the core of Spring. - -The following example shows two XML snippets (the first uses -standard XML format and the second uses the p-namespace) that resolve to the same result: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -The example shows an attribute in the p-namespace called `email` in the bean definition. -This tells Spring to include a property declaration. As previously mentioned, the -p-namespace does not have a schema definition, so you can set the name of the attribute -to the property name. - -This next example includes two more bean definitions that both have a reference to -another bean: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - ----- - -This example includes not only a property value using the p-namespace -but also uses a special format to declare property references. Whereas the first bean -definition uses `` to create a reference from bean -`john` to bean `jane`, the second bean definition uses `p:spouse-ref="jane"` as an -attribute to do the exact same thing. In this case, `spouse` is the property name, -whereas the `-ref` part indicates that this is not a straight value but rather a -reference to another bean. - -NOTE: The p-namespace is not as flexible as the standard XML format. For example, the format -for declaring property references clashes with properties that end in `Ref`, whereas the -standard XML format does not. We recommend that you choose your approach carefully and -communicate this to your team members to avoid producing XML documents that use all -three approaches at the same time. - - -[[beans-c-namespace]] -==== XML Shortcut with the c-namespace - -Similar to the <>, the c-namespace, introduced in Spring -3.1, allows inlined attributes for configuring the constructor arguments rather -then nested `constructor-arg` elements. - -The following example uses the `c:` namespace to do the same thing as the from -<>: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - ----- - -The `c:` namespace uses the same conventions as the `p:` one (a trailing `-ref` for -bean references) for setting the constructor arguments by their names. Similarly, -it needs to be declared in the XML file even though it is not defined in an XSD schema -(it exists inside the Spring core). - -For the rare cases where the constructor argument names are not available (usually if -the bytecode was compiled without debugging information), you can use fallback to the -argument indexes, as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ----- - -NOTE: Due to the XML grammar, the index notation requires the presence of the leading `_`, -as XML attribute names cannot start with a number (even though some IDEs allow it). -A corresponding index notation is also available for `` elements but -not commonly used since the plain order of declaration is usually sufficient there. - -In practice, the constructor resolution -<> is quite efficient in matching -arguments, so unless you really need to, we recommend using the name notation -throughout your configuration. - - -[[beans-compound-property-names]] -==== Compound Property Names - -You can use compound or nested property names when you set bean properties, as long as -all components of the path except the final property name are not `null`. Consider the -following bean definition: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -The `something` bean has a `fred` property, which has a `bob` property, which has a `sammy` -property, and that final `sammy` property is being set to a value of `123`. In order for -this to work, the `fred` property of `something` and the `bob` property of `fred` must not -be `null` after the bean is constructed. Otherwise, a `NullPointerException` is thrown. - - - -[[beans-factory-dependson]] -=== Using `depends-on` - -If a bean is a dependency of another bean, that usually means that one bean is set as a -property of another. Typically you accomplish this with the <` -element>> in XML-based configuration metadata. However, sometimes dependencies between -beans are less direct. An example is when a static initializer in a class needs to be -triggered, such as for database driver registration. The `depends-on` attribute can -explicitly force one or more beans to be initialized before the bean using this element -is initialized. The following example uses the `depends-on` attribute to express a -dependency on a single bean: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ----- - -To express a dependency on multiple beans, supply a list of bean names as the value of -the `depends-on` attribute (commas, whitespace, and semicolons are valid -delimiters): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -NOTE: The `depends-on` attribute can specify both an initialization-time dependency and, -in the case of <> beans only, a corresponding -destruction-time dependency. Dependent beans that define a `depends-on` relationship -with a given bean are destroyed first, prior to the given bean itself being destroyed. -Thus, `depends-on` can also control shutdown order. - - - -[[beans-factory-lazy-init]] -=== Lazy-initialized Beans - -By default, `ApplicationContext` implementations eagerly create and configure all -<> beans as part of the initialization -process. Generally, this pre-instantiation is desirable, because errors in the -configuration or surrounding environment are discovered immediately, as opposed to hours -or even days later. When this behavior is not desirable, you can prevent -pre-instantiation of a singleton bean by marking the bean definition as being -lazy-initialized. A lazy-initialized bean tells the IoC container to create a bean -instance when it is first requested, rather than at startup. - -In XML, this behavior is controlled by the `lazy-init` attribute on the `` -element, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ----- - -When the preceding configuration is consumed by an `ApplicationContext`, the `lazy` bean -is not eagerly pre-instantiated when the `ApplicationContext` starts, -whereas the `not.lazy` bean is eagerly pre-instantiated. - -However, when a lazy-initialized bean is a dependency of a singleton bean that is -not lazy-initialized, the `ApplicationContext` creates the lazy-initialized bean at -startup, because it must satisfy the singleton's dependencies. The lazy-initialized bean -is injected into a singleton bean elsewhere that is not lazy-initialized. - -You can also control lazy-initialization at the container level by using the -`default-lazy-init` attribute on the `` element, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - - - -[[beans-factory-autowire]] -=== Autowiring Collaborators - -The Spring container can autowire relationships between collaborating beans. You can -let Spring resolve collaborators (other beans) automatically for your bean by -inspecting the contents of the `ApplicationContext`. Autowiring has the following -advantages: - -* Autowiring can significantly reduce the need to specify properties or constructor - arguments. (Other mechanisms such as a bean template - <> are also valuable - in this regard.) -* Autowiring can update a configuration as your objects evolve. For example, if you need - to add a dependency to a class, that dependency can be satisfied automatically without - you needing to modify the configuration. Thus autowiring can be especially useful - during development, without negating the option of switching to explicit wiring when - the code base becomes more stable. - -When using XML-based configuration metadata (see <>), you -can specify the autowire mode for a bean definition with the `autowire` attribute of the -`` element. The autowiring functionality has four modes. You specify autowiring -per bean and can thus choose which ones to autowire. The following table describes the -four autowiring modes: - -[[beans-factory-autowiring-modes-tbl]] -.Autowiring modes -[cols="20%,80%"] -|=== -| Mode| Explanation - -| `no` -| (Default) No autowiring. Bean references must be defined by `ref` elements. Changing - the default setting is not recommended for larger deployments, because specifying - collaborators explicitly gives greater control and clarity. To some extent, it - documents the structure of a system. - -| `byName` -| Autowiring by property name. Spring looks for a bean with the same name as the - property that needs to be autowired. For example, if a bean definition is set to - autowire by name and it contains a `master` property (that is, it has a - `setMaster(..)` method), Spring looks for a bean definition named `master` and uses - it to set the property. - -| `byType` -| Lets a property be autowired if exactly one bean of the property type exists in - the container. If more than one exists, a fatal exception is thrown, which indicates - that you may not use `byType` autowiring for that bean. If there are no matching - beans, nothing happens (the property is not set). - -| `constructor` -| Analogous to `byType` but applies to constructor arguments. If there is not exactly - one bean of the constructor argument type in the container, a fatal error is raised. -|=== - -With `byType` or `constructor` autowiring mode, you can wire arrays and -typed collections. In such cases, all autowire candidates within the container that -match the expected type are provided to satisfy the dependency. You can autowire -strongly-typed `Map` instances if the expected key type is `String`. An autowired `Map` -instance's values consist of all bean instances that match the expected type, and the -`Map` instance's keys contain the corresponding bean names. - - -[[beans-autowired-exceptions]] -==== Limitations and Disadvantages of Autowiring - -Autowiring works best when it is used consistently across a project. If autowiring is -not used in general, it might be confusing to developers to use it to wire only one or -two bean definitions. - -Consider the limitations and disadvantages of autowiring: - -* Explicit dependencies in `property` and `constructor-arg` settings always override - autowiring. You cannot autowire simple properties such as primitives, - `Strings`, and `Classes` (and arrays of such simple properties). This limitation is - by-design. -* Autowiring is less exact than explicit wiring. Although, as noted in the earlier table, - Spring is careful to avoid guessing in case of ambiguity that might have unexpected - results. The relationships between your Spring-managed objects are no longer - documented explicitly. -* Wiring information may not be available to tools that may generate documentation from - a Spring container. -* Multiple bean definitions within the container may match the type specified by the - setter method or constructor argument to be autowired. For arrays, collections, or - `Map` instances, this is not necessarily a problem. However, for dependencies that - expect a single value, this ambiguity is not arbitrarily resolved. If no unique bean - definition is available, an exception is thrown. - -In the latter scenario, you have several options: - -* Abandon autowiring in favor of explicit wiring. -* Avoid autowiring for a bean definition by setting its `autowire-candidate` attributes - to `false`, as described in the <>. -* Designate a single bean definition as the primary candidate by setting the - `primary` attribute of its `` element to `true`. -* Implement the more fine-grained control available with annotation-based configuration, - as described in <>. - - - -[[beans-factory-autowire-candidate]] -==== Excluding a Bean from Autowiring - -On a per-bean basis, you can exclude a bean from autowiring. In Spring's XML format, set -the `autowire-candidate` attribute of the `` element to `false`. The container -makes that specific bean definition unavailable to the autowiring infrastructure -(including annotation style configurations such as <>). - -NOTE: The `autowire-candidate` attribute is designed to only affect type-based autowiring. -It does not affect explicit references by name, which get resolved even if the -specified bean is not marked as an autowire candidate. As a consequence, autowiring -by name nevertheless injects a bean if the name matches. - -You can also limit autowire candidates based on pattern-matching against bean names. The -top-level `` element accepts one or more patterns within its -`default-autowire-candidates` attribute. For example, to limit autowire candidate status -to any bean whose name ends with `Repository`, provide a value of `*Repository`. To -provide multiple patterns, define them in a comma-separated list. An explicit value of -`true` or `false` for a bean definition's `autowire-candidate` attribute always takes -precedence. For such beans, the pattern matching rules do not apply. - -These techniques are useful for beans that you never want to be injected into other -beans by autowiring. It does not mean that an excluded bean cannot itself be configured by -using autowiring. Rather, the bean itself is not a candidate for autowiring other beans. - - - -[[beans-factory-method-injection]] -=== Method Injection - -In most application scenarios, most beans in the container are -<>. When a singleton bean needs to -collaborate with another singleton bean or a non-singleton bean needs to collaborate -with another non-singleton bean, you typically handle the dependency by defining one -bean as a property of the other. A problem arises when the bean lifecycles are -different. Suppose singleton bean A needs to use non-singleton (prototype) bean B, -perhaps on each method invocation on A. The container creates the singleton bean A only -once, and thus only gets one opportunity to set the properties. The container cannot -provide bean A with a new instance of bean B every time one is needed. - -A solution is to forego some inversion of control. You can <> by implementing the `ApplicationContextAware` interface, -and by <> ask for (a -typically new) bean B instance every time bean A needs it. The following example -shows this approach: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages",fold="none"] -.Java ----- - package fiona.apple; - - // Spring-API imports - import org.springframework.beans.BeansException; - import org.springframework.context.ApplicationContext; - import org.springframework.context.ApplicationContextAware; - - /** - * A class that uses a stateful Command-style class to perform - * some processing. - */ - public class CommandManager implements ApplicationContextAware { - - private ApplicationContext applicationContext; - - public Object process(Map commandState) { - // grab a new instance of the appropriate Command - Command command = createCommand(); - // set the state on the (hopefully brand new) Command instance - command.setState(commandState); - return command.execute(); - } - - protected Command createCommand() { - // notice the Spring API dependency! - return this.applicationContext.getBean("command", Command.class); - } - - public void setApplicationContext( - ApplicationContext applicationContext) throws BeansException { - this.applicationContext = applicationContext; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages",fold="none"] -.Kotlin ----- - package fiona.apple - - // Spring-API imports - import org.springframework.context.ApplicationContext - import org.springframework.context.ApplicationContextAware - - // A class that uses a stateful Command-style class to perform - // some processing. - class CommandManager : ApplicationContextAware { - - private lateinit var applicationContext: ApplicationContext - - fun process(commandState: Map<*, *>): Any { - // grab a new instance of the appropriate Command - val command = createCommand() - // set the state on the (hopefully brand new) Command instance - command.state = commandState - return command.execute() - } - - // notice the Spring API dependency! - protected fun createCommand() = - applicationContext.getBean("command", Command::class.java) - - override fun setApplicationContext(applicationContext: ApplicationContext) { - this.applicationContext = applicationContext - } - } ----- - -The preceding is not desirable, because the business code is aware of and coupled to the -Spring Framework. Method Injection, a somewhat advanced feature of the Spring IoC -container, lets you handle this use case cleanly. - -**** -You can read more about the motivation for Method Injection in -https://spring.io/blog/2004/08/06/method-injection/[this blog entry]. -**** - - - -[[beans-factory-lookup-method-injection]] -==== Lookup Method Injection - -Lookup method injection is the ability of the container to override methods on -container-managed beans and return the lookup result for another named bean in the -container. The lookup typically involves a prototype bean, as in the scenario described -in <>. The Spring Framework -implements this method injection by using bytecode generation from the CGLIB library to -dynamically generate a subclass that overrides the method. - -[NOTE] -==== -* For this dynamic subclassing to work, the class that the Spring bean container - subclasses cannot be `final`, and the method to be overridden cannot be `final`, either. -* Unit-testing a class that has an `abstract` method requires you to subclass the class - yourself and to supply a stub implementation of the `abstract` method. -* Concrete methods are also necessary for component scanning, which requires concrete - classes to pick up. -* A further key limitation is that lookup methods do not work with factory methods and - in particular not with `@Bean` methods in configuration classes, since, in that case, - the container is not in charge of creating the instance and therefore cannot create - a runtime-generated subclass on the fly. -==== - -In the case of the `CommandManager` class in the previous code snippet, the -Spring container dynamically overrides the implementation of the `createCommand()` -method. The `CommandManager` class does not have any Spring dependencies, as -the reworked example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages",fold="none"] -.Java ----- - package fiona.apple; - - // no more Spring imports! - - public abstract class CommandManager { - - public Object process(Object commandState) { - // grab a new instance of the appropriate Command interface - Command command = createCommand(); - // set the state on the (hopefully brand new) Command instance - command.setState(commandState); - return command.execute(); - } - - // okay... but where is the implementation of this method? - protected abstract Command createCommand(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages",fold="none"] -.Kotlin ----- - package fiona.apple - - // no more Spring imports! - - abstract class CommandManager { - - fun process(commandState: Any): Any { - // grab a new instance of the appropriate Command interface - val command = createCommand() - // set the state on the (hopefully brand new) Command instance - command.state = commandState - return command.execute() - } - - // okay... but where is the implementation of this method? - protected abstract fun createCommand(): Command - } ----- - -In the client class that contains the method to be injected (the `CommandManager` in this -case), the method to be injected requires a signature of the following form: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - [abstract] theMethodName(no-arguments); ----- - -If the method is `abstract`, the dynamically-generated subclass implements the method. -Otherwise, the dynamically-generated subclass overrides the concrete method defined in -the original class. Consider the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - ----- - -The bean identified as `commandManager` calls its own `createCommand()` method -whenever it needs a new instance of the `myCommand` bean. You must be careful to deploy -the `myCommand` bean as a prototype if that is actually what is needed. If it is -a <>, the same instance of the `myCommand` -bean is returned each time. - -Alternatively, within the annotation-based component model, you can declare a lookup -method through the `@Lookup` annotation, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public abstract class CommandManager { - - public Object process(Object commandState) { - Command command = createCommand(); - command.setState(commandState); - return command.execute(); - } - - @Lookup("myCommand") - protected abstract Command createCommand(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - abstract class CommandManager { - - fun process(commandState: Any): Any { - val command = createCommand() - command.state = commandState - return command.execute() - } - - @Lookup("myCommand") - protected abstract fun createCommand(): Command - } ----- - -Or, more idiomatically, you can rely on the target bean getting resolved against the -declared return type of the lookup method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public abstract class CommandManager { - - public Object process(Object commandState) { - Command command = createCommand(); - command.setState(commandState); - return command.execute(); - } - - @Lookup - protected abstract Command createCommand(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - abstract class CommandManager { - - fun process(commandState: Any): Any { - val command = createCommand() - command.state = commandState - return command.execute() - } - - @Lookup - protected abstract fun createCommand(): Command - } ----- - -Note that you should typically declare such annotated lookup methods with a concrete -stub implementation, in order for them to be compatible with Spring's component -scanning rules where abstract classes get ignored by default. This limitation does not -apply to explicitly registered or explicitly imported bean classes. - -[TIP] -==== -Another way of accessing differently scoped target beans is an `ObjectFactory`/ -`Provider` injection point. See <>. - -You may also find the `ServiceLocatorFactoryBean` (in the -`org.springframework.beans.factory.config` package) to be useful. -==== - - - -[[beans-factory-arbitrary-method-replacement]] -==== Arbitrary Method Replacement - -A less useful form of method injection than lookup method injection is the ability to -replace arbitrary methods in a managed bean with another method implementation. You -can safely skip the rest of this section until you actually need this functionality. - -With XML-based configuration metadata, you can use the `replaced-method` element to -replace an existing method implementation with another, for a deployed bean. Consider -the following class, which has a method called `computeValue` that we want to override: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MyValueCalculator { - - public String computeValue(String input) { - // some real code... - } - - // some other methods... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyValueCalculator { - - fun computeValue(input: String): String { - // some real code... - } - - // some other methods... - } ----- - -A class that implements the `org.springframework.beans.factory.support.MethodReplacer` -interface provides the new method definition, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - /** - * meant to be used to override the existing computeValue(String) - * implementation in MyValueCalculator - */ - public class ReplacementComputeValue implements MethodReplacer { - - public Object reimplement(Object o, Method m, Object[] args) throws Throwable { - // get the input value, work with it, and return a computed result - String input = (String) args[0]; - ... - return ...; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - /** - * meant to be used to override the existing computeValue(String) - * implementation in MyValueCalculator - */ - class ReplacementComputeValue : MethodReplacer { - - override fun reimplement(obj: Any, method: Method, args: Array): Any { - // get the input value, work with it, and return a computed result - val input = args[0] as String; - ... - return ...; - } - } ----- - - - -The bean definition to deploy the original class and specify the method override would -resemble the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - String - - - - ----- - -You can use one or more `` elements within the `` -element to indicate the method signature of the method being overridden. The signature -for the arguments is necessary only if the method is overloaded and multiple variants -exist within the class. For convenience, the type string for an argument may be a -substring of the fully qualified type name. For example, the following all match -`java.lang.String`: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - java.lang.String - String - Str ----- - -Because the number of arguments is often enough to distinguish between each possible -choice, this shortcut can save a lot of typing, by letting you type only the -shortest string that matches an argument type. - - - -[[beans-factory-scopes]] -== Bean Scopes - -When you create a bean definition, you create a recipe for creating actual instances -of the class defined by that bean definition. The idea that a bean definition is a -recipe is important, because it means that, as with a class, you can create many object -instances from a single recipe. - -You can control not only the various dependencies and configuration values that are to -be plugged into an object that is created from a particular bean definition but also control -the scope of the objects created from a particular bean definition. This approach is -powerful and flexible, because you can choose the scope of the objects you create -through configuration instead of having to bake in the scope of an object at the Java -class level. Beans can be defined to be deployed in one of a number of scopes. -The Spring Framework supports six scopes, four of which are available only if -you use a web-aware `ApplicationContext`. You can also create -<> - -The following table describes the supported scopes: - -[[beans-factory-scopes-tbl]] -.Bean scopes -[cols="20%,80%"] -|=== -| Scope| Description - -| <> -| (Default) Scopes a single bean definition to a single object instance for each Spring IoC - container. - -| <> -| Scopes a single bean definition to any number of object instances. - -| <> -| Scopes a single bean definition to the lifecycle of a single HTTP request. That is, - each HTTP request has its own instance of a bean created off the back of a single bean - definition. Only valid in the context of a web-aware Spring `ApplicationContext`. - -| <> -| Scopes a single bean definition to the lifecycle of an HTTP `Session`. Only valid in - the context of a web-aware Spring `ApplicationContext`. - -| <> -| Scopes a single bean definition to the lifecycle of a `ServletContext`. Only valid in - the context of a web-aware Spring `ApplicationContext`. - -| <> -| Scopes a single bean definition to the lifecycle of a `WebSocket`. Only valid in - the context of a web-aware Spring `ApplicationContext`. -|=== - -NOTE: A thread scope is available but is not registered by default. For more information, -see the documentation for -{api-spring-framework}/context/support/SimpleThreadScope.html[`SimpleThreadScope`]. -For instructions on how to register this or any other custom scope, see -<>. - - - -[[beans-factory-scopes-singleton]] -=== The Singleton Scope - -Only one shared instance of a singleton bean is managed, and all requests for beans -with an ID or IDs that match that bean definition result in that one specific bean -instance being returned by the Spring container. - -To put it another way, when you define a bean definition and it is scoped as a -singleton, the Spring IoC container creates exactly one instance of the object -defined by that bean definition. This single instance is stored in a cache of such -singleton beans, and all subsequent requests and references for that named bean -return the cached object. The following image shows how the singleton scope works: - -image::singleton.png[] - -Spring's concept of a singleton bean differs from the singleton pattern as defined in -the Gang of Four (GoF) patterns book. The GoF singleton hard-codes the scope of an -object such that one and only one instance of a particular class is created per -ClassLoader. The scope of the Spring singleton is best described as being per-container -and per-bean. This means that, if you define one bean for a particular class in a -single Spring container, the Spring container creates one and only one instance -of the class defined by that bean definition. The singleton scope is the default scope -in Spring. To define a bean as a singleton in XML, you can define a bean as shown in the -following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - - - -[[beans-factory-scopes-prototype]] -=== The Prototype Scope - -The non-singleton prototype scope of bean deployment results in the creation of a new -bean instance every time a request for that specific bean is made. That is, the bean -is injected into another bean or you request it through a `getBean()` method call on the -container. As a rule, you should use the prototype scope for all stateful beans and the -singleton scope for stateless beans. - -The following diagram illustrates the Spring prototype scope: - -image::prototype.png[] - -(A data access object -(DAO) is not typically configured as a prototype, because a typical DAO does not hold -any conversational state. It was easier for us to reuse the core of the -singleton diagram.) - -The following example defines a bean as a prototype in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -In contrast to the other scopes, Spring does not manage the complete lifecycle of a -prototype bean. The container instantiates, configures, and otherwise assembles a -prototype object and hands it to the client, with no further record of that prototype -instance. Thus, although initialization lifecycle callback methods are called on all -objects regardless of scope, in the case of prototypes, configured destruction -lifecycle callbacks are not called. The client code must clean up prototype-scoped -objects and release expensive resources that the prototype beans hold. To get -the Spring container to release resources held by prototype-scoped beans, try using a -custom <>, which holds a reference to -beans that need to be cleaned up. - -In some respects, the Spring container's role in regard to a prototype-scoped bean is a -replacement for the Java `new` operator. All lifecycle management past that point must -be handled by the client. (For details on the lifecycle of a bean in the Spring -container, see <>.) - - - -[[beans-factory-scopes-sing-prot-interaction]] -=== Singleton Beans with Prototype-bean Dependencies - -When you use singleton-scoped beans with dependencies on prototype beans, be aware that -dependencies are resolved at instantiation time. Thus, if you dependency-inject a -prototype-scoped bean into a singleton-scoped bean, a new prototype bean is instantiated -and then dependency-injected into the singleton bean. The prototype instance is the sole -instance that is ever supplied to the singleton-scoped bean. - -However, suppose you want the singleton-scoped bean to acquire a new instance of the -prototype-scoped bean repeatedly at runtime. You cannot dependency-inject a -prototype-scoped bean into your singleton bean, because that injection occurs only -once, when the Spring container instantiates the singleton bean and resolves -and injects its dependencies. If you need a new instance of a prototype bean at -runtime more than once, see <>. - - - -[[beans-factory-scopes-other]] -=== Request, Session, Application, and WebSocket Scopes - -The `request`, `session`, `application`, and `websocket` scopes are available only -if you use a web-aware Spring `ApplicationContext` implementation (such as -`XmlWebApplicationContext`). If you use these scopes with regular Spring IoC containers, -such as the `ClassPathXmlApplicationContext`, an `IllegalStateException` that complains -about an unknown bean scope is thrown. - - - -[[beans-factory-scopes-other-web-configuration]] -==== Initial Web Configuration - -To support the scoping of beans at the `request`, `session`, `application`, and -`websocket` levels (web-scoped beans), some minor initial configuration is -required before you define your beans. (This initial setup is not required -for the standard scopes: `singleton` and `prototype`.) - -How you accomplish this initial setup depends on your particular Servlet environment. - -If you access scoped beans within Spring Web MVC, in effect, within a request that is -processed by the Spring `DispatcherServlet`, no special setup is necessary. -`DispatcherServlet` already exposes all relevant state. - -If you use a Servlet web container, with requests processed outside of Spring's -`DispatcherServlet` (for example, when using JSF), you need to register the -`org.springframework.web.context.request.RequestContextListener` `ServletRequestListener`. -This can be done programmatically by using the `WebApplicationInitializer` interface. -Alternatively, add the following declaration to your web application's `web.xml` file: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ... - - - org.springframework.web.context.request.RequestContextListener - - - ... - ----- - -Alternatively, if there are issues with your listener setup, consider using Spring's -`RequestContextFilter`. The filter mapping depends on the surrounding web -application configuration, so you have to change it as appropriate. The following listing -shows the filter part of a web application: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ... - - requestContextFilter - org.springframework.web.filter.RequestContextFilter - - - requestContextFilter - /* - - ... - ----- - -`DispatcherServlet`, `RequestContextListener`, and `RequestContextFilter` all do exactly -the same thing, namely bind the HTTP request object to the `Thread` that is servicing -that request. This makes beans that are request- and session-scoped available further -down the call chain. - - - -[[beans-factory-scopes-request]] -==== Request scope - -Consider the following XML configuration for a bean definition: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -The Spring container creates a new instance of the `LoginAction` bean by using the -`loginAction` bean definition for each and every HTTP request. That is, the -`loginAction` bean is scoped at the HTTP request level. You can change the internal -state of the instance that is created as much as you want, because other instances -created from the same `loginAction` bean definition do not see these changes in state. -They are particular to an individual request. When the request completes processing, the -bean that is scoped to the request is discarded. - -When using annotation-driven components or Java configuration, the `@RequestScope` annotation -can be used to assign a component to the `request` scope. The following example shows how -to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RequestScope - @Component - public class LoginAction { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RequestScope - @Component - class LoginAction { - // ... - } ----- - - - -[[beans-factory-scopes-session]] -==== Session Scope - -Consider the following XML configuration for a bean definition: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -The Spring container creates a new instance of the `UserPreferences` bean by using the -`userPreferences` bean definition for the lifetime of a single HTTP `Session`. In other -words, the `userPreferences` bean is effectively scoped at the HTTP `Session` level. As -with request-scoped beans, you can change the internal state of the instance that is -created as much as you want, knowing that other HTTP `Session` instances that are also -using instances created from the same `userPreferences` bean definition do not see these -changes in state, because they are particular to an individual HTTP `Session`. When the -HTTP `Session` is eventually discarded, the bean that is scoped to that particular HTTP -`Session` is also discarded. - -When using annotation-driven components or Java configuration, you can use the -`@SessionScope` annotation to assign a component to the `session` scope. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SessionScope - @Component - public class UserPreferences { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SessionScope - @Component - class UserPreferences { - // ... - } ----- - - - - -[[beans-factory-scopes-application]] -==== Application Scope - -Consider the following XML configuration for a bean definition: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -The Spring container creates a new instance of the `AppPreferences` bean by using the -`appPreferences` bean definition once for the entire web application. That is, the -`appPreferences` bean is scoped at the `ServletContext` level and stored as a regular -`ServletContext` attribute. This is somewhat similar to a Spring singleton bean but -differs in two important ways: It is a singleton per `ServletContext`, not per Spring -`ApplicationContext` (for which there may be several in any given web application), -and it is actually exposed and therefore visible as a `ServletContext` attribute. - -When using annotation-driven components or Java configuration, you can use the -`@ApplicationScope` annotation to assign a component to the `application` scope. The -following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ApplicationScope - @Component - public class AppPreferences { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ApplicationScope - @Component - class AppPreferences { - // ... - } ----- - - - - -[[beans-factory-scopes-websocket]] -==== WebSocket Scope - -WebSocket scope is associated with the lifecycle of a WebSocket session and applies to -STOMP over WebSocket applications, see -<> for more details. - - - - -[[beans-factory-scopes-other-injection]] -==== Scoped Beans as Dependencies - -The Spring IoC container manages not only the instantiation of your objects (beans), -but also the wiring up of collaborators (or dependencies). If you want to inject (for -example) an HTTP request-scoped bean into another bean of a longer-lived scope, you may -choose to inject an AOP proxy in place of the scoped bean. That is, you need to inject -a proxy object that exposes the same public interface as the scoped object but that can -also retrieve the real target object from the relevant scope (such as an HTTP request) -and delegate method calls onto the real object. - -[NOTE] -==== -You may also use `` between beans that are scoped as `singleton`, -with the reference then going through an intermediate proxy that is serializable -and therefore able to re-obtain the target singleton bean on deserialization. - -When declaring `` against a bean of scope `prototype`, every method -call on the shared proxy leads to the creation of a new target instance to which the -call is then being forwarded. - -Also, scoped proxies are not the only way to access beans from shorter scopes in a -lifecycle-safe fashion. You may also declare your injection point (that is, the -constructor or setter argument or autowired field) as `ObjectFactory`, -allowing for a `getObject()` call to retrieve the current instance on demand every -time it is needed -- without holding on to the instance or storing it separately. - -As an extended variant, you may declare `ObjectProvider` which delivers -several additional access variants, including `getIfAvailable` and `getIfUnique`. - -The JSR-330 variant of this is called `Provider` and is used with a `Provider` -declaration and a corresponding `get()` call for every retrieval attempt. -See <> for more details on JSR-330 overall. -==== - -The configuration in the following example is only one line, but it is important to -understand the "`why`" as well as the "`how`" behind it: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - <1> - - - - - - - - ----- -<1> The line that defines the proxy. - - -To create such a proxy, you insert a child `` element into a scoped -bean definition (see <> and -<>). -Why do definitions of beans scoped at the `request`, `session` and custom-scope -levels require the `` element? -Consider the following singleton bean definition and contrast it with -what you need to define for the aforementioned scopes (note that the following -`userPreferences` bean definition as it stands is incomplete): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - -In the preceding example, the singleton bean (`userManager`) is injected with a reference -to the HTTP `Session`-scoped bean (`userPreferences`). The salient point here is that the -`userManager` bean is a singleton: it is instantiated exactly once per -container, and its dependencies (in this case only one, the `userPreferences` bean) are -also injected only once. This means that the `userManager` bean operates only on the -exact same `userPreferences` object (that is, the one with which it was originally injected). - -This is not the behavior you want when injecting a shorter-lived scoped bean into a -longer-lived scoped bean (for example, injecting an HTTP `Session`-scoped collaborating -bean as a dependency into singleton bean). Rather, you need a single `userManager` -object, and, for the lifetime of an HTTP `Session`, you need a `userPreferences` object -that is specific to the HTTP `Session`. Thus, the container creates an object that -exposes the exact same public interface as the `UserPreferences` class (ideally an -object that is a `UserPreferences` instance), which can fetch the real -`UserPreferences` object from the scoping mechanism (HTTP request, `Session`, and so -forth). The container injects this proxy object into the `userManager` bean, which is -unaware that this `UserPreferences` reference is a proxy. In this example, when a -`UserManager` instance invokes a method on the dependency-injected `UserPreferences` -object, it is actually invoking a method on the proxy. The proxy then fetches the real -`UserPreferences` object from (in this case) the HTTP `Session` and delegates the -method invocation onto the retrieved real `UserPreferences` object. - -Thus, you need the following (correct and complete) configuration when injecting -`request-` and `session-scoped` beans into collaborating objects, as the following example -shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -[[beans-factory-scopes-other-injection-proxies]] -===== Choosing the Type of Proxy to Create - -By default, when the Spring container creates a proxy for a bean that is marked up with -the `` element, a CGLIB-based class proxy is created. - -[NOTE] -==== -CGLIB proxies intercept only public method calls! Do not call non-public methods -on such a proxy. They are not delegated to the actual scoped target object. -==== - -Alternatively, you can configure the Spring container to create standard JDK -interface-based proxies for such scoped beans, by specifying `false` for the value of -the `proxy-target-class` attribute of the `` element. Using JDK -interface-based proxies means that you do not need additional libraries in your -application classpath to affect such proxying. However, it also means that the class of -the scoped bean must implement at least one interface and that all collaborators -into which the scoped bean is injected must reference the bean through one of its -interfaces. The following example shows a proxy based on an interface: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -For more detailed information about choosing class-based or interface-based proxying, -see <>. - - - -[[beans-factory-scopes-custom]] -=== Custom Scopes - -The bean scoping mechanism is extensible. You can define your own -scopes or even redefine existing scopes, although the latter is considered bad practice -and you cannot override the built-in `singleton` and `prototype` scopes. - - -[[beans-factory-scopes-custom-creating]] -==== Creating a Custom Scope - -To integrate your custom scopes into the Spring container, you need to implement the -`org.springframework.beans.factory.config.Scope` interface, which is described in this -section. For an idea of how to implement your own scopes, see the `Scope` -implementations that are supplied with the Spring Framework itself and the -{api-spring-framework}/beans/factory/config/Scope.html[`Scope`] javadoc, -which explains the methods you need to implement in more detail. - -The `Scope` interface has four methods to get objects from the scope, remove them from -the scope, and let them be destroyed. - -The session scope implementation, for example, returns the session-scoped bean (if it -does not exist, the method returns a new instance of the bean, after having bound it to -the session for future reference). The following method returns the object from the -underlying scope: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Object get(String name, ObjectFactory objectFactory) ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun get(name: String, objectFactory: ObjectFactory<*>): Any ----- - -The session scope implementation, for example, removes the session-scoped bean from the -underlying session. The object should be returned, but you can return `null` if the -object with the specified name is not found. The following method removes the object from -the underlying scope: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Object remove(String name) ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun remove(name: String): Any ----- - -The following method registers a callback that the scope should invoke when it is -destroyed or when the specified object in the scope is destroyed: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - void registerDestructionCallback(String name, Runnable destructionCallback) ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun registerDestructionCallback(name: String, destructionCallback: Runnable) ----- - -See the {api-spring-framework}/beans/factory/config/Scope.html#registerDestructionCallback[javadoc] -or a Spring scope implementation for more information on destruction callbacks. - -The following method obtains the conversation identifier for the underlying scope: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - String getConversationId() ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun getConversationId(): String ----- - -This identifier is different for each scope. For a session scoped implementation, this -identifier can be the session identifier. - - - -[[beans-factory-scopes-custom-using]] -==== Using a Custom Scope - -After you write and test one or more custom `Scope` implementations, you need to make -the Spring container aware of your new scopes. The following method is the central -method to register a new `Scope` with the Spring container: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - void registerScope(String scopeName, Scope scope); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun registerScope(scopeName: String, scope: Scope) ----- - -This method is declared on the `ConfigurableBeanFactory` interface, which is available -through the `BeanFactory` property on most of the concrete `ApplicationContext` -implementations that ship with Spring. - -The first argument to the `registerScope(..)` method is the unique name associated with -a scope. Examples of such names in the Spring container itself are `singleton` and -`prototype`. The second argument to the `registerScope(..)` method is an actual instance -of the custom `Scope` implementation that you wish to register and use. - -Suppose that you write your custom `Scope` implementation, and then register it as shown -in the next example. - -NOTE: The next example uses `SimpleThreadScope`, which is included with Spring but is not -registered by default. The instructions would be the same for your own custom `Scope` -implementations. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Scope threadScope = new SimpleThreadScope(); - beanFactory.registerScope("thread", threadScope); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val threadScope = SimpleThreadScope() - beanFactory.registerScope("thread", threadScope) ----- - -You can then create bean definitions that adhere to the scoping rules of your custom -`Scope`, as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -With a custom `Scope` implementation, you are not limited to programmatic registration -of the scope. You can also do the `Scope` registration declaratively, by using the -`CustomScopeConfigurer` class, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - - - - - - ----- - -NOTE: When you place `` within a `` declaration for a -`FactoryBean` implementation, it is the factory bean itself that is scoped, not the object -returned from `getObject()`. - - - - -[[beans-factory-nature]] -== Customizing the Nature of a Bean - -The Spring Framework provides a number of interfaces you can use to customize the nature -of a bean. This section groups them as follows: - -* <> -* <> -* <> - - - -[[beans-factory-lifecycle]] -=== Lifecycle Callbacks - -To interact with the container's management of the bean lifecycle, you can implement -the Spring `InitializingBean` and `DisposableBean` interfaces. The container calls -`afterPropertiesSet()` for the former and `destroy()` for the latter to let the bean -perform certain actions upon initialization and destruction of your beans. - -[TIP] -==== -The JSR-250 `@PostConstruct` and `@PreDestroy` annotations are generally considered best -practice for receiving lifecycle callbacks in a modern Spring application. Using these -annotations means that your beans are not coupled to Spring-specific interfaces. -For details, see <>. - -If you do not want to use the JSR-250 annotations but you still want to remove -coupling, consider `init-method` and `destroy-method` bean definition metadata. -==== - -Internally, the Spring Framework uses `BeanPostProcessor` implementations to process any -callback interfaces it can find and call the appropriate methods. If you need custom -features or other lifecycle behavior Spring does not by default offer, you can -implement a `BeanPostProcessor` yourself. For more information, see -<>. - -In addition to the initialization and destruction callbacks, Spring-managed objects may -also implement the `Lifecycle` interface so that those objects can participate in the -startup and shutdown process, as driven by the container's own lifecycle. - -The lifecycle callback interfaces are described in this section. - - -[[beans-factory-lifecycle-initializingbean]] -==== Initialization Callbacks - -The `org.springframework.beans.factory.InitializingBean` interface lets a bean -perform initialization work after the container has set all necessary properties on the -bean. The `InitializingBean` interface specifies a single method: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - void afterPropertiesSet() throws Exception; ----- - -We recommend that you do not use the `InitializingBean` interface, because it -unnecessarily couples the code to Spring. Alternatively, we suggest using -the <> annotation or -specifying a POJO initialization method. In the case of XML-based configuration metadata, -you can use the `init-method` attribute to specify the name of the method that has a void -no-argument signature. With Java configuration, you can use the `initMethod` attribute of -`@Bean`. See <>. Consider the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ExampleBean { - - public void init() { - // do some initialization work - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ExampleBean { - - fun init() { - // do some initialization work - } - } ----- - -The preceding example has almost exactly the same effect as the following example -(which consists of two listings): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class AnotherExampleBean implements InitializingBean { - - @Override - public void afterPropertiesSet() { - // do some initialization work - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class AnotherExampleBean : InitializingBean { - - override fun afterPropertiesSet() { - // do some initialization work - } - } ----- - -However, the first of the two preceding examples does not couple the code to Spring. - - -[[beans-factory-lifecycle-disposablebean]] -==== Destruction Callbacks - -Implementing the `org.springframework.beans.factory.DisposableBean` interface lets a -bean get a callback when the container that contains it is destroyed. The -`DisposableBean` interface specifies a single method: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - void destroy() throws Exception; ----- - -We recommend that you do not use the `DisposableBean` callback interface, because it -unnecessarily couples the code to Spring. Alternatively, we suggest using -the <> annotation or -specifying a generic method that is supported by bean definitions. With XML-based -configuration metadata, you can use the `destroy-method` attribute on the ``. -With Java configuration, you can use the `destroyMethod` attribute of `@Bean`. See -<>. Consider the following definition: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ExampleBean { - - public void cleanup() { - // do some destruction work (like releasing pooled connections) - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ExampleBean { - - fun cleanup() { - // do some destruction work (like releasing pooled connections) - } - } ----- - -The preceding definition has almost exactly the same effect as the following definition: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class AnotherExampleBean implements DisposableBean { - - @Override - public void destroy() { - // do some destruction work (like releasing pooled connections) - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class AnotherExampleBean : DisposableBean { - - override fun destroy() { - // do some destruction work (like releasing pooled connections) - } - } ----- - -However, the first of the two preceding definitions does not couple the code to Spring. - -TIP: You can assign the `destroy-method` attribute of a `` element a special -`(inferred)` value, which instructs Spring to automatically detect a public `close` or -`shutdown` method on the specific bean class. (Any class that implements -`java.lang.AutoCloseable` or `java.io.Closeable` would therefore match.) You can also set -this special `(inferred)` value on the `default-destroy-method` attribute of a -`` element to apply this behavior to an entire set of beans (see -<>). Note that this is the -default behavior with Java configuration. - -[[beans-factory-lifecycle-default-init-destroy-methods]] -==== Default Initialization and Destroy Methods - -When you write initialization and destroy method callbacks that do not use the -Spring-specific `InitializingBean` and `DisposableBean` callback interfaces, you -typically write methods with names such as `init()`, `initialize()`, `dispose()`, and so -on. Ideally, the names of such lifecycle callback methods are standardized across a -project so that all developers use the same method names and ensure consistency. - -You can configure the Spring container to "`look`" for named initialization and destroy -callback method names on every bean. This means that you, as an application -developer, can write your application classes and use an initialization callback called -`init()`, without having to configure an `init-method="init"` attribute with each bean -definition. The Spring IoC container calls that method when the bean is created (and in -accordance with the standard lifecycle callback contract <>). This feature also enforces a consistent naming convention for -initialization and destroy method callbacks. - -Suppose that your initialization callback methods are named `init()` and your destroy -callback methods are named `destroy()`. Your class then resembles the class in the -following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class DefaultBlogService implements BlogService { - - private BlogDao blogDao; - - public void setBlogDao(BlogDao blogDao) { - this.blogDao = blogDao; - } - - // this is (unsurprisingly) the initialization callback method - public void init() { - if (this.blogDao == null) { - throw new IllegalStateException("The [blogDao] property must be set."); - } - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class DefaultBlogService : BlogService { - - private var blogDao: BlogDao? = null - - // this is (unsurprisingly) the initialization callback method - fun init() { - if (blogDao == null) { - throw IllegalStateException("The [blogDao] property must be set.") - } - } - } ----- - -You could then use that class in a bean resembling the following: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -The presence of the `default-init-method` attribute on the top-level `` element -attribute causes the Spring IoC container to recognize a method called `init` on the bean -class as the initialization method callback. When a bean is created and assembled, if the -bean class has such a method, it is invoked at the appropriate time. - -You can configure destroy method callbacks similarly (in XML, that is) by using the -`default-destroy-method` attribute on the top-level `` element. - -Where existing bean classes already have callback methods that are named at variance -with the convention, you can override the default by specifying (in XML, that is) the -method name by using the `init-method` and `destroy-method` attributes of the `` -itself. - -The Spring container guarantees that a configured initialization callback is called -immediately after a bean is supplied with all dependencies. Thus, the initialization -callback is called on the raw bean reference, which means that AOP interceptors and so -forth are not yet applied to the bean. A target bean is fully created first and -then an AOP proxy (for example) with its interceptor chain is applied. If the target -bean and the proxy are defined separately, your code can even interact with the raw -target bean, bypassing the proxy. Hence, it would be inconsistent to apply the -interceptors to the `init` method, because doing so would couple the lifecycle of the -target bean to its proxy or interceptors and leave strange semantics when your code -interacts directly with the raw target bean. - - - -[[beans-factory-lifecycle-combined-effects]] -==== Combining Lifecycle Mechanisms - -As of Spring 2.5, you have three options for controlling bean lifecycle behavior: - -* The <> and -<> callback interfaces -* Custom `init()` and `destroy()` methods -* The <>. You can combine these mechanisms to control a given bean. - -NOTE: If multiple lifecycle mechanisms are configured for a bean and each mechanism is -configured with a different method name, then each configured method is run in the -order listed after this note. However, if the same method name is configured -- for example, -`init()` for an initialization method -- for more than one of these lifecycle mechanisms, -that method is run once, as explained in the -<>. - -Multiple lifecycle mechanisms configured for the same bean, with different -initialization methods, are called as follows: - -. Methods annotated with `@PostConstruct` -. `afterPropertiesSet()` as defined by the `InitializingBean` callback interface -. A custom configured `init()` method - -Destroy methods are called in the same order: - -. Methods annotated with `@PreDestroy` -. `destroy()` as defined by the `DisposableBean` callback interface -. A custom configured `destroy()` method - - - -[[beans-factory-lifecycle-processor]] -==== Startup and Shutdown Callbacks - -The `Lifecycle` interface defines the essential methods for any object that has its own -lifecycle requirements (such as starting and stopping some background process): - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface Lifecycle { - - void start(); - - void stop(); - - boolean isRunning(); - } ----- - -Any Spring-managed object may implement the `Lifecycle` interface. Then, when the -`ApplicationContext` itself receives start and stop signals (for example, for a stop/restart -scenario at runtime), it cascades those calls to all `Lifecycle` implementations -defined within that context. It does this by delegating to a `LifecycleProcessor`, shown -in the following listing: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface LifecycleProcessor extends Lifecycle { - - void onRefresh(); - - void onClose(); - } ----- - -Notice that the `LifecycleProcessor` is itself an extension of the `Lifecycle` -interface. It also adds two other methods for reacting to the context being refreshed -and closed. - -[TIP] -==== -Note that the regular `org.springframework.context.Lifecycle` interface is a plain -contract for explicit start and stop notifications and does not imply auto-startup at context -refresh time. For fine-grained control over auto-startup of a specific bean (including startup phases), -consider implementing `org.springframework.context.SmartLifecycle` instead. - -Also, please note that stop notifications are not guaranteed to come before destruction. -On regular shutdown, all `Lifecycle` beans first receive a stop notification before -the general destruction callbacks are being propagated. However, on hot refresh during a -context's lifetime or on stopped refresh attempts, only destroy methods are called. -==== - -The order of startup and shutdown invocations can be important. If a "`depends-on`" -relationship exists between any two objects, the dependent side starts after its -dependency, and it stops before its dependency. However, at times, the direct -dependencies are unknown. You may only know that objects of a certain type should start -prior to objects of another type. In those cases, the `SmartLifecycle` interface defines -another option, namely the `getPhase()` method as defined on its super-interface, -`Phased`. The following listing shows the definition of the `Phased` interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface Phased { - - int getPhase(); - } ----- - -The following listing shows the definition of the `SmartLifecycle` interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface SmartLifecycle extends Lifecycle, Phased { - - boolean isAutoStartup(); - - void stop(Runnable callback); - } ----- - -When starting, the objects with the lowest phase start first. When stopping, the -reverse order is followed. Therefore, an object that implements `SmartLifecycle` and -whose `getPhase()` method returns `Integer.MIN_VALUE` would be among the first to start -and the last to stop. At the other end of the spectrum, a phase value of -`Integer.MAX_VALUE` would indicate that the object should be started last and stopped -first (likely because it depends on other processes to be running). When considering the -phase value, it is also important to know that the default phase for any "`normal`" -`Lifecycle` object that does not implement `SmartLifecycle` is `0`. Therefore, any -negative phase value indicates that an object should start before those standard -components (and stop after them). The reverse is true for any positive phase value. - -The stop method defined by `SmartLifecycle` accepts a callback. Any -implementation must invoke that callback's `run()` method after that implementation's -shutdown process is complete. That enables asynchronous shutdown where necessary, since -the default implementation of the `LifecycleProcessor` interface, -`DefaultLifecycleProcessor`, waits up to its timeout value for the group of objects -within each phase to invoke that callback. The default per-phase timeout is 30 seconds. -You can override the default lifecycle processor instance by defining a bean named -`lifecycleProcessor` within the context. If you want only to modify the timeout, -defining the following would suffice: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - -As mentioned earlier, the `LifecycleProcessor` interface defines callback methods for the -refreshing and closing of the context as well. The latter drives the shutdown -process as if `stop()` had been called explicitly, but it happens when the context is -closing. The 'refresh' callback, on the other hand, enables another feature of -`SmartLifecycle` beans. When the context is refreshed (after all objects have been -instantiated and initialized), that callback is invoked. At that point, the -default lifecycle processor checks the boolean value returned by each -`SmartLifecycle` object's `isAutoStartup()` method. If `true`, that object is -started at that point rather than waiting for an explicit invocation of the context's or -its own `start()` method (unlike the context refresh, the context start does not happen -automatically for a standard context implementation). The `phase` value and any -"`depends-on`" relationships determine the startup order as described earlier. - - - -[[beans-factory-shutdown]] -==== Shutting Down the Spring IoC Container Gracefully in Non-Web Applications - -[NOTE] -==== -This section applies only to non-web applications. Spring's web-based -`ApplicationContext` implementations already have code in place to gracefully shut down -the Spring IoC container when the relevant web application is shut down. -==== - -If you use Spring's IoC container in a non-web application environment (for -example, in a rich client desktop environment), register a shutdown hook with the -JVM. Doing so ensures a graceful shutdown and calls the relevant destroy methods on your -singleton beans so that all resources are released. You must still configure -and implement these destroy callbacks correctly. - -To register a shutdown hook, call the `registerShutdownHook()` method that is -declared on the `ConfigurableApplicationContext` interface, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import org.springframework.context.ConfigurableApplicationContext; - import org.springframework.context.support.ClassPathXmlApplicationContext; - - public final class Boot { - - public static void main(final String[] args) throws Exception { - ConfigurableApplicationContext ctx = new ClassPathXmlApplicationContext("beans.xml"); - - // add a shutdown hook for the above context... - ctx.registerShutdownHook(); - - // app runs here... - - // main method exits, hook is called prior to the app shutting down... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.context.support.ClassPathXmlApplicationContext - - fun main() { - val ctx = ClassPathXmlApplicationContext("beans.xml") - - // add a shutdown hook for the above context... - ctx.registerShutdownHook() - - // app runs here... - - // main method exits, hook is called prior to the app shutting down... - } ----- - - - -[[beans-factory-aware]] -=== `ApplicationContextAware` and `BeanNameAware` - -When an `ApplicationContext` creates an object instance that implements the -`org.springframework.context.ApplicationContextAware` interface, the instance is provided -with a reference to that `ApplicationContext`. The following listing shows the definition -of the `ApplicationContextAware` interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface ApplicationContextAware { - - void setApplicationContext(ApplicationContext applicationContext) throws BeansException; - } ----- - -Thus, beans can programmatically manipulate the `ApplicationContext` that created them, -through the `ApplicationContext` interface or by casting the reference to a known -subclass of this interface (such as `ConfigurableApplicationContext`, which exposes -additional functionality). One use would be the programmatic retrieval of other beans. -Sometimes this capability is useful. However, in general, you should avoid it, because -it couples the code to Spring and does not follow the Inversion of Control style, -where collaborators are provided to beans as properties. Other methods of the -`ApplicationContext` provide access to file resources, publishing application events, -and accessing a `MessageSource`. These additional features are described in -<>. - -Autowiring is another alternative to obtain a reference to the -`ApplicationContext`. The _traditional_ `constructor` and `byType` autowiring modes -(as described in <>) can provide a dependency of type -`ApplicationContext` for a constructor argument or a setter method parameter, -respectively. For more flexibility, including the ability to autowire fields and -multiple parameter methods, use the annotation-based autowiring features. If you do, -the `ApplicationContext` is autowired into a field, constructor argument, or method -parameter that expects the `ApplicationContext` type if the field, constructor, or -method in question carries the `@Autowired` annotation. For more information, see -<>. - -When an `ApplicationContext` creates a class that implements the -`org.springframework.beans.factory.BeanNameAware` interface, the class is provided with -a reference to the name defined in its associated object definition. The following listing -shows the definition of the BeanNameAware interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface BeanNameAware { - - void setBeanName(String name) throws BeansException; - } ----- - -The callback is invoked after population of normal bean properties but before an -initialization callback such as `InitializingBean.afterPropertiesSet()` or a custom -init-method. - - - -[[aware-list]] -=== Other `Aware` Interfaces - -Besides `ApplicationContextAware` and `BeanNameAware` (discussed <>), -Spring offers a wide range of `Aware` callback interfaces that let beans indicate to the container -that they require a certain infrastructure dependency. As a general rule, the name indicates the -dependency type. The following table summarizes the most important `Aware` interfaces: - -[[beans-factory-nature-aware-list]] -.Aware interfaces -|=== -| Name| Injected Dependency| Explained in... - -| `ApplicationContextAware` -| Declaring `ApplicationContext`. -| <> - -| `ApplicationEventPublisherAware` -| Event publisher of the enclosing `ApplicationContext`. -| <> - -| `BeanClassLoaderAware` -| Class loader used to load the bean classes. -| <> - -| `BeanFactoryAware` -| Declaring `BeanFactory`. -| <> - -| `BeanNameAware` -| Name of the declaring bean. -| <> - -| `LoadTimeWeaverAware` -| Defined weaver for processing class definition at load time. -| <> - -| `MessageSourceAware` -| Configured strategy for resolving messages (with support for parameterization and - internationalization). -| <> - -| `NotificationPublisherAware` -| Spring JMX notification publisher. -| <> - -| `ResourceLoaderAware` -| Configured loader for low-level access to resources. -| <> - -| `ServletConfigAware` -| Current `ServletConfig` the container runs in. Valid only in a web-aware Spring - `ApplicationContext`. -| <> - -| `ServletContextAware` -| Current `ServletContext` the container runs in. Valid only in a web-aware Spring - `ApplicationContext`. -| <> -|=== - -Note again that using these interfaces ties your code to the Spring API and does not -follow the Inversion of Control style. As a result, we recommend them for infrastructure -beans that require programmatic access to the container. - - - -[[beans-child-bean-definitions]] -== Bean Definition Inheritance - -A bean definition can contain a lot of configuration information, including constructor -arguments, property values, and container-specific information, such as the initialization -method, a static factory method name, and so on. A child bean definition inherits -configuration data from a parent definition. The child definition can override some -values or add others as needed. Using parent and child bean definitions can save a lot -of typing. Effectively, this is a form of templating. - -If you work with an `ApplicationContext` interface programmatically, child bean -definitions are represented by the `ChildBeanDefinition` class. Most users do not work -with them on this level. Instead, they configure bean definitions declaratively in a class -such as the `ClassPathXmlApplicationContext`. When you use XML-based configuration -metadata, you can indicate a child bean definition by using the `parent` attribute, -specifying the parent bean as the value of this attribute. The following example shows how -to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - <1> - - - ----- -<1> Note the `parent` attribute. - -A child bean definition uses the bean class from the parent definition if none is -specified but can also override it. In the latter case, the child bean class must be -compatible with the parent (that is, it must accept the parent's property values). - -A child bean definition inherits scope, constructor argument values, property values, and -method overrides from the parent, with the option to add new values. Any scope, initialization -method, destroy method, or `static` factory method settings that you specify -override the corresponding parent settings. - -The remaining settings are always taken from the child definition: depends on, -autowire mode, dependency check, singleton, and lazy init. - -The preceding example explicitly marks the parent bean definition as abstract by using -the `abstract` attribute. If the parent definition does not specify a class, explicitly -marking the parent bean definition as `abstract` is required, as the following example -shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - ----- - -The parent bean cannot be instantiated on its own because it is incomplete, and it is -also explicitly marked as `abstract`. When a definition is `abstract`, it is -usable only as a pure template bean definition that serves as a parent definition for -child definitions. Trying to use such an `abstract` parent bean on its own, by referring -to it as a ref property of another bean or doing an explicit `getBean()` call with the -parent bean ID returns an error. Similarly, the container's internal -`preInstantiateSingletons()` method ignores bean definitions that are defined as -abstract. - -NOTE: `ApplicationContext` pre-instantiates all singletons by default. Therefore, it is -important (at least for singleton beans) that if you have a (parent) bean definition -which you intend to use only as a template, and this definition specifies a class, you -must make sure to set the __abstract__ attribute to __true__, otherwise the application -context will actually (attempt to) pre-instantiate the `abstract` bean. - - - - -[[beans-factory-extension]] -== Container Extension Points - -Typically, an application developer does not need to subclass `ApplicationContext` -implementation classes. Instead, the Spring IoC container can be extended by plugging in -implementations of special integration interfaces. The next few sections describe these -integration interfaces. - - - -[[beans-factory-extension-bpp]] -=== Customizing Beans by Using a `BeanPostProcessor` - -The `BeanPostProcessor` interface defines callback methods that you can implement to -provide your own (or override the container's default) instantiation logic, dependency -resolution logic, and so forth. If you want to implement some custom logic after the -Spring container finishes instantiating, configuring, and initializing a bean, you can -plug in one or more custom `BeanPostProcessor` implementations. - -You can configure multiple `BeanPostProcessor` instances, and you can control the order -in which these `BeanPostProcessor` instances run by setting the `order` property. -You can set this property only if the `BeanPostProcessor` implements the `Ordered` -interface. If you write your own `BeanPostProcessor`, you should consider implementing -the `Ordered` interface, too. For further details, see the javadoc of the -{api-spring-framework}/beans/factory/config/BeanPostProcessor.html[`BeanPostProcessor`] -and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces. See also the note -on <>. - -[NOTE] -==== -`BeanPostProcessor` instances operate on bean (or object) instances. That is, -the Spring IoC container instantiates a bean instance and then `BeanPostProcessor` -instances do their work. - -`BeanPostProcessor` instances are scoped per-container. This is relevant only if you -use container hierarchies. If you define a `BeanPostProcessor` in one container, -it post-processes only the beans in that container. In other words, beans that are -defined in one container are not post-processed by a `BeanPostProcessor` defined in -another container, even if both containers are part of the same hierarchy. - -To change the actual bean definition (that is, the blueprint that defines the bean), -you instead need to use a `BeanFactoryPostProcessor`, as described in -<>. -==== - -The `org.springframework.beans.factory.config.BeanPostProcessor` interface consists of -exactly two callback methods. When such a class is registered as a post-processor with -the container, for each bean instance that is created by the container, the -post-processor gets a callback from the container both before container -initialization methods (such as `InitializingBean.afterPropertiesSet()` or any -declared `init` method) are called, and after any bean initialization callbacks. -The post-processor can take any action with the bean instance, including ignoring the -callback completely. A bean post-processor typically checks for callback interfaces, -or it may wrap a bean with a proxy. Some Spring AOP infrastructure classes are -implemented as bean post-processors in order to provide proxy-wrapping logic. - -An `ApplicationContext` automatically detects any beans that are defined in the -configuration metadata that implement the `BeanPostProcessor` interface. The -`ApplicationContext` registers these beans as post-processors so that they can be called -later, upon bean creation. Bean post-processors can be deployed in the container in the -same fashion as any other beans. - -Note that, when declaring a `BeanPostProcessor` by using an `@Bean` factory method on a -configuration class, the return type of the factory method should be the implementation -class itself or at least the `org.springframework.beans.factory.config.BeanPostProcessor` -interface, clearly indicating the post-processor nature of that bean. Otherwise, the -`ApplicationContext` cannot autodetect it by type before fully creating it. -Since a `BeanPostProcessor` needs to be instantiated early in order to apply to the -initialization of other beans in the context, this early type detection is critical. - -[[beans-factory-programmatically-registering-beanpostprocessors]] -.Programmatically registering `BeanPostProcessor` instances -NOTE: While the recommended approach for `BeanPostProcessor` registration is through -`ApplicationContext` auto-detection (as described earlier), you can register them -programmatically against a `ConfigurableBeanFactory` by using the `addBeanPostProcessor` -method. This can be useful when you need to evaluate conditional logic before -registration or even for copying bean post processors across contexts in a hierarchy. -Note, however, that `BeanPostProcessor` instances added programmatically do not respect -the `Ordered` interface. Here, it is the order of registration that dictates the order -of execution. Note also that `BeanPostProcessor` instances registered programmatically -are always processed before those registered through auto-detection, regardless of any -explicit ordering. - -.`BeanPostProcessor` instances and AOP auto-proxying -[NOTE] -==== -Classes that implement the `BeanPostProcessor` interface are special and are treated -differently by the container. All `BeanPostProcessor` instances and beans that they -directly reference are instantiated on startup, as part of the special startup phase -of the `ApplicationContext`. Next, all `BeanPostProcessor` instances are registered -in a sorted fashion and applied to all further beans in the container. Because AOP -auto-proxying is implemented as a `BeanPostProcessor` itself, neither `BeanPostProcessor` -instances nor the beans they directly reference are eligible for auto-proxying and, -thus, do not have aspects woven into them. - -For any such bean, you should see an informational log message: `Bean someBean is not -eligible for getting processed by all BeanPostProcessor interfaces (for example: not -eligible for auto-proxying)`. - -If you have beans wired into your `BeanPostProcessor` by using autowiring or -`@Resource` (which may fall back to autowiring), Spring might access unexpected beans -when searching for type-matching dependency candidates and, therefore, make them -ineligible for auto-proxying or other kinds of bean post-processing. For example, if you -have a dependency annotated with `@Resource` where the field or setter name does not -directly correspond to the declared name of a bean and no name attribute is used, -Spring accesses other beans for matching them by type. -==== - -The following examples show how to write, register, and use `BeanPostProcessor` instances -in an `ApplicationContext`. - - -[[beans-factory-extension-bpp-examples-hw]] -==== Example: Hello World, `BeanPostProcessor`-style - -This first example illustrates basic usage. The example shows a custom -`BeanPostProcessor` implementation that invokes the `toString()` method of each bean as -it is created by the container and prints the resulting string to the system console. - -The following listing shows the custom `BeanPostProcessor` implementation class definition: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package scripting; - - import org.springframework.beans.factory.config.BeanPostProcessor; - - public class InstantiationTracingBeanPostProcessor implements BeanPostProcessor { - - // simply return the instantiated bean as-is - public Object postProcessBeforeInitialization(Object bean, String beanName) { - return bean; // we could potentially return any object reference here... - } - - public Object postProcessAfterInitialization(Object bean, String beanName) { - System.out.println("Bean '" + beanName + "' created : " + bean.toString()); - return bean; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package scripting - - import org.springframework.beans.factory.config.BeanPostProcessor - - class InstantiationTracingBeanPostProcessor : BeanPostProcessor { - - // simply return the instantiated bean as-is - override fun postProcessBeforeInitialization(bean: Any, beanName: String): Any? { - return bean // we could potentially return any object reference here... - } - - override fun postProcessAfterInitialization(bean: Any, beanName: String): Any? { - println("Bean '$beanName' created : $bean") - return bean - } - } ----- - -The following `beans` element uses the `InstantiationTracingBeanPostProcessor`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - ----- - -Notice how the `InstantiationTracingBeanPostProcessor` is merely defined. It does not -even have a name, and, because it is a bean, it can be dependency-injected as you would any -other bean. (The preceding configuration also defines a bean that is backed by a Groovy -script. The Spring dynamic language support is detailed in the chapter entitled -<>.) - -The following Java application runs the preceding code and configuration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import org.springframework.context.ApplicationContext; - import org.springframework.context.support.ClassPathXmlApplicationContext; - import org.springframework.scripting.Messenger; - - public final class Boot { - - public static void main(final String[] args) throws Exception { - ApplicationContext ctx = new ClassPathXmlApplicationContext("scripting/beans.xml"); - Messenger messenger = ctx.getBean("messenger", Messenger.class); - System.out.println(messenger); - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - fun main() { - val ctx = ClassPathXmlApplicationContext("scripting/beans.xml") - val messenger = ctx.getBean("messenger") - println(messenger) - } ----- - -The output of the preceding application resembles the following: - -[literal,subs="verbatim,quotes"] ----- -Bean 'messenger' created : org.springframework.scripting.groovy.GroovyMessenger@272961 -org.springframework.scripting.groovy.GroovyMessenger@272961 ----- - - -[[beans-factory-extension-bpp-examples-aabpp]] -==== Example: The `AutowiredAnnotationBeanPostProcessor` - -Using callback interfaces or annotations in conjunction with a custom `BeanPostProcessor` -implementation is a common means of extending the Spring IoC container. An example is -Spring's `AutowiredAnnotationBeanPostProcessor` -- a `BeanPostProcessor` implementation -that ships with the Spring distribution and autowires annotated fields, setter methods, -and arbitrary config methods. - - - -[[beans-factory-extension-factory-postprocessors]] -=== Customizing Configuration Metadata with a `BeanFactoryPostProcessor` - -The next extension point that we look at is the -`org.springframework.beans.factory.config.BeanFactoryPostProcessor`. The semantics of -this interface are similar to those of the `BeanPostProcessor`, with one major -difference: `BeanFactoryPostProcessor` operates on the bean configuration metadata. -That is, the Spring IoC container lets a `BeanFactoryPostProcessor` read the -configuration metadata and potentially change it _before_ the container instantiates -any beans other than `BeanFactoryPostProcessor` instances. - -You can configure multiple `BeanFactoryPostProcessor` instances, and you can control the order in -which these `BeanFactoryPostProcessor` instances run by setting the `order` property. -However, you can only set this property if the `BeanFactoryPostProcessor` implements the -`Ordered` interface. If you write your own `BeanFactoryPostProcessor`, you should -consider implementing the `Ordered` interface, too. See the javadoc of the -{api-spring-framework}/beans/factory/config/BeanFactoryPostProcessor.html[`BeanFactoryPostProcessor`] -and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces for more details. - -[NOTE] -==== -If you want to change the actual bean instances (that is, the objects that are created -from the configuration metadata), then you instead need to use a `BeanPostProcessor` -(described earlier in <>). While it is technically possible -to work with bean instances within a `BeanFactoryPostProcessor` (for example, by using -`BeanFactory.getBean()`), doing so causes premature bean instantiation, violating the -standard container lifecycle. This may cause negative side effects, such as bypassing -bean post processing. - -Also, `BeanFactoryPostProcessor` instances are scoped per-container. This is only relevant -if you use container hierarchies. If you define a `BeanFactoryPostProcessor` in one -container, it is applied only to the bean definitions in that container. Bean definitions -in one container are not post-processed by `BeanFactoryPostProcessor` instances in another -container, even if both containers are part of the same hierarchy. -==== - -A bean factory post-processor is automatically run when it is declared inside an -`ApplicationContext`, in order to apply changes to the configuration metadata that -define the container. Spring includes a number of predefined bean factory -post-processors, such as `PropertyOverrideConfigurer` and -`PropertySourcesPlaceholderConfigurer`. You can also use a custom `BeanFactoryPostProcessor` --- for example, to register custom property editors. - -An `ApplicationContext` automatically detects any beans that are deployed into it that -implement the `BeanFactoryPostProcessor` interface. It uses these beans as bean factory -post-processors, at the appropriate time. You can deploy these post-processor beans as -you would any other bean. - -NOTE: As with ``BeanPostProcessor``s , you typically do not want to configure -``BeanFactoryPostProcessor``s for lazy initialization. If no other bean references a -`Bean(Factory)PostProcessor`, that post-processor will not get instantiated at all. -Thus, marking it for lazy initialization will be ignored, and the -`Bean(Factory)PostProcessor` will be instantiated eagerly even if you set the -`default-lazy-init` attribute to `true` on the declaration of your `` element. - - -[[beans-factory-placeholderconfigurer]] -==== Example: The Class Name Substitution `PropertySourcesPlaceholderConfigurer` - -You can use the `PropertySourcesPlaceholderConfigurer` to externalize property values -from a bean definition in a separate file by using the standard Java `Properties` format. -Doing so enables the person deploying an application to customize environment-specific -properties, such as database URLs and passwords, without the complexity or risk of -modifying the main XML definition file or files for the container. - -Consider the following XML-based configuration metadata fragment, where a `DataSource` -with placeholder values is defined: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - ----- - -The example shows properties configured from an external `Properties` file. At runtime, -a `PropertySourcesPlaceholderConfigurer` is applied to the metadata that replaces some -properties of the DataSource. The values to replace are specified as placeholders of the -form pass:q[`${property-name}`], which follows the Ant and log4j and JSP EL style. - -The actual values come from another file in the standard Java `Properties` format: - -[literal,subs="verbatim,quotes"] ----- -jdbc.driverClassName=org.hsqldb.jdbcDriver -jdbc.url=jdbc:hsqldb:hsql://production:9002 -jdbc.username=sa -jdbc.password=root ----- - -Therefore, the `${jdbc.username}` string is replaced at runtime with the value, 'sa', and -the same applies for other placeholder values that match keys in the properties file. -The `PropertySourcesPlaceholderConfigurer` checks for placeholders in most properties and -attributes of a bean definition. Furthermore, you can customize the placeholder prefix and suffix. - -With the `context` namespace introduced in Spring 2.5, you can configure property placeholders -with a dedicated configuration element. You can provide one or more locations as a -comma-separated list in the `location` attribute, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -The `PropertySourcesPlaceholderConfigurer` not only looks for properties in the `Properties` -file you specify. By default, if it cannot find a property in the specified properties files, -it checks against Spring `Environment` properties and regular Java `System` properties. - -[TIP] -===== -You can use the `PropertySourcesPlaceholderConfigurer` to substitute class names, which -is sometimes useful when you have to pick a particular implementation class at runtime. -The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - classpath:com/something/strategy.properties - - - custom.strategy.class=com.something.DefaultStrategy - - - - ----- - -If the class cannot be resolved at runtime to a valid class, resolution of the bean -fails when it is about to be created, which is during the `preInstantiateSingletons()` -phase of an `ApplicationContext` for a non-lazy-init bean. -===== - - -[[beans-factory-overrideconfigurer]] -==== Example: The `PropertyOverrideConfigurer` - -The `PropertyOverrideConfigurer`, another bean factory post-processor, resembles the -`PropertySourcesPlaceholderConfigurer`, but unlike the latter, the original definitions -can have default values or no values at all for bean properties. If an overriding -`Properties` file does not have an entry for a certain bean property, the default -context definition is used. - -Note that the bean definition is not aware of being overridden, so it is not -immediately obvious from the XML definition file that the override configurer is being -used. In case of multiple `PropertyOverrideConfigurer` instances that define different -values for the same bean property, the last one wins, due to the overriding mechanism. - -Properties file configuration lines take the following format: - -[literal,subs="verbatim,quotes"] ----- -beanName.property=value ----- - -The following listing shows an example of the format: - -[literal,subs="verbatim,quotes"] ----- -dataSource.driverClassName=com.mysql.jdbc.Driver -dataSource.url=jdbc:mysql:mydb ----- - -This example file can be used with a container definition that contains a bean called -`dataSource` that has `driver` and `url` properties. - -Compound property names are also supported, as long as every component of the path -except the final property being overridden is already non-null (presumably initialized -by the constructors). In the following example, the `sammy` property of the `bob` property of the `fred` property of the `tom` bean -is set to the scalar value `123`: - -[literal,subs="verbatim,quotes"] ----- -tom.fred.bob.sammy=123 ----- - - -NOTE: Specified override values are always literal values. They are not translated into -bean references. This convention also applies when the original value in the XML bean -definition specifies a bean reference. - -With the `context` namespace introduced in Spring 2.5, it is possible to configure -property overriding with a dedicated configuration element, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - - - -[[beans-factory-extension-factorybean]] -=== Customizing Instantiation Logic with a `FactoryBean` - -You can implement the `org.springframework.beans.factory.FactoryBean` interface for objects that -are themselves factories. - -The `FactoryBean` interface is a point of pluggability into the Spring IoC container's -instantiation logic. If you have complex initialization code that is better expressed in -Java as opposed to a (potentially) verbose amount of XML, you can create your own -`FactoryBean`, write the complex initialization inside that class, and then plug your -custom `FactoryBean` into the container. - -The `FactoryBean` interface provides three methods: - -* `T getObject()`: Returns an instance of the object this factory creates. The - instance can possibly be shared, depending on whether this factory returns singletons - or prototypes. -* `boolean isSingleton()`: Returns `true` if this `FactoryBean` returns singletons or - `false` otherwise. The default implementation of this method returns `true`. -* `Class getObjectType()`: Returns the object type returned by the `getObject()` method - or `null` if the type is not known in advance. - -The `FactoryBean` concept and interface are used in a number of places within the Spring -Framework. More than 50 implementations of the `FactoryBean` interface ship with Spring -itself. - -When you need to ask a container for an actual `FactoryBean` instance itself instead of -the bean it produces, prefix the bean's `id` with the ampersand symbol (`&`) when -calling the `getBean()` method of the `ApplicationContext`. So, for a given `FactoryBean` -with an `id` of `myBean`, invoking `getBean("myBean")` on the container returns the -product of the `FactoryBean`, whereas invoking `getBean("&myBean")` returns the -`FactoryBean` instance itself. - - - -[[beans-annotation-config]] -== Annotation-based Container Configuration - -.Are annotations better than XML for configuring Spring? -**** -The introduction of annotation-based configuration raised the question of whether this -approach is "`better`" than XML. The short answer is "`it depends.`" The long answer is -that each approach has its pros and cons, and, usually, it is up to the developer to -decide which strategy suits them better. Due to the way they are defined, annotations -provide a lot of context in their declaration, leading to shorter and more concise -configuration. However, XML excels at wiring up components without touching their source -code or recompiling them. Some developers prefer having the wiring close to the source -while others argue that annotated classes are no longer POJOs and, furthermore, that the -configuration becomes decentralized and harder to control. - -No matter the choice, Spring can accommodate both styles and even mix them together. -It is worth pointing out that through its <> option, Spring lets -annotations be used in a non-invasive way, without touching the target components' -source code and that, in terms of tooling, all configuration styles are supported by -https://spring.io/tools[Spring Tools] for Eclipse, Visual Studio Code, and Theia. -**** - -An alternative to XML setup is provided by annotation-based configuration, which relies -on bytecode metadata for wiring up components instead of XML declarations. Instead of -using XML to describe a bean wiring, the developer moves the configuration into the -component class itself by using annotations on the relevant class, method, or field -declaration. As mentioned in <>, using a -`BeanPostProcessor` in conjunction with annotations is a common means of extending the -Spring IoC container. For example, the <> -annotation provides the same capabilities as described in <> but -with more fine-grained control and wider applicability. In addition, Spring provides -support for JSR-250 annotations, such as `@PostConstruct` and `@PreDestroy`, as well as -support for JSR-330 (Dependency Injection for Java) annotations contained in the -`jakarta.inject` package such as `@Inject` and `@Named`. Details about those annotations -can be found in the <>. - -[NOTE] -==== -Annotation injection is performed before XML injection. Thus, the XML configuration -overrides the annotations for properties wired through both approaches. -==== - -As always, you can register the post-processors as individual bean definitions, but they -can also be implicitly registered by including the following tag in an XML-based Spring -configuration (notice the inclusion of the `context` namespace): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -The `` element implicitly registers the following post-processors: - -* {api-spring-framework}/context/annotation/ConfigurationClassPostProcessor.html[`ConfigurationClassPostProcessor`] -* {api-spring-framework}/beans/factory/annotation/AutowiredAnnotationBeanPostProcessor.html[`AutowiredAnnotationBeanPostProcessor`] -* {api-spring-framework}/context/annotation/CommonAnnotationBeanPostProcessor.html[`CommonAnnotationBeanPostProcessor`] -* {api-spring-framework}/orm/jpa/support/PersistenceAnnotationBeanPostProcessor.html[`PersistenceAnnotationBeanPostProcessor`] -* {api-spring-framework}/context/event/EventListenerMethodProcessor.html[`EventListenerMethodProcessor`] - -[NOTE] -==== -`` only looks for annotations on beans in the same -application context in which it is defined. This means that, if you put -`` in a `WebApplicationContext` for a `DispatcherServlet`, -it only checks for `@Autowired` beans in your controllers, and not your services. See -<> for more information. -==== - - - -[[beans-autowired-annotation]] -=== Using `@Autowired` - -[NOTE] -==== -JSR 330's `@Inject` annotation can be used in place of Spring's `@Autowired` annotation in the -examples included in this section. See <> for more details. -==== - -You can apply the `@Autowired` annotation to constructors, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - private final CustomerPreferenceDao customerPreferenceDao; - - @Autowired - public MovieRecommender(CustomerPreferenceDao customerPreferenceDao) { - this.customerPreferenceDao = customerPreferenceDao; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender @Autowired constructor( - private val customerPreferenceDao: CustomerPreferenceDao) ----- - -[NOTE] -==== -As of Spring Framework 4.3, an `@Autowired` annotation on such a constructor is no longer -necessary if the target bean defines only one constructor to begin with. However, if -several constructors are available and there is no primary/default constructor, at least -one of the constructors must be annotated with `@Autowired` in order to instruct the -container which one to use. See the discussion on -<> for details. -==== - -You can also apply the `@Autowired` annotation to _traditional_ setter methods, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleMovieLister { - - private MovieFinder movieFinder; - - @Autowired - public void setMovieFinder(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SimpleMovieLister { - - @set:Autowired - lateinit var movieFinder: MovieFinder - - // ... - - } ----- - -You can also apply the annotation to methods with arbitrary names and multiple -arguments, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - private MovieCatalog movieCatalog; - - private CustomerPreferenceDao customerPreferenceDao; - - @Autowired - public void prepare(MovieCatalog movieCatalog, - CustomerPreferenceDao customerPreferenceDao) { - this.movieCatalog = movieCatalog; - this.customerPreferenceDao = customerPreferenceDao; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender { - - private lateinit var movieCatalog: MovieCatalog - - private lateinit var customerPreferenceDao: CustomerPreferenceDao - - @Autowired - fun prepare(movieCatalog: MovieCatalog, - customerPreferenceDao: CustomerPreferenceDao) { - this.movieCatalog = movieCatalog - this.customerPreferenceDao = customerPreferenceDao - } - - // ... - } ----- - -You can apply `@Autowired` to fields as well and even mix it with constructors, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - private final CustomerPreferenceDao customerPreferenceDao; - - @Autowired - private MovieCatalog movieCatalog; - - @Autowired - public MovieRecommender(CustomerPreferenceDao customerPreferenceDao) { - this.customerPreferenceDao = customerPreferenceDao; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender @Autowired constructor( - private val customerPreferenceDao: CustomerPreferenceDao) { - - @Autowired - private lateinit var movieCatalog: MovieCatalog - - // ... - } ----- - -[TIP] -==== -Make sure that your target components (for example, `MovieCatalog` or `CustomerPreferenceDao`) -are consistently declared by the type that you use for your `@Autowired`-annotated -injection points. Otherwise, injection may fail due to a "no type match found" error at runtime. - -For XML-defined beans or component classes found via classpath scanning, the container -usually knows the concrete type up front. However, for `@Bean` factory methods, you need -to make sure that the declared return type is sufficiently expressive. For components -that implement several interfaces or for components potentially referred to by their -implementation type, consider declaring the most specific return type on your factory -method (at least as specific as required by the injection points referring to your bean). -==== - -You can also instruct Spring to provide all beans of a particular type from the -`ApplicationContext` by adding the `@Autowired` annotation to a field or method that -expects an array of that type, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - @Autowired - private MovieCatalog[] movieCatalogs; - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender { - - @Autowired - private lateinit var movieCatalogs: Array - - // ... - } ----- - -The same applies for typed collections, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - private Set movieCatalogs; - - @Autowired - public void setMovieCatalogs(Set movieCatalogs) { - this.movieCatalogs = movieCatalogs; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender { - - @Autowired - lateinit var movieCatalogs: Set - - // ... - } ----- - -[[beans-factory-ordered]] -[TIP] -==== -Your target beans can implement the `org.springframework.core.Ordered` interface or use -the `@Order` or standard `@Priority` annotation if you want items in the array or list -to be sorted in a specific order. Otherwise, their order follows the registration -order of the corresponding target bean definitions in the container. - -You can declare the `@Order` annotation at the target class level and on `@Bean` methods, -potentially for individual bean definitions (in case of multiple definitions that -use the same bean class). `@Order` values may influence priorities at injection points, -but be aware that they do not influence singleton startup order, which is an -orthogonal concern determined by dependency relationships and `@DependsOn` declarations. - -Note that the standard `jakarta.annotation.Priority` annotation is not available at the -`@Bean` level, since it cannot be declared on methods. Its semantics can be modeled -through `@Order` values in combination with `@Primary` on a single bean for each type. -==== - -Even typed `Map` instances can be autowired as long as the expected key type is `String`. -The map values contain all beans of the expected type, and the keys contain the -corresponding bean names, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - private Map movieCatalogs; - - @Autowired - public void setMovieCatalogs(Map movieCatalogs) { - this.movieCatalogs = movieCatalogs; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender { - - @Autowired - lateinit var movieCatalogs: Map - - // ... - } ----- - -By default, autowiring fails when no matching candidate beans are available for a given -injection point. In the case of a declared array, collection, or map, at least one -matching element is expected. - -The default behavior is to treat annotated methods and fields as indicating required -dependencies. You can change this behavior as demonstrated in the following example, -enabling the framework to skip a non-satisfiable injection point through marking it as -non-required (i.e., by setting the `required` attribute in `@Autowired` to `false`): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleMovieLister { - - private MovieFinder movieFinder; - - @Autowired(required = false) - public void setMovieFinder(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SimpleMovieLister { - - @Autowired(required = false) - var movieFinder: MovieFinder? = null - - // ... - } ----- - -[NOTE] -==== -A non-required method will not be called at all if its dependency (or one of its -dependencies, in case of multiple arguments) is not available. A non-required field will -not get populated at all in such cases, leaving its default value in place. - -In other words, setting the `required` attribute to `false` indicates that the -corresponding property is _optional_ for autowiring purposes, and the property will be -ignored if it cannot be autowired. This allows properties to be assigned default values -that can be optionally overridden via dependency injection. -==== - - -[[beans-autowired-annotation-constructor-resolution]] - -Injected constructor and factory method arguments are a special case since the `required` -attribute in `@Autowired` has a somewhat different meaning due to Spring's constructor -resolution algorithm that may potentially deal with multiple constructors. Constructor -and factory method arguments are effectively required by default but with a few special -rules in a single-constructor scenario, such as multi-element injection points (arrays, -collections, maps) resolving to empty instances if no matching beans are available. This -allows for a common implementation pattern where all dependencies can be declared in a -unique multi-argument constructor — for example, declared as a single public constructor -without an `@Autowired` annotation. - -[NOTE] -==== -Only one constructor of any given bean class may declare `@Autowired` with the `required` -attribute set to `true`, indicating _the_ constructor to autowire when used as a Spring -bean. As a consequence, if the `required` attribute is left at its default value `true`, -only a single constructor may be annotated with `@Autowired`. If multiple constructors -declare the annotation, they will all have to declare `required=false` in order to be -considered as candidates for autowiring (analogous to `autowire=constructor` in XML). -The constructor with the greatest number of dependencies that can be satisfied by matching -beans in the Spring container will be chosen. If none of the candidates can be satisfied, -then a primary/default constructor (if present) will be used. Similarly, if a class -declares multiple constructors but none of them is annotated with `@Autowired`, then a -primary/default constructor (if present) will be used. If a class only declares a single -constructor to begin with, it will always be used, even if not annotated. Note that an -annotated constructor does not have to be public. -==== - -Alternatively, you can express the non-required nature of a particular dependency -through Java 8's `java.util.Optional`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public class SimpleMovieLister { - - @Autowired - public void setMovieFinder(Optional movieFinder) { - ... - } - } ----- - -As of Spring Framework 5.0, you can also use a `@Nullable` annotation (of any kind -in any package -- for example, `javax.annotation.Nullable` from JSR-305) or just leverage -Kotlin built-in null-safety support: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleMovieLister { - - @Autowired - public void setMovieFinder(@Nullable MovieFinder movieFinder) { - ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SimpleMovieLister { - - @Autowired - var movieFinder: MovieFinder? = null - - // ... - } ----- - -You can also use `@Autowired` for interfaces that are well-known resolvable -dependencies: `BeanFactory`, `ApplicationContext`, `Environment`, `ResourceLoader`, -`ApplicationEventPublisher`, and `MessageSource`. These interfaces and their extended -interfaces, such as `ConfigurableApplicationContext` or `ResourcePatternResolver`, are -automatically resolved, with no special setup necessary. The following example autowires -an `ApplicationContext` object: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - @Autowired - private ApplicationContext context; - - public MovieRecommender() { - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -class MovieRecommender { - - @Autowired - lateinit var context: ApplicationContext - - // ... -} ----- - -[NOTE] -==== -The `@Autowired`, `@Inject`, `@Value`, and `@Resource` annotations are handled by Spring -`BeanPostProcessor` implementations. This means that you cannot apply these annotations -within your own `BeanPostProcessor` or `BeanFactoryPostProcessor` types (if any). -These types must be 'wired up' explicitly by using XML or a Spring `@Bean` method. -==== - - - -[[beans-autowired-annotation-primary]] -=== Fine-tuning Annotation-based Autowiring with `@Primary` - -Because autowiring by type may lead to multiple candidates, it is often necessary to have -more control over the selection process. One way to accomplish this is with Spring's -`@Primary` annotation. `@Primary` indicates that a particular bean should be given -preference when multiple beans are candidates to be autowired to a single-valued -dependency. If exactly one primary bean exists among the candidates, it becomes the -autowired value. - -Consider the following configuration that defines `firstMovieCatalog` as the -primary `MovieCatalog`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class MovieConfiguration { - - @Bean - @Primary - public MovieCatalog firstMovieCatalog() { ... } - - @Bean - public MovieCatalog secondMovieCatalog() { ... } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class MovieConfiguration { - - @Bean - @Primary - fun firstMovieCatalog(): MovieCatalog { ... } - - @Bean - fun secondMovieCatalog(): MovieCatalog { ... } - - // ... - } ----- - -With the preceding configuration, the following `MovieRecommender` is autowired with the -`firstMovieCatalog`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - @Autowired - private MovieCatalog movieCatalog; - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -class MovieRecommender { - - @Autowired - private lateinit var movieCatalog: MovieCatalog - - // ... -} ----- - -The corresponding bean definitions follow: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - ----- - - - -[[beans-autowired-annotation-qualifiers]] -=== Fine-tuning Annotation-based Autowiring with Qualifiers - -`@Primary` is an effective way to use autowiring by type with several instances when one -primary candidate can be determined. When you need more control over the selection process, -you can use Spring's `@Qualifier` annotation. You can associate qualifier values -with specific arguments, narrowing the set of type matches so that a specific bean is -chosen for each argument. In the simplest case, this can be a plain descriptive value, as -shown in the following example: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - @Autowired - @Qualifier("main") - private MovieCatalog movieCatalog; - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender { - - @Autowired - @Qualifier("main") - private lateinit var movieCatalog: MovieCatalog - - // ... - } ----- --- - -You can also specify the `@Qualifier` annotation on individual constructor arguments or -method parameters, as shown in the following example: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - private final MovieCatalog movieCatalog; - - private final CustomerPreferenceDao customerPreferenceDao; - - @Autowired - public void prepare(@Qualifier("main") MovieCatalog movieCatalog, - CustomerPreferenceDao customerPreferenceDao) { - this.movieCatalog = movieCatalog; - this.customerPreferenceDao = customerPreferenceDao; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender { - - private lateinit var movieCatalog: MovieCatalog - - private lateinit var customerPreferenceDao: CustomerPreferenceDao - - @Autowired - fun prepare(@Qualifier("main") movieCatalog: MovieCatalog, - customerPreferenceDao: CustomerPreferenceDao) { - this.movieCatalog = movieCatalog - this.customerPreferenceDao = customerPreferenceDao - } - - // ... - } ----- --- - -The following example shows corresponding bean definitions. - --- -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - <1> - - - - - - <2> - - - - - - - ----- -<1> The bean with the `main` qualifier value is wired with the constructor argument that -is qualified with the same value. -<2> The bean with the `action` qualifier value is wired with the constructor argument that -is qualified with the same value. --- - -For a fallback match, the bean name is considered a default qualifier value. Thus, you -can define the bean with an `id` of `main` instead of the nested qualifier element, leading -to the same matching result. However, although you can use this convention to refer to -specific beans by name, `@Autowired` is fundamentally about type-driven injection with -optional semantic qualifiers. This means that qualifier values, even with the bean name -fallback, always have narrowing semantics within the set of type matches. They do not -semantically express a reference to a unique bean `id`. Good qualifier values are `main` -or `EMEA` or `persistent`, expressing characteristics of a specific component that are -independent from the bean `id`, which may be auto-generated in case of an anonymous bean -definition such as the one in the preceding example. - -Qualifiers also apply to typed collections, as discussed earlier -- for example, to -`Set`. In this case, all matching beans, according to the declared -qualifiers, are injected as a collection. This implies that qualifiers do not have to be -unique. Rather, they constitute filtering criteria. For example, you can define -multiple `MovieCatalog` beans with the same qualifier value "`action`", all of which are -injected into a `Set` annotated with `@Qualifier("action")`. - -[TIP] -==== -Letting qualifier values select against target bean names, within the type-matching -candidates, does not require a `@Qualifier` annotation at the injection point. -If there is no other resolution indicator (such as a qualifier or a primary marker), -for a non-unique dependency situation, Spring matches the injection point name -(that is, the field name or parameter name) against the target bean names and chooses the -same-named candidate, if any. -==== - -That said, if you intend to express annotation-driven injection by name, do not -primarily use `@Autowired`, even if it is capable of selecting by bean name among -type-matching candidates. Instead, use the JSR-250 `@Resource` annotation, which is -semantically defined to identify a specific target component by its unique name, with -the declared type being irrelevant for the matching process. `@Autowired` has rather -different semantics: After selecting candidate beans by type, the specified `String` -qualifier value is considered within those type-selected candidates only (for example, -matching an `account` qualifier against beans marked with the same qualifier label). - -For beans that are themselves defined as a collection, `Map`, or array type, `@Resource` -is a fine solution, referring to the specific collection or array bean by unique name. -That said, as of 4.3, you can match collection, `Map`, and array types through Spring's -`@Autowired` type matching algorithm as well, as long as the element type information -is preserved in `@Bean` return type signatures or collection inheritance hierarchies. -In this case, you can use qualifier values to select among same-typed collections, -as outlined in the previous paragraph. - -As of 4.3, `@Autowired` also considers self references for injection (that is, references -back to the bean that is currently injected). Note that self injection is a fallback. -Regular dependencies on other components always have precedence. In that sense, self -references do not participate in regular candidate selection and are therefore in -particular never primary. On the contrary, they always end up as lowest precedence. -In practice, you should use self references as a last resort only (for example, for -calling other methods on the same instance through the bean's transactional proxy). -Consider factoring out the affected methods to a separate delegate bean in such a scenario. -Alternatively, you can use `@Resource`, which may obtain a proxy back to the current bean -by its unique name. - -[NOTE] -==== -Trying to inject the results from `@Bean` methods on the same configuration class is -effectively a self-reference scenario as well. Either lazily resolve such references -in the method signature where it is actually needed (as opposed to an autowired field -in the configuration class) or declare the affected `@Bean` methods as `static`, -decoupling them from the containing configuration class instance and its lifecycle. -Otherwise, such beans are only considered in the fallback phase, with matching beans -on other configuration classes selected as primary candidates instead (if available). -==== - -`@Autowired` applies to fields, constructors, and multi-argument methods, allowing for -narrowing through qualifier annotations at the parameter level. In contrast, `@Resource` -is supported only for fields and bean property setter methods with a single argument. -As a consequence, you should stick with qualifiers if your injection target is a -constructor or a multi-argument method. - -You can create your own custom qualifier annotations. To do so, define an annotation and -provide the `@Qualifier` annotation within your definition, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target({ElementType.FIELD, ElementType.PARAMETER}) - @Retention(RetentionPolicy.RUNTIME) - @Qualifier - public @interface Genre { - - String value(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER) - @Retention(AnnotationRetention.RUNTIME) - @Qualifier - annotation class Genre(val value: String) ----- --- - -Then you can provide the custom qualifier on autowired fields and parameters, as the -following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - @Autowired - @Genre("Action") - private MovieCatalog actionCatalog; - - private MovieCatalog comedyCatalog; - - @Autowired - public void setComedyCatalog(@Genre("Comedy") MovieCatalog comedyCatalog) { - this.comedyCatalog = comedyCatalog; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender { - - @Autowired - @Genre("Action") - private lateinit var actionCatalog: MovieCatalog - - private lateinit var comedyCatalog: MovieCatalog - - @Autowired - fun setComedyCatalog(@Genre("Comedy") comedyCatalog: MovieCatalog) { - this.comedyCatalog = comedyCatalog - } - - // ... - } ----- --- - -Next, you can provide the information for the candidate bean definitions. You can add -`` tags as sub-elements of the `` tag and then specify the `type` and -`value` to match your custom qualifier annotations. The type is matched against the -fully-qualified class name of the annotation. Alternately, as a convenience if no risk of -conflicting names exists, you can use the short class name. The following example -demonstrates both approaches: - --- -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - ----- --- - -In <>, you can see an annotation-based alternative to -providing the qualifier metadata in XML. Specifically, see <>. - -In some cases, using an annotation without a value may suffice. This can be -useful when the annotation serves a more generic purpose and can be applied across -several different types of dependencies. For example, you may provide an offline -catalog that can be searched when no Internet connection is available. First, define -the simple annotation, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target({ElementType.FIELD, ElementType.PARAMETER}) - @Retention(RetentionPolicy.RUNTIME) - @Qualifier - public @interface Offline { - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER) - @Retention(AnnotationRetention.RUNTIME) - @Qualifier - annotation class Offline ----- --- - -Then add the annotation to the field or property to be autowired, as shown in the -following example: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - @Autowired - @Offline // <1> - private MovieCatalog offlineCatalog; - - // ... - } ----- -<1> This line adds the `@Offline` annotation. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -class MovieRecommender { - - @Autowired - @Offline // <1> - private lateinit var offlineCatalog: MovieCatalog - - // ... -} ----- -<1> This line adds the `@Offline` annotation. --- - -Now the bean definition only needs a qualifier `type`, as shown in the following example: - --- -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - <1> - - ----- -<1> This element specifies the qualifier. --- - - -You can also define custom qualifier annotations that accept named attributes in -addition to or instead of the simple `value` attribute. If multiple attribute values are -then specified on a field or parameter to be autowired, a bean definition must match -all such attribute values to be considered an autowire candidate. As an example, -consider the following annotation definition: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target({ElementType.FIELD, ElementType.PARAMETER}) - @Retention(RetentionPolicy.RUNTIME) - @Qualifier - public @interface MovieQualifier { - - String genre(); - - Format format(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER) - @Retention(AnnotationRetention.RUNTIME) - @Qualifier - annotation class MovieQualifier(val genre: String, val format: Format) ----- --- - -In this case `Format` is an enum, defined as follows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public enum Format { - VHS, DVD, BLURAY - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - enum class Format { - VHS, DVD, BLURAY - } ----- --- - -The fields to be autowired are annotated with the custom qualifier and include values -for both attributes: `genre` and `format`, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - @Autowired - @MovieQualifier(format=Format.VHS, genre="Action") - private MovieCatalog actionVhsCatalog; - - @Autowired - @MovieQualifier(format=Format.VHS, genre="Comedy") - private MovieCatalog comedyVhsCatalog; - - @Autowired - @MovieQualifier(format=Format.DVD, genre="Action") - private MovieCatalog actionDvdCatalog; - - @Autowired - @MovieQualifier(format=Format.BLURAY, genre="Comedy") - private MovieCatalog comedyBluRayCatalog; - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender { - - @Autowired - @MovieQualifier(format = Format.VHS, genre = "Action") - private lateinit var actionVhsCatalog: MovieCatalog - - @Autowired - @MovieQualifier(format = Format.VHS, genre = "Comedy") - private lateinit var comedyVhsCatalog: MovieCatalog - - @Autowired - @MovieQualifier(format = Format.DVD, genre = "Action") - private lateinit var actionDvdCatalog: MovieCatalog - - @Autowired - @MovieQualifier(format = Format.BLURAY, genre = "Comedy") - private lateinit var comedyBluRayCatalog: MovieCatalog - - // ... - } ----- --- - -Finally, the bean definitions should contain matching qualifier values. This example -also demonstrates that you can use bean meta attributes instead of the -`` elements. If available, the `` element and its attributes take -precedence, but the autowiring mechanism falls back on the values provided within the -`` tags if no such qualifier is present, as in the last two bean definitions in -the following example: - --- -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----- --- - - - -[[beans-generics-as-qualifiers]] -=== Using Generics as Autowiring Qualifiers - -In addition to the `@Qualifier` annotation, you can use Java generic types -as an implicit form of qualification. For example, suppose you have the following -configuration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class MyConfiguration { - - @Bean - public StringStore stringStore() { - return new StringStore(); - } - - @Bean - public IntegerStore integerStore() { - return new IntegerStore(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class MyConfiguration { - - @Bean - fun stringStore() = StringStore() - - @Bean - fun integerStore() = IntegerStore() - } ----- - -Assuming that the preceding beans implement a generic interface, (that is, `Store` and -`Store`), you can `@Autowire` the `Store` interface and the generic is -used as a qualifier, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Autowired - private Store s1; // qualifier, injects the stringStore bean - - @Autowired - private Store s2; // qualifier, injects the integerStore bean ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Autowired - private lateinit var s1: Store // qualifier, injects the stringStore bean - - @Autowired - private lateinit var s2: Store // qualifier, injects the integerStore bean ----- - -Generic qualifiers also apply when autowiring lists, `Map` instances and arrays. The -following example autowires a generic `List`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Inject all Store beans as long as they have an generic - // Store beans will not appear in this list - @Autowired - private List> s; ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Inject all Store beans as long as they have an generic - // Store beans will not appear in this list - @Autowired - private lateinit var s: List> ----- - - - -[[beans-custom-autowire-configurer]] -=== Using `CustomAutowireConfigurer` - -{api-spring-framework}/beans/factory/annotation/CustomAutowireConfigurer.html[`CustomAutowireConfigurer`] -is a `BeanFactoryPostProcessor` that lets you register your own custom qualifier -annotation types, even if they are not annotated with Spring's `@Qualifier` annotation. -The following example shows how to use `CustomAutowireConfigurer`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - example.CustomQualifier - - - ----- - -The `AutowireCandidateResolver` determines autowire candidates by: - -* The `autowire-candidate` value of each bean definition -* Any `default-autowire-candidates` patterns available on the `` element -* The presence of `@Qualifier` annotations and any custom annotations registered -with the `CustomAutowireConfigurer` - -When multiple beans qualify as autowire candidates, the determination of a "`primary`" is -as follows: If exactly one bean definition among the candidates has a `primary` -attribute set to `true`, it is selected. - - - -[[beans-resource-annotation]] -=== Injection with `@Resource` - -Spring also supports injection by using the JSR-250 `@Resource` annotation -(`jakarta.annotation.Resource`) on fields or bean property setter methods. -This is a common pattern in Jakarta EE: for example, in JSF-managed beans and JAX-WS -endpoints. Spring supports this pattern for Spring-managed objects as well. - -`@Resource` takes a name attribute. By default, Spring interprets that value as -the bean name to be injected. In other words, it follows by-name semantics, -as demonstrated in the following example: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleMovieLister { - - private MovieFinder movieFinder; - - @Resource(name="myMovieFinder") // <1> - public void setMovieFinder(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - } ----- -<1> This line injects a `@Resource`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -class SimpleMovieLister { - - @Resource(name="myMovieFinder") // <1> - private lateinit var movieFinder:MovieFinder -} ----- -<1> This line injects a `@Resource`. --- - - -If no name is explicitly specified, the default name is derived from the field name or -setter method. In case of a field, it takes the field name. In case of a setter method, -it takes the bean property name. The following example is going to have the bean -named `movieFinder` injected into its setter method: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleMovieLister { - - private MovieFinder movieFinder; - - @Resource - public void setMovieFinder(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SimpleMovieLister { - - @set:Resource - private lateinit var movieFinder: MovieFinder - - } ----- --- - -NOTE: The name provided with the annotation is resolved as a bean name by the -`ApplicationContext` of which the `CommonAnnotationBeanPostProcessor` is aware. -The names can be resolved through JNDI if you configure Spring's -{api-spring-framework}/jndi/support/SimpleJndiBeanFactory.html[`SimpleJndiBeanFactory`] -explicitly. However, we recommend that you rely on the default behavior and -use Spring's JNDI lookup capabilities to preserve the level of indirection. - -In the exclusive case of `@Resource` usage with no explicit name specified, and similar -to `@Autowired`, `@Resource` finds a primary type match instead of a specific named bean -and resolves well known resolvable dependencies: the `BeanFactory`, -`ApplicationContext`, `ResourceLoader`, `ApplicationEventPublisher`, and `MessageSource` -interfaces. - -Thus, in the following example, the `customerPreferenceDao` field first looks for a bean -named "customerPreferenceDao" and then falls back to a primary type match for the type -`CustomerPreferenceDao`: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - @Resource - private CustomerPreferenceDao customerPreferenceDao; - - @Resource - private ApplicationContext context; // <1> - - public MovieRecommender() { - } - - // ... - } ----- -<1> The `context` field is injected based on the known resolvable dependency type: -`ApplicationContext`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender { - - @Resource - private lateinit var customerPreferenceDao: CustomerPreferenceDao - - - @Resource - private lateinit var context: ApplicationContext // <1> - - // ... - } ----- -<1> The `context` field is injected based on the known resolvable dependency type: -`ApplicationContext`. --- - -[[beans-value-annotations]] -=== Using `@Value` - -`@Value` is typically used to inject externalized properties: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - public class MovieRecommender { - - private final String catalog; - - public MovieRecommender(@Value("${catalog.name}") String catalog) { - this.catalog = catalog; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - class MovieRecommender(@Value("\${catalog.name}") private val catalog: String) ----- - -With the following configuration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @PropertySource("classpath:application.properties") - public class AppConfig { } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @PropertySource("classpath:application.properties") - class AppConfig ----- - -And the following `application.properties` file: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - catalog.name=MovieCatalog ----- - -In that case, the `catalog` parameter and field will be equal to the `MovieCatalog` value. - -A default lenient embedded value resolver is provided by Spring. It will try to resolve the -property value and if it cannot be resolved, the property name (for example `${catalog.name}`) -will be injected as the value. If you want to maintain strict control over nonexistent -values, you should declare a `PropertySourcesPlaceholderConfigurer` bean, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public static PropertySourcesPlaceholderConfigurer propertyPlaceholderConfigurer() { - return new PropertySourcesPlaceholderConfigurer(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun propertyPlaceholderConfigurer() = PropertySourcesPlaceholderConfigurer() - } ----- - -NOTE: When configuring a `PropertySourcesPlaceholderConfigurer` using JavaConfig, the -`@Bean` method must be `static`. - -Using the above configuration ensures Spring initialization failure if any `${}` -placeholder could not be resolved. It is also possible to use methods like -`setPlaceholderPrefix`, `setPlaceholderSuffix`, or `setValueSeparator` to customize -placeholders. - -NOTE: Spring Boot configures by default a `PropertySourcesPlaceholderConfigurer` bean that -will get properties from `application.properties` and `application.yml` files. - -Built-in converter support provided by Spring allows simple type conversion (to `Integer` -or `int` for example) to be automatically handled. Multiple comma-separated values can be -automatically converted to `String` array without extra effort. - -It is possible to provide a default value as following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - public class MovieRecommender { - - private final String catalog; - - public MovieRecommender(@Value("${catalog.name:defaultCatalog}") String catalog) { - this.catalog = catalog; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - class MovieRecommender(@Value("\${catalog.name:defaultCatalog}") private val catalog: String) ----- - -A Spring `BeanPostProcessor` uses a `ConversionService` behind the scenes to handle the -process for converting the `String` value in `@Value` to the target type. If you want to -provide conversion support for your own custom type, you can provide your own -`ConversionService` bean instance as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public ConversionService conversionService() { - DefaultFormattingConversionService conversionService = new DefaultFormattingConversionService(); - conversionService.addConverter(new MyCustomConverter()); - return conversionService; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun conversionService(): ConversionService { - return DefaultFormattingConversionService().apply { - addConverter(MyCustomConverter()) - } - } - } ----- - -When `@Value` contains a <> the value will be dynamically -computed at runtime as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - public class MovieRecommender { - - private final String catalog; - - public MovieRecommender(@Value("#{systemProperties['user.catalog'] + 'Catalog' }") String catalog) { - this.catalog = catalog; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - class MovieRecommender( - @Value("#{systemProperties['user.catalog'] + 'Catalog' }") private val catalog: String) ----- - -SpEL also enables the use of more complex data structures: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - public class MovieRecommender { - - private final Map countOfMoviesPerCatalog; - - public MovieRecommender( - @Value("#{{'Thriller': 100, 'Comedy': 300}}") Map countOfMoviesPerCatalog) { - this.countOfMoviesPerCatalog = countOfMoviesPerCatalog; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - class MovieRecommender( - @Value("#{{'Thriller': 100, 'Comedy': 300}}") private val countOfMoviesPerCatalog: Map) ----- - - -[[beans-postconstruct-and-predestroy-annotations]] -=== Using `@PostConstruct` and `@PreDestroy` - -The `CommonAnnotationBeanPostProcessor` not only recognizes the `@Resource` annotation -but also the JSR-250 lifecycle annotations: `jakarta.annotation.PostConstruct` and -`jakarta.annotation.PreDestroy`. Introduced in Spring 2.5, the support for these -annotations offers an alternative to the lifecycle callback mechanism described in -<> and -<>. Provided that the -`CommonAnnotationBeanPostProcessor` is registered within the Spring `ApplicationContext`, -a method carrying one of these annotations is invoked at the same point in the lifecycle -as the corresponding Spring lifecycle interface method or explicitly declared callback -method. In the following example, the cache is pre-populated upon initialization and -cleared upon destruction: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class CachingMovieLister { - - @PostConstruct - public void populateMovieCache() { - // populates the movie cache upon initialization... - } - - @PreDestroy - public void clearMovieCache() { - // clears the movie cache upon destruction... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class CachingMovieLister { - - @PostConstruct - fun populateMovieCache() { - // populates the movie cache upon initialization... - } - - @PreDestroy - fun clearMovieCache() { - // clears the movie cache upon destruction... - } - } ----- - -For details about the effects of combining various lifecycle mechanisms, see -<>. - -[NOTE] -==== -Like `@Resource`, the `@PostConstruct` and `@PreDestroy` annotation types were a part -of the standard Java libraries from JDK 6 to 8. However, the entire `javax.annotation` -package got separated from the core Java modules in JDK 9 and eventually removed in -JDK 11. As of Jakarta EE 9, the package lives in `jakarta.annotation` now. If needed, -the `jakarta.annotation-api` artifact needs to be obtained via Maven Central now, -simply to be added to the application's classpath like any other library. -==== - - - - -[[beans-classpath-scanning]] -== Classpath Scanning and Managed Components - -Most examples in this chapter use XML to specify the configuration metadata that produces -each `BeanDefinition` within the Spring container. The previous section -(<>) demonstrates how to provide a lot of the configuration -metadata through source-level annotations. Even in those examples, however, the "base" -bean definitions are explicitly defined in the XML file, while the annotations drive only -the dependency injection. This section describes an option for implicitly detecting the -candidate components by scanning the classpath. Candidate components are classes that -match against a filter criteria and have a corresponding bean definition registered with -the container. This removes the need to use XML to perform bean registration. Instead, you -can use annotations (for example, `@Component`), AspectJ type expressions, or your own -custom filter criteria to select which classes have bean definitions registered with -the container. - -[NOTE] -==== -You can define beans using Java rather than using XML files. Take a look at the -`@Configuration`, `@Bean`, `@Import`, and `@DependsOn` annotations for examples of how to -use these features. -==== - - - -[[beans-stereotype-annotations]] -=== `@Component` and Further Stereotype Annotations - -The `@Repository` annotation is a marker for any class that fulfills the role or -stereotype of a repository (also known as Data Access Object or DAO). Among the uses -of this marker is the automatic translation of exceptions, as described in -<>. - -Spring provides further stereotype annotations: `@Component`, `@Service`, and -`@Controller`. `@Component` is a generic stereotype for any Spring-managed component. -`@Repository`, `@Service`, and `@Controller` are specializations of `@Component` for -more specific use cases (in the persistence, service, and presentation -layers, respectively). Therefore, you can annotate your component classes with -`@Component`, but, by annotating them with `@Repository`, `@Service`, or `@Controller` -instead, your classes are more properly suited for processing by tools or associating -with aspects. For example, these stereotype annotations make ideal targets for -pointcuts. `@Repository`, `@Service`, and `@Controller` can also -carry additional semantics in future releases of the Spring Framework. Thus, if you are -choosing between using `@Component` or `@Service` for your service layer, `@Service` is -clearly the better choice. Similarly, as stated earlier, `@Repository` is already -supported as a marker for automatic exception translation in your persistence layer. - - - -[[beans-meta-annotations]] -=== Using Meta-annotations and Composed Annotations - -Many of the annotations provided by Spring can be used as meta-annotations in your -own code. A meta-annotation is an annotation that can be applied to another annotation. -For example, the `@Service` annotation mentioned <> -is meta-annotated with `@Component`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target(ElementType.TYPE) - @Retention(RetentionPolicy.RUNTIME) - @Documented - @Component // <1> - public @interface Service { - - // ... - } ----- -<1> The `@Component` causes `@Service` to be treated in the same way as `@Component`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.TYPE) - @Retention(AnnotationRetention.RUNTIME) - @MustBeDocumented - @Component // <1> - annotation class Service { - - // ... - } ----- -<1> The `@Component` causes `@Service` to be treated in the same way as `@Component`. - -You can also combine meta-annotations to create "`composed annotations`". For example, -the `@RestController` annotation from Spring MVC is composed of `@Controller` and -`@ResponseBody`. - -In addition, composed annotations can optionally redeclare attributes from -meta-annotations to allow customization. This can be particularly useful when you -want to only expose a subset of the meta-annotation's attributes. For example, Spring's -`@SessionScope` annotation hard codes the scope name to `session` but still allows -customization of the `proxyMode`. The following listing shows the definition of the -`SessionScope` annotation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target({ElementType.TYPE, ElementType.METHOD}) - @Retention(RetentionPolicy.RUNTIME) - @Documented - @Scope(WebApplicationContext.SCOPE_SESSION) - public @interface SessionScope { - - /** - * Alias for {@link Scope#proxyMode}. - *

Defaults to {@link ScopedProxyMode#TARGET_CLASS}. + */ + @AliasFor(annotation = Scope.class) + ScopedProxyMode proxyMode() default ScopedProxyMode.TARGET_CLASS; + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION) + @Retention(AnnotationRetention.RUNTIME) + @MustBeDocumented + @Scope(WebApplicationContext.SCOPE_SESSION) + annotation class SessionScope( + @get:AliasFor(annotation = Scope::class) + val proxyMode: ScopedProxyMode = ScopedProxyMode.TARGET_CLASS + ) +---- + +You can then use `@SessionScope` without declaring the `proxyMode` as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Service + @SessionScope + public class SessionScopedService { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Service + @SessionScope + class SessionScopedService { + // ... + } +---- + +You can also override the value for the `proxyMode`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Service + @SessionScope(proxyMode = ScopedProxyMode.INTERFACES) + public class SessionScopedUserService implements UserService { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Service + @SessionScope(proxyMode = ScopedProxyMode.INTERFACES) + class SessionScopedUserService : UserService { + // ... + } +---- + +For further details, see the +https://github.com/spring-projects/spring-framework/wiki/Spring-Annotation-Programming-Model[Spring Annotation Programming Model] +wiki page. + + + +[[beans-scanning-autodetection]] +== Automatically Detecting Classes and Registering Bean Definitions + +Spring can automatically detect stereotyped classes and register corresponding +`BeanDefinition` instances with the `ApplicationContext`. For example, the following two classes +are eligible for such autodetection: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Service + public class SimpleMovieLister { + + private MovieFinder movieFinder; + + public SimpleMovieLister(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Service + class SimpleMovieLister(private val movieFinder: MovieFinder) +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Repository + public class JpaMovieFinder implements MovieFinder { + // implementation elided for clarity + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Repository + class JpaMovieFinder : MovieFinder { + // implementation elided for clarity + } +---- + + +To autodetect these classes and register the corresponding beans, you need to add +`@ComponentScan` to your `@Configuration` class, where the `basePackages` attribute +is a common parent package for the two classes. (Alternatively, you can specify a +comma- or semicolon- or space-separated list that includes the parent package of each class.) + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ComponentScan(basePackages = "org.example") + public class AppConfig { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ComponentScan(basePackages = ["org.example"]) + class AppConfig { + // ... + } +---- + +NOTE: For brevity, the preceding example could have used the `value` attribute of the +annotation (that is, `@ComponentScan("org.example")`). + +The following alternative uses XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + +TIP: The use of `` implicitly enables the functionality of +``. There is usually no need to include the +`` element when using ``. + +[NOTE] +==== +The scanning of classpath packages requires the presence of corresponding directory +entries in the classpath. When you build JARs with Ant, make sure that you do not +activate the files-only switch of the JAR task. Also, classpath directories may not be +exposed based on security policies in some environments -- for example, standalone apps on +JDK 1.7.0_45 and higher (which requires 'Trusted-Library' setup in your manifests -- see +https://stackoverflow.com/questions/19394570/java-jre-7u45-breaks-classloader-getresources). + +On JDK 9's module path (Jigsaw), Spring's classpath scanning generally works as expected. +However, make sure that your component classes are exported in your `module-info` +descriptors. If you expect Spring to invoke non-public members of your classes, make +sure that they are 'opened' (that is, that they use an `opens` declaration instead of an +`exports` declaration in your `module-info` descriptor). +==== + +Furthermore, the `AutowiredAnnotationBeanPostProcessor` and +`CommonAnnotationBeanPostProcessor` are both implicitly included when you use the +component-scan element. That means that the two components are autodetected and +wired together -- all without any bean configuration metadata provided in XML. + +NOTE: You can disable the registration of `AutowiredAnnotationBeanPostProcessor` and +`CommonAnnotationBeanPostProcessor` by including the `annotation-config` attribute +with a value of `false`. + + + +[[beans-scanning-filters]] +== Using Filters to Customize Scanning + +By default, classes annotated with `@Component`, `@Repository`, `@Service`, `@Controller`, +`@Configuration`, or a custom annotation that itself is annotated with `@Component` are +the only detected candidate components. However, you can modify and extend this behavior +by applying custom filters. Add them as `includeFilters` or `excludeFilters` attributes of +the `@ComponentScan` annotation (or as `` or +`` child elements of the `` element in +XML configuration). Each filter element requires the `type` and `expression` attributes. +The following table describes the filtering options: + +[[beans-scanning-filters-tbl]] +.Filter Types +|=== +| Filter Type| Example Expression| Description + +| annotation (default) +| `org.example.SomeAnnotation` +| An annotation to be _present_ or _meta-present_ at the type level in target components. + +| assignable +| `org.example.SomeClass` +| A class (or interface) that the target components are assignable to (extend or implement). + +| aspectj +| `org.example..*Service+` +| An AspectJ type expression to be matched by the target components. + +| regex +| `org\.example\.Default.*` +| A regex expression to be matched by the target components' class names. + +| custom +| `org.example.MyTypeFilter` +| A custom implementation of the `org.springframework.core.type.TypeFilter` interface. +|=== + +The following example shows the configuration ignoring all `@Repository` annotations +and using "`stub`" repositories instead: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ComponentScan(basePackages = "org.example", + includeFilters = @Filter(type = FilterType.REGEX, pattern = ".*Stub.*Repository"), + excludeFilters = @Filter(Repository.class)) + public class AppConfig { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ComponentScan(basePackages = ["org.example"], + includeFilters = [Filter(type = FilterType.REGEX, pattern = [".*Stub.*Repository"])], + excludeFilters = [Filter(Repository::class)]) + class AppConfig { + // ... + } +---- + +The following listing shows the equivalent XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + +NOTE: You can also disable the default filters by setting `useDefaultFilters=false` on the +annotation or by providing `use-default-filters="false"` as an attribute of the +`` element. This effectively disables automatic detection of classes +annotated or meta-annotated with `@Component`, `@Repository`, `@Service`, `@Controller`, +`@RestController`, or `@Configuration`. + + + +[[beans-factorybeans-annotations]] +== Defining Bean Metadata within Components + +Spring components can also contribute bean definition metadata to the container. You can do +this with the same `@Bean` annotation used to define bean metadata within `@Configuration` +annotated classes. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + public class FactoryMethodComponent { + + @Bean + @Qualifier("public") + public TestBean publicInstance() { + return new TestBean("publicInstance"); + } + + public void doWork() { + // Component method implementation omitted + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + class FactoryMethodComponent { + + @Bean + @Qualifier("public") + fun publicInstance() = TestBean("publicInstance") + + fun doWork() { + // Component method implementation omitted + } + } +---- + +The preceding class is a Spring component that has application-specific code in its +`doWork()` method. However, it also contributes a bean definition that has a factory +method referring to the method `publicInstance()`. The `@Bean` annotation identifies the +factory method and other bean definition properties, such as a qualifier value through +the `@Qualifier` annotation. Other method-level annotations that can be specified are +`@Scope`, `@Lazy`, and custom qualifier annotations. + +TIP: In addition to its role for component initialization, you can also place the `@Lazy` +annotation on injection points marked with `@Autowired` or `@Inject`. In this context, +it leads to the injection of a lazy-resolution proxy. However, such a proxy approach +is rather limited. For sophisticated lazy interactions, in particular in combination +with optional dependencies, we recommend `ObjectProvider` instead. + +Autowired fields and methods are supported, as previously discussed, with additional +support for autowiring of `@Bean` methods. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + public class FactoryMethodComponent { + + private static int i; + + @Bean + @Qualifier("public") + public TestBean publicInstance() { + return new TestBean("publicInstance"); + } + + // use of a custom qualifier and autowiring of method parameters + @Bean + protected TestBean protectedInstance( + @Qualifier("public") TestBean spouse, + @Value("#{privateInstance.age}") String country) { + TestBean tb = new TestBean("protectedInstance", 1); + tb.setSpouse(spouse); + tb.setCountry(country); + return tb; + } + + @Bean + private TestBean privateInstance() { + return new TestBean("privateInstance", i++); + } + + @Bean + @RequestScope + public TestBean requestScopedInstance() { + return new TestBean("requestScopedInstance", 3); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + class FactoryMethodComponent { + + companion object { + private var i: Int = 0 + } + + @Bean + @Qualifier("public") + fun publicInstance() = TestBean("publicInstance") + + // use of a custom qualifier and autowiring of method parameters + @Bean + protected fun protectedInstance( + @Qualifier("public") spouse: TestBean, + @Value("#{privateInstance.age}") country: String) = TestBean("protectedInstance", 1).apply { + this.spouse = spouse + this.country = country + } + + @Bean + private fun privateInstance() = TestBean("privateInstance", i++) + + @Bean + @RequestScope + fun requestScopedInstance() = TestBean("requestScopedInstance", 3) + } +---- + +The example autowires the `String` method parameter `country` to the value of the `age` +property on another bean named `privateInstance`. A Spring Expression Language element +defines the value of the property through the notation `#{ }`. For `@Value` +annotations, an expression resolver is preconfigured to look for bean names when +resolving expression text. + +As of Spring Framework 4.3, you may also declare a factory method parameter of type +`InjectionPoint` (or its more specific subclass: `DependencyDescriptor`) to +access the requesting injection point that triggers the creation of the current bean. +Note that this applies only to the actual creation of bean instances, not to the +injection of existing instances. As a consequence, this feature makes most sense for +beans of prototype scope. For other scopes, the factory method only ever sees the +injection point that triggered the creation of a new bean instance in the given scope +(for example, the dependency that triggered the creation of a lazy singleton bean). +You can use the provided injection point metadata with semantic care in such scenarios. +The following example shows how to use `InjectionPoint`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + public class FactoryMethodComponent { + + @Bean @Scope("prototype") + public TestBean prototypeInstance(InjectionPoint injectionPoint) { + return new TestBean("prototypeInstance for " + injectionPoint.getMember()); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + class FactoryMethodComponent { + + @Bean + @Scope("prototype") + fun prototypeInstance(injectionPoint: InjectionPoint) = + TestBean("prototypeInstance for ${injectionPoint.member}") + } +---- + +The `@Bean` methods in a regular Spring component are processed differently than their +counterparts inside a Spring `@Configuration` class. The difference is that `@Component` +classes are not enhanced with CGLIB to intercept the invocation of methods and fields. +CGLIB proxying is the means by which invoking methods or fields within `@Bean` methods +in `@Configuration` classes creates bean metadata references to collaborating objects. +Such methods are not invoked with normal Java semantics but rather go through the +container in order to provide the usual lifecycle management and proxying of Spring +beans, even when referring to other beans through programmatic calls to `@Bean` methods. +In contrast, invoking a method or field in a `@Bean` method within a plain `@Component` +class has standard Java semantics, with no special CGLIB processing or other +constraints applying. + +[NOTE] +==== +You may declare `@Bean` methods as `static`, allowing for them to be called without +creating their containing configuration class as an instance. This makes particular +sense when defining post-processor beans (for example, of type `BeanFactoryPostProcessor` +or `BeanPostProcessor`), since such beans get initialized early in the container +lifecycle and should avoid triggering other parts of the configuration at that point. + +Calls to static `@Bean` methods never get intercepted by the container, not even within +`@Configuration` classes (as described earlier in this section), due to technical +limitations: CGLIB subclassing can override only non-static methods. As a consequence, +a direct call to another `@Bean` method has standard Java semantics, resulting +in an independent instance being returned straight from the factory method itself. + +The Java language visibility of `@Bean` methods does not have an immediate impact on +the resulting bean definition in Spring's container. You can freely declare your +factory methods as you see fit in non-`@Configuration` classes and also for static +methods anywhere. However, regular `@Bean` methods in `@Configuration` classes need +to be overridable -- that is, they must not be declared as `private` or `final`. + +`@Bean` methods are also discovered on base classes of a given component or +configuration class, as well as on Java 8 default methods declared in interfaces +implemented by the component or configuration class. This allows for a lot of +flexibility in composing complex configuration arrangements, with even multiple +inheritance being possible through Java 8 default methods as of Spring 4.2. + +Finally, a single class may hold multiple `@Bean` methods for the same +bean, as an arrangement of multiple factory methods to use depending on available +dependencies at runtime. This is the same algorithm as for choosing the "`greediest`" +constructor or factory method in other configuration scenarios: The variant with +the largest number of satisfiable dependencies is picked at construction time, +analogous to how the container selects between multiple `@Autowired` constructors. +==== + + + +[[beans-scanning-name-generator]] +== Naming Autodetected Components + +When a component is autodetected as part of the scanning process, its bean name is +generated by the `BeanNameGenerator` strategy known to that scanner. By default, any +Spring stereotype annotation (`@Component`, `@Repository`, `@Service`, and +`@Controller`) that contains a name `value` thereby provides that name to the +corresponding bean definition. + +If such an annotation contains no name `value` or for any other detected component +(such as those discovered by custom filters), the default bean name generator returns +the uncapitalized non-qualified class name. For example, if the following component +classes were detected, the names would be `myMovieLister` and `movieFinderImpl`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Service("myMovieLister") + public class SimpleMovieLister { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Service("myMovieLister") + class SimpleMovieLister { + // ... + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Repository + public class MovieFinderImpl implements MovieFinder { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Repository + class MovieFinderImpl : MovieFinder { + // ... + } +---- + +If you do not want to rely on the default bean-naming strategy, you can provide a custom +bean-naming strategy. First, implement the +{api-spring-framework}/beans/factory/support/BeanNameGenerator.html[`BeanNameGenerator`] +interface, and be sure to include a default no-arg constructor. Then, provide the fully +qualified class name when configuring the scanner, as the following example annotation +and bean definition show. + +TIP: If you run into naming conflicts due to multiple autodetected components having the +same non-qualified class name (i.e., classes with identical names but residing in +different packages), you may need to configure a `BeanNameGenerator` that defaults to the +fully qualified class name for the generated bean name. As of Spring Framework 5.2.3, the +`FullyQualifiedAnnotationBeanNameGenerator` located in package +`org.springframework.context.annotation` can be used for such purposes. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ComponentScan(basePackages = "org.example", nameGenerator = MyNameGenerator.class) + public class AppConfig { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ComponentScan(basePackages = ["org.example"], nameGenerator = MyNameGenerator::class) + class AppConfig { + // ... + } +---- + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +As a general rule, consider specifying the name with the annotation whenever other +components may be making explicit references to it. On the other hand, the +auto-generated names are adequate whenever the container is responsible for wiring. + + + +[[beans-scanning-scope-resolver]] +== Providing a Scope for Autodetected Components + +As with Spring-managed components in general, the default and most common scope for +autodetected components is `singleton`. However, sometimes you need a different scope +that can be specified by the `@Scope` annotation. You can provide the name of the +scope within the annotation, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Scope("prototype") + @Repository + public class MovieFinderImpl implements MovieFinder { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Scope("prototype") + @Repository + class MovieFinderImpl : MovieFinder { + // ... + } +---- + +NOTE: `@Scope` annotations are only introspected on the concrete bean class (for annotated +components) or the factory method (for `@Bean` methods). In contrast to XML bean +definitions, there is no notion of bean definition inheritance, and inheritance +hierarchies at the class level are irrelevant for metadata purposes. + +For details on web-specific scopes such as "`request`" or "`session`" in a Spring context, +see <>. As with the pre-built annotations for those scopes, +you may also compose your own scoping annotations by using Spring's meta-annotation +approach: for example, a custom annotation meta-annotated with `@Scope("prototype")`, +possibly also declaring a custom scoped-proxy mode. + +NOTE: To provide a custom strategy for scope resolution rather than relying on the +annotation-based approach, you can implement the +{api-spring-framework}/context/annotation/ScopeMetadataResolver.html[`ScopeMetadataResolver`] +interface. Be sure to include a default no-arg constructor. Then you can provide the +fully qualified class name when configuring the scanner, as the following example of both +an annotation and a bean definition shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ComponentScan(basePackages = "org.example", scopeResolver = MyScopeResolver.class) + public class AppConfig { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ComponentScan(basePackages = ["org.example"], scopeResolver = MyScopeResolver::class) + class AppConfig { + // ... + } +---- + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +When using certain non-singleton scopes, it may be necessary to generate proxies for the +scoped objects. The reasoning is described in <>. +For this purpose, a scoped-proxy attribute is available on the component-scan +element. The three possible values are: `no`, `interfaces`, and `targetClass`. For example, +the following configuration results in standard JDK dynamic proxies: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ComponentScan(basePackages = "org.example", scopedProxy = ScopedProxyMode.INTERFACES) + public class AppConfig { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ComponentScan(basePackages = ["org.example"], scopedProxy = ScopedProxyMode.INTERFACES) + class AppConfig { + // ... + } +---- + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + + + +[[beans-scanning-qualifiers]] +== Providing Qualifier Metadata with Annotations + +The `@Qualifier` annotation is discussed in <>. +The examples in that section demonstrate the use of the `@Qualifier` annotation and +custom qualifier annotations to provide fine-grained control when you resolve autowire +candidates. Because those examples were based on XML bean definitions, the qualifier +metadata was provided on the candidate bean definitions by using the `qualifier` or `meta` +child elements of the `bean` element in the XML. When relying upon classpath scanning for +auto-detection of components, you can provide the qualifier metadata with type-level +annotations on the candidate class. The following three examples demonstrate this +technique: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + @Qualifier("Action") + public class ActionMovieCatalog implements MovieCatalog { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + @Qualifier("Action") + class ActionMovieCatalog : MovieCatalog +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + @Genre("Action") + public class ActionMovieCatalog implements MovieCatalog { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + @Genre("Action") + class ActionMovieCatalog : MovieCatalog { + // ... + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + @Offline + public class CachingMovieCatalog implements MovieCatalog { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +@Component +@Offline +class CachingMovieCatalog : MovieCatalog { + // ... +} +---- + +NOTE: As with most annotation-based alternatives, keep in mind that the annotation metadata is +bound to the class definition itself, while the use of XML allows for multiple beans +of the same type to provide variations in their qualifier metadata, because that +metadata is provided per-instance rather than per-class. + + + +[[beans-scanning-index]] +== Generating an Index of Candidate Components + +While classpath scanning is very fast, it is possible to improve the startup performance +of large applications by creating a static list of candidates at compilation time. In this +mode, all modules that are targets of component scanning must use this mechanism. + +NOTE: Your existing `@ComponentScan` or `` directives must remain +unchanged to request the context to scan candidates in certain packages. When the +`ApplicationContext` detects such an index, it automatically uses it rather than scanning +the classpath. + +To generate the index, add an additional dependency to each module that contains +components that are targets for component scan directives. The following example shows +how to do so with Maven: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + org.springframework + spring-context-indexer + {spring-version} + true + + +---- + +With Gradle 4.5 and earlier, the dependency should be declared in the `compileOnly` +configuration, as shown in the following example: + +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- + dependencies { + compileOnly "org.springframework:spring-context-indexer:{spring-version}" + } +---- + +With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` +configuration, as shown in the following example: + +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- + dependencies { + annotationProcessor "org.springframework:spring-context-indexer:{spring-version}" + } +---- + +The `spring-context-indexer` artifact generates a `META-INF/spring.components` file that +is included in the jar file. + +NOTE: When working with this mode in your IDE, the `spring-context-indexer` must be +registered as an annotation processor to make sure the index is up-to-date when +candidate components are updated. + +TIP: The index is enabled automatically when a `META-INF/spring.components` file is found +on the classpath. If an index is partially available for some libraries (or use cases) +but could not be built for the whole application, you can fall back to a regular classpath +arrangement (as though no index were present at all) by setting `spring.index.ignore` to +`true`, either as a JVM system property or via the +<> mechanism. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc b/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc new file mode 100644 index 000000000000..d568e9b3ac40 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc @@ -0,0 +1,951 @@ +[[context-introduction]] += Additional Capabilities of the `ApplicationContext` + +As discussed in the <>, the `org.springframework.beans.factory` +package provides basic functionality for managing and manipulating beans, including in a +programmatic way. The `org.springframework.context` package adds the +{api-spring-framework}/context/ApplicationContext.html[`ApplicationContext`] +interface, which extends the `BeanFactory` interface, in addition to extending other +interfaces to provide additional functionality in a more application +framework-oriented style. Many people use the `ApplicationContext` in a completely +declarative fashion, not even creating it programmatically, but instead relying on +support classes such as `ContextLoader` to automatically instantiate an +`ApplicationContext` as part of the normal startup process of a Jakarta EE web application. + +To enhance `BeanFactory` functionality in a more framework-oriented style, the context +package also provides the following functionality: + +* Access to messages in i18n-style, through the `MessageSource` interface. +* Access to resources, such as URLs and files, through the `ResourceLoader` interface. +* Event publication, namely to beans that implement the `ApplicationListener` interface, + through the use of the `ApplicationEventPublisher` interface. +* Loading of multiple (hierarchical) contexts, letting each be focused on one + particular layer, such as the web layer of an application, through the + `HierarchicalBeanFactory` interface. + + + +[[context-functionality-messagesource]] +== Internationalization using `MessageSource` + +The `ApplicationContext` interface extends an interface called `MessageSource` and, +therefore, provides internationalization ("`i18n`") functionality. Spring also provides the +`HierarchicalMessageSource` interface, which can resolve messages hierarchically. +Together, these interfaces provide the foundation upon which Spring effects message +resolution. The methods defined on these interfaces include: + +* `String getMessage(String code, Object[] args, String default, Locale loc)`: The basic + method used to retrieve a message from the `MessageSource`. When no message is found + for the specified locale, the default message is used. Any arguments passed in become + replacement values, using the `MessageFormat` functionality provided by the standard + library. +* `String getMessage(String code, Object[] args, Locale loc)`: Essentially the same as + the previous method but with one difference: No default message can be specified. If + the message cannot be found, a `NoSuchMessageException` is thrown. +* `String getMessage(MessageSourceResolvable resolvable, Locale locale)`: All properties + used in the preceding methods are also wrapped in a class named + `MessageSourceResolvable`, which you can use with this method. + +When an `ApplicationContext` is loaded, it automatically searches for a `MessageSource` +bean defined in the context. The bean must have the name `messageSource`. If such a bean +is found, all calls to the preceding methods are delegated to the message source. If no +message source is found, the `ApplicationContext` attempts to find a parent containing a +bean with the same name. If it does, it uses that bean as the `MessageSource`. If the +`ApplicationContext` cannot find any source for messages, an empty +`DelegatingMessageSource` is instantiated in order to be able to accept calls to the +methods defined above. + +Spring provides three `MessageSource` implementations, `ResourceBundleMessageSource`, `ReloadableResourceBundleMessageSource` +and `StaticMessageSource`. All of them implement `HierarchicalMessageSource` in order to do nested +messaging. The `StaticMessageSource` is rarely used but provides programmatic ways to +add messages to the source. The following example shows `ResourceBundleMessageSource`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + format + exceptions + windows + + + + +---- + +The example assumes that you have three resource bundles called `format`, `exceptions` and `windows` +defined in your classpath. Any request to resolve a message is +handled in the JDK-standard way of resolving messages through `ResourceBundle` objects. For the +purposes of the example, assume the contents of two of the above resource bundle files +are as follows: + +[source,properties,indent=0,subs="verbatim,quotes"] +---- + # in format.properties + message=Alligators rock! +---- + +[source,properties,indent=0,subs="verbatim,quotes"] +---- + # in exceptions.properties + argument.required=The {0} argument is required. +---- + +The next example shows a program to run the `MessageSource` functionality. +Remember that all `ApplicationContext` implementations are also `MessageSource` +implementations and so can be cast to the `MessageSource` interface. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static void main(String[] args) { + MessageSource resources = new ClassPathXmlApplicationContext("beans.xml"); + String message = resources.getMessage("message", null, "Default", Locale.ENGLISH); + System.out.println(message); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun main() { + val resources = ClassPathXmlApplicationContext("beans.xml") + val message = resources.getMessage("message", null, "Default", Locale.ENGLISH) + println(message) + } +---- + +The resulting output from the above program is as follows: + +[literal,subs="verbatim,quotes"] +---- +Alligators rock! +---- + +To summarize, the `MessageSource` is defined in a file called `beans.xml`, which +exists at the root of your classpath. The `messageSource` bean definition refers to a +number of resource bundles through its `basenames` property. The three files that are +passed in the list to the `basenames` property exist as files at the root of your +classpath and are called `format.properties`, `exceptions.properties`, and +`windows.properties`, respectively. + +The next example shows arguments passed to the message lookup. These arguments are +converted into `String` objects and inserted into placeholders in the lookup message. + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class Example { + + private MessageSource messages; + + public void setMessages(MessageSource messages) { + this.messages = messages; + } + + public void execute() { + String message = this.messages.getMessage("argument.required", + new Object [] {"userDao"}, "Required", Locale.ENGLISH); + System.out.println(message); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class Example { + + lateinit var messages: MessageSource + + fun execute() { + val message = messages.getMessage("argument.required", + arrayOf("userDao"), "Required", Locale.ENGLISH) + println(message) + } +} +---- + +The resulting output from the invocation of the `execute()` method is as follows: + +[literal,subs="verbatim,quotes"] +---- +The userDao argument is required. +---- + +With regard to internationalization ("`i18n`"), Spring's various `MessageSource` +implementations follow the same locale resolution and fallback rules as the standard JDK +`ResourceBundle`. In short, and continuing with the example `messageSource` defined +previously, if you want to resolve messages against the British (`en-GB`) locale, you +would create files called `format_en_GB.properties`, `exceptions_en_GB.properties`, and +`windows_en_GB.properties`, respectively. + +Typically, locale resolution is managed by the surrounding environment of the +application. In the following example, the locale against which (British) messages are +resolved is specified manually: + +[literal,subs="verbatim,quotes"] +---- +# in exceptions_en_GB.properties +argument.required=Ebagum lad, the ''{0}'' argument is required, I say, required. +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static void main(final String[] args) { + MessageSource resources = new ClassPathXmlApplicationContext("beans.xml"); + String message = resources.getMessage("argument.required", + new Object [] {"userDao"}, "Required", Locale.UK); + System.out.println(message); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun main() { + val resources = ClassPathXmlApplicationContext("beans.xml") + val message = resources.getMessage("argument.required", + arrayOf("userDao"), "Required", Locale.UK) + println(message) + } +---- + +The resulting output from the running of the above program is as follows: + +[literal,subs="verbatim,quotes"] +---- +Ebagum lad, the 'userDao' argument is required, I say, required. +---- + +You can also use the `MessageSourceAware` interface to acquire a reference to any +`MessageSource` that has been defined. Any bean that is defined in an +`ApplicationContext` that implements the `MessageSourceAware` interface is injected with +the application context's `MessageSource` when the bean is created and configured. + +NOTE: Because Spring's `MessageSource` is based on Java's `ResourceBundle`, it does not merge +bundles with the same base name, but will only use the first bundle found. +Subsequent message bundles with the same base name are ignored. + +NOTE: As an alternative to `ResourceBundleMessageSource`, Spring provides a +`ReloadableResourceBundleMessageSource` class. This variant supports the same bundle +file format but is more flexible than the standard JDK based +`ResourceBundleMessageSource` implementation. In particular, it allows for reading +files from any Spring resource location (not only from the classpath) and supports hot +reloading of bundle property files (while efficiently caching them in between). +See the {api-spring-framework}/context/support/ReloadableResourceBundleMessageSource.html[`ReloadableResourceBundleMessageSource`] +javadoc for details. + + + +[[context-functionality-events]] +== Standard and Custom Events + +Event handling in the `ApplicationContext` is provided through the `ApplicationEvent` +class and the `ApplicationListener` interface. If a bean that implements the +`ApplicationListener` interface is deployed into the context, every time an +`ApplicationEvent` gets published to the `ApplicationContext`, that bean is notified. +Essentially, this is the standard Observer design pattern. + +TIP: As of Spring 4.2, the event infrastructure has been significantly improved and offers +an <> as well as the +ability to publish any arbitrary event (that is, an object that does not necessarily +extend from `ApplicationEvent`). When such an object is published, we wrap it in an +event for you. + +The following table describes the standard events that Spring provides: + +[[beans-ctx-events-tbl]] +.Built-in Events +[cols="30%,70%"] +|=== +| Event| Explanation + +| `ContextRefreshedEvent` +| Published when the `ApplicationContext` is initialized or refreshed (for example, by + using the `refresh()` method on the `ConfigurableApplicationContext` interface). + Here, "`initialized`" means that all beans are loaded, post-processor beans are detected + and activated, singletons are pre-instantiated, and the `ApplicationContext` object is + ready for use. As long as the context has not been closed, a refresh can be triggered + multiple times, provided that the chosen `ApplicationContext` actually supports such + "`hot`" refreshes. For example, `XmlWebApplicationContext` supports hot refreshes, but + `GenericApplicationContext` does not. + +| `ContextStartedEvent` +| Published when the `ApplicationContext` is started by using the `start()` method on the + `ConfigurableApplicationContext` interface. Here, "`started`" means that all `Lifecycle` + beans receive an explicit start signal. Typically, this signal is used to restart beans + after an explicit stop, but it may also be used to start components that have not been + configured for autostart (for example, components that have not already started on + initialization). + +| `ContextStoppedEvent` +| Published when the `ApplicationContext` is stopped by using the `stop()` method on the + `ConfigurableApplicationContext` interface. Here, "`stopped`" means that all `Lifecycle` + beans receive an explicit stop signal. A stopped context may be restarted through a + `start()` call. + +| `ContextClosedEvent` +| Published when the `ApplicationContext` is being closed by using the `close()` method + on the `ConfigurableApplicationContext` interface or via a JVM shutdown hook. Here, + "closed" means that all singleton beans will be destroyed. Once the context is closed, + it reaches its end of life and cannot be refreshed or restarted. + +| `RequestHandledEvent` +| A web-specific event telling all beans that an HTTP request has been serviced. This + event is published after the request is complete. This event is only applicable to + web applications that use Spring's `DispatcherServlet`. + +| `ServletRequestHandledEvent` +| A subclass of `RequestHandledEvent` that adds Servlet-specific context information. + +|=== + +You can also create and publish your own custom events. The following example shows a +simple class that extends Spring's `ApplicationEvent` base class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class BlockedListEvent extends ApplicationEvent { + + private final String address; + private final String content; + + public BlockedListEvent(Object source, String address, String content) { + super(source); + this.address = address; + this.content = content; + } + + // accessor and other methods... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class BlockedListEvent(source: Any, + val address: String, + val content: String) : ApplicationEvent(source) +---- + +To publish a custom `ApplicationEvent`, call the `publishEvent()` method on an +`ApplicationEventPublisher`. Typically, this is done by creating a class that implements +`ApplicationEventPublisherAware` and registering it as a Spring bean. The following +example shows such a class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class EmailService implements ApplicationEventPublisherAware { + + private List blockedList; + private ApplicationEventPublisher publisher; + + public void setBlockedList(List blockedList) { + this.blockedList = blockedList; + } + + public void setApplicationEventPublisher(ApplicationEventPublisher publisher) { + this.publisher = publisher; + } + + public void sendEmail(String address, String content) { + if (blockedList.contains(address)) { + publisher.publishEvent(new BlockedListEvent(this, address, content)); + return; + } + // send email... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class EmailService : ApplicationEventPublisherAware { + + private lateinit var blockedList: List + private lateinit var publisher: ApplicationEventPublisher + + fun setBlockedList(blockedList: List) { + this.blockedList = blockedList + } + + override fun setApplicationEventPublisher(publisher: ApplicationEventPublisher) { + this.publisher = publisher + } + + fun sendEmail(address: String, content: String) { + if (blockedList!!.contains(address)) { + publisher!!.publishEvent(BlockedListEvent(this, address, content)) + return + } + // send email... + } + } +---- + +At configuration time, the Spring container detects that `EmailService` implements +`ApplicationEventPublisherAware` and automatically calls +`setApplicationEventPublisher()`. In reality, the parameter passed in is the Spring +container itself. You are interacting with the application context through its +`ApplicationEventPublisher` interface. + +To receive the custom `ApplicationEvent`, you can create a class that implements +`ApplicationListener` and register it as a Spring bean. The following example +shows such a class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class BlockedListNotifier implements ApplicationListener { + + private String notificationAddress; + + public void setNotificationAddress(String notificationAddress) { + this.notificationAddress = notificationAddress; + } + + public void onApplicationEvent(BlockedListEvent event) { + // notify appropriate parties via notificationAddress... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class BlockedListNotifier : ApplicationListener { + + lateinit var notificationAddress: String + + override fun onApplicationEvent(event: BlockedListEvent) { + // notify appropriate parties via notificationAddress... + } + } +---- + +Notice that `ApplicationListener` is generically parameterized with the type of your +custom event (`BlockedListEvent` in the preceding example). This means that the +`onApplicationEvent()` method can remain type-safe, avoiding any need for downcasting. +You can register as many event listeners as you wish, but note that, by default, event +listeners receive events synchronously. This means that the `publishEvent()` method +blocks until all listeners have finished processing the event. One advantage of this +synchronous and single-threaded approach is that, when a listener receives an event, it +operates inside the transaction context of the publisher if a transaction context is +available. If another strategy for event publication becomes necessary, see the javadoc +for Spring's +{api-spring-framework}/context/event/ApplicationEventMulticaster.html[`ApplicationEventMulticaster`] interface +and {api-spring-framework}/context/event/SimpleApplicationEventMulticaster.html[`SimpleApplicationEventMulticaster`] +implementation for configuration options. + +The following example shows the bean definitions used to register and configure each of +the classes above: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + known.spammer@example.org + known.hacker@example.org + john.doe@example.org + + + + + + + +---- + +Putting it all together, when the `sendEmail()` method of the `emailService` bean is +called, if there are any email messages that should be blocked, a custom event of type +`BlockedListEvent` is published. The `blockedListNotifier` bean is registered as an +`ApplicationListener` and receives the `BlockedListEvent`, at which point it can +notify appropriate parties. + +NOTE: Spring's eventing mechanism is designed for simple communication between Spring beans +within the same application context. However, for more sophisticated enterprise +integration needs, the separately maintained +https://projects.spring.io/spring-integration/[Spring Integration] project provides +complete support for building lightweight, +https://www.enterpriseintegrationpatterns.com[pattern-oriented], event-driven +architectures that build upon the well-known Spring programming model. + + +[[context-functionality-events-annotation]] +=== Annotation-based Event Listeners + +You can register an event listener on any method of a managed bean by using the +`@EventListener` annotation. The `BlockedListNotifier` can be rewritten as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class BlockedListNotifier { + + private String notificationAddress; + + public void setNotificationAddress(String notificationAddress) { + this.notificationAddress = notificationAddress; + } + + @EventListener + public void processBlockedListEvent(BlockedListEvent event) { + // notify appropriate parties via notificationAddress... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class BlockedListNotifier { + + lateinit var notificationAddress: String + + @EventListener + fun processBlockedListEvent(event: BlockedListEvent) { + // notify appropriate parties via notificationAddress... + } + } +---- + +The method signature once again declares the event type to which it listens, +but, this time, with a flexible name and without implementing a specific listener interface. +The event type can also be narrowed through generics as long as the actual event type +resolves your generic parameter in its implementation hierarchy. + +If your method should listen to several events or if you want to define it with no +parameter at all, the event types can also be specified on the annotation itself. The +following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @EventListener({ContextStartedEvent.class, ContextRefreshedEvent.class}) + public void handleContextStart() { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @EventListener(ContextStartedEvent::class, ContextRefreshedEvent::class) + fun handleContextStart() { + // ... + } +---- + +It is also possible to add additional runtime filtering by using the `condition` attribute +of the annotation that defines a <>, which should match +to actually invoke the method for a particular event. + +The following example shows how our notifier can be rewritten to be invoked only if the +`content` attribute of the event is equal to `my-event`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @EventListener(condition = "#blEvent.content == 'my-event'") + public void processBlockedListEvent(BlockedListEvent blEvent) { + // notify appropriate parties via notificationAddress... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @EventListener(condition = "#blEvent.content == 'my-event'") + fun processBlockedListEvent(blEvent: BlockedListEvent) { + // notify appropriate parties via notificationAddress... + } +---- + +Each `SpEL` expression evaluates against a dedicated context. The following table lists the +items made available to the context so that you can use them for conditional event processing: + +[[context-functionality-events-annotation-tbl]] +.Event SpEL available metadata +|=== +| Name| Location| Description| Example + +| Event +| root object +| The actual `ApplicationEvent`. +| `#root.event` or `event` + +| Arguments array +| root object +| The arguments (as an object array) used to invoke the method. +| `#root.args` or `args`; `args[0]` to access the first argument, etc. + +| __Argument name__ +| evaluation context +| The name of any of the method arguments. If, for some reason, the names are not available + (for example, because there is no debug information in the compiled byte code), individual + arguments are also available using the `#a<#arg>` syntax where `<#arg>` stands for the + argument index (starting from 0). +| `#blEvent` or `#a0` (you can also use `#p0` or `#p<#arg>` parameter notation as an alias) +|=== + +Note that `#root.event` gives you access to the underlying event, even if your method +signature actually refers to an arbitrary object that was published. + +If you need to publish an event as the result of processing another event, you can change the +method signature to return the event that should be published, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @EventListener + public ListUpdateEvent handleBlockedListEvent(BlockedListEvent event) { + // notify appropriate parties via notificationAddress and + // then publish a ListUpdateEvent... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @EventListener + fun handleBlockedListEvent(event: BlockedListEvent): ListUpdateEvent { + // notify appropriate parties via notificationAddress and + // then publish a ListUpdateEvent... + } +---- + +NOTE: This feature is not supported for +<>. + +The `handleBlockedListEvent()` method publishes a new `ListUpdateEvent` for every +`BlockedListEvent` that it handles. If you need to publish several events, you can return +a `Collection` or an array of events instead. + + +[[context-functionality-events-async]] +=== Asynchronous Listeners + +If you want a particular listener to process events asynchronously, you can reuse the +<>. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @EventListener + @Async + public void processBlockedListEvent(BlockedListEvent event) { + // BlockedListEvent is processed in a separate thread + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @EventListener + @Async + fun processBlockedListEvent(event: BlockedListEvent) { + // BlockedListEvent is processed in a separate thread + } +---- + +Be aware of the following limitations when using asynchronous events: + +* If an asynchronous event listener throws an `Exception`, it is not propagated to the + caller. See + {api-spring-framework}/aop/interceptor/AsyncUncaughtExceptionHandler.html[`AsyncUncaughtExceptionHandler`] + for more details. +* Asynchronous event listener methods cannot publish a subsequent event by returning a + value. If you need to publish another event as the result of the processing, inject an + {api-spring-framework}/context/ApplicationEventPublisher.html[`ApplicationEventPublisher`] + to publish the event manually. + + +[[context-functionality-events-order]] +=== Ordering Listeners + +If you need one listener to be invoked before another one, you can add the `@Order` +annotation to the method declaration, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @EventListener + @Order(42) + public void processBlockedListEvent(BlockedListEvent event) { + // notify appropriate parties via notificationAddress... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @EventListener + @Order(42) + fun processBlockedListEvent(event: BlockedListEvent) { + // notify appropriate parties via notificationAddress... + } +---- + + +[[context-functionality-events-generics]] +=== Generic Events + +You can also use generics to further define the structure of your event. Consider using an +`EntityCreatedEvent` where `T` is the type of the actual entity that got created. For example, you +can create the following listener definition to receive only `EntityCreatedEvent` for a +`Person`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @EventListener + public void onPersonCreated(EntityCreatedEvent event) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @EventListener + fun onPersonCreated(event: EntityCreatedEvent) { + // ... + } +---- + +Due to type erasure, this works only if the event that is fired resolves the generic +parameters on which the event listener filters (that is, something like +`class PersonCreatedEvent extends EntityCreatedEvent { ... }`). + +In certain circumstances, this may become quite tedious if all events follow the same +structure (as should be the case for the event in the preceding example). In such a case, +you can implement `ResolvableTypeProvider` to guide the framework beyond what the runtime +environment provides. The following event shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class EntityCreatedEvent extends ApplicationEvent implements ResolvableTypeProvider { + + public EntityCreatedEvent(T entity) { + super(entity); + } + + @Override + public ResolvableType getResolvableType() { + return ResolvableType.forClassWithGenerics(getClass(), ResolvableType.forInstance(getSource())); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class EntityCreatedEvent(entity: T) : ApplicationEvent(entity), ResolvableTypeProvider { + + override fun getResolvableType(): ResolvableType? { + return ResolvableType.forClassWithGenerics(javaClass, ResolvableType.forInstance(getSource())) + } + } +---- + +TIP: This works not only for `ApplicationEvent` but any arbitrary object that you send as +an event. + + + +[[context-functionality-resources]] +== Convenient Access to Low-level Resources + +For optimal usage and understanding of application contexts, you should familiarize +yourself with Spring's `Resource` abstraction, as described in <>. + +An application context is a `ResourceLoader`, which can be used to load `Resource` objects. +A `Resource` is essentially a more feature rich version of the JDK `java.net.URL` class. +In fact, the implementations of the `Resource` wrap an instance of `java.net.URL`, where +appropriate. A `Resource` can obtain low-level resources from almost any location in a +transparent fashion, including from the classpath, a filesystem location, anywhere +describable with a standard URL, and some other variations. If the resource location +string is a simple path without any special prefixes, where those resources come from is +specific and appropriate to the actual application context type. + +You can configure a bean deployed into the application context to implement the special +callback interface, `ResourceLoaderAware`, to be automatically called back at +initialization time with the application context itself passed in as the `ResourceLoader`. +You can also expose properties of type `Resource`, to be used to access static resources. +They are injected into it like any other properties. You can specify those `Resource` +properties as simple `String` paths and rely on automatic conversion from those text +strings to actual `Resource` objects when the bean is deployed. + +The location path or paths supplied to an `ApplicationContext` constructor are actually +resource strings and, in simple form, are treated appropriately according to the specific +context implementation. For example `ClassPathXmlApplicationContext` treats a simple +location path as a classpath location. You can also use location paths (resource strings) +with special prefixes to force loading of definitions from the classpath or a URL, +regardless of the actual context type. + + + +[[context-functionality-startup]] +== Application Startup Tracking + +The `ApplicationContext` manages the lifecycle of Spring applications and provides a rich +programming model around components. As a result, complex applications can have equally +complex component graphs and startup phases. + +Tracking the application startup steps with specific metrics can help understand where +time is being spent during the startup phase, but it can also be used as a way to better +understand the context lifecycle as a whole. + +The `AbstractApplicationContext` (and its subclasses) is instrumented with an +`ApplicationStartup`, which collects `StartupStep` data about various startup phases: + +* application context lifecycle (base packages scanning, config classes management) +* beans lifecycle (instantiation, smart initialization, post processing) +* application events processing + +Here is an example of instrumentation in the `AnnotationConfigApplicationContext`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // create a startup step and start recording + StartupStep scanPackages = this.getApplicationStartup().start("spring.context.base-packages.scan"); + // add tagging information to the current step + scanPackages.tag("packages", () -> Arrays.toString(basePackages)); + // perform the actual phase we're instrumenting + this.scanner.scan(basePackages); + // end the current step + scanPackages.end(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // create a startup step and start recording + val scanPackages = this.getApplicationStartup().start("spring.context.base-packages.scan") + // add tagging information to the current step + scanPackages.tag("packages", () -> Arrays.toString(basePackages)) + // perform the actual phase we're instrumenting + this.scanner.scan(basePackages) + // end the current step + scanPackages.end() +---- + +The application context is already instrumented with multiple steps. +Once recorded, these startup steps can be collected, displayed and analyzed with specific tools. +For a complete list of existing startup steps, you can check out the +<>. + +The default `ApplicationStartup` implementation is a no-op variant, for minimal overhead. +This means no metrics will be collected during application startup by default. +Spring Framework ships with an implementation for tracking startup steps with Java Flight Recorder: +`FlightRecorderApplicationStartup`. To use this variant, you must configure an instance of it +to the `ApplicationContext` as soon as it's been created. + +Developers can also use the `ApplicationStartup` infrastructure if they're providing their own +`AbstractApplicationContext` subclass, or if they wish to collect more precise data. + +WARNING: `ApplicationStartup` is meant to be only used during application startup and for +the core container; this is by no means a replacement for Java profilers or +metrics libraries like https://micrometer.io[Micrometer]. + +To start collecting custom `StartupStep`, components can either get the `ApplicationStartup` +instance from the application context directly, make their component implement `ApplicationStartupAware`, +or ask for the `ApplicationStartup` type on any injection point. + +NOTE: Developers should not use the `"spring.*"` namespace when creating custom startup steps. +This namespace is reserved for internal Spring usage and is subject to change. + +[[context-create]] +== Convenient ApplicationContext Instantiation for Web Applications + +You can create `ApplicationContext` instances declaratively by using, for example, a +`ContextLoader`. Of course, you can also create `ApplicationContext` instances +programmatically by using one of the `ApplicationContext` implementations. + +You can register an `ApplicationContext` by using the `ContextLoaderListener`, as the +following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + contextConfigLocation + /WEB-INF/daoContext.xml /WEB-INF/applicationContext.xml + + + + org.springframework.web.context.ContextLoaderListener + +---- + +The listener inspects the `contextConfigLocation` parameter. If the parameter does not +exist, the listener uses `/WEB-INF/applicationContext.xml` as a default. When the +parameter does exist, the listener separates the `String` by using predefined +delimiters (comma, semicolon, and whitespace) and uses the values as locations where +application contexts are searched. Ant-style path patterns are supported as well. +Examples are `/WEB-INF/{asterisk}Context.xml` (for all files with names that end with +`Context.xml` and that reside in the `WEB-INF` directory) and `/WEB-INF/**/*Context.xml` +(for all such files in any subdirectory of `WEB-INF`). + + + +[[context-deploy-rar]] +== Deploying a Spring `ApplicationContext` as a Jakarta EE RAR File + +It is possible to deploy a Spring `ApplicationContext` as a RAR file, encapsulating the +context and all of its required bean classes and library JARs in a Jakarta EE RAR deployment +unit. This is the equivalent of bootstrapping a stand-alone `ApplicationContext` (only hosted +in Jakarta EE environment) being able to access the Jakarta EE servers facilities. RAR deployment +is a more natural alternative to a scenario of deploying a headless WAR file -- in effect, +a WAR file without any HTTP entry points that is used only for bootstrapping a Spring +`ApplicationContext` in a Jakarta EE environment. + +RAR deployment is ideal for application contexts that do not need HTTP entry points but +rather consist only of message endpoints and scheduled jobs. Beans in such a context can +use application server resources such as the JTA transaction manager and JNDI-bound JDBC +`DataSource` instances and JMS `ConnectionFactory` instances and can also register with +the platform's JMX server -- all through Spring's standard transaction management and JNDI +and JMX support facilities. Application components can also interact with the application +server's JCA `WorkManager` through Spring's `TaskExecutor` abstraction. + +See the javadoc of the +{api-spring-framework}/jca/context/SpringContextResourceAdapter.html[`SpringContextResourceAdapter`] +class for the configuration details involved in RAR deployment. + +For a simple deployment of a Spring ApplicationContext as a Jakarta EE RAR file: + +. Package +all application classes into a RAR file (which is a standard JAR file with a different +file extension). +. Add all required library JARs into the root of the RAR archive. +. Add a +`META-INF/ra.xml` deployment descriptor (as shown in the {api-spring-framework}/jca/context/SpringContextResourceAdapter.html[javadoc for `SpringContextResourceAdapter`]) +and the corresponding Spring XML bean definition file(s) (typically +`META-INF/applicationContext.xml`). +. Drop the resulting RAR file into your +application server's deployment directory. + +NOTE: Such RAR deployment units are usually self-contained. They do not expose components +to the outside world, not even to other modules of the same application. Interaction with a +RAR-based `ApplicationContext` usually occurs through JMS destinations that it shares with +other modules. A RAR-based `ApplicationContext` may also, for example, schedule some jobs +or react to new files in the file system (or the like). If it needs to allow synchronous +access from the outside, it could (for example) export RMI endpoints, which may be used +by other application modules on the same machine. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc b/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc new file mode 100644 index 000000000000..249ef15f3806 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc @@ -0,0 +1,46 @@ +[[context-load-time-weaver]] += Registering a `LoadTimeWeaver` + +The `LoadTimeWeaver` is used by Spring to dynamically transform classes as they are +loaded into the Java virtual machine (JVM). + +To enable load-time weaving, you can add the `@EnableLoadTimeWeaving` to one of your +`@Configuration` classes, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableLoadTimeWeaving + public class AppConfig { + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableLoadTimeWeaving + class AppConfig +---- + +Alternatively, for XML configuration, you can use the `context:load-time-weaver` element: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +Once configured for the `ApplicationContext`, any bean within that `ApplicationContext` +may implement `LoadTimeWeaverAware`, thereby receiving a reference to the load-time +weaver instance. This is particularly useful in combination with +<> where load-time weaving may be +necessary for JPA class transformation. +Consult the +{api-spring-framework}/orm/jpa/LocalContainerEntityManagerFactoryBean.html[`LocalContainerEntityManagerFactoryBean`] +javadoc for more detail. For more on AspectJ load-time weaving, see <>. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/definition.adoc b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc new file mode 100644 index 000000000000..7caf554ce272 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc @@ -0,0 +1,430 @@ +[[beans-definition]] += Bean Overview + +A Spring IoC container manages one or more beans. These beans are created with the +configuration metadata that you supply to the container (for example, in the form of XML +`` definitions). + +Within the container itself, these bean definitions are represented as `BeanDefinition` +objects, which contain (among other information) the following metadata: + +* A package-qualified class name: typically, the actual implementation class of the + bean being defined. +* Bean behavioral configuration elements, which state how the bean should behave in the + container (scope, lifecycle callbacks, and so forth). +* References to other beans that are needed for the bean to do its work. These + references are also called collaborators or dependencies. +* Other configuration settings to set in the newly created object -- for example, the size + limit of the pool or the number of connections to use in a bean that manages a + connection pool. + +This metadata translates to a set of properties that make up each bean definition. +The following table describes these properties: + +[[beans-factory-bean-definition-tbl]] +.The bean definition +|=== +| Property| Explained in... + +| Class +| <> + +| Name +| <> + +| Scope +| <> + +| Constructor arguments +| <> + +| Properties +| <> + +| Autowiring mode +| <> + +| Lazy initialization mode +| <> + +| Initialization method +| <> + +| Destruction method +| <> +|=== + +In addition to bean definitions that contain information on how to create a specific +bean, the `ApplicationContext` implementations also permit the registration of existing +objects that are created outside the container (by users). This is done by accessing the +ApplicationContext's `BeanFactory` through the `getBeanFactory()` method, which returns +the `DefaultListableBeanFactory` implementation. `DefaultListableBeanFactory` supports +this registration through the `registerSingleton(..)` and `registerBeanDefinition(..)` +methods. However, typical applications work solely with beans defined through regular +bean definition metadata. + +[NOTE] +==== +Bean metadata and manually supplied singleton instances need to be registered as early +as possible, in order for the container to properly reason about them during autowiring +and other introspection steps. While overriding existing metadata and existing +singleton instances is supported to some degree, the registration of new beans at +runtime (concurrently with live access to the factory) is not officially supported and may +lead to concurrent access exceptions, inconsistent state in the bean container, or both. +==== + + + +[[beans-beanname]] +== Naming Beans + +Every bean has one or more identifiers. These identifiers must be unique within the +container that hosts the bean. A bean usually has only one identifier. However, if it +requires more than one, the extra ones can be considered aliases. + +In XML-based configuration metadata, you use the `id` attribute, the `name` attribute, or +both to specify bean identifiers. The `id` attribute lets you specify exactly one `id`. +Conventionally, these names are alphanumeric ('myBean', 'someService', etc.), but they +can contain special characters as well. If you want to introduce other aliases for the +bean, you can also specify them in the `name` attribute, separated by a comma (`,`), +semicolon (`;`), or white space. Although the `id` attribute is defined as an +`xsd:string` type, bean `id` uniqueness is enforced by the container, though not by XML +parsers. + +You are not required to supply a `name` or an `id` for a bean. If you do not supply a +`name` or `id` explicitly, the container generates a unique name for that bean. However, +if you want to refer to that bean by name, through the use of the `ref` element or a +Service Locator style lookup, you must provide a name. +Motivations for not supplying a name are related to using <> and <>. + +.Bean Naming Conventions +**** +The convention is to use the standard Java convention for instance field names when +naming beans. That is, bean names start with a lowercase letter and are camel-cased +from there. Examples of such names include `accountManager`, +`accountService`, `userDao`, `loginController`, and so forth. + +Naming beans consistently makes your configuration easier to read and understand. +Also, if you use Spring AOP, it helps a lot when applying advice to a set of beans +related by name. +**** + +NOTE: With component scanning in the classpath, Spring generates bean names for unnamed +components, following the rules described earlier: essentially, taking the simple class name +and turning its initial character to lower-case. However, in the (unusual) special +case when there is more than one character and both the first and second characters +are upper case, the original casing gets preserved. These are the same rules as +defined by `java.beans.Introspector.decapitalize` (which Spring uses here). + + +[[beans-beanname-alias]] +=== Aliasing a Bean outside the Bean Definition + +In a bean definition itself, you can supply more than one name for the bean, by using a +combination of up to one name specified by the `id` attribute and any number of other +names in the `name` attribute. These names can be equivalent aliases to the same bean +and are useful for some situations, such as letting each component in an application +refer to a common dependency by using a bean name that is specific to that component +itself. + +Specifying all aliases where the bean is actually defined is not always adequate, +however. It is sometimes desirable to introduce an alias for a bean that is defined +elsewhere. This is commonly the case in large systems where configuration is split +amongst each subsystem, with each subsystem having its own set of object definitions. +In XML-based configuration metadata, you can use the `` element to accomplish +this. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +In this case, a bean (in the same container) named `fromName` may also, +after the use of this alias definition, be referred to as `toName`. + +For example, the configuration metadata for subsystem A may refer to a DataSource by the +name of `subsystemA-dataSource`. The configuration metadata for subsystem B may refer to +a DataSource by the name of `subsystemB-dataSource`. When composing the main application +that uses both these subsystems, the main application refers to the DataSource by the +name of `myApp-dataSource`. To have all three names refer to the same object, you can +add the following alias definitions to the configuration metadata: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + +---- + +Now each component and the main application can refer to the dataSource through a name +that is unique and guaranteed not to clash with any other definition (effectively +creating a namespace), yet they refer to the same bean. + +.Java-configuration +**** +If you use Java Configuration, the `@Bean` annotation can be used to provide aliases. +See <> for details. +**** + + + +[[beans-factory-class]] +== Instantiating Beans + +A bean definition is essentially a recipe for creating one or more objects. The +container looks at the recipe for a named bean when asked and uses the configuration +metadata encapsulated by that bean definition to create (or acquire) an actual object. + +If you use XML-based configuration metadata, you specify the type (or class) of object +that is to be instantiated in the `class` attribute of the `` element. This +`class` attribute (which, internally, is a `Class` property on a `BeanDefinition` +instance) is usually mandatory. (For exceptions, see +<> and <>.) +You can use the `Class` property in one of two ways: + +* Typically, to specify the bean class to be constructed in the case where the container + itself directly creates the bean by calling its constructor reflectively, somewhat + equivalent to Java code with the `new` operator. +* To specify the actual class containing the `static` factory method that is + invoked to create the object, in the less common case where the container invokes a + `static` factory method on a class to create the bean. The object type returned + from the invocation of the `static` factory method may be the same class or another + class entirely. + +.Nested class names +**** +If you want to configure a bean definition for a nested class, you may use either the +binary name or the source name of the nested class. + +For example, if you have a class called `SomeThing` in the `com.example` package, and +this `SomeThing` class has a `static` nested class called `OtherThing`, they can be +separated by a dollar sign (`$`) or a dot (`.`). So the value of the `class` attribute in +a bean definition would be `com.example.SomeThing$OtherThing` or +`com.example.SomeThing.OtherThing`. +**** + + +[[beans-factory-class-ctor]] +=== Instantiation with a Constructor + +When you create a bean by the constructor approach, all normal classes are usable by and +compatible with Spring. That is, the class being developed does not need to implement +any specific interfaces or to be coded in a specific fashion. Simply specifying the bean +class should suffice. However, depending on what type of IoC you use for that specific +bean, you may need a default (empty) constructor. + +The Spring IoC container can manage virtually any class you want it to manage. It is +not limited to managing true JavaBeans. Most Spring users prefer actual JavaBeans with +only a default (no-argument) constructor and appropriate setters and getters modeled +after the properties in the container. You can also have more exotic non-bean-style +classes in your container. If, for example, you need to use a legacy connection pool +that absolutely does not adhere to the JavaBean specification, Spring can manage it as +well. + +With XML-based configuration metadata you can specify your bean class as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +For details about the mechanism for supplying arguments to the constructor (if required) +and setting object instance properties after the object is constructed, see +<>. + + +[[beans-factory-class-static-factory-method]] +=== Instantiation with a Static Factory Method + +When defining a bean that you create with a static factory method, use the `class` +attribute to specify the class that contains the `static` factory method and an attribute +named `factory-method` to specify the name of the factory method itself. You should be +able to call this method (with optional arguments, as described later) and return a live +object, which subsequently is treated as if it had been created through a constructor. +One use for such a bean definition is to call `static` factories in legacy code. + +The following bean definition specifies that the bean will be created by calling a +factory method. The definition does not specify the type (class) of the returned object, +but rather the class containing the factory method. In this example, the +`createInstance()` method must be a `static` method. The following example shows how to +specify a factory method: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +The following example shows a class that would work with the preceding bean definition: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ClientService { + private static ClientService clientService = new ClientService(); + private ClientService() {} + + public static ClientService createInstance() { + return clientService; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ClientService private constructor() { + companion object { + private val clientService = ClientService() + @JvmStatic + fun createInstance() = clientService + } + } +---- + +For details about the mechanism for supplying (optional) arguments to the factory method +and setting object instance properties after the object is returned from the factory, +see <>. + + +[[beans-factory-class-instance-factory-method]] +=== Instantiation by Using an Instance Factory Method + +Similar to instantiation through a <>, instantiation with an instance factory method invokes a non-static +method of an existing bean from the container to create a new bean. To use this +mechanism, leave the `class` attribute empty and, in the `factory-bean` attribute, +specify the name of a bean in the current (or parent or ancestor) container that contains +the instance method that is to be invoked to create the object. Set the name of the +factory method itself with the `factory-method` attribute. The following example shows +how to configure such a bean: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +The following example shows the corresponding class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class DefaultServiceLocator { + + private static ClientService clientService = new ClientServiceImpl(); + + public ClientService createClientServiceInstance() { + return clientService; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class DefaultServiceLocator { + companion object { + private val clientService = ClientServiceImpl() + } + fun createClientServiceInstance(): ClientService { + return clientService + } + } +---- + +One factory class can also hold more than one factory method, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +The following example shows the corresponding class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class DefaultServiceLocator { + + private static ClientService clientService = new ClientServiceImpl(); + + private static AccountService accountService = new AccountServiceImpl(); + + public ClientService createClientServiceInstance() { + return clientService; + } + + public AccountService createAccountServiceInstance() { + return accountService; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class DefaultServiceLocator { + companion object { + private val clientService = ClientServiceImpl() + private val accountService = AccountServiceImpl() + } + + fun createClientServiceInstance(): ClientService { + return clientService + } + + fun createAccountServiceInstance(): AccountService { + return accountService + } + } +---- + +This approach shows that the factory bean itself can be managed and configured through +dependency injection (DI). See <>. + +NOTE: In Spring documentation, "factory bean" refers to a bean that is configured in the +Spring container and that creates objects through an +<> or +<> factory method. By contrast, +`FactoryBean` (notice the capitalization) refers to a Spring-specific +<> implementation class. + + +[[beans-factory-type-determination]] +=== Determining a Bean's Runtime Type + +The runtime type of a specific bean is non-trivial to determine. A specified class in +the bean metadata definition is just an initial class reference, potentially combined +with a declared factory method or being a `FactoryBean` class which may lead to a +different runtime type of the bean, or not being set at all in case of an instance-level +factory method (which is resolved via the specified `factory-bean` name instead). +Additionally, AOP proxying may wrap a bean instance with an interface-based proxy with +limited exposure of the target bean's actual type (just its implemented interfaces). + +The recommended way to find out about the actual runtime type of a particular bean is +a `BeanFactory.getType` call for the specified bean name. This takes all of the above +cases into account and returns the type of object that a `BeanFactory.getBean` call is +going to return for the same bean name. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies.adoc new file mode 100644 index 000000000000..aa670335d810 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies.adoc @@ -0,0 +1,11 @@ +[[beans-dependencies]] += Dependencies + +A typical enterprise application does not consist of a single object (or bean in the +Spring parlance). Even the simplest application has a few objects that work together to +present what the end-user sees as a coherent application. This next section explains how +you go from defining a number of bean definitions that stand alone to a fully realized +application where objects collaborate to achieve a goal. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc new file mode 100644 index 000000000000..3ca999ae95d7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc @@ -0,0 +1,127 @@ +[[beans-factory-autowire]] += Autowiring Collaborators + +The Spring container can autowire relationships between collaborating beans. You can +let Spring resolve collaborators (other beans) automatically for your bean by +inspecting the contents of the `ApplicationContext`. Autowiring has the following +advantages: + +* Autowiring can significantly reduce the need to specify properties or constructor + arguments. (Other mechanisms such as a bean template + <> are also valuable + in this regard.) +* Autowiring can update a configuration as your objects evolve. For example, if you need + to add a dependency to a class, that dependency can be satisfied automatically without + you needing to modify the configuration. Thus autowiring can be especially useful + during development, without negating the option of switching to explicit wiring when + the code base becomes more stable. + +When using XML-based configuration metadata (see <>), you +can specify the autowire mode for a bean definition with the `autowire` attribute of the +`` element. The autowiring functionality has four modes. You specify autowiring +per bean and can thus choose which ones to autowire. The following table describes the +four autowiring modes: + +[[beans-factory-autowiring-modes-tbl]] +.Autowiring modes +[cols="20%,80%"] +|=== +| Mode| Explanation + +| `no` +| (Default) No autowiring. Bean references must be defined by `ref` elements. Changing + the default setting is not recommended for larger deployments, because specifying + collaborators explicitly gives greater control and clarity. To some extent, it + documents the structure of a system. + +| `byName` +| Autowiring by property name. Spring looks for a bean with the same name as the + property that needs to be autowired. For example, if a bean definition is set to + autowire by name and it contains a `master` property (that is, it has a + `setMaster(..)` method), Spring looks for a bean definition named `master` and uses + it to set the property. + +| `byType` +| Lets a property be autowired if exactly one bean of the property type exists in + the container. If more than one exists, a fatal exception is thrown, which indicates + that you may not use `byType` autowiring for that bean. If there are no matching + beans, nothing happens (the property is not set). + +| `constructor` +| Analogous to `byType` but applies to constructor arguments. If there is not exactly + one bean of the constructor argument type in the container, a fatal error is raised. +|=== + +With `byType` or `constructor` autowiring mode, you can wire arrays and +typed collections. In such cases, all autowire candidates within the container that +match the expected type are provided to satisfy the dependency. You can autowire +strongly-typed `Map` instances if the expected key type is `String`. An autowired `Map` +instance's values consist of all bean instances that match the expected type, and the +`Map` instance's keys contain the corresponding bean names. + + +[[beans-autowired-exceptions]] +== Limitations and Disadvantages of Autowiring + +Autowiring works best when it is used consistently across a project. If autowiring is +not used in general, it might be confusing to developers to use it to wire only one or +two bean definitions. + +Consider the limitations and disadvantages of autowiring: + +* Explicit dependencies in `property` and `constructor-arg` settings always override + autowiring. You cannot autowire simple properties such as primitives, + `Strings`, and `Classes` (and arrays of such simple properties). This limitation is + by-design. +* Autowiring is less exact than explicit wiring. Although, as noted in the earlier table, + Spring is careful to avoid guessing in case of ambiguity that might have unexpected + results. The relationships between your Spring-managed objects are no longer + documented explicitly. +* Wiring information may not be available to tools that may generate documentation from + a Spring container. +* Multiple bean definitions within the container may match the type specified by the + setter method or constructor argument to be autowired. For arrays, collections, or + `Map` instances, this is not necessarily a problem. However, for dependencies that + expect a single value, this ambiguity is not arbitrarily resolved. If no unique bean + definition is available, an exception is thrown. + +In the latter scenario, you have several options: + +* Abandon autowiring in favor of explicit wiring. +* Avoid autowiring for a bean definition by setting its `autowire-candidate` attributes + to `false`, as described in the <>. +* Designate a single bean definition as the primary candidate by setting the + `primary` attribute of its `` element to `true`. +* Implement the more fine-grained control available with annotation-based configuration, + as described in <>. + + + +[[beans-factory-autowire-candidate]] +== Excluding a Bean from Autowiring + +On a per-bean basis, you can exclude a bean from autowiring. In Spring's XML format, set +the `autowire-candidate` attribute of the `` element to `false`. The container +makes that specific bean definition unavailable to the autowiring infrastructure +(including annotation style configurations such as <>). + +NOTE: The `autowire-candidate` attribute is designed to only affect type-based autowiring. +It does not affect explicit references by name, which get resolved even if the +specified bean is not marked as an autowire candidate. As a consequence, autowiring +by name nevertheless injects a bean if the name matches. + +You can also limit autowire candidates based on pattern-matching against bean names. The +top-level `` element accepts one or more patterns within its +`default-autowire-candidates` attribute. For example, to limit autowire candidate status +to any bean whose name ends with `Repository`, provide a value of `*Repository`. To +provide multiple patterns, define them in a comma-separated list. An explicit value of +`true` or `false` for a bean definition's `autowire-candidate` attribute always takes +precedence. For such beans, the pattern matching rules do not apply. + +These techniques are useful for beans that you never want to be injected into other +beans by autowiring. It does not mean that an excluded bean cannot itself be configured by +using autowiring. Rather, the bean itself is not a candidate for autowiring other beans. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc new file mode 100644 index 000000000000..7d686d4e1364 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc @@ -0,0 +1,560 @@ +[[beans-factory-collaborators]] += Dependency Injection + +Dependency injection (DI) is a process whereby objects define their dependencies +(that is, the other objects with which they work) only through constructor arguments, +arguments to a factory method, or properties that are set on the object instance after +it is constructed or returned from a factory method. The container then injects those +dependencies when it creates the bean. This process is fundamentally the inverse (hence +the name, Inversion of Control) of the bean itself controlling the instantiation +or location of its dependencies on its own by using direct construction of classes or +the Service Locator pattern. + +Code is cleaner with the DI principle, and decoupling is more effective when objects are +provided with their dependencies. The object does not look up its dependencies and does +not know the location or class of the dependencies. As a result, your classes become easier +to test, particularly when the dependencies are on interfaces or abstract base classes, +which allow for stub or mock implementations to be used in unit tests. + +DI exists in two major variants: <> and <>. + + +[[beans-constructor-injection]] +== Constructor-based Dependency Injection + +Constructor-based DI is accomplished by the container invoking a constructor with a +number of arguments, each representing a dependency. Calling a `static` factory method +with specific arguments to construct the bean is nearly equivalent, and this discussion +treats arguments to a constructor and to a `static` factory method similarly. The +following example shows a class that can only be dependency-injected with constructor +injection: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleMovieLister { + + // the SimpleMovieLister has a dependency on a MovieFinder + private final MovieFinder movieFinder; + + // a constructor so that the Spring container can inject a MovieFinder + public SimpleMovieLister(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + + // business logic that actually uses the injected MovieFinder is omitted... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // a constructor so that the Spring container can inject a MovieFinder + class SimpleMovieLister(private val movieFinder: MovieFinder) { + // business logic that actually uses the injected MovieFinder is omitted... + } +---- + +Notice that there is nothing special about this class. It is a POJO that +has no dependencies on container specific interfaces, base classes, or annotations. + +[[beans-factory-ctor-arguments-resolution]] +=== Constructor Argument Resolution + +Constructor argument resolution matching occurs by using the argument's type. If no +potential ambiguity exists in the constructor arguments of a bean definition, the +order in which the constructor arguments are defined in a bean definition is the order +in which those arguments are supplied to the appropriate constructor when the bean is +being instantiated. Consider the following class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package x.y; + + public class ThingOne { + + public ThingOne(ThingTwo thingTwo, ThingThree thingThree) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package x.y + + class ThingOne(thingTwo: ThingTwo, thingThree: ThingThree) +---- + +Assuming that the `ThingTwo` and `ThingThree` classes are not related by inheritance, no +potential ambiguity exists. Thus, the following configuration works fine, and you do not +need to specify the constructor argument indexes or types explicitly in the +`` element. + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + +---- + +When another bean is referenced, the type is known, and matching can occur (as was the +case with the preceding example). When a simple type is used, such as +`true`, Spring cannot determine the type of the value, and so cannot match +by type without help. Consider the following class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package examples; + + public class ExampleBean { + + // Number of years to calculate the Ultimate Answer + private final int years; + + // The Answer to Life, the Universe, and Everything + private final String ultimateAnswer; + + public ExampleBean(int years, String ultimateAnswer) { + this.years = years; + this.ultimateAnswer = ultimateAnswer; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package examples + + class ExampleBean( + private val years: Int, // Number of years to calculate the Ultimate Answer + private val ultimateAnswer: String // The Answer to Life, the Universe, and Everything + ) +---- + +.[[beans-factory-ctor-arguments-type]]Constructor argument type matching +-- +In the preceding scenario, the container can use type matching with simple types if +you explicitly specify the type of the constructor argument by using the `type` attribute, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- +-- + +.[[beans-factory-ctor-arguments-index]]Constructor argument index +-- +You can use the `index` attribute to specify explicitly the index of constructor arguments, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- + +In addition to resolving the ambiguity of multiple simple values, specifying an index +resolves ambiguity where a constructor has two arguments of the same type. + +NOTE: The index is 0-based. +-- + +.[[beans-factory-ctor-arguments-name]]Constructor argument name +-- +You can also use the constructor parameter name for value disambiguation, as the following +example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- + +Keep in mind that, to make this work out of the box, your code must be compiled with the +debug flag enabled so that Spring can look up the parameter name from the constructor. +If you cannot or do not want to compile your code with the debug flag, you can use the +https://download.oracle.com/javase/8/docs/api/java/beans/ConstructorProperties.html[@ConstructorProperties] +JDK annotation to explicitly name your constructor arguments. The sample class would +then have to look as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package examples; + + public class ExampleBean { + + // Fields omitted + + @ConstructorProperties({"years", "ultimateAnswer"}) + public ExampleBean(int years, String ultimateAnswer) { + this.years = years; + this.ultimateAnswer = ultimateAnswer; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package examples + + class ExampleBean + @ConstructorProperties("years", "ultimateAnswer") + constructor(val years: Int, val ultimateAnswer: String) +---- +-- + + +[[beans-setter-injection]] +== Setter-based Dependency Injection + +Setter-based DI is accomplished by the container calling setter methods on your +beans after invoking a no-argument constructor or a no-argument `static` factory method to +instantiate your bean. + +The following example shows a class that can only be dependency-injected by using pure +setter injection. This class is conventional Java. It is a POJO that has no dependencies +on container specific interfaces, base classes, or annotations. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleMovieLister { + + // the SimpleMovieLister has a dependency on the MovieFinder + private MovieFinder movieFinder; + + // a setter method so that the Spring container can inject a MovieFinder + public void setMovieFinder(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + + // business logic that actually uses the injected MovieFinder is omitted... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +class SimpleMovieLister { + + // a late-initialized property so that the Spring container can inject a MovieFinder + lateinit var movieFinder: MovieFinder + + // business logic that actually uses the injected MovieFinder is omitted... +} +---- + + +The `ApplicationContext` supports constructor-based and setter-based DI for the beans it +manages. It also supports setter-based DI after some dependencies have already been +injected through the constructor approach. You configure the dependencies in the form of +a `BeanDefinition`, which you use in conjunction with `PropertyEditor` instances to +convert properties from one format to another. However, most Spring users do not work +with these classes directly (that is, programmatically) but rather with XML `bean` +definitions, annotated components (that is, classes annotated with `@Component`, +`@Controller`, and so forth), or `@Bean` methods in Java-based `@Configuration` classes. +These sources are then converted internally into instances of `BeanDefinition` and used to +load an entire Spring IoC container instance. + +[[beans-constructor-vs-setter-injection]] +.Constructor-based or setter-based DI? +**** +Since you can mix constructor-based and setter-based DI, it is a good rule of thumb to +use constructors for mandatory dependencies and setter methods or configuration methods +for optional dependencies. Note that use of the <> +annotation on a setter method can be used to make the property be a required dependency; +however, constructor injection with programmatic validation of arguments is preferable. + +The Spring team generally advocates constructor injection, as it lets you implement +application components as immutable objects and ensures that required dependencies +are not `null`. Furthermore, constructor-injected components are always returned to the client +(calling) code in a fully initialized state. As a side note, a large number of constructor +arguments is a bad code smell, implying that the class likely has too many +responsibilities and should be refactored to better address proper separation of concerns. + +Setter injection should primarily only be used for optional dependencies that can be +assigned reasonable default values within the class. Otherwise, not-null checks must be +performed everywhere the code uses the dependency. One benefit of setter injection is that +setter methods make objects of that class amenable to reconfiguration or re-injection +later. Management through <> is therefore a compelling +use case for setter injection. + +Use the DI style that makes the most sense for a particular class. Sometimes, when dealing +with third-party classes for which you do not have the source, the choice is made for you. +For example, if a third-party class does not expose any setter methods, then constructor +injection may be the only available form of DI. +**** + + +[[beans-dependency-resolution]] +== Dependency Resolution Process + +The container performs bean dependency resolution as follows: + +* The `ApplicationContext` is created and initialized with configuration metadata that + describes all the beans. Configuration metadata can be specified by XML, Java code, or + annotations. +* For each bean, its dependencies are expressed in the form of properties, constructor + arguments, or arguments to the static-factory method (if you use that instead of a + normal constructor). These dependencies are provided to the bean, when the bean is + actually created. +* Each property or constructor argument is an actual definition of the value to set, or + a reference to another bean in the container. +* Each property or constructor argument that is a value is converted from its specified + format to the actual type of that property or constructor argument. By default, Spring + can convert a value supplied in string format to all built-in types, such as `int`, + `long`, `String`, `boolean`, and so forth. + +The Spring container validates the configuration of each bean as the container is created. +However, the bean properties themselves are not set until the bean is actually created. +Beans that are singleton-scoped and set to be pre-instantiated (the default) are created +when the container is created. Scopes are defined in <>. Otherwise, +the bean is created only when it is requested. Creation of a bean potentially causes a +graph of beans to be created, as the bean's dependencies and its dependencies' +dependencies (and so on) are created and assigned. Note that resolution mismatches among +those dependencies may show up late -- that is, on first creation of the affected bean. + +.Circular dependencies +**** +If you use predominantly constructor injection, it is possible to create an unresolvable +circular dependency scenario. + +For example: Class A requires an instance of class B through constructor injection, and +class B requires an instance of class A through constructor injection. If you configure +beans for classes A and B to be injected into each other, the Spring IoC container +detects this circular reference at runtime, and throws a +`BeanCurrentlyInCreationException`. + +One possible solution is to edit the source code of some classes to be configured by +setters rather than constructors. Alternatively, avoid constructor injection and use +setter injection only. In other words, although it is not recommended, you can configure +circular dependencies with setter injection. + +Unlike the typical case (with no circular dependencies), a circular dependency +between bean A and bean B forces one of the beans to be injected into the other prior to +being fully initialized itself (a classic chicken-and-egg scenario). +**** + +You can generally trust Spring to do the right thing. It detects configuration problems, +such as references to non-existent beans and circular dependencies, at container +load-time. Spring sets properties and resolves dependencies as late as possible, when +the bean is actually created. This means that a Spring container that has loaded +correctly can later generate an exception when you request an object if there is a +problem creating that object or one of its dependencies -- for example, the bean throws an +exception as a result of a missing or invalid property. This potentially delayed +visibility of some configuration issues is why `ApplicationContext` implementations by +default pre-instantiate singleton beans. At the cost of some upfront time and memory to +create these beans before they are actually needed, you discover configuration issues +when the `ApplicationContext` is created, not later. You can still override this default +behavior so that singleton beans initialize lazily, rather than being eagerly +pre-instantiated. + +If no circular dependencies exist, when one or more collaborating beans are being +injected into a dependent bean, each collaborating bean is totally configured prior +to being injected into the dependent bean. This means that, if bean A has a dependency on +bean B, the Spring IoC container completely configures bean B prior to invoking the +setter method on bean A. In other words, the bean is instantiated (if it is not a +pre-instantiated singleton), its dependencies are set, and the relevant lifecycle +methods (such as a <> +or the <>) +are invoked. + + +[[beans-some-examples]] +== Examples of Dependency Injection + +The following example uses XML-based configuration metadata for setter-based DI. A small +part of a Spring XML configuration file specifies some bean definitions as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + +---- + +The following example shows the corresponding `ExampleBean` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ExampleBean { + + private AnotherBean beanOne; + + private YetAnotherBean beanTwo; + + private int i; + + public void setBeanOne(AnotherBean beanOne) { + this.beanOne = beanOne; + } + + public void setBeanTwo(YetAnotherBean beanTwo) { + this.beanTwo = beanTwo; + } + + public void setIntegerProperty(int i) { + this.i = i; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +class ExampleBean { + lateinit var beanOne: AnotherBean + lateinit var beanTwo: YetAnotherBean + var i: Int = 0 +} +---- + +In the preceding example, setters are declared to match against the properties specified +in the XML file. The following example uses constructor-based DI: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + +---- + +The following example shows the corresponding `ExampleBean` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ExampleBean { + + private AnotherBean beanOne; + + private YetAnotherBean beanTwo; + + private int i; + + public ExampleBean( + AnotherBean anotherBean, YetAnotherBean yetAnotherBean, int i) { + this.beanOne = anotherBean; + this.beanTwo = yetAnotherBean; + this.i = i; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +class ExampleBean( + private val beanOne: AnotherBean, + private val beanTwo: YetAnotherBean, + private val i: Int) +---- + +The constructor arguments specified in the bean definition are used as arguments to +the constructor of the `ExampleBean`. + +Now consider a variant of this example, where, instead of using a constructor, Spring is +told to call a `static` factory method to return an instance of the object: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + +---- + +The following example shows the corresponding `ExampleBean` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ExampleBean { + + // a private constructor + private ExampleBean(...) { + ... + } + + // a static factory method; the arguments to this method can be + // considered the dependencies of the bean that is returned, + // regardless of how those arguments are actually used. + public static ExampleBean createInstance ( + AnotherBean anotherBean, YetAnotherBean yetAnotherBean, int i) { + + ExampleBean eb = new ExampleBean (...); + // some other operations... + return eb; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ExampleBean private constructor() { + companion object { + // a static factory method; the arguments to this method can be + // considered the dependencies of the bean that is returned, + // regardless of how those arguments are actually used. + @JvmStatic + fun createInstance(anotherBean: AnotherBean, yetAnotherBean: YetAnotherBean, i: Int): ExampleBean { + val eb = ExampleBean (...) + // some other operations... + return eb + } + } + } +---- + +Arguments to the `static` factory method are supplied by `` elements, +exactly the same as if a constructor had actually been used. The type of the class being +returned by the factory method does not have to be of the same type as the class that +contains the `static` factory method (although, in this example, it is). An instance +(non-static) factory method can be used in an essentially identical fashion (aside +from the use of the `factory-bean` attribute instead of the `class` attribute), so we +do not discuss those details here. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc new file mode 100644 index 000000000000..988075e19d04 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc @@ -0,0 +1,40 @@ +[[beans-factory-dependson]] += Using `depends-on` + +If a bean is a dependency of another bean, that usually means that one bean is set as a +property of another. Typically you accomplish this with the <` +element>> in XML-based configuration metadata. However, sometimes dependencies between +beans are less direct. An example is when a static initializer in a class needs to be +triggered, such as for database driver registration. The `depends-on` attribute can +explicitly force one or more beans to be initialized before the bean using this element +is initialized. The following example uses the `depends-on` attribute to express a +dependency on a single bean: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + +---- + +To express a dependency on multiple beans, supply a list of bean names as the value of +the `depends-on` attribute (commas, whitespace, and semicolons are valid +delimiters): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + +NOTE: The `depends-on` attribute can specify both an initialization-time dependency and, +in the case of <> beans only, a corresponding +destruction-time dependency. Dependent beans that define a `depends-on` relationship +with a given bean are destroyed first, prior to the given bean itself being destroyed. +Thus, `depends-on` can also control shutdown order. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc new file mode 100644 index 000000000000..cbb8eeb36111 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc @@ -0,0 +1,42 @@ +[[beans-factory-lazy-init]] += Lazy-initialized Beans + +By default, `ApplicationContext` implementations eagerly create and configure all +<> beans as part of the initialization +process. Generally, this pre-instantiation is desirable, because errors in the +configuration or surrounding environment are discovered immediately, as opposed to hours +or even days later. When this behavior is not desirable, you can prevent +pre-instantiation of a singleton bean by marking the bean definition as being +lazy-initialized. A lazy-initialized bean tells the IoC container to create a bean +instance when it is first requested, rather than at startup. + +In XML, this behavior is controlled by the `lazy-init` attribute on the `` +element, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + +---- + +When the preceding configuration is consumed by an `ApplicationContext`, the `lazy` bean +is not eagerly pre-instantiated when the `ApplicationContext` starts, +whereas the `not.lazy` bean is eagerly pre-instantiated. + +However, when a lazy-initialized bean is a dependency of a singleton bean that is +not lazy-initialized, the `ApplicationContext` creates the lazy-initialized bean at +startup, because it must satisfy the singleton's dependencies. The lazy-initialized bean +is injected into a singleton bean elsewhere that is not lazy-initialized. + +You can also control lazy-initialization at the container level by using the +`default-lazy-init` attribute on the `` element, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc new file mode 100644 index 000000000000..5f97b946fdef --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc @@ -0,0 +1,398 @@ +[[beans-factory-method-injection]] += Method Injection + +In most application scenarios, most beans in the container are +<>. When a singleton bean needs to +collaborate with another singleton bean or a non-singleton bean needs to collaborate +with another non-singleton bean, you typically handle the dependency by defining one +bean as a property of the other. A problem arises when the bean lifecycles are +different. Suppose singleton bean A needs to use non-singleton (prototype) bean B, +perhaps on each method invocation on A. The container creates the singleton bean A only +once, and thus only gets one opportunity to set the properties. The container cannot +provide bean A with a new instance of bean B every time one is needed. + +A solution is to forego some inversion of control. You can <> by implementing the `ApplicationContextAware` interface, +and by <> ask for (a +typically new) bean B instance every time bean A needs it. The following example +shows this approach: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages",fold="none"] +.Java +---- + package fiona.apple; + + // Spring-API imports + import org.springframework.beans.BeansException; + import org.springframework.context.ApplicationContext; + import org.springframework.context.ApplicationContextAware; + + /** + * A class that uses a stateful Command-style class to perform + * some processing. + */ + public class CommandManager implements ApplicationContextAware { + + private ApplicationContext applicationContext; + + public Object process(Map commandState) { + // grab a new instance of the appropriate Command + Command command = createCommand(); + // set the state on the (hopefully brand new) Command instance + command.setState(commandState); + return command.execute(); + } + + protected Command createCommand() { + // notice the Spring API dependency! + return this.applicationContext.getBean("command", Command.class); + } + + public void setApplicationContext( + ApplicationContext applicationContext) throws BeansException { + this.applicationContext = applicationContext; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages",fold="none"] +.Kotlin +---- + package fiona.apple + + // Spring-API imports + import org.springframework.context.ApplicationContext + import org.springframework.context.ApplicationContextAware + + // A class that uses a stateful Command-style class to perform + // some processing. + class CommandManager : ApplicationContextAware { + + private lateinit var applicationContext: ApplicationContext + + fun process(commandState: Map<*, *>): Any { + // grab a new instance of the appropriate Command + val command = createCommand() + // set the state on the (hopefully brand new) Command instance + command.state = commandState + return command.execute() + } + + // notice the Spring API dependency! + protected fun createCommand() = + applicationContext.getBean("command", Command::class.java) + + override fun setApplicationContext(applicationContext: ApplicationContext) { + this.applicationContext = applicationContext + } + } +---- + +The preceding is not desirable, because the business code is aware of and coupled to the +Spring Framework. Method Injection, a somewhat advanced feature of the Spring IoC +container, lets you handle this use case cleanly. + +**** +You can read more about the motivation for Method Injection in +https://spring.io/blog/2004/08/06/method-injection/[this blog entry]. +**** + + + +[[beans-factory-lookup-method-injection]] +== Lookup Method Injection + +Lookup method injection is the ability of the container to override methods on +container-managed beans and return the lookup result for another named bean in the +container. The lookup typically involves a prototype bean, as in the scenario described +in <>. The Spring Framework +implements this method injection by using bytecode generation from the CGLIB library to +dynamically generate a subclass that overrides the method. + +[NOTE] +==== +* For this dynamic subclassing to work, the class that the Spring bean container + subclasses cannot be `final`, and the method to be overridden cannot be `final`, either. +* Unit-testing a class that has an `abstract` method requires you to subclass the class + yourself and to supply a stub implementation of the `abstract` method. +* Concrete methods are also necessary for component scanning, which requires concrete + classes to pick up. +* A further key limitation is that lookup methods do not work with factory methods and + in particular not with `@Bean` methods in configuration classes, since, in that case, + the container is not in charge of creating the instance and therefore cannot create + a runtime-generated subclass on the fly. +==== + +In the case of the `CommandManager` class in the previous code snippet, the +Spring container dynamically overrides the implementation of the `createCommand()` +method. The `CommandManager` class does not have any Spring dependencies, as +the reworked example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages",fold="none"] +.Java +---- + package fiona.apple; + + // no more Spring imports! + + public abstract class CommandManager { + + public Object process(Object commandState) { + // grab a new instance of the appropriate Command interface + Command command = createCommand(); + // set the state on the (hopefully brand new) Command instance + command.setState(commandState); + return command.execute(); + } + + // okay... but where is the implementation of this method? + protected abstract Command createCommand(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages",fold="none"] +.Kotlin +---- + package fiona.apple + + // no more Spring imports! + + abstract class CommandManager { + + fun process(commandState: Any): Any { + // grab a new instance of the appropriate Command interface + val command = createCommand() + // set the state on the (hopefully brand new) Command instance + command.state = commandState + return command.execute() + } + + // okay... but where is the implementation of this method? + protected abstract fun createCommand(): Command + } +---- + +In the client class that contains the method to be injected (the `CommandManager` in this +case), the method to be injected requires a signature of the following form: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + [abstract] theMethodName(no-arguments); +---- + +If the method is `abstract`, the dynamically-generated subclass implements the method. +Otherwise, the dynamically-generated subclass overrides the concrete method defined in +the original class. Consider the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + +---- + +The bean identified as `commandManager` calls its own `createCommand()` method +whenever it needs a new instance of the `myCommand` bean. You must be careful to deploy +the `myCommand` bean as a prototype if that is actually what is needed. If it is +a <>, the same instance of the `myCommand` +bean is returned each time. + +Alternatively, within the annotation-based component model, you can declare a lookup +method through the `@Lookup` annotation, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public abstract class CommandManager { + + public Object process(Object commandState) { + Command command = createCommand(); + command.setState(commandState); + return command.execute(); + } + + @Lookup("myCommand") + protected abstract Command createCommand(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + abstract class CommandManager { + + fun process(commandState: Any): Any { + val command = createCommand() + command.state = commandState + return command.execute() + } + + @Lookup("myCommand") + protected abstract fun createCommand(): Command + } +---- + +Or, more idiomatically, you can rely on the target bean getting resolved against the +declared return type of the lookup method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public abstract class CommandManager { + + public Object process(Object commandState) { + Command command = createCommand(); + command.setState(commandState); + return command.execute(); + } + + @Lookup + protected abstract Command createCommand(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + abstract class CommandManager { + + fun process(commandState: Any): Any { + val command = createCommand() + command.state = commandState + return command.execute() + } + + @Lookup + protected abstract fun createCommand(): Command + } +---- + +Note that you should typically declare such annotated lookup methods with a concrete +stub implementation, in order for them to be compatible with Spring's component +scanning rules where abstract classes get ignored by default. This limitation does not +apply to explicitly registered or explicitly imported bean classes. + +[TIP] +==== +Another way of accessing differently scoped target beans is an `ObjectFactory`/ +`Provider` injection point. See <>. + +You may also find the `ServiceLocatorFactoryBean` (in the +`org.springframework.beans.factory.config` package) to be useful. +==== + + + +[[beans-factory-arbitrary-method-replacement]] +== Arbitrary Method Replacement + +A less useful form of method injection than lookup method injection is the ability to +replace arbitrary methods in a managed bean with another method implementation. You +can safely skip the rest of this section until you actually need this functionality. + +With XML-based configuration metadata, you can use the `replaced-method` element to +replace an existing method implementation with another, for a deployed bean. Consider +the following class, which has a method called `computeValue` that we want to override: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MyValueCalculator { + + public String computeValue(String input) { + // some real code... + } + + // some other methods... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyValueCalculator { + + fun computeValue(input: String): String { + // some real code... + } + + // some other methods... + } +---- + +A class that implements the `org.springframework.beans.factory.support.MethodReplacer` +interface provides the new method definition, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + /** + * meant to be used to override the existing computeValue(String) + * implementation in MyValueCalculator + */ + public class ReplacementComputeValue implements MethodReplacer { + + public Object reimplement(Object o, Method m, Object[] args) throws Throwable { + // get the input value, work with it, and return a computed result + String input = (String) args[0]; + ... + return ...; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + /** + * meant to be used to override the existing computeValue(String) + * implementation in MyValueCalculator + */ + class ReplacementComputeValue : MethodReplacer { + + override fun reimplement(obj: Any, method: Method, args: Array): Any { + // get the input value, work with it, and return a computed result + val input = args[0] as String; + ... + return ...; + } + } +---- + + + +The bean definition to deploy the original class and specify the method override would +resemble the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + String + + + + +---- + +You can use one or more `` elements within the `` +element to indicate the method signature of the method being overridden. The signature +for the arguments is necessary only if the method is overloaded and multiple variants +exist within the class. For convenience, the type string for an argument may be a +substring of the fully qualified type name. For example, the following all match +`java.lang.String`: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + java.lang.String + String + Str +---- + +Because the number of arguments is often enough to distinguish between each possible +choice, this shortcut can save a lot of typing, by letting you type only the +shortest string that matches an argument type. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc new file mode 100644 index 000000000000..0453dc43ca9b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc @@ -0,0 +1,608 @@ +[[beans-factory-properties-detailed]] += Dependencies and Configuration in Detail + +As mentioned in the <>, you can define bean +properties and constructor arguments as references to other managed beans (collaborators) +or as values defined inline. Spring's XML-based configuration metadata supports +sub-element types within its `` and `` elements for this +purpose. + + +[[beans-value-element]] +== Straight Values (Primitives, Strings, and so on) + +The `value` attribute of the `` element specifies a property or constructor +argument as a human-readable string representation. Spring's +<> is used to convert these +values from a `String` to the actual type of the property or argument. +The following example shows various values being set: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +The following example uses the <> for even more succinct +XML configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + +---- + +The preceding XML is more succinct. However, typos are discovered at runtime rather than +design time, unless you use an IDE (such as https://www.jetbrains.com/idea/[IntelliJ +IDEA] or the https://spring.io/tools[Spring Tools for Eclipse]) +that supports automatic property completion when you create bean definitions. Such IDE +assistance is highly recommended. + +You can also configure a `java.util.Properties` instance, as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + jdbc.driver.className=com.mysql.jdbc.Driver + jdbc.url=jdbc:mysql://localhost:3306/mydb + + + +---- + +The Spring container converts the text inside the `` element into a +`java.util.Properties` instance by using the JavaBeans `PropertyEditor` mechanism. This +is a nice shortcut, and is one of a few places where the Spring team do favor the use of +the nested `` element over the `value` attribute style. + +[[beans-idref-element]] +=== The `idref` element + +The `idref` element is simply an error-proof way to pass the `id` (a string value - not +a reference) of another bean in the container to a `` or `` +element. The following example shows how to use it: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +The preceding bean definition snippet is exactly equivalent (at runtime) to the +following snippet: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + +---- + +The first form is preferable to the second, because using the `idref` tag lets the +container validate at deployment time that the referenced, named bean actually +exists. In the second variation, no validation is performed on the value that is passed +to the `targetName` property of the `client` bean. Typos are only discovered (with most +likely fatal results) when the `client` bean is actually instantiated. If the `client` +bean is a <> bean, this typo and the resulting exception +may only be discovered long after the container is deployed. + +NOTE: The `local` attribute on the `idref` element is no longer supported in the 4.0 beans +XSD, since it does not provide value over a regular `bean` reference any more. Change +your existing `idref local` references to `idref bean` when upgrading to the 4.0 schema. + +A common place (at least in versions earlier than Spring 2.0) where the `` element +brings value is in the configuration of <> in a +`ProxyFactoryBean` bean definition. Using `` elements when you specify the +interceptor names prevents you from misspelling an interceptor ID. + + +[[beans-ref-element]] +== References to Other Beans (Collaborators) + +The `ref` element is the final element inside a `` or `` +definition element. Here, you set the value of the specified property of a bean to be a +reference to another bean (a collaborator) managed by the container. The referenced bean +is a dependency of the bean whose property is to be set, and it is initialized on demand +as needed before the property is set. (If the collaborator is a singleton bean, it may +already be initialized by the container.) All references are ultimately a reference to +another object. Scoping and validation depend on whether you specify the ID or name of the +other object through the `bean` or `parent` attribute. + +Specifying the target bean through the `bean` attribute of the `` tag is the most +general form and allows creation of a reference to any bean in the same container or +parent container, regardless of whether it is in the same XML file. The value of the +`bean` attribute may be the same as the `id` attribute of the target bean or be the same +as one of the values in the `name` attribute of the target bean. The following example +shows how to use a `ref` element: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +Specifying the target bean through the `parent` attribute creates a reference to a bean +that is in a parent container of the current container. The value of the `parent` +attribute may be the same as either the `id` attribute of the target bean or one of the +values in the `name` attribute of the target bean. The target bean must be in a +parent container of the current one. You should use this bean reference variant mainly +when you have a hierarchy of containers and you want to wrap an existing bean in a parent +container with a proxy that has the same name as the parent bean. The following pair of +listings shows how to use the `parent` attribute: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + class="org.springframework.aop.framework.ProxyFactoryBean"> + + + + + +---- + +NOTE: The `local` attribute on the `ref` element is no longer supported in the 4.0 beans +XSD, since it does not provide value over a regular `bean` reference any more. Change +your existing `ref local` references to `ref bean` when upgrading to the 4.0 schema. + + +[[beans-inner-beans]] +== Inner Beans + +A `` element inside the `` or `` elements defines an +inner bean, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + +---- + +An inner bean definition does not require a defined ID or name. If specified, the container +does not use such a value as an identifier. The container also ignores the `scope` flag on +creation, because inner beans are always anonymous and are always created with the outer +bean. It is not possible to access inner beans independently or to inject them into +collaborating beans other than into the enclosing bean. + +As a corner case, it is possible to receive destruction callbacks from a custom scope -- +for example, for a request-scoped inner bean contained within a singleton bean. The creation +of the inner bean instance is tied to its containing bean, but destruction callbacks let it +participate in the request scope's lifecycle. This is not a common scenario. Inner beans +typically simply share their containing bean's scope. + + +[[beans-collection-elements]] +== Collections + +The ``, ``, ``, and `` elements set the properties +and arguments of the Java `Collection` types `List`, `Set`, `Map`, and `Properties`, +respectively. The following example shows how to use them: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + administrator@example.org + support@example.org + development@example.org + + + + + + a list element followed by a reference + + + + + + + + + + + + + + just some string + + + + +---- + +The value of a map key or value, or a set value, can also be any of the +following elements: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + bean | ref | idref | list | set | map | props | value | null +---- + +[[beans-collection-elements-merging]] +=== Collection Merging + +The Spring container also supports merging collections. An application +developer can define a parent ``, ``, `` or `` element +and have child ``, ``, `` or `` elements inherit and +override values from the parent collection. That is, the child collection's values are +the result of merging the elements of the parent and child collections, with the child's +collection elements overriding values specified in the parent collection. + +This section on merging discusses the parent-child bean mechanism. Readers unfamiliar +with parent and child bean definitions may wish to read the +<> before continuing. + +The following example demonstrates collection merging: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + administrator@example.com + support@example.com + + + + + + + + sales@example.com + support@example.co.uk + + + + +---- + +Notice the use of the `merge=true` attribute on the `` element of the +`adminEmails` property of the `child` bean definition. When the `child` bean is resolved +and instantiated by the container, the resulting instance has an `adminEmails` +`Properties` collection that contains the result of merging the child's +`adminEmails` collection with the parent's `adminEmails` collection. The following listing +shows the result: + +[literal,subs="verbatim,quotes"] +---- +administrator=administrator@example.com +sales=sales@example.com +support=support@example.co.uk +---- + +The child `Properties` collection's value set inherits all property elements from the +parent ``, and the child's value for the `support` value overrides the value in +the parent collection. + +This merging behavior applies similarly to the ``, ``, and `` +collection types. In the specific case of the `` element, the semantics +associated with the `List` collection type (that is, the notion of an `ordered` +collection of values) is maintained. The parent's values precede all of the child list's +values. In the case of the `Map`, `Set`, and `Properties` collection types, no ordering +exists. Hence, no ordering semantics are in effect for the collection types that underlie +the associated `Map`, `Set`, and `Properties` implementation types that the container +uses internally. + +[[beans-collection-merge-limitations]] +=== Limitations of Collection Merging + +You cannot merge different collection types (such as a `Map` and a `List`). If you +do attempt to do so, an appropriate `Exception` is thrown. The `merge` attribute must be +specified on the lower, inherited, child definition. Specifying the `merge` attribute on +a parent collection definition is redundant and does not result in the desired merging. + +[[beans-collection-elements-strongly-typed]] +=== Strongly-typed collection + +Thanks to Java's support for generic types, you can use strongly typed collections. +That is, it is possible to declare a `Collection` type such that it can only contain +(for example) `String` elements. If you use Spring to dependency-inject a +strongly-typed `Collection` into a bean, you can take advantage of Spring's +type-conversion support such that the elements of your strongly-typed `Collection` +instances are converted to the appropriate type prior to being added to the `Collection`. +The following Java class and bean definition show how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SomeClass { + + private Map accounts; + + public void setAccounts(Map accounts) { + this.accounts = accounts; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +class SomeClass { + lateinit var accounts: Map +} +---- + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + +---- + +When the `accounts` property of the `something` bean is prepared for injection, the generics +information about the element type of the strongly-typed `Map` is +available by reflection. Thus, Spring's type conversion infrastructure recognizes the +various value elements as being of type `Float`, and the string values (`9.99`, `2.75`, and +`3.99`) are converted into an actual `Float` type. + + +[[beans-null-element]] +== Null and Empty String Values + +Spring treats empty arguments for properties and the like as empty `Strings`. The +following XML-based configuration metadata snippet sets the `email` property to the empty +`String` value (""). + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +The preceding example is equivalent to the following Java code: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + exampleBean.setEmail(""); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + exampleBean.email = "" +---- + + +The `` element handles `null` values. The following listing shows an example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + +---- + +The preceding configuration is equivalent to the following Java code: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + exampleBean.setEmail(null); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + exampleBean.email = null +---- + + +[[beans-p-namespace]] +== XML Shortcut with the p-namespace + +The p-namespace lets you use the `bean` element's attributes (instead of nested +`` elements) to describe your property values collaborating beans, or both. + +Spring supports extensible configuration formats <>, +which are based on an XML Schema definition. The `beans` configuration format discussed in +this chapter is defined in an XML Schema document. However, the p-namespace is not defined +in an XSD file and exists only in the core of Spring. + +The following example shows two XML snippets (the first uses +standard XML format and the second uses the p-namespace) that resolve to the same result: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + +---- + +The example shows an attribute in the p-namespace called `email` in the bean definition. +This tells Spring to include a property declaration. As previously mentioned, the +p-namespace does not have a schema definition, so you can set the name of the attribute +to the property name. + +This next example includes two more bean definitions that both have a reference to +another bean: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + +---- + +This example includes not only a property value using the p-namespace +but also uses a special format to declare property references. Whereas the first bean +definition uses `` to create a reference from bean +`john` to bean `jane`, the second bean definition uses `p:spouse-ref="jane"` as an +attribute to do the exact same thing. In this case, `spouse` is the property name, +whereas the `-ref` part indicates that this is not a straight value but rather a +reference to another bean. + +NOTE: The p-namespace is not as flexible as the standard XML format. For example, the format +for declaring property references clashes with properties that end in `Ref`, whereas the +standard XML format does not. We recommend that you choose your approach carefully and +communicate this to your team members to avoid producing XML documents that use all +three approaches at the same time. + + +[[beans-c-namespace]] +== XML Shortcut with the c-namespace + +Similar to the <>, the c-namespace, introduced in Spring +3.1, allows inlined attributes for configuring the constructor arguments rather +then nested `constructor-arg` elements. + +The following example uses the `c:` namespace to do the same thing as the from +<>: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + +---- + +The `c:` namespace uses the same conventions as the `p:` one (a trailing `-ref` for +bean references) for setting the constructor arguments by their names. Similarly, +it needs to be declared in the XML file even though it is not defined in an XSD schema +(it exists inside the Spring core). + +For the rare cases where the constructor argument names are not available (usually if +the bytecode was compiled without debugging information), you can use fallback to the +argument indexes, as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + +---- + +NOTE: Due to the XML grammar, the index notation requires the presence of the leading `_`, +as XML attribute names cannot start with a number (even though some IDEs allow it). +A corresponding index notation is also available for `` elements but +not commonly used since the plain order of declaration is usually sufficient there. + +In practice, the constructor resolution +<> is quite efficient in matching +arguments, so unless you really need to, we recommend using the name notation +throughout your configuration. + + +[[beans-compound-property-names]] +== Compound Property Names + +You can use compound or nested property names when you set bean properties, as long as +all components of the path except the final property name are not `null`. Consider the +following bean definition: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +The `something` bean has a `fred` property, which has a `bob` property, which has a `sammy` +property, and that final `sammy` property is being set to a value of `123`. In order for +this to work, the `fred` property of `something` and the `bob` property of `fred` must not +be `null` after the bean is constructed. Otherwise, a `NullPointerException` is thrown. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/environment.adoc b/framework-docs/modules/ROOT/pages/core/beans/environment.adoc new file mode 100644 index 000000000000..9c51906bdac9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/environment.adoc @@ -0,0 +1,729 @@ +[[beans-environment]] += Environment Abstraction + +The {api-spring-framework}/core/env/Environment.html[`Environment`] interface +is an abstraction integrated in the container that models two key +aspects of the application environment: <> +and <>. + +A profile is a named, logical group of bean definitions to be registered with the +container only if the given profile is active. Beans may be assigned to a profile +whether defined in XML or with annotations. The role of the `Environment` object with +relation to profiles is in determining which profiles (if any) are currently active, +and which profiles (if any) should be active by default. + +Properties play an important role in almost all applications and may originate from +a variety of sources: properties files, JVM system properties, system environment +variables, JNDI, servlet context parameters, ad-hoc `Properties` objects, `Map` objects, and so +on. The role of the `Environment` object with relation to properties is to provide the +user with a convenient service interface for configuring property sources and resolving +properties from them. + + + +[[beans-definition-profiles]] +== Bean Definition Profiles + +Bean definition profiles provide a mechanism in the core container that allows for +registration of different beans in different environments. The word, "`environment,`" +can mean different things to different users, and this feature can help with many +use cases, including: + +* Working against an in-memory datasource in development versus looking up that same +datasource from JNDI when in QA or production. +* Registering monitoring infrastructure only when deploying an application into a +performance environment. +* Registering customized implementations of beans for customer A versus customer +B deployments. + +Consider the first use case in a practical application that requires a +`DataSource`. In a test environment, the configuration might resemble the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Bean + public DataSource dataSource() { + return new EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("my-schema.sql") + .addScript("my-test-data.sql") + .build(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Bean + fun dataSource(): DataSource { + return EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("my-schema.sql") + .addScript("my-test-data.sql") + .build() + } +---- + +Now consider how this application can be deployed into a QA or production +environment, assuming that the datasource for the application is registered +with the production application server's JNDI directory. Our `dataSource` bean +now looks like the following listing: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Bean(destroyMethod = "") + public DataSource dataSource() throws Exception { + Context ctx = new InitialContext(); + return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource"); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Bean(destroyMethod = "") + fun dataSource(): DataSource { + val ctx = InitialContext() + return ctx.lookup("java:comp/env/jdbc/datasource") as DataSource + } +---- + +The problem is how to switch between using these two variations based on the +current environment. Over time, Spring users have devised a number of ways to +get this done, usually relying on a combination of system environment variables +and XML `` statements containing pass:q[`${placeholder}`] tokens that resolve +to the correct configuration file path depending on the value of an environment +variable. Bean definition profiles is a core container feature that provides a +solution to this problem. + +If we generalize the use case shown in the preceding example of environment-specific bean +definitions, we end up with the need to register certain bean definitions in +certain contexts but not in others. You could say that you want to register a +certain profile of bean definitions in situation A and a different profile in +situation B. We start by updating our configuration to reflect this need. + + +[[beans-definition-profiles-java]] +=== Using `@Profile` + +The {api-spring-framework}/context/annotation/Profile.html[`@Profile`] +annotation lets you indicate that a component is eligible for registration +when one or more specified profiles are active. Using our preceding example, we +can rewrite the `dataSource` configuration as follows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @Profile("development") + public class StandaloneDataConfig { + + @Bean + public DataSource dataSource() { + return new EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .addScript("classpath:com/bank/config/sql/test-data.sql") + .build(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @Profile("development") + class StandaloneDataConfig { + + @Bean + fun dataSource(): DataSource { + return EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .addScript("classpath:com/bank/config/sql/test-data.sql") + .build() + } + } +---- +-- + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @Profile("production") + public class JndiDataConfig { + + @Bean(destroyMethod = "") // <1> + public DataSource dataSource() throws Exception { + Context ctx = new InitialContext(); + return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource"); + } + } +---- +<1> `@Bean(destroyMethod = "")` disables default destroy method inference. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @Profile("production") + class JndiDataConfig { + + @Bean(destroyMethod = "") // <1> + fun dataSource(): DataSource { + val ctx = InitialContext() + return ctx.lookup("java:comp/env/jdbc/datasource") as DataSource + } + } +---- +<1> `@Bean(destroyMethod = "")` disables default destroy method inference. +-- + +NOTE: As mentioned earlier, with `@Bean` methods, you typically choose to use programmatic +JNDI lookups, by using either Spring's `JndiTemplate`/`JndiLocatorDelegate` helpers or the +straight JNDI `InitialContext` usage shown earlier but not the `JndiObjectFactoryBean` +variant, which would force you to declare the return type as the `FactoryBean` type. + +The profile string may contain a simple profile name (for example, `production`) or a +profile expression. A profile expression allows for more complicated profile logic to be +expressed (for example, `production & us-east`). The following operators are supported in +profile expressions: + +* `!`: A logical `NOT` of the profile +* `&`: A logical `AND` of the profiles +* `|`: A logical `OR` of the profiles + +NOTE: You cannot mix the `&` and `|` operators without using parentheses. For example, +`production & us-east | eu-central` is not a valid expression. It must be expressed as +`production & (us-east | eu-central)`. + +You can use `@Profile` as a <> for the purpose +of creating a custom composed annotation. The following example defines a custom +`@Production` annotation that you can use as a drop-in replacement for +`@Profile("production")`: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target(ElementType.TYPE) + @Retention(RetentionPolicy.RUNTIME) + @Profile("production") + public @interface Production { + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.CLASS) + @Retention(AnnotationRetention.RUNTIME) + @Profile("production") + annotation class Production +---- +-- + +TIP: If a `@Configuration` class is marked with `@Profile`, all of the `@Bean` methods and +`@Import` annotations associated with that class are bypassed unless one or more of +the specified profiles are active. If a `@Component` or `@Configuration` class is marked +with `@Profile({"p1", "p2"})`, that class is not registered or processed unless +profiles 'p1' or 'p2' have been activated. If a given profile is prefixed with the +NOT operator (`!`), the annotated element is registered only if the profile is not +active. For example, given `@Profile({"p1", "!p2"})`, registration will occur if profile +'p1' is active or if profile 'p2' is not active. + +`@Profile` can also be declared at the method level to include only one particular bean +of a configuration class (for example, for alternative variants of a particular bean), as +the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean("dataSource") + @Profile("development") // <1> + public DataSource standaloneDataSource() { + return new EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .addScript("classpath:com/bank/config/sql/test-data.sql") + .build(); + } + + @Bean("dataSource") + @Profile("production") // <2> + public DataSource jndiDataSource() throws Exception { + Context ctx = new InitialContext(); + return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource"); + } + } +---- +<1> The `standaloneDataSource` method is available only in the `development` profile. +<2> The `jndiDataSource` method is available only in the `production` profile. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean("dataSource") + @Profile("development") // <1> + fun standaloneDataSource(): DataSource { + return EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .addScript("classpath:com/bank/config/sql/test-data.sql") + .build() + } + + @Bean("dataSource") + @Profile("production") // <2> + fun jndiDataSource() = + InitialContext().lookup("java:comp/env/jdbc/datasource") as DataSource + } +---- +<1> The `standaloneDataSource` method is available only in the `development` profile. +<2> The `jndiDataSource` method is available only in the `production` profile. +-- + +[NOTE] +==== +With `@Profile` on `@Bean` methods, a special scenario may apply: In the case of +overloaded `@Bean` methods of the same Java method name (analogous to constructor +overloading), a `@Profile` condition needs to be consistently declared on all +overloaded methods. If the conditions are inconsistent, only the condition on the +first declaration among the overloaded methods matters. Therefore, `@Profile` can +not be used to select an overloaded method with a particular argument signature over +another. Resolution between all factory methods for the same bean follows Spring's +constructor resolution algorithm at creation time. + +If you want to define alternative beans with different profile conditions, +use distinct Java method names that point to the same bean name by using the `@Bean` name +attribute, as shown in the preceding example. If the argument signatures are all +the same (for example, all of the variants have no-arg factory methods), this is the only +way to represent such an arrangement in a valid Java class in the first place +(since there can only be one method of a particular name and argument signature). +==== + + +[[beans-definition-profiles-xml]] +=== XML Bean Definition Profiles + +The XML counterpart is the `profile` attribute of the `` element. Our preceding sample +configuration can be rewritten in two XML files, as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- + +It is also possible to avoid that split and nest `` elements within the same file, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + +---- + +The `spring-bean.xsd` has been constrained to allow such elements only as the +last ones in the file. This should help provide flexibility without incurring +clutter in the XML files. + +[NOTE] +===== +The XML counterpart does not support the profile expressions described earlier. It is possible, +however, to negate a profile by using the `!` operator. It is also possible to apply a logical +"`and`" by nesting the profiles, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + +---- + +In the preceding example, the `dataSource` bean is exposed if both the `production` and +`us-east` profiles are active. +===== + + +[[beans-definition-profiles-enable]] +=== Activating a Profile + +Now that we have updated our configuration, we still need to instruct Spring which +profile is active. If we started our sample application right now, we would see +a `NoSuchBeanDefinitionException` thrown, because the container could not find +the Spring bean named `dataSource`. + +Activating a profile can be done in several ways, but the most straightforward is to do +it programmatically against the `Environment` API which is available through an +`ApplicationContext`. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); + ctx.getEnvironment().setActiveProfiles("development"); + ctx.register(SomeConfig.class, StandaloneDataConfig.class, JndiDataConfig.class); + ctx.refresh(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val ctx = AnnotationConfigApplicationContext().apply { + environment.setActiveProfiles("development") + register(SomeConfig::class.java, StandaloneDataConfig::class.java, JndiDataConfig::class.java) + refresh() + } +---- + +In addition, you can also declaratively activate profiles through the +`spring.profiles.active` property, which may be specified through system environment +variables, JVM system properties, servlet context parameters in `web.xml`, or even as an +entry in JNDI (see <>). In integration tests, active +profiles can be declared by using the `@ActiveProfiles` annotation in the `spring-test` +module (see <>). + +Note that profiles are not an "`either-or`" proposition. You can activate multiple +profiles at once. Programmatically, you can provide multiple profile names to the +`setActiveProfiles()` method, which accepts `String...` varargs. The following example +activates multiple profiles: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ctx.getEnvironment().setActiveProfiles("profile1", "profile2"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + ctx.getEnvironment().setActiveProfiles("profile1", "profile2") +---- + +Declaratively, `spring.profiles.active` may accept a comma-separated list of profile names, +as the following example shows: + +[literal,indent=0,subs="verbatim,quotes"] +---- + -Dspring.profiles.active="profile1,profile2" +---- + + +[[beans-definition-profiles-default]] +=== Default Profile + +The default profile represents the profile that is enabled by default. Consider the +following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @Profile("default") + public class DefaultDataConfig { + + @Bean + public DataSource dataSource() { + return new EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .build(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @Profile("default") + class DefaultDataConfig { + + @Bean + fun dataSource(): DataSource { + return EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .build() + } + } +---- + +If no profile is active, the `dataSource` is created. You can see this +as a way to provide a default definition for one or more beans. If any +profile is enabled, the default profile does not apply. + +You can change the name of the default profile by using `setDefaultProfiles()` on +the `Environment` or, declaratively, by using the `spring.profiles.default` property. + + + +[[beans-property-source-abstraction]] +== `PropertySource` Abstraction + +Spring's `Environment` abstraction provides search operations over a configurable +hierarchy of property sources. Consider the following listing: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ApplicationContext ctx = new GenericApplicationContext(); + Environment env = ctx.getEnvironment(); + boolean containsMyProperty = env.containsProperty("my-property"); + System.out.println("Does my environment contain the 'my-property' property? " + containsMyProperty); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val ctx = GenericApplicationContext() + val env = ctx.environment + val containsMyProperty = env.containsProperty("my-property") + println("Does my environment contain the 'my-property' property? $containsMyProperty") +---- + +In the preceding snippet, we see a high-level way of asking Spring whether the `my-property` property is +defined for the current environment. To answer this question, the `Environment` object performs +a search over a set of {api-spring-framework}/core/env/PropertySource.html[`PropertySource`] +objects. A `PropertySource` is a simple abstraction over any source of key-value pairs, and +Spring's {api-spring-framework}/core/env/StandardEnvironment.html[`StandardEnvironment`] +is configured with two PropertySource objects -- one representing the set of JVM system properties +(`System.getProperties()`) and one representing the set of system environment variables +(`System.getenv()`). + +NOTE: These default property sources are present for `StandardEnvironment`, for use in standalone +applications. {api-spring-framework}/web/context/support/StandardServletEnvironment.html[`StandardServletEnvironment`] +is populated with additional default property sources including servlet config, servlet +context parameters, and a {api-spring-framework}/jndi/JndiPropertySource.html[`JndiPropertySource`] +if JNDI is available. + +Concretely, when you use the `StandardEnvironment`, the call to `env.containsProperty("my-property")` +returns true if a `my-property` system property or `my-property` environment variable is present at +runtime. + +[TIP] +==== +The search performed is hierarchical. By default, system properties have precedence over +environment variables. So, if the `my-property` property happens to be set in both places during +a call to `env.getProperty("my-property")`, the system property value "`wins`" and is returned. +Note that property values are not merged +but rather completely overridden by a preceding entry. + +For a common `StandardServletEnvironment`, the full hierarchy is as follows, with the +highest-precedence entries at the top: + +. ServletConfig parameters (if applicable -- for example, in case of a `DispatcherServlet` context) +. ServletContext parameters (web.xml context-param entries) +. JNDI environment variables (`java:comp/env/` entries) +. JVM system properties (`-D` command-line arguments) +. JVM system environment (operating system environment variables) +==== + +Most importantly, the entire mechanism is configurable. Perhaps you have a custom source +of properties that you want to integrate into this search. To do so, implement +and instantiate your own `PropertySource` and add it to the set of `PropertySources` for the +current `Environment`. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- +ConfigurableApplicationContext ctx = new GenericApplicationContext(); +MutablePropertySources sources = ctx.getEnvironment().getPropertySources(); +sources.addFirst(new MyPropertySource()); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val ctx = GenericApplicationContext() + val sources = ctx.environment.propertySources + sources.addFirst(MyPropertySource()) +---- + +In the preceding code, `MyPropertySource` has been added with highest precedence in the +search. If it contains a `my-property` property, the property is detected and returned, in favor of +any `my-property` property in any other `PropertySource`. The +{api-spring-framework}/core/env/MutablePropertySources.html[`MutablePropertySources`] +API exposes a number of methods that allow for precise manipulation of the set of +property sources. + + + +[[beans-using-propertysource]] +== Using `@PropertySource` + +The {api-spring-framework}/context/annotation/PropertySource.html[`@PropertySource`] +annotation provides a convenient and declarative mechanism for adding a `PropertySource` +to Spring's `Environment`. + +Given a file called `app.properties` that contains the key-value pair `testbean.name=myTestBean`, +the following `@Configuration` class uses `@PropertySource` in such a way that +a call to `testBean.getName()` returns `myTestBean`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @PropertySource("classpath:/com/myco/app.properties") + public class AppConfig { + + @Autowired + Environment env; + + @Bean + public TestBean testBean() { + TestBean testBean = new TestBean(); + testBean.setName(env.getProperty("testbean.name")); + return testBean; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @PropertySource("classpath:/com/myco/app.properties") + class AppConfig { + + @Autowired + private lateinit var env: Environment + + @Bean + fun testBean() = TestBean().apply { + name = env.getProperty("testbean.name")!! + } + } +---- + +Any `${...}` placeholders present in a `@PropertySource` resource location are +resolved against the set of property sources already registered against the +environment, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @PropertySource("classpath:/com/${my.placeholder:default/path}/app.properties") + public class AppConfig { + + @Autowired + Environment env; + + @Bean + public TestBean testBean() { + TestBean testBean = new TestBean(); + testBean.setName(env.getProperty("testbean.name")); + return testBean; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @PropertySource("classpath:/com/\${my.placeholder:default/path}/app.properties") + class AppConfig { + + @Autowired + private lateinit var env: Environment + + @Bean + fun testBean() = TestBean().apply { + name = env.getProperty("testbean.name")!! + } + } +---- + +Assuming that `my.placeholder` is present in one of the property sources already +registered (for example, system properties or environment variables), the placeholder is +resolved to the corresponding value. If not, then `default/path` is used +as a default. If no default is specified and a property cannot be resolved, an +`IllegalArgumentException` is thrown. + +NOTE: The `@PropertySource` annotation is repeatable, according to Java 8 conventions. +However, all such `@PropertySource` annotations need to be declared at the same +level, either directly on the configuration class or as meta-annotations within the +same custom annotation. Mixing direct annotations and meta-annotations is not +recommended, since direct annotations effectively override meta-annotations. + + + +[[beans-placeholder-resolution-in-statements]] +== Placeholder Resolution in Statements + +Historically, the value of placeholders in elements could be resolved only against +JVM system properties or environment variables. This is no longer the case. Because +the `Environment` abstraction is integrated throughout the container, it is easy to +route resolution of placeholders through it. This means that you may configure the +resolution process in any way you like. You can change the precedence of searching through +system properties and environment variables or remove them entirely. You can also add your +own property sources to the mix, as appropriate. + +Concretely, the following statement works regardless of where the `customer` +property is defined, as long as it is available in the `Environment`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc new file mode 100644 index 000000000000..51a30ee61062 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc @@ -0,0 +1,481 @@ +[[beans-factory-extension]] += Container Extension Points + +Typically, an application developer does not need to subclass `ApplicationContext` +implementation classes. Instead, the Spring IoC container can be extended by plugging in +implementations of special integration interfaces. The next few sections describe these +integration interfaces. + + + +[[beans-factory-extension-bpp]] +== Customizing Beans by Using a `BeanPostProcessor` + +The `BeanPostProcessor` interface defines callback methods that you can implement to +provide your own (or override the container's default) instantiation logic, dependency +resolution logic, and so forth. If you want to implement some custom logic after the +Spring container finishes instantiating, configuring, and initializing a bean, you can +plug in one or more custom `BeanPostProcessor` implementations. + +You can configure multiple `BeanPostProcessor` instances, and you can control the order +in which these `BeanPostProcessor` instances run by setting the `order` property. +You can set this property only if the `BeanPostProcessor` implements the `Ordered` +interface. If you write your own `BeanPostProcessor`, you should consider implementing +the `Ordered` interface, too. For further details, see the javadoc of the +{api-spring-framework}/beans/factory/config/BeanPostProcessor.html[`BeanPostProcessor`] +and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces. See also the note +on <>. + +[NOTE] +==== +`BeanPostProcessor` instances operate on bean (or object) instances. That is, +the Spring IoC container instantiates a bean instance and then `BeanPostProcessor` +instances do their work. + +`BeanPostProcessor` instances are scoped per-container. This is relevant only if you +use container hierarchies. If you define a `BeanPostProcessor` in one container, +it post-processes only the beans in that container. In other words, beans that are +defined in one container are not post-processed by a `BeanPostProcessor` defined in +another container, even if both containers are part of the same hierarchy. + +To change the actual bean definition (that is, the blueprint that defines the bean), +you instead need to use a `BeanFactoryPostProcessor`, as described in +<>. +==== + +The `org.springframework.beans.factory.config.BeanPostProcessor` interface consists of +exactly two callback methods. When such a class is registered as a post-processor with +the container, for each bean instance that is created by the container, the +post-processor gets a callback from the container both before container +initialization methods (such as `InitializingBean.afterPropertiesSet()` or any +declared `init` method) are called, and after any bean initialization callbacks. +The post-processor can take any action with the bean instance, including ignoring the +callback completely. A bean post-processor typically checks for callback interfaces, +or it may wrap a bean with a proxy. Some Spring AOP infrastructure classes are +implemented as bean post-processors in order to provide proxy-wrapping logic. + +An `ApplicationContext` automatically detects any beans that are defined in the +configuration metadata that implement the `BeanPostProcessor` interface. The +`ApplicationContext` registers these beans as post-processors so that they can be called +later, upon bean creation. Bean post-processors can be deployed in the container in the +same fashion as any other beans. + +Note that, when declaring a `BeanPostProcessor` by using an `@Bean` factory method on a +configuration class, the return type of the factory method should be the implementation +class itself or at least the `org.springframework.beans.factory.config.BeanPostProcessor` +interface, clearly indicating the post-processor nature of that bean. Otherwise, the +`ApplicationContext` cannot autodetect it by type before fully creating it. +Since a `BeanPostProcessor` needs to be instantiated early in order to apply to the +initialization of other beans in the context, this early type detection is critical. + +[[beans-factory-programmatically-registering-beanpostprocessors]] +.Programmatically registering `BeanPostProcessor` instances +NOTE: While the recommended approach for `BeanPostProcessor` registration is through +`ApplicationContext` auto-detection (as described earlier), you can register them +programmatically against a `ConfigurableBeanFactory` by using the `addBeanPostProcessor` +method. This can be useful when you need to evaluate conditional logic before +registration or even for copying bean post processors across contexts in a hierarchy. +Note, however, that `BeanPostProcessor` instances added programmatically do not respect +the `Ordered` interface. Here, it is the order of registration that dictates the order +of execution. Note also that `BeanPostProcessor` instances registered programmatically +are always processed before those registered through auto-detection, regardless of any +explicit ordering. + +.`BeanPostProcessor` instances and AOP auto-proxying +[NOTE] +==== +Classes that implement the `BeanPostProcessor` interface are special and are treated +differently by the container. All `BeanPostProcessor` instances and beans that they +directly reference are instantiated on startup, as part of the special startup phase +of the `ApplicationContext`. Next, all `BeanPostProcessor` instances are registered +in a sorted fashion and applied to all further beans in the container. Because AOP +auto-proxying is implemented as a `BeanPostProcessor` itself, neither `BeanPostProcessor` +instances nor the beans they directly reference are eligible for auto-proxying and, +thus, do not have aspects woven into them. + +For any such bean, you should see an informational log message: `Bean someBean is not +eligible for getting processed by all BeanPostProcessor interfaces (for example: not +eligible for auto-proxying)`. + +If you have beans wired into your `BeanPostProcessor` by using autowiring or +`@Resource` (which may fall back to autowiring), Spring might access unexpected beans +when searching for type-matching dependency candidates and, therefore, make them +ineligible for auto-proxying or other kinds of bean post-processing. For example, if you +have a dependency annotated with `@Resource` where the field or setter name does not +directly correspond to the declared name of a bean and no name attribute is used, +Spring accesses other beans for matching them by type. +==== + +The following examples show how to write, register, and use `BeanPostProcessor` instances +in an `ApplicationContext`. + + +[[beans-factory-extension-bpp-examples-hw]] +=== Example: Hello World, `BeanPostProcessor`-style + +This first example illustrates basic usage. The example shows a custom +`BeanPostProcessor` implementation that invokes the `toString()` method of each bean as +it is created by the container and prints the resulting string to the system console. + +The following listing shows the custom `BeanPostProcessor` implementation class definition: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package scripting; + + import org.springframework.beans.factory.config.BeanPostProcessor; + + public class InstantiationTracingBeanPostProcessor implements BeanPostProcessor { + + // simply return the instantiated bean as-is + public Object postProcessBeforeInitialization(Object bean, String beanName) { + return bean; // we could potentially return any object reference here... + } + + public Object postProcessAfterInitialization(Object bean, String beanName) { + System.out.println("Bean '" + beanName + "' created : " + bean.toString()); + return bean; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package scripting + + import org.springframework.beans.factory.config.BeanPostProcessor + + class InstantiationTracingBeanPostProcessor : BeanPostProcessor { + + // simply return the instantiated bean as-is + override fun postProcessBeforeInitialization(bean: Any, beanName: String): Any? { + return bean // we could potentially return any object reference here... + } + + override fun postProcessAfterInitialization(bean: Any, beanName: String): Any? { + println("Bean '$beanName' created : $bean") + return bean + } + } +---- + +The following `beans` element uses the `InstantiationTracingBeanPostProcessor`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + +---- + +Notice how the `InstantiationTracingBeanPostProcessor` is merely defined. It does not +even have a name, and, because it is a bean, it can be dependency-injected as you would any +other bean. (The preceding configuration also defines a bean that is backed by a Groovy +script. The Spring dynamic language support is detailed in the chapter entitled +<>.) + +The following Java application runs the preceding code and configuration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import org.springframework.context.ApplicationContext; + import org.springframework.context.support.ClassPathXmlApplicationContext; + import org.springframework.scripting.Messenger; + + public final class Boot { + + public static void main(final String[] args) throws Exception { + ApplicationContext ctx = new ClassPathXmlApplicationContext("scripting/beans.xml"); + Messenger messenger = ctx.getBean("messenger", Messenger.class); + System.out.println(messenger); + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + fun main() { + val ctx = ClassPathXmlApplicationContext("scripting/beans.xml") + val messenger = ctx.getBean("messenger") + println(messenger) + } +---- + +The output of the preceding application resembles the following: + +[literal,subs="verbatim,quotes"] +---- +Bean 'messenger' created : org.springframework.scripting.groovy.GroovyMessenger@272961 +org.springframework.scripting.groovy.GroovyMessenger@272961 +---- + + +[[beans-factory-extension-bpp-examples-aabpp]] +=== Example: The `AutowiredAnnotationBeanPostProcessor` + +Using callback interfaces or annotations in conjunction with a custom `BeanPostProcessor` +implementation is a common means of extending the Spring IoC container. An example is +Spring's `AutowiredAnnotationBeanPostProcessor` -- a `BeanPostProcessor` implementation +that ships with the Spring distribution and autowires annotated fields, setter methods, +and arbitrary config methods. + + + +[[beans-factory-extension-factory-postprocessors]] +== Customizing Configuration Metadata with a `BeanFactoryPostProcessor` + +The next extension point that we look at is the +`org.springframework.beans.factory.config.BeanFactoryPostProcessor`. The semantics of +this interface are similar to those of the `BeanPostProcessor`, with one major +difference: `BeanFactoryPostProcessor` operates on the bean configuration metadata. +That is, the Spring IoC container lets a `BeanFactoryPostProcessor` read the +configuration metadata and potentially change it _before_ the container instantiates +any beans other than `BeanFactoryPostProcessor` instances. + +You can configure multiple `BeanFactoryPostProcessor` instances, and you can control the order in +which these `BeanFactoryPostProcessor` instances run by setting the `order` property. +However, you can only set this property if the `BeanFactoryPostProcessor` implements the +`Ordered` interface. If you write your own `BeanFactoryPostProcessor`, you should +consider implementing the `Ordered` interface, too. See the javadoc of the +{api-spring-framework}/beans/factory/config/BeanFactoryPostProcessor.html[`BeanFactoryPostProcessor`] +and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces for more details. + +[NOTE] +==== +If you want to change the actual bean instances (that is, the objects that are created +from the configuration metadata), then you instead need to use a `BeanPostProcessor` +(described earlier in <>). While it is technically possible +to work with bean instances within a `BeanFactoryPostProcessor` (for example, by using +`BeanFactory.getBean()`), doing so causes premature bean instantiation, violating the +standard container lifecycle. This may cause negative side effects, such as bypassing +bean post processing. + +Also, `BeanFactoryPostProcessor` instances are scoped per-container. This is only relevant +if you use container hierarchies. If you define a `BeanFactoryPostProcessor` in one +container, it is applied only to the bean definitions in that container. Bean definitions +in one container are not post-processed by `BeanFactoryPostProcessor` instances in another +container, even if both containers are part of the same hierarchy. +==== + +A bean factory post-processor is automatically run when it is declared inside an +`ApplicationContext`, in order to apply changes to the configuration metadata that +define the container. Spring includes a number of predefined bean factory +post-processors, such as `PropertyOverrideConfigurer` and +`PropertySourcesPlaceholderConfigurer`. You can also use a custom `BeanFactoryPostProcessor` +-- for example, to register custom property editors. + +An `ApplicationContext` automatically detects any beans that are deployed into it that +implement the `BeanFactoryPostProcessor` interface. It uses these beans as bean factory +post-processors, at the appropriate time. You can deploy these post-processor beans as +you would any other bean. + +NOTE: As with ``BeanPostProcessor``s , you typically do not want to configure +``BeanFactoryPostProcessor``s for lazy initialization. If no other bean references a +`Bean(Factory)PostProcessor`, that post-processor will not get instantiated at all. +Thus, marking it for lazy initialization will be ignored, and the +`Bean(Factory)PostProcessor` will be instantiated eagerly even if you set the +`default-lazy-init` attribute to `true` on the declaration of your `` element. + + +[[beans-factory-placeholderconfigurer]] +=== Example: The Class Name Substitution `PropertySourcesPlaceholderConfigurer` + +You can use the `PropertySourcesPlaceholderConfigurer` to externalize property values +from a bean definition in a separate file by using the standard Java `Properties` format. +Doing so enables the person deploying an application to customize environment-specific +properties, such as database URLs and passwords, without the complexity or risk of +modifying the main XML definition file or files for the container. + +Consider the following XML-based configuration metadata fragment, where a `DataSource` +with placeholder values is defined: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + +---- + +The example shows properties configured from an external `Properties` file. At runtime, +a `PropertySourcesPlaceholderConfigurer` is applied to the metadata that replaces some +properties of the DataSource. The values to replace are specified as placeholders of the +form pass:q[`${property-name}`], which follows the Ant and log4j and JSP EL style. + +The actual values come from another file in the standard Java `Properties` format: + +[literal,subs="verbatim,quotes"] +---- +jdbc.driverClassName=org.hsqldb.jdbcDriver +jdbc.url=jdbc:hsqldb:hsql://production:9002 +jdbc.username=sa +jdbc.password=root +---- + +Therefore, the `${jdbc.username}` string is replaced at runtime with the value, 'sa', and +the same applies for other placeholder values that match keys in the properties file. +The `PropertySourcesPlaceholderConfigurer` checks for placeholders in most properties and +attributes of a bean definition. Furthermore, you can customize the placeholder prefix and suffix. + +With the `context` namespace introduced in Spring 2.5, you can configure property placeholders +with a dedicated configuration element. You can provide one or more locations as a +comma-separated list in the `location` attribute, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +The `PropertySourcesPlaceholderConfigurer` not only looks for properties in the `Properties` +file you specify. By default, if it cannot find a property in the specified properties files, +it checks against Spring `Environment` properties and regular Java `System` properties. + +[TIP] +===== +You can use the `PropertySourcesPlaceholderConfigurer` to substitute class names, which +is sometimes useful when you have to pick a particular implementation class at runtime. +The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + classpath:com/something/strategy.properties + + + custom.strategy.class=com.something.DefaultStrategy + + + + +---- + +If the class cannot be resolved at runtime to a valid class, resolution of the bean +fails when it is about to be created, which is during the `preInstantiateSingletons()` +phase of an `ApplicationContext` for a non-lazy-init bean. +===== + + +[[beans-factory-overrideconfigurer]] +=== Example: The `PropertyOverrideConfigurer` + +The `PropertyOverrideConfigurer`, another bean factory post-processor, resembles the +`PropertySourcesPlaceholderConfigurer`, but unlike the latter, the original definitions +can have default values or no values at all for bean properties. If an overriding +`Properties` file does not have an entry for a certain bean property, the default +context definition is used. + +Note that the bean definition is not aware of being overridden, so it is not +immediately obvious from the XML definition file that the override configurer is being +used. In case of multiple `PropertyOverrideConfigurer` instances that define different +values for the same bean property, the last one wins, due to the overriding mechanism. + +Properties file configuration lines take the following format: + +[literal,subs="verbatim,quotes"] +---- +beanName.property=value +---- + +The following listing shows an example of the format: + +[literal,subs="verbatim,quotes"] +---- +dataSource.driverClassName=com.mysql.jdbc.Driver +dataSource.url=jdbc:mysql:mydb +---- + +This example file can be used with a container definition that contains a bean called +`dataSource` that has `driver` and `url` properties. + +Compound property names are also supported, as long as every component of the path +except the final property being overridden is already non-null (presumably initialized +by the constructors). In the following example, the `sammy` property of the `bob` property of the `fred` property of the `tom` bean +is set to the scalar value `123`: + +[literal,subs="verbatim,quotes"] +---- +tom.fred.bob.sammy=123 +---- + + +NOTE: Specified override values are always literal values. They are not translated into +bean references. This convention also applies when the original value in the XML bean +definition specifies a bean reference. + +With the `context` namespace introduced in Spring 2.5, it is possible to configure +property overriding with a dedicated configuration element, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + + + +[[beans-factory-extension-factorybean]] +== Customizing Instantiation Logic with a `FactoryBean` + +You can implement the `org.springframework.beans.factory.FactoryBean` interface for objects that +are themselves factories. + +The `FactoryBean` interface is a point of pluggability into the Spring IoC container's +instantiation logic. If you have complex initialization code that is better expressed in +Java as opposed to a (potentially) verbose amount of XML, you can create your own +`FactoryBean`, write the complex initialization inside that class, and then plug your +custom `FactoryBean` into the container. + +The `FactoryBean` interface provides three methods: + +* `T getObject()`: Returns an instance of the object this factory creates. The + instance can possibly be shared, depending on whether this factory returns singletons + or prototypes. +* `boolean isSingleton()`: Returns `true` if this `FactoryBean` returns singletons or + `false` otherwise. The default implementation of this method returns `true`. +* `Class getObjectType()`: Returns the object type returned by the `getObject()` method + or `null` if the type is not known in advance. + +The `FactoryBean` concept and interface are used in a number of places within the Spring +Framework. More than 50 implementations of the `FactoryBean` interface ship with Spring +itself. + +When you need to ask a container for an actual `FactoryBean` instance itself instead of +the bean it produces, prefix the bean's `id` with the ampersand symbol (`&`) when +calling the `getBean()` method of the `ApplicationContext`. So, for a given `FactoryBean` +with an `id` of `myBean`, invoking `getBean("myBean")` on the container returns the +product of the `FactoryBean`, whereas invoking `getBean("&myBean")` returns the +`FactoryBean` instance itself. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc new file mode 100644 index 000000000000..13cf361ed28b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc @@ -0,0 +1,643 @@ +[[beans-factory-nature]] += Customizing the Nature of a Bean + +The Spring Framework provides a number of interfaces you can use to customize the nature +of a bean. This section groups them as follows: + +* <> +* <> +* <> + + + +[[beans-factory-lifecycle]] +== Lifecycle Callbacks + +To interact with the container's management of the bean lifecycle, you can implement +the Spring `InitializingBean` and `DisposableBean` interfaces. The container calls +`afterPropertiesSet()` for the former and `destroy()` for the latter to let the bean +perform certain actions upon initialization and destruction of your beans. + +[TIP] +==== +The JSR-250 `@PostConstruct` and `@PreDestroy` annotations are generally considered best +practice for receiving lifecycle callbacks in a modern Spring application. Using these +annotations means that your beans are not coupled to Spring-specific interfaces. +For details, see <>. + +If you do not want to use the JSR-250 annotations but you still want to remove +coupling, consider `init-method` and `destroy-method` bean definition metadata. +==== + +Internally, the Spring Framework uses `BeanPostProcessor` implementations to process any +callback interfaces it can find and call the appropriate methods. If you need custom +features or other lifecycle behavior Spring does not by default offer, you can +implement a `BeanPostProcessor` yourself. For more information, see +<>. + +In addition to the initialization and destruction callbacks, Spring-managed objects may +also implement the `Lifecycle` interface so that those objects can participate in the +startup and shutdown process, as driven by the container's own lifecycle. + +The lifecycle callback interfaces are described in this section. + + +[[beans-factory-lifecycle-initializingbean]] +=== Initialization Callbacks + +The `org.springframework.beans.factory.InitializingBean` interface lets a bean +perform initialization work after the container has set all necessary properties on the +bean. The `InitializingBean` interface specifies a single method: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + void afterPropertiesSet() throws Exception; +---- + +We recommend that you do not use the `InitializingBean` interface, because it +unnecessarily couples the code to Spring. Alternatively, we suggest using +the <> annotation or +specifying a POJO initialization method. In the case of XML-based configuration metadata, +you can use the `init-method` attribute to specify the name of the method that has a void +no-argument signature. With Java configuration, you can use the `initMethod` attribute of +`@Bean`. See <>. Consider the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ExampleBean { + + public void init() { + // do some initialization work + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ExampleBean { + + fun init() { + // do some initialization work + } + } +---- + +The preceding example has almost exactly the same effect as the following example +(which consists of two listings): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class AnotherExampleBean implements InitializingBean { + + @Override + public void afterPropertiesSet() { + // do some initialization work + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class AnotherExampleBean : InitializingBean { + + override fun afterPropertiesSet() { + // do some initialization work + } + } +---- + +However, the first of the two preceding examples does not couple the code to Spring. + + +[[beans-factory-lifecycle-disposablebean]] +=== Destruction Callbacks + +Implementing the `org.springframework.beans.factory.DisposableBean` interface lets a +bean get a callback when the container that contains it is destroyed. The +`DisposableBean` interface specifies a single method: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + void destroy() throws Exception; +---- + +We recommend that you do not use the `DisposableBean` callback interface, because it +unnecessarily couples the code to Spring. Alternatively, we suggest using +the <> annotation or +specifying a generic method that is supported by bean definitions. With XML-based +configuration metadata, you can use the `destroy-method` attribute on the ``. +With Java configuration, you can use the `destroyMethod` attribute of `@Bean`. See +<>. Consider the following definition: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ExampleBean { + + public void cleanup() { + // do some destruction work (like releasing pooled connections) + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ExampleBean { + + fun cleanup() { + // do some destruction work (like releasing pooled connections) + } + } +---- + +The preceding definition has almost exactly the same effect as the following definition: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class AnotherExampleBean implements DisposableBean { + + @Override + public void destroy() { + // do some destruction work (like releasing pooled connections) + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class AnotherExampleBean : DisposableBean { + + override fun destroy() { + // do some destruction work (like releasing pooled connections) + } + } +---- + +However, the first of the two preceding definitions does not couple the code to Spring. + +TIP: You can assign the `destroy-method` attribute of a `` element a special +`(inferred)` value, which instructs Spring to automatically detect a public `close` or +`shutdown` method on the specific bean class. (Any class that implements +`java.lang.AutoCloseable` or `java.io.Closeable` would therefore match.) You can also set +this special `(inferred)` value on the `default-destroy-method` attribute of a +`` element to apply this behavior to an entire set of beans (see +<>). Note that this is the +default behavior with Java configuration. + +[[beans-factory-lifecycle-default-init-destroy-methods]] +=== Default Initialization and Destroy Methods + +When you write initialization and destroy method callbacks that do not use the +Spring-specific `InitializingBean` and `DisposableBean` callback interfaces, you +typically write methods with names such as `init()`, `initialize()`, `dispose()`, and so +on. Ideally, the names of such lifecycle callback methods are standardized across a +project so that all developers use the same method names and ensure consistency. + +You can configure the Spring container to "`look`" for named initialization and destroy +callback method names on every bean. This means that you, as an application +developer, can write your application classes and use an initialization callback called +`init()`, without having to configure an `init-method="init"` attribute with each bean +definition. The Spring IoC container calls that method when the bean is created (and in +accordance with the standard lifecycle callback contract <>). This feature also enforces a consistent naming convention for +initialization and destroy method callbacks. + +Suppose that your initialization callback methods are named `init()` and your destroy +callback methods are named `destroy()`. Your class then resembles the class in the +following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class DefaultBlogService implements BlogService { + + private BlogDao blogDao; + + public void setBlogDao(BlogDao blogDao) { + this.blogDao = blogDao; + } + + // this is (unsurprisingly) the initialization callback method + public void init() { + if (this.blogDao == null) { + throw new IllegalStateException("The [blogDao] property must be set."); + } + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class DefaultBlogService : BlogService { + + private var blogDao: BlogDao? = null + + // this is (unsurprisingly) the initialization callback method + fun init() { + if (blogDao == null) { + throw IllegalStateException("The [blogDao] property must be set.") + } + } + } +---- + +You could then use that class in a bean resembling the following: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +The presence of the `default-init-method` attribute on the top-level `` element +attribute causes the Spring IoC container to recognize a method called `init` on the bean +class as the initialization method callback. When a bean is created and assembled, if the +bean class has such a method, it is invoked at the appropriate time. + +You can configure destroy method callbacks similarly (in XML, that is) by using the +`default-destroy-method` attribute on the top-level `` element. + +Where existing bean classes already have callback methods that are named at variance +with the convention, you can override the default by specifying (in XML, that is) the +method name by using the `init-method` and `destroy-method` attributes of the `` +itself. + +The Spring container guarantees that a configured initialization callback is called +immediately after a bean is supplied with all dependencies. Thus, the initialization +callback is called on the raw bean reference, which means that AOP interceptors and so +forth are not yet applied to the bean. A target bean is fully created first and +then an AOP proxy (for example) with its interceptor chain is applied. If the target +bean and the proxy are defined separately, your code can even interact with the raw +target bean, bypassing the proxy. Hence, it would be inconsistent to apply the +interceptors to the `init` method, because doing so would couple the lifecycle of the +target bean to its proxy or interceptors and leave strange semantics when your code +interacts directly with the raw target bean. + + + +[[beans-factory-lifecycle-combined-effects]] +=== Combining Lifecycle Mechanisms + +As of Spring 2.5, you have three options for controlling bean lifecycle behavior: + +* The <> and +<> callback interfaces +* Custom `init()` and `destroy()` methods +* The <>. You can combine these mechanisms to control a given bean. + +NOTE: If multiple lifecycle mechanisms are configured for a bean and each mechanism is +configured with a different method name, then each configured method is run in the +order listed after this note. However, if the same method name is configured -- for example, +`init()` for an initialization method -- for more than one of these lifecycle mechanisms, +that method is run once, as explained in the +<>. + +Multiple lifecycle mechanisms configured for the same bean, with different +initialization methods, are called as follows: + +. Methods annotated with `@PostConstruct` +. `afterPropertiesSet()` as defined by the `InitializingBean` callback interface +. A custom configured `init()` method + +Destroy methods are called in the same order: + +. Methods annotated with `@PreDestroy` +. `destroy()` as defined by the `DisposableBean` callback interface +. A custom configured `destroy()` method + + + +[[beans-factory-lifecycle-processor]] +=== Startup and Shutdown Callbacks + +The `Lifecycle` interface defines the essential methods for any object that has its own +lifecycle requirements (such as starting and stopping some background process): + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface Lifecycle { + + void start(); + + void stop(); + + boolean isRunning(); + } +---- + +Any Spring-managed object may implement the `Lifecycle` interface. Then, when the +`ApplicationContext` itself receives start and stop signals (for example, for a stop/restart +scenario at runtime), it cascades those calls to all `Lifecycle` implementations +defined within that context. It does this by delegating to a `LifecycleProcessor`, shown +in the following listing: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface LifecycleProcessor extends Lifecycle { + + void onRefresh(); + + void onClose(); + } +---- + +Notice that the `LifecycleProcessor` is itself an extension of the `Lifecycle` +interface. It also adds two other methods for reacting to the context being refreshed +and closed. + +[TIP] +==== +Note that the regular `org.springframework.context.Lifecycle` interface is a plain +contract for explicit start and stop notifications and does not imply auto-startup at context +refresh time. For fine-grained control over auto-startup of a specific bean (including startup phases), +consider implementing `org.springframework.context.SmartLifecycle` instead. + +Also, please note that stop notifications are not guaranteed to come before destruction. +On regular shutdown, all `Lifecycle` beans first receive a stop notification before +the general destruction callbacks are being propagated. However, on hot refresh during a +context's lifetime or on stopped refresh attempts, only destroy methods are called. +==== + +The order of startup and shutdown invocations can be important. If a "`depends-on`" +relationship exists between any two objects, the dependent side starts after its +dependency, and it stops before its dependency. However, at times, the direct +dependencies are unknown. You may only know that objects of a certain type should start +prior to objects of another type. In those cases, the `SmartLifecycle` interface defines +another option, namely the `getPhase()` method as defined on its super-interface, +`Phased`. The following listing shows the definition of the `Phased` interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface Phased { + + int getPhase(); + } +---- + +The following listing shows the definition of the `SmartLifecycle` interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface SmartLifecycle extends Lifecycle, Phased { + + boolean isAutoStartup(); + + void stop(Runnable callback); + } +---- + +When starting, the objects with the lowest phase start first. When stopping, the +reverse order is followed. Therefore, an object that implements `SmartLifecycle` and +whose `getPhase()` method returns `Integer.MIN_VALUE` would be among the first to start +and the last to stop. At the other end of the spectrum, a phase value of +`Integer.MAX_VALUE` would indicate that the object should be started last and stopped +first (likely because it depends on other processes to be running). When considering the +phase value, it is also important to know that the default phase for any "`normal`" +`Lifecycle` object that does not implement `SmartLifecycle` is `0`. Therefore, any +negative phase value indicates that an object should start before those standard +components (and stop after them). The reverse is true for any positive phase value. + +The stop method defined by `SmartLifecycle` accepts a callback. Any +implementation must invoke that callback's `run()` method after that implementation's +shutdown process is complete. That enables asynchronous shutdown where necessary, since +the default implementation of the `LifecycleProcessor` interface, +`DefaultLifecycleProcessor`, waits up to its timeout value for the group of objects +within each phase to invoke that callback. The default per-phase timeout is 30 seconds. +You can override the default lifecycle processor instance by defining a bean named +`lifecycleProcessor` within the context. If you want only to modify the timeout, +defining the following would suffice: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- + +As mentioned earlier, the `LifecycleProcessor` interface defines callback methods for the +refreshing and closing of the context as well. The latter drives the shutdown +process as if `stop()` had been called explicitly, but it happens when the context is +closing. The 'refresh' callback, on the other hand, enables another feature of +`SmartLifecycle` beans. When the context is refreshed (after all objects have been +instantiated and initialized), that callback is invoked. At that point, the +default lifecycle processor checks the boolean value returned by each +`SmartLifecycle` object's `isAutoStartup()` method. If `true`, that object is +started at that point rather than waiting for an explicit invocation of the context's or +its own `start()` method (unlike the context refresh, the context start does not happen +automatically for a standard context implementation). The `phase` value and any +"`depends-on`" relationships determine the startup order as described earlier. + + + +[[beans-factory-shutdown]] +=== Shutting Down the Spring IoC Container Gracefully in Non-Web Applications + +[NOTE] +==== +This section applies only to non-web applications. Spring's web-based +`ApplicationContext` implementations already have code in place to gracefully shut down +the Spring IoC container when the relevant web application is shut down. +==== + +If you use Spring's IoC container in a non-web application environment (for +example, in a rich client desktop environment), register a shutdown hook with the +JVM. Doing so ensures a graceful shutdown and calls the relevant destroy methods on your +singleton beans so that all resources are released. You must still configure +and implement these destroy callbacks correctly. + +To register a shutdown hook, call the `registerShutdownHook()` method that is +declared on the `ConfigurableApplicationContext` interface, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import org.springframework.context.ConfigurableApplicationContext; + import org.springframework.context.support.ClassPathXmlApplicationContext; + + public final class Boot { + + public static void main(final String[] args) throws Exception { + ConfigurableApplicationContext ctx = new ClassPathXmlApplicationContext("beans.xml"); + + // add a shutdown hook for the above context... + ctx.registerShutdownHook(); + + // app runs here... + + // main method exits, hook is called prior to the app shutting down... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.context.support.ClassPathXmlApplicationContext + + fun main() { + val ctx = ClassPathXmlApplicationContext("beans.xml") + + // add a shutdown hook for the above context... + ctx.registerShutdownHook() + + // app runs here... + + // main method exits, hook is called prior to the app shutting down... + } +---- + + + +[[beans-factory-aware]] +== `ApplicationContextAware` and `BeanNameAware` + +When an `ApplicationContext` creates an object instance that implements the +`org.springframework.context.ApplicationContextAware` interface, the instance is provided +with a reference to that `ApplicationContext`. The following listing shows the definition +of the `ApplicationContextAware` interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface ApplicationContextAware { + + void setApplicationContext(ApplicationContext applicationContext) throws BeansException; + } +---- + +Thus, beans can programmatically manipulate the `ApplicationContext` that created them, +through the `ApplicationContext` interface or by casting the reference to a known +subclass of this interface (such as `ConfigurableApplicationContext`, which exposes +additional functionality). One use would be the programmatic retrieval of other beans. +Sometimes this capability is useful. However, in general, you should avoid it, because +it couples the code to Spring and does not follow the Inversion of Control style, +where collaborators are provided to beans as properties. Other methods of the +`ApplicationContext` provide access to file resources, publishing application events, +and accessing a `MessageSource`. These additional features are described in +<>. + +Autowiring is another alternative to obtain a reference to the +`ApplicationContext`. The _traditional_ `constructor` and `byType` autowiring modes +(as described in <>) can provide a dependency of type +`ApplicationContext` for a constructor argument or a setter method parameter, +respectively. For more flexibility, including the ability to autowire fields and +multiple parameter methods, use the annotation-based autowiring features. If you do, +the `ApplicationContext` is autowired into a field, constructor argument, or method +parameter that expects the `ApplicationContext` type if the field, constructor, or +method in question carries the `@Autowired` annotation. For more information, see +<>. + +When an `ApplicationContext` creates a class that implements the +`org.springframework.beans.factory.BeanNameAware` interface, the class is provided with +a reference to the name defined in its associated object definition. The following listing +shows the definition of the BeanNameAware interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface BeanNameAware { + + void setBeanName(String name) throws BeansException; + } +---- + +The callback is invoked after population of normal bean properties but before an +initialization callback such as `InitializingBean.afterPropertiesSet()` or a custom +init-method. + + + +[[aware-list]] +== Other `Aware` Interfaces + +Besides `ApplicationContextAware` and `BeanNameAware` (discussed <>), +Spring offers a wide range of `Aware` callback interfaces that let beans indicate to the container +that they require a certain infrastructure dependency. As a general rule, the name indicates the +dependency type. The following table summarizes the most important `Aware` interfaces: + +[[beans-factory-nature-aware-list]] +.Aware interfaces +|=== +| Name| Injected Dependency| Explained in... + +| `ApplicationContextAware` +| Declaring `ApplicationContext`. +| <> + +| `ApplicationEventPublisherAware` +| Event publisher of the enclosing `ApplicationContext`. +| <> + +| `BeanClassLoaderAware` +| Class loader used to load the bean classes. +| <> + +| `BeanFactoryAware` +| Declaring `BeanFactory`. +| <> + +| `BeanNameAware` +| Name of the declaring bean. +| <> + +| `LoadTimeWeaverAware` +| Defined weaver for processing class definition at load time. +| <> + +| `MessageSourceAware` +| Configured strategy for resolving messages (with support for parameterization and + internationalization). +| <> + +| `NotificationPublisherAware` +| Spring JMX notification publisher. +| <> + +| `ResourceLoaderAware` +| Configured loader for low-level access to resources. +| <> + +| `ServletConfigAware` +| Current `ServletConfig` the container runs in. Valid only in a web-aware Spring + `ApplicationContext`. +| <> + +| `ServletContextAware` +| Current `ServletContext` the container runs in. Valid only in a web-aware Spring + `ApplicationContext`. +| <> +|=== + +Note again that using these interfaces ties your code to the Spring API and does not +follow the Inversion of Control style. As a result, we recommend them for infrastructure +beans that require programmatic access to the container. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc new file mode 100644 index 000000000000..7925a2504c70 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc @@ -0,0 +1,714 @@ +[[beans-factory-scopes]] += Bean Scopes + +When you create a bean definition, you create a recipe for creating actual instances +of the class defined by that bean definition. The idea that a bean definition is a +recipe is important, because it means that, as with a class, you can create many object +instances from a single recipe. + +You can control not only the various dependencies and configuration values that are to +be plugged into an object that is created from a particular bean definition but also control +the scope of the objects created from a particular bean definition. This approach is +powerful and flexible, because you can choose the scope of the objects you create +through configuration instead of having to bake in the scope of an object at the Java +class level. Beans can be defined to be deployed in one of a number of scopes. +The Spring Framework supports six scopes, four of which are available only if +you use a web-aware `ApplicationContext`. You can also create +<> + +The following table describes the supported scopes: + +[[beans-factory-scopes-tbl]] +.Bean scopes +[cols="20%,80%"] +|=== +| Scope| Description + +| <> +| (Default) Scopes a single bean definition to a single object instance for each Spring IoC + container. + +| <> +| Scopes a single bean definition to any number of object instances. + +| <> +| Scopes a single bean definition to the lifecycle of a single HTTP request. That is, + each HTTP request has its own instance of a bean created off the back of a single bean + definition. Only valid in the context of a web-aware Spring `ApplicationContext`. + +| <> +| Scopes a single bean definition to the lifecycle of an HTTP `Session`. Only valid in + the context of a web-aware Spring `ApplicationContext`. + +| <> +| Scopes a single bean definition to the lifecycle of a `ServletContext`. Only valid in + the context of a web-aware Spring `ApplicationContext`. + +| <> +| Scopes a single bean definition to the lifecycle of a `WebSocket`. Only valid in + the context of a web-aware Spring `ApplicationContext`. +|=== + +NOTE: A thread scope is available but is not registered by default. For more information, +see the documentation for +{api-spring-framework}/context/support/SimpleThreadScope.html[`SimpleThreadScope`]. +For instructions on how to register this or any other custom scope, see +<>. + + + +[[beans-factory-scopes-singleton]] +== The Singleton Scope + +Only one shared instance of a singleton bean is managed, and all requests for beans +with an ID or IDs that match that bean definition result in that one specific bean +instance being returned by the Spring container. + +To put it another way, when you define a bean definition and it is scoped as a +singleton, the Spring IoC container creates exactly one instance of the object +defined by that bean definition. This single instance is stored in a cache of such +singleton beans, and all subsequent requests and references for that named bean +return the cached object. The following image shows how the singleton scope works: + +image::singleton.png[] + +Spring's concept of a singleton bean differs from the singleton pattern as defined in +the Gang of Four (GoF) patterns book. The GoF singleton hard-codes the scope of an +object such that one and only one instance of a particular class is created per +ClassLoader. The scope of the Spring singleton is best described as being per-container +and per-bean. This means that, if you define one bean for a particular class in a +single Spring container, the Spring container creates one and only one instance +of the class defined by that bean definition. The singleton scope is the default scope +in Spring. To define a bean as a singleton in XML, you can define a bean as shown in the +following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + +---- + + + +[[beans-factory-scopes-prototype]] +== The Prototype Scope + +The non-singleton prototype scope of bean deployment results in the creation of a new +bean instance every time a request for that specific bean is made. That is, the bean +is injected into another bean or you request it through a `getBean()` method call on the +container. As a rule, you should use the prototype scope for all stateful beans and the +singleton scope for stateless beans. + +The following diagram illustrates the Spring prototype scope: + +image::prototype.png[] + +(A data access object +(DAO) is not typically configured as a prototype, because a typical DAO does not hold +any conversational state. It was easier for us to reuse the core of the +singleton diagram.) + +The following example defines a bean as a prototype in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +In contrast to the other scopes, Spring does not manage the complete lifecycle of a +prototype bean. The container instantiates, configures, and otherwise assembles a +prototype object and hands it to the client, with no further record of that prototype +instance. Thus, although initialization lifecycle callback methods are called on all +objects regardless of scope, in the case of prototypes, configured destruction +lifecycle callbacks are not called. The client code must clean up prototype-scoped +objects and release expensive resources that the prototype beans hold. To get +the Spring container to release resources held by prototype-scoped beans, try using a +custom <>, which holds a reference to +beans that need to be cleaned up. + +In some respects, the Spring container's role in regard to a prototype-scoped bean is a +replacement for the Java `new` operator. All lifecycle management past that point must +be handled by the client. (For details on the lifecycle of a bean in the Spring +container, see <>.) + + + +[[beans-factory-scopes-sing-prot-interaction]] +== Singleton Beans with Prototype-bean Dependencies + +When you use singleton-scoped beans with dependencies on prototype beans, be aware that +dependencies are resolved at instantiation time. Thus, if you dependency-inject a +prototype-scoped bean into a singleton-scoped bean, a new prototype bean is instantiated +and then dependency-injected into the singleton bean. The prototype instance is the sole +instance that is ever supplied to the singleton-scoped bean. + +However, suppose you want the singleton-scoped bean to acquire a new instance of the +prototype-scoped bean repeatedly at runtime. You cannot dependency-inject a +prototype-scoped bean into your singleton bean, because that injection occurs only +once, when the Spring container instantiates the singleton bean and resolves +and injects its dependencies. If you need a new instance of a prototype bean at +runtime more than once, see <>. + + + +[[beans-factory-scopes-other]] +== Request, Session, Application, and WebSocket Scopes + +The `request`, `session`, `application`, and `websocket` scopes are available only +if you use a web-aware Spring `ApplicationContext` implementation (such as +`XmlWebApplicationContext`). If you use these scopes with regular Spring IoC containers, +such as the `ClassPathXmlApplicationContext`, an `IllegalStateException` that complains +about an unknown bean scope is thrown. + + + +[[beans-factory-scopes-other-web-configuration]] +=== Initial Web Configuration + +To support the scoping of beans at the `request`, `session`, `application`, and +`websocket` levels (web-scoped beans), some minor initial configuration is +required before you define your beans. (This initial setup is not required +for the standard scopes: `singleton` and `prototype`.) + +How you accomplish this initial setup depends on your particular Servlet environment. + +If you access scoped beans within Spring Web MVC, in effect, within a request that is +processed by the Spring `DispatcherServlet`, no special setup is necessary. +`DispatcherServlet` already exposes all relevant state. + +If you use a Servlet web container, with requests processed outside of Spring's +`DispatcherServlet` (for example, when using JSF), you need to register the +`org.springframework.web.context.request.RequestContextListener` `ServletRequestListener`. +This can be done programmatically by using the `WebApplicationInitializer` interface. +Alternatively, add the following declaration to your web application's `web.xml` file: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + ... + + + org.springframework.web.context.request.RequestContextListener + + + ... + +---- + +Alternatively, if there are issues with your listener setup, consider using Spring's +`RequestContextFilter`. The filter mapping depends on the surrounding web +application configuration, so you have to change it as appropriate. The following listing +shows the filter part of a web application: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + ... + + requestContextFilter + org.springframework.web.filter.RequestContextFilter + + + requestContextFilter + /* + + ... + +---- + +`DispatcherServlet`, `RequestContextListener`, and `RequestContextFilter` all do exactly +the same thing, namely bind the HTTP request object to the `Thread` that is servicing +that request. This makes beans that are request- and session-scoped available further +down the call chain. + + + +[[beans-factory-scopes-request]] +=== Request scope + +Consider the following XML configuration for a bean definition: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +The Spring container creates a new instance of the `LoginAction` bean by using the +`loginAction` bean definition for each and every HTTP request. That is, the +`loginAction` bean is scoped at the HTTP request level. You can change the internal +state of the instance that is created as much as you want, because other instances +created from the same `loginAction` bean definition do not see these changes in state. +They are particular to an individual request. When the request completes processing, the +bean that is scoped to the request is discarded. + +When using annotation-driven components or Java configuration, the `@RequestScope` annotation +can be used to assign a component to the `request` scope. The following example shows how +to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RequestScope + @Component + public class LoginAction { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RequestScope + @Component + class LoginAction { + // ... + } +---- + + + +[[beans-factory-scopes-session]] +=== Session Scope + +Consider the following XML configuration for a bean definition: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +The Spring container creates a new instance of the `UserPreferences` bean by using the +`userPreferences` bean definition for the lifetime of a single HTTP `Session`. In other +words, the `userPreferences` bean is effectively scoped at the HTTP `Session` level. As +with request-scoped beans, you can change the internal state of the instance that is +created as much as you want, knowing that other HTTP `Session` instances that are also +using instances created from the same `userPreferences` bean definition do not see these +changes in state, because they are particular to an individual HTTP `Session`. When the +HTTP `Session` is eventually discarded, the bean that is scoped to that particular HTTP +`Session` is also discarded. + +When using annotation-driven components or Java configuration, you can use the +`@SessionScope` annotation to assign a component to the `session` scope. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SessionScope + @Component + public class UserPreferences { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SessionScope + @Component + class UserPreferences { + // ... + } +---- + + + + +[[beans-factory-scopes-application]] +=== Application Scope + +Consider the following XML configuration for a bean definition: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +The Spring container creates a new instance of the `AppPreferences` bean by using the +`appPreferences` bean definition once for the entire web application. That is, the +`appPreferences` bean is scoped at the `ServletContext` level and stored as a regular +`ServletContext` attribute. This is somewhat similar to a Spring singleton bean but +differs in two important ways: It is a singleton per `ServletContext`, not per Spring +`ApplicationContext` (for which there may be several in any given web application), +and it is actually exposed and therefore visible as a `ServletContext` attribute. + +When using annotation-driven components or Java configuration, you can use the +`@ApplicationScope` annotation to assign a component to the `application` scope. The +following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ApplicationScope + @Component + public class AppPreferences { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ApplicationScope + @Component + class AppPreferences { + // ... + } +---- + + + + +[[beans-factory-scopes-websocket]] +=== WebSocket Scope + +WebSocket scope is associated with the lifecycle of a WebSocket session and applies to +STOMP over WebSocket applications, see +<> for more details. + + + + +[[beans-factory-scopes-other-injection]] +=== Scoped Beans as Dependencies + +The Spring IoC container manages not only the instantiation of your objects (beans), +but also the wiring up of collaborators (or dependencies). If you want to inject (for +example) an HTTP request-scoped bean into another bean of a longer-lived scope, you may +choose to inject an AOP proxy in place of the scoped bean. That is, you need to inject +a proxy object that exposes the same public interface as the scoped object but that can +also retrieve the real target object from the relevant scope (such as an HTTP request) +and delegate method calls onto the real object. + +[NOTE] +==== +You may also use `` between beans that are scoped as `singleton`, +with the reference then going through an intermediate proxy that is serializable +and therefore able to re-obtain the target singleton bean on deserialization. + +When declaring `` against a bean of scope `prototype`, every method +call on the shared proxy leads to the creation of a new target instance to which the +call is then being forwarded. + +Also, scoped proxies are not the only way to access beans from shorter scopes in a +lifecycle-safe fashion. You may also declare your injection point (that is, the +constructor or setter argument or autowired field) as `ObjectFactory`, +allowing for a `getObject()` call to retrieve the current instance on demand every +time it is needed -- without holding on to the instance or storing it separately. + +As an extended variant, you may declare `ObjectProvider` which delivers +several additional access variants, including `getIfAvailable` and `getIfUnique`. + +The JSR-330 variant of this is called `Provider` and is used with a `Provider` +declaration and a corresponding `get()` call for every retrieval attempt. +See <> for more details on JSR-330 overall. +==== + +The configuration in the following example is only one line, but it is important to +understand the "`why`" as well as the "`how`" behind it: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + <1> + + + + + + + + +---- +<1> The line that defines the proxy. + + +To create such a proxy, you insert a child `` element into a scoped +bean definition (see <> and +<>). +Why do definitions of beans scoped at the `request`, `session` and custom-scope +levels require the `` element? +Consider the following singleton bean definition and contrast it with +what you need to define for the aforementioned scopes (note that the following +`userPreferences` bean definition as it stands is incomplete): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + +---- + +In the preceding example, the singleton bean (`userManager`) is injected with a reference +to the HTTP `Session`-scoped bean (`userPreferences`). The salient point here is that the +`userManager` bean is a singleton: it is instantiated exactly once per +container, and its dependencies (in this case only one, the `userPreferences` bean) are +also injected only once. This means that the `userManager` bean operates only on the +exact same `userPreferences` object (that is, the one with which it was originally injected). + +This is not the behavior you want when injecting a shorter-lived scoped bean into a +longer-lived scoped bean (for example, injecting an HTTP `Session`-scoped collaborating +bean as a dependency into singleton bean). Rather, you need a single `userManager` +object, and, for the lifetime of an HTTP `Session`, you need a `userPreferences` object +that is specific to the HTTP `Session`. Thus, the container creates an object that +exposes the exact same public interface as the `UserPreferences` class (ideally an +object that is a `UserPreferences` instance), which can fetch the real +`UserPreferences` object from the scoping mechanism (HTTP request, `Session`, and so +forth). The container injects this proxy object into the `userManager` bean, which is +unaware that this `UserPreferences` reference is a proxy. In this example, when a +`UserManager` instance invokes a method on the dependency-injected `UserPreferences` +object, it is actually invoking a method on the proxy. The proxy then fetches the real +`UserPreferences` object from (in this case) the HTTP `Session` and delegates the +method invocation onto the retrieved real `UserPreferences` object. + +Thus, you need the following (correct and complete) configuration when injecting +`request-` and `session-scoped` beans into collaborating objects, as the following example +shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +[[beans-factory-scopes-other-injection-proxies]] +==== Choosing the Type of Proxy to Create + +By default, when the Spring container creates a proxy for a bean that is marked up with +the `` element, a CGLIB-based class proxy is created. + +[NOTE] +==== +CGLIB proxies intercept only public method calls! Do not call non-public methods +on such a proxy. They are not delegated to the actual scoped target object. +==== + +Alternatively, you can configure the Spring container to create standard JDK +interface-based proxies for such scoped beans, by specifying `false` for the value of +the `proxy-target-class` attribute of the `` element. Using JDK +interface-based proxies means that you do not need additional libraries in your +application classpath to affect such proxying. However, it also means that the class of +the scoped bean must implement at least one interface and that all collaborators +into which the scoped bean is injected must reference the bean through one of its +interfaces. The following example shows a proxy based on an interface: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + +---- + +For more detailed information about choosing class-based or interface-based proxying, +see <>. + + + +[[beans-factory-scopes-custom]] +== Custom Scopes + +The bean scoping mechanism is extensible. You can define your own +scopes or even redefine existing scopes, although the latter is considered bad practice +and you cannot override the built-in `singleton` and `prototype` scopes. + + +[[beans-factory-scopes-custom-creating]] +=== Creating a Custom Scope + +To integrate your custom scopes into the Spring container, you need to implement the +`org.springframework.beans.factory.config.Scope` interface, which is described in this +section. For an idea of how to implement your own scopes, see the `Scope` +implementations that are supplied with the Spring Framework itself and the +{api-spring-framework}/beans/factory/config/Scope.html[`Scope`] javadoc, +which explains the methods you need to implement in more detail. + +The `Scope` interface has four methods to get objects from the scope, remove them from +the scope, and let them be destroyed. + +The session scope implementation, for example, returns the session-scoped bean (if it +does not exist, the method returns a new instance of the bean, after having bound it to +the session for future reference). The following method returns the object from the +underlying scope: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Object get(String name, ObjectFactory objectFactory) +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun get(name: String, objectFactory: ObjectFactory<*>): Any +---- + +The session scope implementation, for example, removes the session-scoped bean from the +underlying session. The object should be returned, but you can return `null` if the +object with the specified name is not found. The following method removes the object from +the underlying scope: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Object remove(String name) +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun remove(name: String): Any +---- + +The following method registers a callback that the scope should invoke when it is +destroyed or when the specified object in the scope is destroyed: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + void registerDestructionCallback(String name, Runnable destructionCallback) +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun registerDestructionCallback(name: String, destructionCallback: Runnable) +---- + +See the {api-spring-framework}/beans/factory/config/Scope.html#registerDestructionCallback[javadoc] +or a Spring scope implementation for more information on destruction callbacks. + +The following method obtains the conversation identifier for the underlying scope: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + String getConversationId() +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun getConversationId(): String +---- + +This identifier is different for each scope. For a session scoped implementation, this +identifier can be the session identifier. + + + +[[beans-factory-scopes-custom-using]] +=== Using a Custom Scope + +After you write and test one or more custom `Scope` implementations, you need to make +the Spring container aware of your new scopes. The following method is the central +method to register a new `Scope` with the Spring container: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + void registerScope(String scopeName, Scope scope); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun registerScope(scopeName: String, scope: Scope) +---- + +This method is declared on the `ConfigurableBeanFactory` interface, which is available +through the `BeanFactory` property on most of the concrete `ApplicationContext` +implementations that ship with Spring. + +The first argument to the `registerScope(..)` method is the unique name associated with +a scope. Examples of such names in the Spring container itself are `singleton` and +`prototype`. The second argument to the `registerScope(..)` method is an actual instance +of the custom `Scope` implementation that you wish to register and use. + +Suppose that you write your custom `Scope` implementation, and then register it as shown +in the next example. + +NOTE: The next example uses `SimpleThreadScope`, which is included with Spring but is not +registered by default. The instructions would be the same for your own custom `Scope` +implementations. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Scope threadScope = new SimpleThreadScope(); + beanFactory.registerScope("thread", threadScope); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val threadScope = SimpleThreadScope() + beanFactory.registerScope("thread", threadScope) +---- + +You can then create bean definitions that adhere to the scoping rules of your custom +`Scope`, as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +With a custom `Scope` implementation, you are not limited to programmatic registration +of the scope. You can also do the `Scope` registration declaratively, by using the +`CustomScopeConfigurer` class, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + + + + + + + + +---- + +NOTE: When you place `` within a `` declaration for a +`FactoryBean` implementation, it is the factory bean itself that is scoped, not the object +returned from `getObject()`. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc b/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc new file mode 100644 index 000000000000..8ceef04028d5 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc @@ -0,0 +1,43 @@ +[[beans-introduction]] += Introduction to the Spring IoC Container and Beans + +This chapter covers the Spring Framework implementation of the Inversion of Control +(IoC) principle. IoC is also known as dependency injection (DI). It is a process whereby +objects define their dependencies (that is, the other objects they work with) only through +constructor arguments, arguments to a factory method, or properties that are set on the +object instance after it is constructed or returned from a factory method. The container +then injects those dependencies when it creates the bean. This process is fundamentally +the inverse (hence the name, Inversion of Control) of the bean itself +controlling the instantiation or location of its dependencies by using direct +construction of classes or a mechanism such as the Service Locator pattern. + +The `org.springframework.beans` and `org.springframework.context` packages are the basis +for Spring Framework's IoC container. The +{api-spring-framework}/beans/factory/BeanFactory.html[`BeanFactory`] +interface provides an advanced configuration mechanism capable of managing any type of +object. +{api-spring-framework}/context/ApplicationContext.html[`ApplicationContext`] +is a sub-interface of `BeanFactory`. It adds: + +* Easier integration with Spring's AOP features +* Message resource handling (for use in internationalization) +* Event publication +* Application-layer specific contexts such as the `WebApplicationContext` +for use in web applications. + +In short, the `BeanFactory` provides the configuration framework and basic functionality, +and the `ApplicationContext` adds more enterprise-specific functionality. The +`ApplicationContext` is a complete superset of the `BeanFactory` and is used exclusively +in this chapter in descriptions of Spring's IoC container. For more information on using +the `BeanFactory` instead of the `ApplicationContext,` see the section covering the +<>. + +In Spring, the objects that form the backbone of your application and that are managed +by the Spring IoC container are called beans. A bean is an object that is +instantiated, assembled, and managed by a Spring IoC container. Otherwise, a +bean is simply one of many objects in your application. Beans, and the dependencies +among them, are reflected in the configuration metadata used by a container. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/java.adoc b/framework-docs/modules/ROOT/pages/core/beans/java.adoc new file mode 100644 index 000000000000..7cd289d7c44e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/java.adoc @@ -0,0 +1,18 @@ +[[beans-java]] += Java-based Container Configuration + +This section covers how to use annotations in your Java code to configure the Spring +container. It includes the following topics: + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/basic-concepts.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/basic-concepts.adoc new file mode 100644 index 000000000000..70236637f5a4 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/java/basic-concepts.adoc @@ -0,0 +1,82 @@ +[[beans-java-basic-concepts]] += Basic Concepts: `@Bean` and `@Configuration` + +The central artifacts in Spring's Java configuration support are +`@Configuration`-annotated classes and `@Bean`-annotated methods. + +The `@Bean` annotation is used to indicate that a method instantiates, configures, and +initializes a new object to be managed by the Spring IoC container. For those familiar +with Spring's `` XML configuration, the `@Bean` annotation plays the same role as +the `` element. You can use `@Bean`-annotated methods with any Spring +`@Component`. However, they are most often used with `@Configuration` beans. + +Annotating a class with `@Configuration` indicates that its primary purpose is as a +source of bean definitions. Furthermore, `@Configuration` classes let inter-bean +dependencies be defined by calling other `@Bean` methods in the same class. +The simplest possible `@Configuration` class reads as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public MyServiceImpl myService() { + return new MyServiceImpl(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun myService(): MyServiceImpl { + return MyServiceImpl() + } + } +---- + +The preceding `AppConfig` class is equivalent to the following Spring `` XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +.Full @Configuration vs "`lite`" @Bean mode? +**** +When `@Bean` methods are declared within classes that are not annotated with +`@Configuration`, they are referred to as being processed in a "`lite`" mode. Bean methods +declared in a `@Component` or even in a plain old class are considered to be "`lite`", +with a different primary purpose of the containing class and a `@Bean` method +being a sort of bonus there. For example, service components may expose management views +to the container through an additional `@Bean` method on each applicable component class. +In such scenarios, `@Bean` methods are a general-purpose factory method mechanism. + +Unlike full `@Configuration`, lite `@Bean` methods cannot declare inter-bean dependencies. +Instead, they operate on their containing component's internal state and, optionally, on +arguments that they may declare. Such a `@Bean` method should therefore not invoke other +`@Bean` methods. Each such method is literally only a factory method for a particular +bean reference, without any special runtime semantics. The positive side-effect here is +that no CGLIB subclassing has to be applied at runtime, so there are no limitations in +terms of class design (that is, the containing class may be `final` and so forth). + +In common scenarios, `@Bean` methods are to be declared within `@Configuration` classes, +ensuring that "`full`" mode is always used and that cross-method references therefore +get redirected to the container's lifecycle management. This prevents the same +`@Bean` method from accidentally being invoked through a regular Java call, which helps +to reduce subtle bugs that can be hard to track down when operating in "`lite`" mode. +**** + +The `@Bean` and `@Configuration` annotations are discussed in depth in the following sections. +First, however, we cover the various ways of creating a spring container by using +Java-based configuration. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc new file mode 100644 index 000000000000..7872e94cfa72 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc @@ -0,0 +1,518 @@ +[[beans-java-bean-annotation]] += Using the `@Bean` Annotation + +`@Bean` is a method-level annotation and a direct analog of the XML `` element. +The annotation supports some of the attributes offered by ``, such as: + +* <> +* <> +* <> +* `name`. + +You can use the `@Bean` annotation in a `@Configuration`-annotated or in a +`@Component`-annotated class. + + +[[beans-java-declaring-a-bean]] +== Declaring a Bean + +To declare a bean, you can annotate a method with the `@Bean` annotation. You use this +method to register a bean definition within an `ApplicationContext` of the type +specified as the method's return value. By default, the bean name is the same as +the method name. The following example shows a `@Bean` method declaration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public TransferServiceImpl transferService() { + return new TransferServiceImpl(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun transferService() = TransferServiceImpl() + } +---- + +The preceding configuration is exactly equivalent to the following Spring XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +Both declarations make a bean named `transferService` available in the +`ApplicationContext`, bound to an object instance of type `TransferServiceImpl`, as the +following text image shows: + +[literal,subs="verbatim,quotes"] +---- +transferService -> com.acme.TransferServiceImpl +---- + +You can also use default methods to define beans. This allows composition of bean +configurations by implementing interfaces with bean definitions on default methods. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public interface BaseConfig { + + @Bean + default TransferServiceImpl transferService() { + return new TransferServiceImpl(); + } + } + + @Configuration + public class AppConfig implements BaseConfig { + + } +---- + +You can also declare your `@Bean` method with an interface (or base class) +return type, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public TransferService transferService() { + return new TransferServiceImpl(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun transferService(): TransferService { + return TransferServiceImpl() + } + } +---- + +However, this limits the visibility for advance type prediction to the specified +interface type (`TransferService`). Then, with the full type (`TransferServiceImpl`) +known to the container only once the affected singleton bean has been instantiated. +Non-lazy singleton beans get instantiated according to their declaration order, +so you may see different type matching results depending on when another component +tries to match by a non-declared type (such as `@Autowired TransferServiceImpl`, +which resolves only once the `transferService` bean has been instantiated). + +TIP: If you consistently refer to your types by a declared service interface, your +`@Bean` return types may safely join that design decision. However, for components +that implement several interfaces or for components potentially referred to by their +implementation type, it is safer to declare the most specific return type possible +(at least as specific as required by the injection points that refer to your bean). + + +[[beans-java-dependencies]] +== Bean Dependencies + +A `@Bean`-annotated method can have an arbitrary number of parameters that describe the +dependencies required to build that bean. For instance, if our `TransferService` +requires an `AccountRepository`, we can materialize that dependency with a method +parameter, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public TransferService transferService(AccountRepository accountRepository) { + return new TransferServiceImpl(accountRepository); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun transferService(accountRepository: AccountRepository): TransferService { + return TransferServiceImpl(accountRepository) + } + } +---- + + +The resolution mechanism is pretty much identical to constructor-based dependency +injection. See <> for more details. + + +[[beans-java-lifecycle-callbacks]] +== Receiving Lifecycle Callbacks + +Any classes defined with the `@Bean` annotation support the regular lifecycle callbacks +and can use the `@PostConstruct` and `@PreDestroy` annotations from JSR-250. See +<> for further +details. + +The regular Spring <> callbacks are fully supported as +well. If a bean implements `InitializingBean`, `DisposableBean`, or `Lifecycle`, their +respective methods are called by the container. + +The standard set of `*Aware` interfaces (such as <>, +<>, +<>, +<>, and so on) are also fully supported. + +The `@Bean` annotation supports specifying arbitrary initialization and destruction +callback methods, much like Spring XML's `init-method` and `destroy-method` attributes +on the `bean` element, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class BeanOne { + + public void init() { + // initialization logic + } + } + + public class BeanTwo { + + public void cleanup() { + // destruction logic + } + } + + @Configuration + public class AppConfig { + + @Bean(initMethod = "init") + public BeanOne beanOne() { + return new BeanOne(); + } + + @Bean(destroyMethod = "cleanup") + public BeanTwo beanTwo() { + return new BeanTwo(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +class BeanOne { + + fun init() { + // initialization logic + } +} + +class BeanTwo { + + fun cleanup() { + // destruction logic + } +} + +@Configuration +class AppConfig { + + @Bean(initMethod = "init") + fun beanOne() = BeanOne() + + @Bean(destroyMethod = "cleanup") + fun beanTwo() = BeanTwo() +} +---- + +[NOTE] +===== +By default, beans defined with Java configuration that have a public `close` or `shutdown` +method are automatically enlisted with a destruction callback. If you have a public +`close` or `shutdown` method and you do not wish for it to be called when the container +shuts down, you can add `@Bean(destroyMethod = "")` to your bean definition to disable the +default `(inferred)` mode. + +You may want to do that by default for a resource that you acquire with JNDI, as its +lifecycle is managed outside the application. In particular, make sure to always do it +for a `DataSource`, as it is known to be problematic on Jakarta EE application servers. + +The following example shows how to prevent an automatic destruction callback for a +`DataSource`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Bean(destroyMethod = "") + public DataSource dataSource() throws NamingException { + return (DataSource) jndiTemplate.lookup("MyDS"); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Bean(destroyMethod = "") + fun dataSource(): DataSource { + return jndiTemplate.lookup("MyDS") as DataSource + } +---- + +Also, with `@Bean` methods, you typically use programmatic JNDI lookups, either by +using Spring's `JndiTemplate` or `JndiLocatorDelegate` helpers or straight JNDI +`InitialContext` usage but not the `JndiObjectFactoryBean` variant (which would force +you to declare the return type as the `FactoryBean` type instead of the actual target +type, making it harder to use for cross-reference calls in other `@Bean` methods that +intend to refer to the provided resource here). +===== + +In the case of `BeanOne` from the example above the preceding note, it would be equally valid to call the `init()` +method directly during construction, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public BeanOne beanOne() { + BeanOne beanOne = new BeanOne(); + beanOne.init(); + return beanOne; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun beanOne() = BeanOne().apply { + init() + } + + // ... + } +---- + +TIP: When you work directly in Java, you can do anything you like with your objects and do +not always need to rely on the container lifecycle. + + +[[beans-java-specifying-bean-scope]] +== Specifying Bean Scope + +Spring includes the `@Scope` annotation so that you can specify the scope of a bean. + +[[beans-java-available-scopes]] +=== Using the `@Scope` Annotation + +You can specify that your beans defined with the `@Bean` annotation should have a +specific scope. You can use any of the standard scopes specified in the +<> section. + +The default scope is `singleton`, but you can override this with the `@Scope` annotation, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class MyConfiguration { + + @Bean + @Scope("prototype") + public Encryptor encryptor() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class MyConfiguration { + + @Bean + @Scope("prototype") + fun encryptor(): Encryptor { + // ... + } + } +---- + +[[beans-java-scoped-proxy]] +=== `@Scope` and `scoped-proxy` + +Spring offers a convenient way of working with scoped dependencies through +<>. The easiest way to create +such a proxy when using the XML configuration is the `` element. +Configuring your beans in Java with a `@Scope` annotation offers equivalent support +with the `proxyMode` attribute. The default is `ScopedProxyMode.DEFAULT`, which +typically indicates that no scoped proxy should be created unless a different default +has been configured at the component-scan instruction level. You can specify +`ScopedProxyMode.TARGET_CLASS`, `ScopedProxyMode.INTERFACES` or `ScopedProxyMode.NO`. + +If you port the scoped proxy example from the XML reference documentation (see +<>) to our `@Bean` using Java, +it resembles the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // an HTTP Session-scoped bean exposed as a proxy + @Bean + @SessionScope + public UserPreferences userPreferences() { + return new UserPreferences(); + } + + @Bean + public Service userService() { + UserService service = new SimpleUserService(); + // a reference to the proxied userPreferences bean + service.setUserPreferences(userPreferences()); + return service; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // an HTTP Session-scoped bean exposed as a proxy + @Bean + @SessionScope + fun userPreferences() = UserPreferences() + + @Bean + fun userService(): Service { + return SimpleUserService().apply { + // a reference to the proxied userPreferences bean + setUserPreferences(userPreferences()) + } + } +---- + +[[beans-java-customizing-bean-naming]] +== Customizing Bean Naming + +By default, configuration classes use a `@Bean` method's name as the name of the +resulting bean. This functionality can be overridden, however, with the `name` attribute, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean("myThing") + public Thing thing() { + return new Thing(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean("myThing") + fun thing() = Thing() + } +---- + + +[[beans-java-bean-aliasing]] +== Bean Aliasing + +As discussed in <>, it is sometimes desirable to give a single bean +multiple names, otherwise known as bean aliasing. The `name` attribute of the `@Bean` +annotation accepts a String array for this purpose. The following example shows how to set +a number of aliases for a bean: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean({"dataSource", "subsystemA-dataSource", "subsystemB-dataSource"}) + public DataSource dataSource() { + // instantiate, configure and return DataSource bean... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean("dataSource", "subsystemA-dataSource", "subsystemB-dataSource") + fun dataSource(): DataSource { + // instantiate, configure and return DataSource bean... + } + } +---- + + +[[beans-java-bean-description]] +== Bean Description + +Sometimes, it is helpful to provide a more detailed textual description of a bean. This can +be particularly useful when beans are exposed (perhaps through JMX) for monitoring purposes. + +To add a description to a `@Bean`, you can use the +{api-spring-framework}/context/annotation/Description.html[`@Description`] +annotation, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + @Description("Provides a basic example of a bean") + public Thing thing() { + return new Thing(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + @Description("Provides a basic example of a bean") + fun thing() = Thing() + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc new file mode 100644 index 000000000000..9b02fa8f3367 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc @@ -0,0 +1,777 @@ +[[beans-java-composing-configuration-classes]] += Composing Java-based Configurations + +Spring's Java-based configuration feature lets you compose annotations, which can reduce +the complexity of your configuration. + + +[[beans-java-using-import]] +== Using the `@Import` Annotation + +Much as the `` element is used within Spring XML files to aid in modularizing +configurations, the `@Import` annotation allows for loading `@Bean` definitions from +another configuration class, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class ConfigA { + + @Bean + public A a() { + return new A(); + } + } + + @Configuration + @Import(ConfigA.class) + public class ConfigB { + + @Bean + public B b() { + return new B(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class ConfigA { + + @Bean + fun a() = A() + } + + @Configuration + @Import(ConfigA::class) + class ConfigB { + + @Bean + fun b() = B() + } +---- + +Now, rather than needing to specify both `ConfigA.class` and `ConfigB.class` when +instantiating the context, only `ConfigB` needs to be supplied explicitly, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static void main(String[] args) { + ApplicationContext ctx = new AnnotationConfigApplicationContext(ConfigB.class); + + // now both beans A and B will be available... + A a = ctx.getBean(A.class); + B b = ctx.getBean(B.class); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + fun main() { + val ctx = AnnotationConfigApplicationContext(ConfigB::class.java) + + // now both beans A and B will be available... + val a = ctx.getBean() + val b = ctx.getBean() + } +---- + +This approach simplifies container instantiation, as only one class needs to be dealt +with, rather than requiring you to remember a potentially large number of +`@Configuration` classes during construction. + +TIP: As of Spring Framework 4.2, `@Import` also supports references to regular component +classes, analogous to the `AnnotationConfigApplicationContext.register` method. +This is particularly useful if you want to avoid component scanning, by using a few +configuration classes as entry points to explicitly define all your components. + +[[beans-java-injecting-imported-beans]] +=== Injecting Dependencies on Imported `@Bean` Definitions + +The preceding example works but is simplistic. In most practical scenarios, beans have +dependencies on one another across configuration classes. When using XML, this is not an +issue, because no compiler is involved, and you can declare +`ref="someBean"` and trust Spring to work it out during container initialization. +When using `@Configuration` classes, the Java compiler places constraints on +the configuration model, in that references to other beans must be valid Java syntax. + +Fortunately, solving this problem is simple. As <>, +a `@Bean` method can have an arbitrary number of parameters that describe the bean +dependencies. Consider the following more real-world scenario with several `@Configuration` +classes, each depending on beans declared in the others: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class ServiceConfig { + + @Bean + public TransferService transferService(AccountRepository accountRepository) { + return new TransferServiceImpl(accountRepository); + } + } + + @Configuration + public class RepositoryConfig { + + @Bean + public AccountRepository accountRepository(DataSource dataSource) { + return new JdbcAccountRepository(dataSource); + } + } + + @Configuration + @Import({ServiceConfig.class, RepositoryConfig.class}) + public class SystemTestConfig { + + @Bean + public DataSource dataSource() { + // return new DataSource + } + } + + public static void main(String[] args) { + ApplicationContext ctx = new AnnotationConfigApplicationContext(SystemTestConfig.class); + // everything wires up across configuration classes... + TransferService transferService = ctx.getBean(TransferService.class); + transferService.transfer(100.00, "A123", "C456"); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + @Configuration + class ServiceConfig { + + @Bean + fun transferService(accountRepository: AccountRepository): TransferService { + return TransferServiceImpl(accountRepository) + } + } + + @Configuration + class RepositoryConfig { + + @Bean + fun accountRepository(dataSource: DataSource): AccountRepository { + return JdbcAccountRepository(dataSource) + } + } + + @Configuration + @Import(ServiceConfig::class, RepositoryConfig::class) + class SystemTestConfig { + + @Bean + fun dataSource(): DataSource { + // return new DataSource + } + } + + + fun main() { + val ctx = AnnotationConfigApplicationContext(SystemTestConfig::class.java) + // everything wires up across configuration classes... + val transferService = ctx.getBean() + transferService.transfer(100.00, "A123", "C456") + } +---- + + +There is another way to achieve the same result. Remember that `@Configuration` classes are +ultimately only another bean in the container: This means that they can take advantage of +`@Autowired` and `@Value` injection and other features the same as any other bean. + +[WARNING] +==== +Make sure that the dependencies you inject that way are of the simplest kind only. `@Configuration` +classes are processed quite early during the initialization of the context, and forcing a dependency +to be injected this way may lead to unexpected early initialization. Whenever possible, resort to +parameter-based injection, as in the preceding example. + +Also, be particularly careful with `BeanPostProcessor` and `BeanFactoryPostProcessor` definitions +through `@Bean`. Those should usually be declared as `static @Bean` methods, not triggering the +instantiation of their containing configuration class. Otherwise, `@Autowired` and `@Value` may not +work on the configuration class itself, since it is possible to create it as a bean instance earlier than +{api-spring-framework}/beans/factory/annotation/AutowiredAnnotationBeanPostProcessor.html[`AutowiredAnnotationBeanPostProcessor`]. +==== + +The following example shows how one bean can be autowired to another bean: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class ServiceConfig { + + @Autowired + private AccountRepository accountRepository; + + @Bean + public TransferService transferService() { + return new TransferServiceImpl(accountRepository); + } + } + + @Configuration + public class RepositoryConfig { + + private final DataSource dataSource; + + public RepositoryConfig(DataSource dataSource) { + this.dataSource = dataSource; + } + + @Bean + public AccountRepository accountRepository() { + return new JdbcAccountRepository(dataSource); + } + } + + @Configuration + @Import({ServiceConfig.class, RepositoryConfig.class}) + public class SystemTestConfig { + + @Bean + public DataSource dataSource() { + // return new DataSource + } + } + + public static void main(String[] args) { + ApplicationContext ctx = new AnnotationConfigApplicationContext(SystemTestConfig.class); + // everything wires up across configuration classes... + TransferService transferService = ctx.getBean(TransferService.class); + transferService.transfer(100.00, "A123", "C456"); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + @Configuration + class ServiceConfig { + + @Autowired + lateinit var accountRepository: AccountRepository + + @Bean + fun transferService(): TransferService { + return TransferServiceImpl(accountRepository) + } + } + + @Configuration + class RepositoryConfig(private val dataSource: DataSource) { + + @Bean + fun accountRepository(): AccountRepository { + return JdbcAccountRepository(dataSource) + } + } + + @Configuration + @Import(ServiceConfig::class, RepositoryConfig::class) + class SystemTestConfig { + + @Bean + fun dataSource(): DataSource { + // return new DataSource + } + } + + fun main() { + val ctx = AnnotationConfigApplicationContext(SystemTestConfig::class.java) + // everything wires up across configuration classes... + val transferService = ctx.getBean() + transferService.transfer(100.00, "A123", "C456") + } +---- + +TIP: Constructor injection in `@Configuration` classes is only supported as of Spring +Framework 4.3. Note also that there is no need to specify `@Autowired` if the target +bean defines only one constructor. + +.[[beans-java-injecting-imported-beans-fq]]Fully-qualifying imported beans for ease of navigation +-- +In the preceding scenario, using `@Autowired` works well and provides the desired +modularity, but determining exactly where the autowired bean definitions are declared is +still somewhat ambiguous. For example, as a developer looking at `ServiceConfig`, how do +you know exactly where the `@Autowired AccountRepository` bean is declared? It is not +explicit in the code, and this may be just fine. Remember that the +https://spring.io/tools[Spring Tools for Eclipse] provides tooling that +can render graphs showing how everything is wired, which may be all you need. Also, +your Java IDE can easily find all declarations and uses of the `AccountRepository` type +and quickly show you the location of `@Bean` methods that return that type. + +In cases where this ambiguity is not acceptable and you wish to have direct navigation +from within your IDE from one `@Configuration` class to another, consider autowiring the +configuration classes themselves. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class ServiceConfig { + + @Autowired + private RepositoryConfig repositoryConfig; + + @Bean + public TransferService transferService() { + // navigate 'through' the config class to the @Bean method! + return new TransferServiceImpl(repositoryConfig.accountRepository()); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +@Configuration +class ServiceConfig { + + @Autowired + private lateinit var repositoryConfig: RepositoryConfig + + @Bean + fun transferService(): TransferService { + // navigate 'through' the config class to the @Bean method! + return TransferServiceImpl(repositoryConfig.accountRepository()) + } +} +---- + +In the preceding situation, where `AccountRepository` is defined is completely explicit. +However, `ServiceConfig` is now tightly coupled to `RepositoryConfig`. That is the +tradeoff. This tight coupling can be somewhat mitigated by using interface-based or +abstract class-based `@Configuration` classes. Consider the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class ServiceConfig { + + @Autowired + private RepositoryConfig repositoryConfig; + + @Bean + public TransferService transferService() { + return new TransferServiceImpl(repositoryConfig.accountRepository()); + } + } + + @Configuration + public interface RepositoryConfig { + + @Bean + AccountRepository accountRepository(); + } + + @Configuration + public class DefaultRepositoryConfig implements RepositoryConfig { + + @Bean + public AccountRepository accountRepository() { + return new JdbcAccountRepository(...); + } + } + + @Configuration + @Import({ServiceConfig.class, DefaultRepositoryConfig.class}) // import the concrete config! + public class SystemTestConfig { + + @Bean + public DataSource dataSource() { + // return DataSource + } + + } + + public static void main(String[] args) { + ApplicationContext ctx = new AnnotationConfigApplicationContext(SystemTestConfig.class); + TransferService transferService = ctx.getBean(TransferService.class); + transferService.transfer(100.00, "A123", "C456"); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + @Configuration + class ServiceConfig { + + @Autowired + private lateinit var repositoryConfig: RepositoryConfig + + @Bean + fun transferService(): TransferService { + return TransferServiceImpl(repositoryConfig.accountRepository()) + } + } + + @Configuration + interface RepositoryConfig { + + @Bean + fun accountRepository(): AccountRepository + } + + @Configuration + class DefaultRepositoryConfig : RepositoryConfig { + + @Bean + fun accountRepository(): AccountRepository { + return JdbcAccountRepository(...) + } + } + + @Configuration + @Import(ServiceConfig::class, DefaultRepositoryConfig::class) // import the concrete config! + class SystemTestConfig { + + @Bean + fun dataSource(): DataSource { + // return DataSource + } + + } + + fun main() { + val ctx = AnnotationConfigApplicationContext(SystemTestConfig::class.java) + val transferService = ctx.getBean() + transferService.transfer(100.00, "A123", "C456") + } +---- + +Now `ServiceConfig` is loosely coupled with respect to the concrete +`DefaultRepositoryConfig`, and built-in IDE tooling is still useful: You can easily +get a type hierarchy of `RepositoryConfig` implementations. In this +way, navigating `@Configuration` classes and their dependencies becomes no different +than the usual process of navigating interface-based code. +-- + +TIP: If you want to influence the startup creation order of certain beans, consider +declaring some of them as `@Lazy` (for creation on first access instead of on startup) +or as `@DependsOn` certain other beans (making sure that specific other beans are +created before the current bean, beyond what the latter's direct dependencies imply). + + +[[beans-java-conditional]] +== Conditionally Include `@Configuration` Classes or `@Bean` Methods + +It is often useful to conditionally enable or disable a complete `@Configuration` class +or even individual `@Bean` methods, based on some arbitrary system state. One common +example of this is to use the `@Profile` annotation to activate beans only when a specific +profile has been enabled in the Spring `Environment` (see <> +for details). + +The `@Profile` annotation is actually implemented by using a much more flexible annotation +called {api-spring-framework}/context/annotation/Conditional.html[`@Conditional`]. +The `@Conditional` annotation indicates specific +`org.springframework.context.annotation.Condition` implementations that should be +consulted before a `@Bean` is registered. + +Implementations of the `Condition` interface provide a `matches(...)` +method that returns `true` or `false`. For example, the following listing shows the actual +`Condition` implementation used for `@Profile`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Override + public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) { + // Read the @Profile annotation attributes + MultiValueMap attrs = metadata.getAllAnnotationAttributes(Profile.class.getName()); + if (attrs != null) { + for (Object value : attrs.get("value")) { + if (context.getEnvironment().acceptsProfiles(((String[]) value))) { + return true; + } + } + return false; + } + return true; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + override fun matches(context: ConditionContext, metadata: AnnotatedTypeMetadata): Boolean { + // Read the @Profile annotation attributes + val attrs = metadata.getAllAnnotationAttributes(Profile::class.java.name) + if (attrs != null) { + for (value in attrs["value"]!!) { + if (context.environment.acceptsProfiles(Profiles.of(*value as Array))) { + return true + } + } + return false + } + return true + } +---- + +See the {api-spring-framework}/context/annotation/Conditional.html[`@Conditional`] +javadoc for more detail. + + +[[beans-java-combining]] +== Combining Java and XML Configuration + +Spring's `@Configuration` class support does not aim to be a 100% complete replacement +for Spring XML. Some facilities, such as Spring XML namespaces, remain an ideal way to +configure the container. In cases where XML is convenient or necessary, you have a +choice: either instantiate the container in an "`XML-centric`" way by using, for example, +`ClassPathXmlApplicationContext`, or instantiate it in a "`Java-centric`" way by using +`AnnotationConfigApplicationContext` and the `@ImportResource` annotation to import XML +as needed. + +[[beans-java-combining-xml-centric]] +=== XML-centric Use of `@Configuration` Classes + +It may be preferable to bootstrap the Spring container from XML and include +`@Configuration` classes in an ad-hoc fashion. For example, in a large existing codebase +that uses Spring XML, it is easier to create `@Configuration` classes on an +as-needed basis and include them from the existing XML files. Later in this section, we cover the +options for using `@Configuration` classes in this kind of "`XML-centric`" situation. + +.[[beans-java-combining-xml-centric-declare-as-bean]]Declaring `@Configuration` classes as plain Spring `` elements +-- +Remember that `@Configuration` classes are ultimately bean definitions in the +container. In this series examples, we create a `@Configuration` class named `AppConfig` and +include it within `system-test-config.xml` as a `` definition. Because +`` is switched on, the container recognizes the +`@Configuration` annotation and processes the `@Bean` methods declared in `AppConfig` +properly. + +The following example shows an ordinary configuration class in Java: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Autowired + private DataSource dataSource; + + @Bean + public AccountRepository accountRepository() { + return new JdbcAccountRepository(dataSource); + } + + @Bean + public TransferService transferService() { + return new TransferService(accountRepository()); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Autowired + private lateinit var dataSource: DataSource + + @Bean + fun accountRepository(): AccountRepository { + return JdbcAccountRepository(dataSource) + } + + @Bean + fun transferService() = TransferService(accountRepository()) + } +---- + +The following example shows part of a sample `system-test-config.xml` file: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + +---- + +The following example shows a possible `jdbc.properties` file: + +[literal,subs="verbatim,quotes"] +---- +jdbc.url=jdbc:hsqldb:hsql://localhost/xdb +jdbc.username=sa +jdbc.password= +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static void main(String[] args) { + ApplicationContext ctx = new ClassPathXmlApplicationContext("classpath:/com/acme/system-test-config.xml"); + TransferService transferService = ctx.getBean(TransferService.class); + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun main() { + val ctx = ClassPathXmlApplicationContext("classpath:/com/acme/system-test-config.xml") + val transferService = ctx.getBean() + // ... + } +---- + + +NOTE: In `system-test-config.xml` file, the `AppConfig` `` does not declare an `id` +element. While it would be acceptable to do so, it is unnecessary, given that no other bean +ever refers to it, and it is unlikely to be explicitly fetched from the container by name. +Similarly, the `DataSource` bean is only ever autowired by type, so an explicit bean `id` +is not strictly required. +-- + +.[[beans-java-combining-xml-centric-component-scan]] Using to pick up `@Configuration` classes +-- +Because `@Configuration` is meta-annotated with `@Component`, `@Configuration`-annotated +classes are automatically candidates for component scanning. Using the same scenario as +described in the previous example, we can redefine `system-test-config.xml` to take advantage of component-scanning. +Note that, in this case, we need not explicitly declare +``, because `` enables the same +functionality. + +The following example shows the modified `system-test-config.xml` file: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + +---- +-- + +[[beans-java-combining-java-centric]] +=== `@Configuration` Class-centric Use of XML with `@ImportResource` + +In applications where `@Configuration` classes are the primary mechanism for configuring +the container, it is still likely necessary to use at least some XML. In these +scenarios, you can use `@ImportResource` and define only as much XML as you need. Doing +so achieves a "`Java-centric`" approach to configuring the container and keeps XML to a +bare minimum. The following example (which includes a configuration class, an XML file +that defines a bean, a properties file, and the `main` class) shows how to use +the `@ImportResource` annotation to achieve "`Java-centric`" configuration that uses XML +as needed: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ImportResource("classpath:/com/acme/properties-config.xml") + public class AppConfig { + + @Value("${jdbc.url}") + private String url; + + @Value("${jdbc.username}") + private String username; + + @Value("${jdbc.password}") + private String password; + + @Bean + public DataSource dataSource() { + return new DriverManagerDataSource(url, username, password); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ImportResource("classpath:/com/acme/properties-config.xml") + class AppConfig { + + @Value("\${jdbc.url}") + private lateinit var url: String + + @Value("\${jdbc.username}") + private lateinit var username: String + + @Value("\${jdbc.password}") + private lateinit var password: String + + @Bean + fun dataSource(): DataSource { + return DriverManagerDataSource(url, username, password) + } + } +---- + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + properties-config.xml + + + +---- + +[literal,subs="verbatim,quotes"] +---- +jdbc.properties +jdbc.url=jdbc:hsqldb:hsql://localhost/xdb +jdbc.username=sa +jdbc.password= +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static void main(String[] args) { + ApplicationContext ctx = new AnnotationConfigApplicationContext(AppConfig.class); + TransferService transferService = ctx.getBean(TransferService.class); + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + fun main() { + val ctx = AnnotationConfigApplicationContext(AppConfig::class.java) + val transferService = ctx.getBean() + // ... + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc new file mode 100644 index 000000000000..74907e874b25 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc @@ -0,0 +1,240 @@ +[[beans-java-configuration-annotation]] += Using the `@Configuration` annotation + +`@Configuration` is a class-level annotation indicating that an object is a source of +bean definitions. `@Configuration` classes declare beans through `@Bean`-annotated +methods. Calls to `@Bean` methods on `@Configuration` classes can also be used to define +inter-bean dependencies. See <> for a general introduction. + + +[[beans-java-injecting-dependencies]] +== Injecting Inter-bean Dependencies + +When beans have dependencies on one another, expressing that dependency is as simple +as having one bean method call another, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public BeanOne beanOne() { + return new BeanOne(beanTwo()); + } + + @Bean + public BeanTwo beanTwo() { + return new BeanTwo(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun beanOne() = BeanOne(beanTwo()) + + @Bean + fun beanTwo() = BeanTwo() + } +---- + +In the preceding example, `beanOne` receives a reference to `beanTwo` through constructor +injection. + +NOTE: This method of declaring inter-bean dependencies works only when the `@Bean` method +is declared within a `@Configuration` class. You cannot declare inter-bean dependencies +by using plain `@Component` classes. + + + +[[beans-java-method-injection]] +== Lookup Method Injection + +As noted earlier, <> is an +advanced feature that you should use rarely. It is useful in cases where a +singleton-scoped bean has a dependency on a prototype-scoped bean. Using Java for this +type of configuration provides a natural means for implementing this pattern. The +following example shows how to use lookup method injection: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public abstract class CommandManager { + public Object process(Object commandState) { + // grab a new instance of the appropriate Command interface + Command command = createCommand(); + // set the state on the (hopefully brand new) Command instance + command.setState(commandState); + return command.execute(); + } + + // okay... but where is the implementation of this method? + protected abstract Command createCommand(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + abstract class CommandManager { + fun process(commandState: Any): Any { + // grab a new instance of the appropriate Command interface + val command = createCommand() + // set the state on the (hopefully brand new) Command instance + command.setState(commandState) + return command.execute() + } + + // okay... but where is the implementation of this method? + protected abstract fun createCommand(): Command + } +---- + +By using Java configuration, you can create a subclass of `CommandManager` where +the abstract `createCommand()` method is overridden in such a way that it looks up a new +(prototype) command object. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Bean + @Scope("prototype") + public AsyncCommand asyncCommand() { + AsyncCommand command = new AsyncCommand(); + // inject dependencies here as required + return command; + } + + @Bean + public CommandManager commandManager() { + // return new anonymous implementation of CommandManager with createCommand() + // overridden to return a new prototype Command object + return new CommandManager() { + protected Command createCommand() { + return asyncCommand(); + } + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Bean + @Scope("prototype") + fun asyncCommand(): AsyncCommand { + val command = AsyncCommand() + // inject dependencies here as required + return command + } + + @Bean + fun commandManager(): CommandManager { + // return new anonymous implementation of CommandManager with createCommand() + // overridden to return a new prototype Command object + return object : CommandManager() { + override fun createCommand(): Command { + return asyncCommand() + } + } + } +---- + + +[[beans-java-further-information-java-config]] +== Further Information About How Java-based Configuration Works Internally + +Consider the following example, which shows a `@Bean` annotated method being called twice: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public ClientService clientService1() { + ClientServiceImpl clientService = new ClientServiceImpl(); + clientService.setClientDao(clientDao()); + return clientService; + } + + @Bean + public ClientService clientService2() { + ClientServiceImpl clientService = new ClientServiceImpl(); + clientService.setClientDao(clientDao()); + return clientService; + } + + @Bean + public ClientDao clientDao() { + return new ClientDaoImpl(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun clientService1(): ClientService { + return ClientServiceImpl().apply { + clientDao = clientDao() + } + } + + @Bean + fun clientService2(): ClientService { + return ClientServiceImpl().apply { + clientDao = clientDao() + } + } + + @Bean + fun clientDao(): ClientDao { + return ClientDaoImpl() + } + } +---- + +`clientDao()` has been called once in `clientService1()` and once in `clientService2()`. +Since this method creates a new instance of `ClientDaoImpl` and returns it, you would +normally expect to have two instances (one for each service). That definitely would be +problematic: In Spring, instantiated beans have a `singleton` scope by default. This is +where the magic comes in: All `@Configuration` classes are subclassed at startup-time +with `CGLIB`. In the subclass, the child method checks the container first for any +cached (scoped) beans before it calls the parent method and creates a new instance. + +NOTE: The behavior could be different according to the scope of your bean. We are talking +about singletons here. + +[NOTE] +==== +It is not necessary to add CGLIB to your classpath because CGLIB classes are repackaged +under the `org.springframework.cglib` package and included directly within the +`spring-core` JAR. +==== + +[TIP] +==== +There are a few restrictions due to the fact that CGLIB dynamically adds features at +startup-time. In particular, configuration classes must not be final. However, any +constructors are allowed on configuration classes, including the use of `@Autowired` or a +single non-default constructor declaration for default injection. + +If you prefer to avoid any CGLIB-imposed limitations, consider declaring your `@Bean` +methods on non-`@Configuration` classes (for example, on plain `@Component` classes +instead) or by annotating your configuration class with +`@Configuration(proxyBeanMethods = false)`. Cross-method calls between `@Bean` methods +are then not intercepted, so you have to exclusively rely on dependency injection at the +constructor or method level there. +==== + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc new file mode 100644 index 000000000000..9b3c6605aa71 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc @@ -0,0 +1,255 @@ +[[beans-java-instantiating-container]] += Instantiating the Spring Container by Using `AnnotationConfigApplicationContext` + +The following sections document Spring's `AnnotationConfigApplicationContext`, introduced in Spring +3.0. This versatile `ApplicationContext` implementation is capable of accepting not only +`@Configuration` classes as input but also plain `@Component` classes and classes +annotated with JSR-330 metadata. + +When `@Configuration` classes are provided as input, the `@Configuration` class itself +is registered as a bean definition and all declared `@Bean` methods within the class +are also registered as bean definitions. + +When `@Component` and JSR-330 classes are provided, they are registered as bean +definitions, and it is assumed that DI metadata such as `@Autowired` or `@Inject` are +used within those classes where necessary. + + +[[beans-java-instantiating-container-constructor]] +== Simple Construction + +In much the same way that Spring XML files are used as input when instantiating a +`ClassPathXmlApplicationContext`, you can use `@Configuration` classes as input when +instantiating an `AnnotationConfigApplicationContext`. This allows for completely +XML-free usage of the Spring container, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static void main(String[] args) { + ApplicationContext ctx = new AnnotationConfigApplicationContext(AppConfig.class); + MyService myService = ctx.getBean(MyService.class); + myService.doStuff(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + fun main() { + val ctx = AnnotationConfigApplicationContext(AppConfig::class.java) + val myService = ctx.getBean() + myService.doStuff() + } +---- + +As mentioned earlier, `AnnotationConfigApplicationContext` is not limited to working only +with `@Configuration` classes. Any `@Component` or JSR-330 annotated class may be supplied +as input to the constructor, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static void main(String[] args) { + ApplicationContext ctx = new AnnotationConfigApplicationContext(MyServiceImpl.class, Dependency1.class, Dependency2.class); + MyService myService = ctx.getBean(MyService.class); + myService.doStuff(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + fun main() { + val ctx = AnnotationConfigApplicationContext(MyServiceImpl::class.java, Dependency1::class.java, Dependency2::class.java) + val myService = ctx.getBean() + myService.doStuff() + } +---- + +The preceding example assumes that `MyServiceImpl`, `Dependency1`, and `Dependency2` use Spring +dependency injection annotations such as `@Autowired`. + + +[[beans-java-instantiating-container-register]] +== Building the Container Programmatically by Using `register(Class...)` + +You can instantiate an `AnnotationConfigApplicationContext` by using a no-arg constructor +and then configure it by using the `register()` method. This approach is particularly useful +when programmatically building an `AnnotationConfigApplicationContext`. The following +example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static void main(String[] args) { + AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); + ctx.register(AppConfig.class, OtherConfig.class); + ctx.register(AdditionalConfig.class); + ctx.refresh(); + MyService myService = ctx.getBean(MyService.class); + myService.doStuff(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + fun main() { + val ctx = AnnotationConfigApplicationContext() + ctx.register(AppConfig::class.java, OtherConfig::class.java) + ctx.register(AdditionalConfig::class.java) + ctx.refresh() + val myService = ctx.getBean() + myService.doStuff() + } +---- + + +[[beans-java-instantiating-container-scan]] +== Enabling Component Scanning with `scan(String...)` + +To enable component scanning, you can annotate your `@Configuration` class as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ComponentScan(basePackages = "com.acme") // <1> + public class AppConfig { + // ... + } +---- +<1> This annotation enables component scanning. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ComponentScan(basePackages = ["com.acme"]) // <1> + class AppConfig { + // ... + } +---- +<1> This annotation enables component scanning. + + +[TIP] +===== +Experienced Spring users may be familiar with the XML declaration equivalent from +Spring's `context:` namespace, shown in the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- +===== + +In the preceding example, the `com.acme` package is scanned to look for any +`@Component`-annotated classes, and those classes are registered as Spring bean +definitions within the container. `AnnotationConfigApplicationContext` exposes the +`scan(String...)` method to allow for the same component-scanning functionality, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public static void main(String[] args) { + AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); + ctx.scan("com.acme"); + ctx.refresh(); + MyService myService = ctx.getBean(MyService.class); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun main() { + val ctx = AnnotationConfigApplicationContext() + ctx.scan("com.acme") + ctx.refresh() + val myService = ctx.getBean() + } +---- + +NOTE: Remember that `@Configuration` classes are <> +with `@Component`, so they are candidates for component-scanning. In the preceding example, +assuming that `AppConfig` is declared within the `com.acme` package (or any package +underneath), it is picked up during the call to `scan()`. Upon `refresh()`, all its `@Bean` +methods are processed and registered as bean definitions within the container. + + +[[beans-java-instantiating-container-web]] +== Support for Web Applications with `AnnotationConfigWebApplicationContext` + +A `WebApplicationContext` variant of `AnnotationConfigApplicationContext` is available +with `AnnotationConfigWebApplicationContext`. You can use this implementation when +configuring the Spring `ContextLoaderListener` servlet listener, Spring MVC +`DispatcherServlet`, and so forth. The following `web.xml` snippet configures a typical +Spring MVC web application (note the use of the `contextClass` context-param and +init-param): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + contextClass + + org.springframework.web.context.support.AnnotationConfigWebApplicationContext + + + + + + contextConfigLocation + com.acme.AppConfig + + + + + org.springframework.web.context.ContextLoaderListener + + + + + dispatcher + org.springframework.web.servlet.DispatcherServlet + + + contextClass + + org.springframework.web.context.support.AnnotationConfigWebApplicationContext + + + + + contextConfigLocation + com.acme.web.MvcConfig + + + + + + dispatcher + /app/* + + +---- + +NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an +alternative to `AnnotationConfigWebApplicationContext`. See the +{api-spring-framework}/web/context/support/GenericWebApplicationContext.html[`GenericWebApplicationContext`] +javadoc for details. + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/standard-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/standard-annotations.adoc new file mode 100644 index 000000000000..77f58b4a694e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/standard-annotations.adoc @@ -0,0 +1,351 @@ +[[beans-standard-annotations]] += Using JSR 330 Standard Annotations + +Spring offers support for JSR-330 standard annotations (Dependency Injection). Those +annotations are scanned in the same way as the Spring annotations. To use them, you need +to have the relevant jars in your classpath. + +[NOTE] +===== +If you use Maven, the `jakarta.inject` artifact is available in the standard Maven +repository ( +https://repo.maven.apache.org/maven2/jakarta/inject/jakarta.inject-api/2.0.0/[https://repo.maven.apache.org/maven2/jakarta/inject/jakarta.inject-api/2.0.0/]). +You can add the following dependency to your file pom.xml: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + jakarta.inject + jakarta.inject-api + 2.0.0 + +---- +===== + + + +[[beans-inject-named]] +== Dependency Injection with `@Inject` and `@Named` + +Instead of `@Autowired`, you can use `@jakarta.inject.Inject` as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import jakarta.inject.Inject; + + public class SimpleMovieLister { + + private MovieFinder movieFinder; + + @Inject + public void setMovieFinder(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + + public void listMovies() { + this.movieFinder.findMovies(...); + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import jakarta.inject.Inject + + class SimpleMovieLister { + + @Inject + lateinit var movieFinder: MovieFinder + + + fun listMovies() { + movieFinder.findMovies(...) + // ... + } + } +---- + +As with `@Autowired`, you can use `@Inject` at the field level, method level +and constructor-argument level. Furthermore, you may declare your injection point as a +`Provider`, allowing for on-demand access to beans of shorter scopes or lazy access to +other beans through a `Provider.get()` call. The following example offers a variant of the +preceding example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import jakarta.inject.Inject; + import jakarta.inject.Provider; + + public class SimpleMovieLister { + + private Provider movieFinder; + + @Inject + public void setMovieFinder(Provider movieFinder) { + this.movieFinder = movieFinder; + } + + public void listMovies() { + this.movieFinder.get().findMovies(...); + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import jakarta.inject.Inject + + class SimpleMovieLister { + + @Inject + lateinit var movieFinder: Provider + + + fun listMovies() { + movieFinder.get().findMovies(...) + // ... + } + } +---- + +If you would like to use a qualified name for the dependency that should be injected, +you should use the `@Named` annotation, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import jakarta.inject.Inject; + import jakarta.inject.Named; + + public class SimpleMovieLister { + + private MovieFinder movieFinder; + + @Inject + public void setMovieFinder(@Named("main") MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import jakarta.inject.Inject + import jakarta.inject.Named + + class SimpleMovieLister { + + private lateinit var movieFinder: MovieFinder + + @Inject + fun setMovieFinder(@Named("main") movieFinder: MovieFinder) { + this.movieFinder = movieFinder + } + + // ... + } +---- + +As with `@Autowired`, `@Inject` can also be used with `java.util.Optional` or +`@Nullable`. This is even more applicable here, since `@Inject` does not have +a `required` attribute. The following pair of examples show how to use `@Inject` and +`@Nullable`: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public class SimpleMovieLister { + + @Inject + public void setMovieFinder(Optional movieFinder) { + // ... + } + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleMovieLister { + + @Inject + public void setMovieFinder(@Nullable MovieFinder movieFinder) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SimpleMovieLister { + + @Inject + var movieFinder: MovieFinder? = null + } +---- + + + +[[beans-named]] +== `@Named` and `@ManagedBean`: Standard Equivalents to the `@Component` Annotation + +Instead of `@Component`, you can use `@jakarta.inject.Named` or `jakarta.annotation.ManagedBean`, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import jakarta.inject.Inject; + import jakarta.inject.Named; + + @Named("movieListener") // @ManagedBean("movieListener") could be used as well + public class SimpleMovieLister { + + private MovieFinder movieFinder; + + @Inject + public void setMovieFinder(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import jakarta.inject.Inject + import jakarta.inject.Named + + @Named("movieListener") // @ManagedBean("movieListener") could be used as well + class SimpleMovieLister { + + @Inject + lateinit var movieFinder: MovieFinder + + // ... + } +---- + +It is very common to use `@Component` without specifying a name for the component. +`@Named` can be used in a similar fashion, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import jakarta.inject.Inject; + import jakarta.inject.Named; + + @Named + public class SimpleMovieLister { + + private MovieFinder movieFinder; + + @Inject + public void setMovieFinder(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import jakarta.inject.Inject + import jakarta.inject.Named + + @Named + class SimpleMovieLister { + + @Inject + lateinit var movieFinder: MovieFinder + + // ... + } +---- + +When you use `@Named` or `@ManagedBean`, you can use component scanning in the +exact same way as when you use Spring annotations, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ComponentScan(basePackages = "org.example") + public class AppConfig { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ComponentScan(basePackages = ["org.example"]) + class AppConfig { + // ... + } +---- + +NOTE: In contrast to `@Component`, the JSR-330 `@Named` and the JSR-250 `@ManagedBean` +annotations are not composable. You should use Spring's stereotype model for building +custom component annotations. + + + +[[beans-standard-annotations-limitations]] +== Limitations of JSR-330 Standard Annotations + +When you work with standard annotations, you should know that some significant +features are not available, as the following table shows: + +[[annotations-comparison]] +.Spring component model elements versus JSR-330 variants +|=== +| Spring| jakarta.inject.*| jakarta.inject restrictions / comments + +| @Autowired +| @Inject +| `@Inject` has no 'required' attribute. Can be used with Java 8's `Optional` instead. + +| @Component +| @Named / @ManagedBean +| JSR-330 does not provide a composable model, only a way to identify named components. + +| @Scope("singleton") +| @Singleton +| The JSR-330 default scope is like Spring's `prototype`. However, in order to keep it + consistent with Spring's general defaults, a JSR-330 bean declared in the Spring + container is a `singleton` by default. In order to use a scope other than `singleton`, + you should use Spring's `@Scope` annotation. `jakarta.inject` also provides a + `jakarta.inject.Scope` annotation: however, this one is only intended to be used + for creating custom annotations. + +| @Qualifier +| @Qualifier / @Named +| `jakarta.inject.Qualifier` is just a meta-annotation for building custom qualifiers. + Concrete `String` qualifiers (like Spring's `@Qualifier` with a value) can be associated + through `jakarta.inject.Named`. + +| @Value +| - +| no equivalent + +| @Lazy +| - +| no equivalent + +| ObjectFactory +| Provider +| `jakarta.inject.Provider` is a direct alternative to Spring's `ObjectFactory`, + only with a shorter `get()` method name. It can also be used in combination with + Spring's `@Autowired` or with non-annotated constructors and setter methods. +|=== + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions.adoc b/framework-docs/modules/ROOT/pages/core/expressions.adoc index 6d22a97e00f1..69cc559abf01 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions.adoc @@ -55,2126 +55,3 @@ The expression language supports the following functionality: -[[expressions-evaluation]] -== Evaluation - -This section introduces the simple use of SpEL interfaces and its expression language. -The complete language reference can be found in -<>. - -The following code introduces the SpEL API to evaluate the literal string expression, -`Hello World`. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - Expression exp = parser.parseExpression("'Hello World'"); // <1> - String message = (String) exp.getValue(); ----- -<1> The value of the message variable is `'Hello World'`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - val exp = parser.parseExpression("'Hello World'") // <1> - val message = exp.value as String ----- -<1> The value of the message variable is `'Hello World'`. - - -The SpEL classes and interfaces you are most likely to use are located in the -`org.springframework.expression` package and its sub-packages, such as `spel.support`. - -The `ExpressionParser` interface is responsible for parsing an expression string. In -the preceding example, the expression string is a string literal denoted by the surrounding single -quotation marks. The `Expression` interface is responsible for evaluating the previously defined -expression string. Two exceptions that can be thrown, `ParseException` and -`EvaluationException`, when calling `parser.parseExpression` and `exp.getValue`, -respectively. - -SpEL supports a wide range of features, such as calling methods, accessing properties, -and calling constructors. - -In the following example of method invocation, we call the `concat` method on the string literal: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - Expression exp = parser.parseExpression("'Hello World'.concat('!')"); // <1> - String message = (String) exp.getValue(); ----- -<1> The value of `message` is now 'Hello World!'. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - val exp = parser.parseExpression("'Hello World'.concat('!')") // <1> - val message = exp.value as String ----- -<1> The value of `message` is now 'Hello World!'. - -The following example of calling a JavaBean property calls the `String` property `Bytes`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - - // invokes 'getBytes()' - Expression exp = parser.parseExpression("'Hello World'.bytes"); // <1> - byte[] bytes = (byte[]) exp.getValue(); ----- -<1> This line converts the literal to a byte array. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - - // invokes 'getBytes()' - val exp = parser.parseExpression("'Hello World'.bytes") // <1> - val bytes = exp.value as ByteArray ----- -<1> This line converts the literal to a byte array. - -SpEL also supports nested properties by using the standard dot notation (such as -`prop1.prop2.prop3`) and also the corresponding setting of property values. -Public fields may also be accessed. - -The following example shows how to use dot notation to get the length of a literal: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - - // invokes 'getBytes().length' - Expression exp = parser.parseExpression("'Hello World'.bytes.length"); // <1> - int length = (Integer) exp.getValue(); ----- -<1> `'Hello World'.bytes.length` gives the length of the literal. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - - // invokes 'getBytes().length' - val exp = parser.parseExpression("'Hello World'.bytes.length") // <1> - val length = exp.value as Int ----- -<1> `'Hello World'.bytes.length` gives the length of the literal. - -The String's constructor can be called instead of using a string literal, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - Expression exp = parser.parseExpression("new String('hello world').toUpperCase()"); // <1> - String message = exp.getValue(String.class); ----- -<1> Construct a new `String` from the literal and make it be upper case. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - val exp = parser.parseExpression("new String('hello world').toUpperCase()") // <1> - val message = exp.getValue(String::class.java) ----- -<1> Construct a new `String` from the literal and make it be upper case. - - -Note the use of the generic method: `public T getValue(Class desiredResultType)`. -Using this method removes the need to cast the value of the expression to the desired -result type. An `EvaluationException` is thrown if the value cannot be cast to the -type `T` or converted by using the registered type converter. - -The more common usage of SpEL is to provide an expression string that is evaluated -against a specific object instance (called the root object). The following example shows -how to retrieve the `name` property from an instance of the `Inventor` class or -create a boolean condition: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Create and set a calendar - GregorianCalendar c = new GregorianCalendar(); - c.set(1856, 7, 9); - - // The constructor arguments are name, birthday, and nationality. - Inventor tesla = new Inventor("Nikola Tesla", c.getTime(), "Serbian"); - - ExpressionParser parser = new SpelExpressionParser(); - - Expression exp = parser.parseExpression("name"); // Parse name as an expression - String name = (String) exp.getValue(tesla); - // name == "Nikola Tesla" - - exp = parser.parseExpression("name == 'Nikola Tesla'"); - boolean result = exp.getValue(tesla, Boolean.class); - // result == true ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Create and set a calendar - val c = GregorianCalendar() - c.set(1856, 7, 9) - - // The constructor arguments are name, birthday, and nationality. - val tesla = Inventor("Nikola Tesla", c.time, "Serbian") - - val parser = SpelExpressionParser() - - var exp = parser.parseExpression("name") // Parse name as an expression - val name = exp.getValue(tesla) as String - // name == "Nikola Tesla" - - exp = parser.parseExpression("name == 'Nikola Tesla'") - val result = exp.getValue(tesla, Boolean::class.java) - // result == true ----- - - - - -[[expressions-evaluation-context]] -=== Understanding `EvaluationContext` - -The `EvaluationContext` interface is used when evaluating an expression to resolve -properties, methods, or fields and to help perform type conversion. Spring provides two -implementations. - -* `SimpleEvaluationContext`: Exposes a subset of essential SpEL language features and -configuration options, for categories of expressions that do not require the full extent -of the SpEL language syntax and should be meaningfully restricted. Examples include but -are not limited to data binding expressions and property-based filters. - -* `StandardEvaluationContext`: Exposes the full set of SpEL language features and -configuration options. You can use it to specify a default root object and to configure -every available evaluation-related strategy. - -`SimpleEvaluationContext` is designed to support only a subset of the SpEL language syntax. -It excludes Java type references, constructors, and bean references. It also requires -you to explicitly choose the level of support for properties and methods in expressions. -By default, the `create()` static factory method enables only read access to properties. -You can also obtain a builder to configure the exact level of support needed, targeting -one or some combination of the following: - -* Custom `PropertyAccessor` only (no reflection) -* Data binding properties for read-only access -* Data binding properties for read and write - - -[[expressions-type-conversion]] -==== Type Conversion - -By default, SpEL uses the conversion service available in Spring core -(`org.springframework.core.convert.ConversionService`). This conversion service comes -with many built-in converters for common conversions but is also fully extensible so that -you can add custom conversions between types. Additionally, it is -generics-aware. This means that, when you work with generic types in -expressions, SpEL attempts conversions to maintain type correctness for any objects -it encounters. - -What does this mean in practice? Suppose assignment, using `setValue()`, is being used -to set a `List` property. The type of the property is actually `List`. SpEL -recognizes that the elements of the list need to be converted to `Boolean` before -being placed in it. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - class Simple { - public List booleanList = new ArrayList<>(); - } - - Simple simple = new Simple(); - simple.booleanList.add(true); - - EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); - - // "false" is passed in here as a String. SpEL and the conversion service - // will recognize that it needs to be a Boolean and convert it accordingly. - parser.parseExpression("booleanList[0]").setValue(context, simple, "false"); - - // b is false - Boolean b = simple.booleanList.get(0); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class Simple { - var booleanList: MutableList = ArrayList() - } - - val simple = Simple() - simple.booleanList.add(true) - - val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() - - // "false" is passed in here as a String. SpEL and the conversion service - // will recognize that it needs to be a Boolean and convert it accordingly. - parser.parseExpression("booleanList[0]").setValue(context, simple, "false") - - // b is false - val b = simple.booleanList[0] ----- - - -[[expressions-parser-configuration]] -=== Parser Configuration - -It is possible to configure the SpEL expression parser by using a parser configuration -object (`org.springframework.expression.spel.SpelParserConfiguration`). The configuration -object controls the behavior of some of the expression components. For example, if you -index into an array or collection and the element at the specified index is `null`, SpEL -can automatically create the element. This is useful when using expressions made up of a -chain of property references. If you index into an array or list and specify an index -that is beyond the end of the current size of the array or list, SpEL can automatically -grow the array or list to accommodate that index. In order to add an element at the -specified index, SpEL will try to create the element using the element type's default -constructor before setting the specified value. If the element type does not have a -default constructor, `null` will be added to the array or list. If there is no built-in -or custom converter that knows how to set the value, `null` will remain in the array or -list at the specified index. The following example demonstrates how to automatically grow -the list: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - class Demo { - public List list; - } - - // Turn on: - // - auto null reference initialization - // - auto collection growing - SpelParserConfiguration config = new SpelParserConfiguration(true, true); - - ExpressionParser parser = new SpelExpressionParser(config); - - Expression expression = parser.parseExpression("list[3]"); - - Demo demo = new Demo(); - - Object o = expression.getValue(demo); - - // demo.list will now be a real collection of 4 entries - // Each entry is a new empty String ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class Demo { - var list: List? = null - } - - // Turn on: - // - auto null reference initialization - // - auto collection growing - val config = SpelParserConfiguration(true, true) - - val parser = SpelExpressionParser(config) - - val expression = parser.parseExpression("list[3]") - - val demo = Demo() - - val o = expression.getValue(demo) - - // demo.list will now be a real collection of 4 entries - // Each entry is a new empty String ----- - - - -[[expressions-spel-compilation]] -=== SpEL Compilation - -Spring Framework 4.1 includes a basic expression compiler. Expressions are usually -interpreted, which provides a lot of dynamic flexibility during evaluation but -does not provide optimum performance. For occasional expression usage, -this is fine, but, when used by other components such as Spring Integration, -performance can be very important, and there is no real need for the dynamism. - -The SpEL compiler is intended to address this need. During evaluation, the compiler -generates a Java class that embodies the expression behavior at runtime and uses that -class to achieve much faster expression evaluation. Due to the lack of typing around -expressions, the compiler uses information gathered during the interpreted evaluations -of an expression when performing compilation. For example, it does not know the type -of a property reference purely from the expression, but during the first interpreted -evaluation, it finds out what it is. Of course, basing compilation on such derived -information can cause trouble later if the types of the various expression elements -change over time. For this reason, compilation is best suited to expressions whose -type information is not going to change on repeated evaluations. - -Consider the following basic expression: - ----- -someArray[0].someProperty.someOtherProperty < 0.1 ----- - -Because the preceding expression involves array access, some property de-referencing, -and numeric operations, the performance gain can be very noticeable. In an example -micro benchmark run of 50000 iterations, it took 75ms to evaluate by using the -interpreter and only 3ms using the compiled version of the expression. - - -[[expressions-compiler-configuration]] -==== Compiler Configuration - -The compiler is not turned on by default, but you can turn it on in either of two -different ways. You can turn it on by using the parser configuration process -(<>) or by using a Spring property -when SpEL usage is embedded inside another component. This section discusses both of -these options. - -The compiler can operate in one of three modes, which are captured in the -`org.springframework.expression.spel.SpelCompilerMode` enum. The modes are as follows: - -* `OFF` (default): The compiler is switched off. -* `IMMEDIATE`: In immediate mode, the expressions are compiled as soon as possible. This -is typically after the first interpreted evaluation. If the compiled expression fails -(typically due to a type changing, as described earlier), the caller of the expression -evaluation receives an exception. -* `MIXED`: In mixed mode, the expressions silently switch between interpreted and compiled -mode over time. After some number of interpreted runs, they switch to compiled -form and, if something goes wrong with the compiled form (such as a type changing, as -described earlier), the expression automatically switches back to interpreted form -again. Sometime later, it may generate another compiled form and switch to it. Basically, -the exception that the user gets in `IMMEDIATE` mode is instead handled internally. - -`IMMEDIATE` mode exists because `MIXED` mode could cause issues for expressions that -have side effects. If a compiled expression blows up after partially succeeding, it -may have already done something that has affected the state of the system. If this -has happened, the caller may not want it to silently re-run in interpreted mode, -since part of the expression may be running twice. - -After selecting a mode, use the `SpelParserConfiguration` to configure the parser. The -following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - SpelParserConfiguration config = new SpelParserConfiguration(SpelCompilerMode.IMMEDIATE, - this.getClass().getClassLoader()); - - SpelExpressionParser parser = new SpelExpressionParser(config); - - Expression expr = parser.parseExpression("payload"); - - MyMessage message = new MyMessage(); - - Object payload = expr.getValue(message); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val config = SpelParserConfiguration(SpelCompilerMode.IMMEDIATE, - this.javaClass.classLoader) - - val parser = SpelExpressionParser(config) - - val expr = parser.parseExpression("payload") - - val message = MyMessage() - - val payload = expr.getValue(message) ----- - -When you specify the compiler mode, you can also specify a classloader (passing null is allowed). -Compiled expressions are defined in a child classloader created under any that is supplied. -It is important to ensure that, if a classloader is specified, it can see all the types involved in -the expression evaluation process. If you do not specify a classloader, a default classloader is used -(typically the context classloader for the thread that is running during expression evaluation). - -The second way to configure the compiler is for use when SpEL is embedded inside some -other component and it may not be possible to configure it through a configuration -object. In these cases, it is possible to set the `spring.expression.compiler.mode` -property via a JVM system property (or via the -<> mechanism) to one of the -`SpelCompilerMode` enum values (`off`, `immediate`, or `mixed`). - - -[[expressions-compiler-limitations]] -==== Compiler Limitations - -Since Spring Framework 4.1, the basic compilation framework is in place. However, the framework -does not yet support compiling every kind of expression. The initial focus has been on the -common expressions that are likely to be used in performance-critical contexts. The following -kinds of expression cannot be compiled at the moment: - -* Expressions involving assignment -* Expressions relying on the conversion service -* Expressions using custom resolvers or accessors -* Expressions using selection or projection - -More types of expressions will be compilable in the future. - - - - -[[expressions-beandef]] -== Expressions in Bean Definitions - -You can use SpEL expressions with XML-based or annotation-based configuration metadata for -defining `BeanDefinition` instances. In both cases, the syntax to define the expression is of the -form `#{ }`. - - - -[[expressions-beandef-xml-based]] -=== XML Configuration - -A property or constructor argument value can be set by using expressions, as the following -example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ----- - -All beans in the application context are available as predefined variables with their -common bean name. This includes standard context beans such as `environment` (of type -`org.springframework.core.env.Environment`) as well as `systemProperties` and -`systemEnvironment` (of type `Map`) for access to the runtime environment. - -The following example shows access to the `systemProperties` bean as a SpEL variable: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - ----- - -Note that you do not have to prefix the predefined variable with the `#` symbol here. - -You can also refer to other bean properties by name, as the following example shows: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - ----- - - - -[[expressions-beandef-annotation-based]] -=== Annotation Configuration - -To specify a default value, you can place the `@Value` annotation on fields, methods, -and method or constructor parameters. - -The following example sets the default value of a field: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class FieldValueTestBean { - - @Value("#{ systemProperties['user.region'] }") - private String defaultLocale; - - public void setDefaultLocale(String defaultLocale) { - this.defaultLocale = defaultLocale; - } - - public String getDefaultLocale() { - return this.defaultLocale; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class FieldValueTestBean { - - @Value("#{ systemProperties['user.region'] }") - var defaultLocale: String? = null - } ----- - -The following example shows the equivalent but on a property setter method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class PropertyValueTestBean { - - private String defaultLocale; - - @Value("#{ systemProperties['user.region'] }") - public void setDefaultLocale(String defaultLocale) { - this.defaultLocale = defaultLocale; - } - - public String getDefaultLocale() { - return this.defaultLocale; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class PropertyValueTestBean { - - @Value("#{ systemProperties['user.region'] }") - var defaultLocale: String? = null - } ----- - -Autowired methods and constructors can also use the `@Value` annotation, as the following -examples show: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleMovieLister { - - private MovieFinder movieFinder; - private String defaultLocale; - - @Autowired - public void configure(MovieFinder movieFinder, - @Value("#{ systemProperties['user.region'] }") String defaultLocale) { - this.movieFinder = movieFinder; - this.defaultLocale = defaultLocale; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SimpleMovieLister { - - private lateinit var movieFinder: MovieFinder - private lateinit var defaultLocale: String - - @Autowired - fun configure(movieFinder: MovieFinder, - @Value("#{ systemProperties['user.region'] }") defaultLocale: String) { - this.movieFinder = movieFinder - this.defaultLocale = defaultLocale - } - - // ... - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MovieRecommender { - - private String defaultLocale; - - private CustomerPreferenceDao customerPreferenceDao; - - public MovieRecommender(CustomerPreferenceDao customerPreferenceDao, - @Value("#{systemProperties['user.country']}") String defaultLocale) { - this.customerPreferenceDao = customerPreferenceDao; - this.defaultLocale = defaultLocale; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MovieRecommender(private val customerPreferenceDao: CustomerPreferenceDao, - @Value("#{systemProperties['user.country']}") private val defaultLocale: String) { - // ... - } ----- - - - - -[[expressions-language-ref]] -== Language Reference - -This section describes how the Spring Expression Language works. It covers the following -topics: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - - - -[[expressions-ref-literal]] -=== Literal Expressions - -SpEL supports the following types of literal expressions. - -- strings -- numeric values: integer (`int` or `long`), hexadecimal (`int` or `long`), real (`float` - or `double`) -- boolean values: `true` or `false` -- null - -Strings can delimited by single quotation marks (`'`) or double quotation marks (`"`). To -include a single quotation mark within a string literal enclosed in single quotation -marks, use two adjacent single quotation mark characters. Similarly, to include a double -quotation mark within a string literal enclosed in double quotation marks, use two -adjacent double quotation mark characters. - -Numbers support the use of the negative sign, exponential notation, and decimal points. -By default, real numbers are parsed by using `Double.parseDouble()`. - -The following listing shows simple usage of literals. Typically, they are not used in -isolation like this but, rather, as part of a more complex expression -- for example, -using a literal on one side of a logical comparison operator or as an argument to a -method. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - - // evaluates to "Hello World" - String helloWorld = (String) parser.parseExpression("'Hello World'").getValue(); - - // evaluates to "Tony's Pizza" - String pizzaParlor = (String) parser.parseExpression("'Tony''s Pizza'").getValue(); - - double avogadrosNumber = (Double) parser.parseExpression("6.0221415E+23").getValue(); - - // evaluates to 2147483647 - int maxValue = (Integer) parser.parseExpression("0x7FFFFFFF").getValue(); - - boolean trueValue = (Boolean) parser.parseExpression("true").getValue(); - - Object nullValue = parser.parseExpression("null").getValue(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - - // evaluates to "Hello World" - val helloWorld = parser.parseExpression("'Hello World'").value as String - - // evaluates to "Tony's Pizza" - val pizzaParlor = parser.parseExpression("'Tony''s Pizza'").value as String - - val avogadrosNumber = parser.parseExpression("6.0221415E+23").value as Double - - // evaluates to 2147483647 - val maxValue = parser.parseExpression("0x7FFFFFFF").value as Int - - val trueValue = parser.parseExpression("true").value as Boolean - - val nullValue = parser.parseExpression("null").value ----- - - - -[[expressions-properties-arrays]] -=== Properties, Arrays, Lists, Maps, and Indexers - -Navigating with property references is easy. To do so, use a period to indicate a nested -property value. The instances of the `Inventor` class, `pupin` and `tesla`, were -populated with data listed in the <> section. To navigate "down" the object graph and get Tesla's year of birth and -Pupin's city of birth, we use the following expressions: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // evaluates to 1856 - int year = (Integer) parser.parseExpression("birthdate.year + 1900").getValue(context); - - String city = (String) parser.parseExpression("placeOfBirth.city").getValue(context); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // evaluates to 1856 - val year = parser.parseExpression("birthdate.year + 1900").getValue(context) as Int - - val city = parser.parseExpression("placeOfBirth.city").getValue(context) as String ----- - -[NOTE] -==== -Case insensitivity is allowed for the first letter of property names. Thus, the -expressions in the above example may be written as `Birthdate.Year + 1900` and -`PlaceOfBirth.City`, respectively. In addition, properties may optionally be accessed via -method invocations -- for example, `getPlaceOfBirth().getCity()` instead of -`placeOfBirth.city`. -==== - -The contents of arrays and lists are obtained by using square bracket notation, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); - - // Inventions Array - - // evaluates to "Induction motor" - String invention = parser.parseExpression("inventions[3]").getValue( - context, tesla, String.class); - - // Members List - - // evaluates to "Nikola Tesla" - String name = parser.parseExpression("members[0].name").getValue( - context, ieee, String.class); - - // List and Array navigation - // evaluates to "Wireless communication" - String invention = parser.parseExpression("members[0].inventions[6]").getValue( - context, ieee, String.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() - - // Inventions Array - - // evaluates to "Induction motor" - val invention = parser.parseExpression("inventions[3]").getValue( - context, tesla, String::class.java) - - // Members List - - // evaluates to "Nikola Tesla" - val name = parser.parseExpression("members[0].name").getValue( - context, ieee, String::class.java) - - // List and Array navigation - // evaluates to "Wireless communication" - val invention = parser.parseExpression("members[0].inventions[6]").getValue( - context, ieee, String::class.java) ----- - -The contents of maps are obtained by specifying the literal key value within the -brackets. In the following example, because keys for the `officers` map are strings, we can specify -string literals: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Officer's Dictionary - - Inventor pupin = parser.parseExpression("officers['president']").getValue( - societyContext, Inventor.class); - - // evaluates to "Idvor" - String city = parser.parseExpression("officers['president'].placeOfBirth.city").getValue( - societyContext, String.class); - - // setting values - parser.parseExpression("officers['advisors'][0].placeOfBirth.country").setValue( - societyContext, "Croatia"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Officer's Dictionary - - val pupin = parser.parseExpression("officers['president']").getValue( - societyContext, Inventor::class.java) - - // evaluates to "Idvor" - val city = parser.parseExpression("officers['president'].placeOfBirth.city").getValue( - societyContext, String::class.java) - - // setting values - parser.parseExpression("officers['advisors'][0].placeOfBirth.country").setValue( - societyContext, "Croatia") ----- - - - -[[expressions-inline-lists]] -=== Inline Lists - -You can directly express lists in an expression by using `{}` notation. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // evaluates to a Java list containing the four numbers - List numbers = (List) parser.parseExpression("{1,2,3,4}").getValue(context); - - List listOfLists = (List) parser.parseExpression("{{'a','b'},{'x','y'}}").getValue(context); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // evaluates to a Java list containing the four numbers - val numbers = parser.parseExpression("{1,2,3,4}").getValue(context) as List<*> - - val listOfLists = parser.parseExpression("{{'a','b'},{'x','y'}}").getValue(context) as List<*> ----- - -`{}` by itself means an empty list. For performance reasons, if the list is itself -entirely composed of fixed literals, a constant list is created to represent the -expression (rather than building a new list on each evaluation). - - - -[[expressions-inline-maps]] -=== Inline Maps - -You can also directly express maps in an expression by using `{key:value}` notation. The -following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // evaluates to a Java map containing the two entries - Map inventorInfo = (Map) parser.parseExpression("{name:'Nikola',dob:'10-July-1856'}").getValue(context); - - Map mapOfMaps = (Map) parser.parseExpression("{name:{first:'Nikola',last:'Tesla'},dob:{day:10,month:'July',year:1856}}").getValue(context); ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - // evaluates to a Java map containing the two entries - val inventorInfo = parser.parseExpression("{name:'Nikola',dob:'10-July-1856'}").getValue(context) as Map<*, *> - - val mapOfMaps = parser.parseExpression("{name:{first:'Nikola',last:'Tesla'},dob:{day:10,month:'July',year:1856}}").getValue(context) as Map<*, *> ----- - -`{:}` by itself means an empty map. For performance reasons, if the map is itself -composed of fixed literals or other nested constant structures (lists or maps), a -constant map is created to represent the expression (rather than building a new map on -each evaluation). Quoting of the map keys is optional (unless the key contains a period -(`.`)). The examples above do not use quoted keys. - - - -[[expressions-array-construction]] -=== Array Construction - -You can build arrays by using the familiar Java syntax, optionally supplying an initializer -to have the array populated at construction time. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - int[] numbers1 = (int[]) parser.parseExpression("new int[4]").getValue(context); - - // Array with initializer - int[] numbers2 = (int[]) parser.parseExpression("new int[]{1,2,3}").getValue(context); - - // Multi dimensional array - int[][] numbers3 = (int[][]) parser.parseExpression("new int[4][5]").getValue(context); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val numbers1 = parser.parseExpression("new int[4]").getValue(context) as IntArray - - // Array with initializer - val numbers2 = parser.parseExpression("new int[]{1,2,3}").getValue(context) as IntArray - - // Multi dimensional array - val numbers3 = parser.parseExpression("new int[4][5]").getValue(context) as Array ----- - -You cannot currently supply an initializer when you construct a multi-dimensional array. - - - -[[expressions-methods]] -=== Methods - -You can invoke methods by using typical Java programming syntax. You can also invoke methods -on literals. Variable arguments are also supported. The following examples show how to -invoke methods: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // string literal, evaluates to "bc" - String bc = parser.parseExpression("'abc'.substring(1, 3)").getValue(String.class); - - // evaluates to true - boolean isMember = parser.parseExpression("isMember('Mihajlo Pupin')").getValue( - societyContext, Boolean.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // string literal, evaluates to "bc" - val bc = parser.parseExpression("'abc'.substring(1, 3)").getValue(String::class.java) - - // evaluates to true - val isMember = parser.parseExpression("isMember('Mihajlo Pupin')").getValue( - societyContext, Boolean::class.java) ----- - - -[[expressions-operators]] -=== Operators - -The Spring Expression Language supports the following kinds of operators: - -* <> -* <> -* <> -* <> - - -[[expressions-operators-relational]] -==== Relational Operators - -The relational operators (equal, not equal, less than, less than or equal, greater than, -and greater than or equal) are supported by using standard operator notation. -These operators work on `Number` types as well as types implementing `Comparable`. -The following listing shows a few examples of operators: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // evaluates to true - boolean trueValue = parser.parseExpression("2 == 2").getValue(Boolean.class); - - // evaluates to false - boolean falseValue = parser.parseExpression("2 < -5.0").getValue(Boolean.class); - - // evaluates to true - boolean trueValue = parser.parseExpression("'black' < 'block'").getValue(Boolean.class); - - // uses CustomValue:::compareTo - boolean trueValue = parser.parseExpression("new CustomValue(1) < new CustomValue(2)").getValue(Boolean.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // evaluates to true - val trueValue = parser.parseExpression("2 == 2").getValue(Boolean::class.java) - - // evaluates to false - val falseValue = parser.parseExpression("2 < -5.0").getValue(Boolean::class.java) - - // evaluates to true - val trueValue = parser.parseExpression("'black' < 'block'").getValue(Boolean::class.java) - - // uses CustomValue:::compareTo - val trueValue = parser.parseExpression("new CustomValue(1) < new CustomValue(2)").getValue(Boolean::class.java); ----- - -[NOTE] -==== -Greater-than and less-than comparisons against `null` follow a simple rule: `null` is treated as -nothing (that is NOT as zero). As a consequence, any other value is always greater -than `null` (`X > null` is always `true`) and no other value is ever less than nothing -(`X < null` is always `false`). - -If you prefer numeric comparisons instead, avoid number-based `null` comparisons -in favor of comparisons against zero (for example, `X > 0` or `X < 0`). -==== - -In addition to the standard relational operators, SpEL supports the `instanceof` and regular -expression-based `matches` operator. The following listing shows examples of both: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // evaluates to false - boolean falseValue = parser.parseExpression( - "'xyz' instanceof T(Integer)").getValue(Boolean.class); - - // evaluates to true - boolean trueValue = parser.parseExpression( - "'5.00' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean.class); - - // evaluates to false - boolean falseValue = parser.parseExpression( - "'5.0067' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // evaluates to false - val falseValue = parser.parseExpression( - "'xyz' instanceof T(Integer)").getValue(Boolean::class.java) - - // evaluates to true - val trueValue = parser.parseExpression( - "'5.00' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean::class.java) - - // evaluates to false - val falseValue = parser.parseExpression( - "'5.0067' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean::class.java) ----- - -CAUTION: Be careful with primitive types, as they are immediately boxed up to their -wrapper types. For example, `1 instanceof T(int)` evaluates to `false`, while -`1 instanceof T(Integer)` evaluates to `true`, as expected. - -Each symbolic operator can also be specified as a purely alphabetic equivalent. This -avoids problems where the symbols used have special meaning for the document type in -which the expression is embedded (such as in an XML document). The textual equivalents are: - -* `lt` (`<`) -* `gt` (`>`) -* `le` (`\<=`) -* `ge` (`>=`) -* `eq` (`==`) -* `ne` (`!=`) -* `div` (`/`) -* `mod` (`%`) -* `not` (`!`). - -All of the textual operators are case-insensitive. - - -[[expressions-operators-logical]] -==== Logical Operators - -SpEL supports the following logical operators: - -* `and` (`&&`) -* `or` (`||`) -* `not` (`!`) - -The following example shows how to use the logical operators: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // -- AND -- - - // evaluates to false - boolean falseValue = parser.parseExpression("true and false").getValue(Boolean.class); - - // evaluates to true - String expression = "isMember('Nikola Tesla') and isMember('Mihajlo Pupin')"; - boolean trueValue = parser.parseExpression(expression).getValue(societyContext, Boolean.class); - - // -- OR -- - - // evaluates to true - boolean trueValue = parser.parseExpression("true or false").getValue(Boolean.class); - - // evaluates to true - String expression = "isMember('Nikola Tesla') or isMember('Albert Einstein')"; - boolean trueValue = parser.parseExpression(expression).getValue(societyContext, Boolean.class); - - // -- NOT -- - - // evaluates to false - boolean falseValue = parser.parseExpression("!true").getValue(Boolean.class); - - // -- AND and NOT -- - String expression = "isMember('Nikola Tesla') and !isMember('Mihajlo Pupin')"; - boolean falseValue = parser.parseExpression(expression).getValue(societyContext, Boolean.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // -- AND -- - - // evaluates to false - val falseValue = parser.parseExpression("true and false").getValue(Boolean::class.java) - - // evaluates to true - val expression = "isMember('Nikola Tesla') and isMember('Mihajlo Pupin')" - val trueValue = parser.parseExpression(expression).getValue(societyContext, Boolean::class.java) - - // -- OR -- - - // evaluates to true - val trueValue = parser.parseExpression("true or false").getValue(Boolean::class.java) - - // evaluates to true - val expression = "isMember('Nikola Tesla') or isMember('Albert Einstein')" - val trueValue = parser.parseExpression(expression).getValue(societyContext, Boolean::class.java) - - // -- NOT -- - - // evaluates to false - val falseValue = parser.parseExpression("!true").getValue(Boolean::class.java) - - // -- AND and NOT -- - val expression = "isMember('Nikola Tesla') and !isMember('Mihajlo Pupin')" - val falseValue = parser.parseExpression(expression).getValue(societyContext, Boolean::class.java) ----- - - -[[expressions-operators-mathematical]] -==== Mathematical Operators - -You can use the addition operator (`+`) on both numbers and strings. You can use the -subtraction (`-`), multiplication (`*`), and division (`/`) operators only on numbers. -You can also use the modulus (`%`) and exponential power (`^`) operators on numbers. -Standard operator precedence is enforced. The following example shows the mathematical -operators in use: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Addition - int two = parser.parseExpression("1 + 1").getValue(Integer.class); // 2 - - String testString = parser.parseExpression( - "'test' + ' ' + 'string'").getValue(String.class); // 'test string' - - // Subtraction - int four = parser.parseExpression("1 - -3").getValue(Integer.class); // 4 - - double d = parser.parseExpression("1000.00 - 1e4").getValue(Double.class); // -9000 - - // Multiplication - int six = parser.parseExpression("-2 * -3").getValue(Integer.class); // 6 - - double twentyFour = parser.parseExpression("2.0 * 3e0 * 4").getValue(Double.class); // 24.0 - - // Division - int minusTwo = parser.parseExpression("6 / -3").getValue(Integer.class); // -2 - - double one = parser.parseExpression("8.0 / 4e0 / 2").getValue(Double.class); // 1.0 - - // Modulus - int three = parser.parseExpression("7 % 4").getValue(Integer.class); // 3 - - int one = parser.parseExpression("8 / 5 % 2").getValue(Integer.class); // 1 - - // Operator precedence - int minusTwentyOne = parser.parseExpression("1+2-3*8").getValue(Integer.class); // -21 ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Addition - val two = parser.parseExpression("1 + 1").getValue(Int::class.java) // 2 - - val testString = parser.parseExpression( - "'test' + ' ' + 'string'").getValue(String::class.java) // 'test string' - - // Subtraction - val four = parser.parseExpression("1 - -3").getValue(Int::class.java) // 4 - - val d = parser.parseExpression("1000.00 - 1e4").getValue(Double::class.java) // -9000 - - // Multiplication - val six = parser.parseExpression("-2 * -3").getValue(Int::class.java) // 6 - - val twentyFour = parser.parseExpression("2.0 * 3e0 * 4").getValue(Double::class.java) // 24.0 - - // Division - val minusTwo = parser.parseExpression("6 / -3").getValue(Int::class.java) // -2 - - val one = parser.parseExpression("8.0 / 4e0 / 2").getValue(Double::class.java) // 1.0 - - // Modulus - val three = parser.parseExpression("7 % 4").getValue(Int::class.java) // 3 - - val one = parser.parseExpression("8 / 5 % 2").getValue(Int::class.java) // 1 - - // Operator precedence - val minusTwentyOne = parser.parseExpression("1+2-3*8").getValue(Int::class.java) // -21 ----- - - -[[expressions-assignment]] -==== The Assignment Operator - -To set a property, use the assignment operator (`=`). This is typically done within a -call to `setValue` but can also be done inside a call to `getValue`. The following -listing shows both ways to use the assignment operator: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Inventor inventor = new Inventor(); - EvaluationContext context = SimpleEvaluationContext.forReadWriteDataBinding().build(); - - parser.parseExpression("name").setValue(context, inventor, "Aleksandar Seovic"); - - // alternatively - String aleks = parser.parseExpression( - "name = 'Aleksandar Seovic'").getValue(context, inventor, String.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val inventor = Inventor() - val context = SimpleEvaluationContext.forReadWriteDataBinding().build() - - parser.parseExpression("name").setValue(context, inventor, "Aleksandar Seovic") - - // alternatively - val aleks = parser.parseExpression( - "name = 'Aleksandar Seovic'").getValue(context, inventor, String::class.java) ----- - - -[[expressions-types]] -=== Types - -You can use the special `T` operator to specify an instance of `java.lang.Class` (the -type). Static methods are invoked by using this operator as well. The -`StandardEvaluationContext` uses a `TypeLocator` to find types, and the -`StandardTypeLocator` (which can be replaced) is built with an understanding of the -`java.lang` package. This means that `T()` references to types within the `java.lang` -package do not need to be fully qualified, but all other type references must be. The -following example shows how to use the `T` operator: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Class dateClass = parser.parseExpression("T(java.util.Date)").getValue(Class.class); - - Class stringClass = parser.parseExpression("T(String)").getValue(Class.class); - - boolean trueValue = parser.parseExpression( - "T(java.math.RoundingMode).CEILING < T(java.math.RoundingMode).FLOOR") - .getValue(Boolean.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val dateClass = parser.parseExpression("T(java.util.Date)").getValue(Class::class.java) - - val stringClass = parser.parseExpression("T(String)").getValue(Class::class.java) - - val trueValue = parser.parseExpression( - "T(java.math.RoundingMode).CEILING < T(java.math.RoundingMode).FLOOR") - .getValue(Boolean::class.java) ----- - - - -[[expressions-constructors]] -=== Constructors - -You can invoke constructors by using the `new` operator. You should use the fully -qualified class name for all types except those located in the `java.lang` package -(`Integer`, `Float`, `String`, and so on). The following example shows how to use the -`new` operator to invoke constructors: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Inventor einstein = p.parseExpression( - "new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German')") - .getValue(Inventor.class); - - // create new Inventor instance within the add() method of List - p.parseExpression( - "Members.add(new org.spring.samples.spel.inventor.Inventor( - 'Albert Einstein', 'German'))").getValue(societyContext); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val einstein = p.parseExpression( - "new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German')") - .getValue(Inventor::class.java) - - // create new Inventor instance within the add() method of List - p.parseExpression( - "Members.add(new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German'))") - .getValue(societyContext) ----- - - - -[[expressions-ref-variables]] -=== Variables - -You can reference variables in the expression by using the `#variableName` syntax. Variables -are set by using the `setVariable` method on `EvaluationContext` implementations. - -[NOTE] -==== -Valid variable names must be composed of one or more of the following supported -characters. - -* letters: `A` to `Z` and `a` to `z` -* digits: `0` to `9` -* underscore: `_` -* dollar sign: `$` -==== - -The following example shows how to use variables. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Inventor tesla = new Inventor("Nikola Tesla", "Serbian"); - - EvaluationContext context = SimpleEvaluationContext.forReadWriteDataBinding().build(); - context.setVariable("newName", "Mike Tesla"); - - parser.parseExpression("name = #newName").getValue(context, tesla); - System.out.println(tesla.getName()) // "Mike Tesla" ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val tesla = Inventor("Nikola Tesla", "Serbian") - - val context = SimpleEvaluationContext.forReadWriteDataBinding().build() - context.setVariable("newName", "Mike Tesla") - - parser.parseExpression("name = #newName").getValue(context, tesla) - println(tesla.name) // "Mike Tesla" ----- - - -[[expressions-this-root]] -==== The `#this` and `#root` Variables - -The `#this` variable is always defined and refers to the current evaluation object -(against which unqualified references are resolved). The `#root` variable is always -defined and refers to the root context object. Although `#this` may vary as components of -an expression are evaluated, `#root` always refers to the root. The following examples -show how to use the `#this` and `#root` variables: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // create an array of integers - List primes = new ArrayList<>(); - primes.addAll(Arrays.asList(2,3,5,7,11,13,17)); - - // create parser and set variable 'primes' as the array of integers - ExpressionParser parser = new SpelExpressionParser(); - EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataAccess(); - context.setVariable("primes", primes); - - // all prime numbers > 10 from the list (using selection ?{...}) - // evaluates to [11, 13, 17] - List primesGreaterThanTen = (List) parser.parseExpression( - "#primes.?[#this>10]").getValue(context); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // create an array of integers - val primes = ArrayList() - primes.addAll(listOf(2, 3, 5, 7, 11, 13, 17)) - - // create parser and set variable 'primes' as the array of integers - val parser = SpelExpressionParser() - val context = SimpleEvaluationContext.forReadOnlyDataAccess() - context.setVariable("primes", primes) - - // all prime numbers > 10 from the list (using selection ?{...}) - // evaluates to [11, 13, 17] - val primesGreaterThanTen = parser.parseExpression( - "#primes.?[#this>10]").getValue(context) as List ----- - - - -[[expressions-ref-functions]] -=== Functions - -You can extend SpEL by registering user-defined functions that can be called within the -expression string. The function is registered through the `EvaluationContext`. The -following example shows how to register a user-defined function: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Method method = ...; - - EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); - context.setVariable("myFunction", method); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val method: Method = ... - - val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() - context.setVariable("myFunction", method) ----- - -For example, consider the following utility method that reverses a string: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public abstract class StringUtils { - - public static String reverseString(String input) { - StringBuilder backwards = new StringBuilder(input.length()); - for (int i = 0; i < input.length(); i++) { - backwards.append(input.charAt(input.length() - 1 - i)); - } - return backwards.toString(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun reverseString(input: String): String { - val backwards = StringBuilder(input.length) - for (i in 0 until input.length) { - backwards.append(input[input.length - 1 - i]) - } - return backwards.toString() - } ----- - -You can then register and use the preceding method, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - - EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); - context.setVariable("reverseString", - StringUtils.class.getDeclaredMethod("reverseString", String.class)); - - String helloWorldReversed = parser.parseExpression( - "#reverseString('hello')").getValue(context, String.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - - val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() - context.setVariable("reverseString", ::reverseString::javaMethod) - - val helloWorldReversed = parser.parseExpression( - "#reverseString('hello')").getValue(context, String::class.java) ----- - - - -[[expressions-bean-references]] -=== Bean References - -If the evaluation context has been configured with a bean resolver, you can -look up beans from an expression by using the `@` symbol. The following example shows how -to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - StandardEvaluationContext context = new StandardEvaluationContext(); - context.setBeanResolver(new MyBeanResolver()); - - // This will end up calling resolve(context,"something") on MyBeanResolver during evaluation - Object bean = parser.parseExpression("@something").getValue(context); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - val context = StandardEvaluationContext() - context.setBeanResolver(MyBeanResolver()) - - // This will end up calling resolve(context,"something") on MyBeanResolver during evaluation - val bean = parser.parseExpression("@something").getValue(context) ----- - -To access a factory bean itself, you should instead prefix the bean name with an `&` symbol. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - StandardEvaluationContext context = new StandardEvaluationContext(); - context.setBeanResolver(new MyBeanResolver()); - - // This will end up calling resolve(context,"&foo") on MyBeanResolver during evaluation - Object bean = parser.parseExpression("&foo").getValue(context); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - val context = StandardEvaluationContext() - context.setBeanResolver(MyBeanResolver()) - - // This will end up calling resolve(context,"&foo") on MyBeanResolver during evaluation - val bean = parser.parseExpression("&foo").getValue(context) ----- - - -[[expressions-operator-ternary]] -=== Ternary Operator (If-Then-Else) - -You can use the ternary operator for performing if-then-else conditional logic inside -the expression. The following listing shows a minimal example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - String falseString = parser.parseExpression( - "false ? 'trueExp' : 'falseExp'").getValue(String.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val falseString = parser.parseExpression( - "false ? 'trueExp' : 'falseExp'").getValue(String::class.java) ----- - -In this case, the boolean `false` results in returning the string value `'falseExp'`. A more -realistic example follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - parser.parseExpression("name").setValue(societyContext, "IEEE"); - societyContext.setVariable("queryName", "Nikola Tesla"); - - expression = "isMember(#queryName)? #queryName + ' is a member of the ' " + - "+ Name + ' Society' : #queryName + ' is not a member of the ' + Name + ' Society'"; - - String queryResultString = parser.parseExpression(expression) - .getValue(societyContext, String.class); - // queryResultString = "Nikola Tesla is a member of the IEEE Society" ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - parser.parseExpression("name").setValue(societyContext, "IEEE") - societyContext.setVariable("queryName", "Nikola Tesla") - - expression = "isMember(#queryName)? #queryName + ' is a member of the ' " + "+ Name + ' Society' : #queryName + ' is not a member of the ' + Name + ' Society'" - - val queryResultString = parser.parseExpression(expression) - .getValue(societyContext, String::class.java) - // queryResultString = "Nikola Tesla is a member of the IEEE Society" ----- - -See the next section on the Elvis operator for an even shorter syntax for the -ternary operator. - - - -[[expressions-operator-elvis]] -=== The Elvis Operator - -The Elvis operator is a shortening of the ternary operator syntax and is used in the -https://www.groovy-lang.org/operators.html#_elvis_operator[Groovy] language. -With the ternary operator syntax, you usually have to repeat a variable twice, as the -following example shows: - -[source,groovy,indent=0,subs="verbatim,quotes"] ----- - String name = "Elvis Presley"; - String displayName = (name != null ? name : "Unknown"); ----- - -Instead, you can use the Elvis operator (named for the resemblance to Elvis' hair style). -The following example shows how to use the Elvis operator: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - - String name = parser.parseExpression("name?:'Unknown'").getValue(new Inventor(), String.class); - System.out.println(name); // 'Unknown' ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - - val name = parser.parseExpression("name?:'Unknown'").getValue(Inventor(), String::class.java) - println(name) // 'Unknown' ----- - -The following listing shows a more complex example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); - - Inventor tesla = new Inventor("Nikola Tesla", "Serbian"); - String name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String.class); - System.out.println(name); // Nikola Tesla - - tesla.setName(null); - name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String.class); - System.out.println(name); // Elvis Presley ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() - - val tesla = Inventor("Nikola Tesla", "Serbian") - var name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String::class.java) - println(name) // Nikola Tesla - - tesla.setName(null) - name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String::class.java) - println(name) // Elvis Presley ----- - -[NOTE] -===== -You can use the Elvis operator to apply default values in expressions. The following -example shows how to use the Elvis operator in a `@Value` expression: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Value("#{systemProperties['pop3.port'] ?: 25}") ----- - -This will inject a system property `pop3.port` if it is defined or 25 if not. -===== - - -[[expressions-operator-safe-navigation]] -=== Safe Navigation Operator - -The safe navigation operator is used to avoid a `NullPointerException` and comes from -the https://www.groovy-lang.org/operators.html#_safe_navigation_operator[Groovy] -language. Typically, when you have a reference to an object, you might need to verify that -it is not null before accessing methods or properties of the object. To avoid this, the -safe navigation operator returns null instead of throwing an exception. The following -example shows how to use the safe navigation operator: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ExpressionParser parser = new SpelExpressionParser(); - EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); - - Inventor tesla = new Inventor("Nikola Tesla", "Serbian"); - tesla.setPlaceOfBirth(new PlaceOfBirth("Smiljan")); - - String city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String.class); - System.out.println(city); // Smiljan - - tesla.setPlaceOfBirth(null); - city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String.class); - System.out.println(city); // null - does not throw NullPointerException!!! ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val parser = SpelExpressionParser() - val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() - - val tesla = Inventor("Nikola Tesla", "Serbian") - tesla.setPlaceOfBirth(PlaceOfBirth("Smiljan")) - - var city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String::class.java) - println(city) // Smiljan - - tesla.setPlaceOfBirth(null) - city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String::class.java) - println(city) // null - does not throw NullPointerException!!! ----- - - - -[[expressions-collection-selection]] -=== Collection Selection - -Selection is a powerful expression language feature that lets you transform a -source collection into another collection by selecting from its entries. - -Selection uses a syntax of `.?[selectionExpression]`. It filters the collection and -returns a new collection that contains a subset of the original elements. For example, -selection lets us easily get a list of Serbian inventors, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - List list = (List) parser.parseExpression( - "members.?[nationality == 'Serbian']").getValue(societyContext); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val list = parser.parseExpression( - "members.?[nationality == 'Serbian']").getValue(societyContext) as List ----- - -Selection is supported for arrays and anything that implements `java.lang.Iterable` or -`java.util.Map`. For a list or array, the selection criteria is evaluated against each -individual element. Against a map, the selection criteria is evaluated against each map -entry (objects of the Java type `Map.Entry`). Each map entry has its `key` and `value` -accessible as properties for use in the selection. - -The following expression returns a new map that consists of those elements of the -original map where the entry's value is less than 27: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Map newMap = parser.parseExpression("map.?[value<27]").getValue(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val newMap = parser.parseExpression("map.?[value<27]").getValue() ----- - -In addition to returning all the selected elements, you can retrieve only the first or -the last element. To obtain the first element matching the selection, the syntax is -`.^[selectionExpression]`. To obtain the last matching selection, the syntax is -`.$[selectionExpression]`. - - - -[[expressions-collection-projection]] -=== Collection Projection - -Projection lets a collection drive the evaluation of a sub-expression, and the result is -a new collection. The syntax for projection is `.![projectionExpression]`. For example, -suppose we have a list of inventors but want the list of cities where they were born. -Effectively, we want to evaluate 'placeOfBirth.city' for every entry in the inventor -list. The following example uses projection to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // returns ['Smiljan', 'Idvor' ] - List placesOfBirth = (List)parser.parseExpression("members.![placeOfBirth.city]"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // returns ['Smiljan', 'Idvor' ] - val placesOfBirth = parser.parseExpression("members.![placeOfBirth.city]") as List<*> ----- - -Projection is supported for arrays and anything that implements `java.lang.Iterable` or -`java.util.Map`. When using a map to drive projection, the projection expression is -evaluated against each entry in the map (represented as a Java `Map.Entry`). The result -of a projection across a map is a list that consists of the evaluation of the projection -expression against each map entry. - - - -[[expressions-templating]] -=== Expression templating - -Expression templates allow mixing literal text with one or more evaluation blocks. -Each evaluation block is delimited with prefix and suffix characters that you can -define. A common choice is to use `#{ }` as the delimiters, as the following example -shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - String randomPhrase = parser.parseExpression( - "random number is #{T(java.lang.Math).random()}", - new TemplateParserContext()).getValue(String.class); - - // evaluates to "random number is 0.7038186818312008" ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val randomPhrase = parser.parseExpression( - "random number is #{T(java.lang.Math).random()}", - TemplateParserContext()).getValue(String::class.java) - - // evaluates to "random number is 0.7038186818312008" ----- - -The string is evaluated by concatenating the literal text `'random number is '` with the -result of evaluating the expression inside the `#{ }` delimiter (in this case, the result -of calling that `random()` method). The second argument to the `parseExpression()` method -is of the type `ParserContext`. The `ParserContext` interface is used to influence how -the expression is parsed in order to support the expression templating functionality. -The definition of `TemplateParserContext` follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class TemplateParserContext implements ParserContext { - - public String getExpressionPrefix() { - return "#{"; - } - - public String getExpressionSuffix() { - return "}"; - } - - public boolean isTemplate() { - return true; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class TemplateParserContext : ParserContext { - - override fun getExpressionPrefix(): String { - return "#{" - } - - override fun getExpressionSuffix(): String { - return "}" - } - - override fun isTemplate(): Boolean { - return true - } - } ----- - - -[[expressions-example-classes]] -== Classes Used in the Examples - -This section lists the classes used in the examples throughout this chapter. - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Inventor.Java ----- - package org.spring.samples.spel.inventor; - - import java.util.Date; - import java.util.GregorianCalendar; - - public class Inventor { - - private String name; - private String nationality; - private String[] inventions; - private Date birthdate; - private PlaceOfBirth placeOfBirth; - - public Inventor(String name, String nationality) { - GregorianCalendar c= new GregorianCalendar(); - this.name = name; - this.nationality = nationality; - this.birthdate = c.getTime(); - } - - public Inventor(String name, Date birthdate, String nationality) { - this.name = name; - this.nationality = nationality; - this.birthdate = birthdate; - } - - public Inventor() { - } - - public String getName() { - return name; - } - - public void setName(String name) { - this.name = name; - } - - public String getNationality() { - return nationality; - } - - public void setNationality(String nationality) { - this.nationality = nationality; - } - - public Date getBirthdate() { - return birthdate; - } - - public void setBirthdate(Date birthdate) { - this.birthdate = birthdate; - } - - public PlaceOfBirth getPlaceOfBirth() { - return placeOfBirth; - } - - public void setPlaceOfBirth(PlaceOfBirth placeOfBirth) { - this.placeOfBirth = placeOfBirth; - } - - public void setInventions(String[] inventions) { - this.inventions = inventions; - } - - public String[] getInventions() { - return inventions; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Inventor.kt ----- - package org.spring.samples.spel.inventor - - class Inventor( - var name: String, - var nationality: String, - var inventions: Array? = null, - var birthdate: Date = GregorianCalendar().time, - var placeOfBirth: PlaceOfBirth? = null) ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.PlaceOfBirth.java ----- - package org.spring.samples.spel.inventor; - - public class PlaceOfBirth { - - private String city; - private String country; - - public PlaceOfBirth(String city) { - this.city=city; - } - - public PlaceOfBirth(String city, String country) { - this(city); - this.country = country; - } - - public String getCity() { - return city; - } - - public void setCity(String s) { - this.city = s; - } - - public String getCountry() { - return country; - } - - public void setCountry(String country) { - this.country = country; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.PlaceOfBirth.kt ----- - package org.spring.samples.spel.inventor - - class PlaceOfBirth(var city: String, var country: String? = null) { ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Society.java ----- - package org.spring.samples.spel.inventor; - - import java.util.*; - - public class Society { - - private String name; - - public static String Advisors = "advisors"; - public static String President = "president"; - - private List members = new ArrayList<>(); - private Map officers = new HashMap(); - - public List getMembers() { - return members; - } - - public Map getOfficers() { - return officers; - } - - public String getName() { - return name; - } - - public void setName(String name) { - this.name = name; - } - - public boolean isMember(String name) { - for (Inventor inventor : members) { - if (inventor.getName().equals(name)) { - return true; - } - } - return false; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Society.kt ----- - package org.spring.samples.spel.inventor - - import java.util.* - - class Society { - - val Advisors = "advisors" - val President = "president" - - var name: String? = null - - val members = ArrayList() - val officers = mapOf() - - fun isMember(name: String): Boolean { - for (inventor in members) { - if (inventor.name == name) { - return true - } - } - return false - } - } ----- diff --git a/framework-docs/modules/ROOT/pages/core/expressions/beandef.adoc b/framework-docs/modules/ROOT/pages/core/expressions/beandef.adoc new file mode 100644 index 000000000000..be689fb15760 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/beandef.adoc @@ -0,0 +1,195 @@ +[[expressions-beandef]] += Expressions in Bean Definitions + +You can use SpEL expressions with XML-based or annotation-based configuration metadata for +defining `BeanDefinition` instances. In both cases, the syntax to define the expression is of the +form `#{ }`. + + + +[[expressions-beandef-xml-based]] +== XML Configuration + +A property or constructor argument value can be set by using expressions, as the following +example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + +---- + +All beans in the application context are available as predefined variables with their +common bean name. This includes standard context beans such as `environment` (of type +`org.springframework.core.env.Environment`) as well as `systemProperties` and +`systemEnvironment` (of type `Map`) for access to the runtime environment. + +The following example shows access to the `systemProperties` bean as a SpEL variable: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + +---- + +Note that you do not have to prefix the predefined variable with the `#` symbol here. + +You can also refer to other bean properties by name, as the following example shows: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + + + +---- + + + +[[expressions-beandef-annotation-based]] +== Annotation Configuration + +To specify a default value, you can place the `@Value` annotation on fields, methods, +and method or constructor parameters. + +The following example sets the default value of a field: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class FieldValueTestBean { + + @Value("#{ systemProperties['user.region'] }") + private String defaultLocale; + + public void setDefaultLocale(String defaultLocale) { + this.defaultLocale = defaultLocale; + } + + public String getDefaultLocale() { + return this.defaultLocale; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class FieldValueTestBean { + + @Value("#{ systemProperties['user.region'] }") + var defaultLocale: String? = null + } +---- + +The following example shows the equivalent but on a property setter method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class PropertyValueTestBean { + + private String defaultLocale; + + @Value("#{ systemProperties['user.region'] }") + public void setDefaultLocale(String defaultLocale) { + this.defaultLocale = defaultLocale; + } + + public String getDefaultLocale() { + return this.defaultLocale; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class PropertyValueTestBean { + + @Value("#{ systemProperties['user.region'] }") + var defaultLocale: String? = null + } +---- + +Autowired methods and constructors can also use the `@Value` annotation, as the following +examples show: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleMovieLister { + + private MovieFinder movieFinder; + private String defaultLocale; + + @Autowired + public void configure(MovieFinder movieFinder, + @Value("#{ systemProperties['user.region'] }") String defaultLocale) { + this.movieFinder = movieFinder; + this.defaultLocale = defaultLocale; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SimpleMovieLister { + + private lateinit var movieFinder: MovieFinder + private lateinit var defaultLocale: String + + @Autowired + fun configure(movieFinder: MovieFinder, + @Value("#{ systemProperties['user.region'] }") defaultLocale: String) { + this.movieFinder = movieFinder + this.defaultLocale = defaultLocale + } + + // ... + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + private String defaultLocale; + + private CustomerPreferenceDao customerPreferenceDao; + + public MovieRecommender(CustomerPreferenceDao customerPreferenceDao, + @Value("#{systemProperties['user.country']}") String defaultLocale) { + this.customerPreferenceDao = customerPreferenceDao; + this.defaultLocale = defaultLocale; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender(private val customerPreferenceDao: CustomerPreferenceDao, + @Value("#{systemProperties['user.country']}") private val defaultLocale: String) { + // ... + } +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc b/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc new file mode 100644 index 000000000000..d427d16586e9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc @@ -0,0 +1,467 @@ +[[expressions-evaluation]] += Evaluation + +This section introduces the simple use of SpEL interfaces and its expression language. +The complete language reference can be found in +<>. + +The following code introduces the SpEL API to evaluate the literal string expression, +`Hello World`. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + Expression exp = parser.parseExpression("'Hello World'"); // <1> + String message = (String) exp.getValue(); +---- +<1> The value of the message variable is `'Hello World'`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + val exp = parser.parseExpression("'Hello World'") // <1> + val message = exp.value as String +---- +<1> The value of the message variable is `'Hello World'`. + + +The SpEL classes and interfaces you are most likely to use are located in the +`org.springframework.expression` package and its sub-packages, such as `spel.support`. + +The `ExpressionParser` interface is responsible for parsing an expression string. In +the preceding example, the expression string is a string literal denoted by the surrounding single +quotation marks. The `Expression` interface is responsible for evaluating the previously defined +expression string. Two exceptions that can be thrown, `ParseException` and +`EvaluationException`, when calling `parser.parseExpression` and `exp.getValue`, +respectively. + +SpEL supports a wide range of features, such as calling methods, accessing properties, +and calling constructors. + +In the following example of method invocation, we call the `concat` method on the string literal: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + Expression exp = parser.parseExpression("'Hello World'.concat('!')"); // <1> + String message = (String) exp.getValue(); +---- +<1> The value of `message` is now 'Hello World!'. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + val exp = parser.parseExpression("'Hello World'.concat('!')") // <1> + val message = exp.value as String +---- +<1> The value of `message` is now 'Hello World!'. + +The following example of calling a JavaBean property calls the `String` property `Bytes`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + + // invokes 'getBytes()' + Expression exp = parser.parseExpression("'Hello World'.bytes"); // <1> + byte[] bytes = (byte[]) exp.getValue(); +---- +<1> This line converts the literal to a byte array. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + + // invokes 'getBytes()' + val exp = parser.parseExpression("'Hello World'.bytes") // <1> + val bytes = exp.value as ByteArray +---- +<1> This line converts the literal to a byte array. + +SpEL also supports nested properties by using the standard dot notation (such as +`prop1.prop2.prop3`) and also the corresponding setting of property values. +Public fields may also be accessed. + +The following example shows how to use dot notation to get the length of a literal: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + + // invokes 'getBytes().length' + Expression exp = parser.parseExpression("'Hello World'.bytes.length"); // <1> + int length = (Integer) exp.getValue(); +---- +<1> `'Hello World'.bytes.length` gives the length of the literal. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + + // invokes 'getBytes().length' + val exp = parser.parseExpression("'Hello World'.bytes.length") // <1> + val length = exp.value as Int +---- +<1> `'Hello World'.bytes.length` gives the length of the literal. + +The String's constructor can be called instead of using a string literal, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + Expression exp = parser.parseExpression("new String('hello world').toUpperCase()"); // <1> + String message = exp.getValue(String.class); +---- +<1> Construct a new `String` from the literal and make it be upper case. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + val exp = parser.parseExpression("new String('hello world').toUpperCase()") // <1> + val message = exp.getValue(String::class.java) +---- +<1> Construct a new `String` from the literal and make it be upper case. + + +Note the use of the generic method: `public T getValue(Class desiredResultType)`. +Using this method removes the need to cast the value of the expression to the desired +result type. An `EvaluationException` is thrown if the value cannot be cast to the +type `T` or converted by using the registered type converter. + +The more common usage of SpEL is to provide an expression string that is evaluated +against a specific object instance (called the root object). The following example shows +how to retrieve the `name` property from an instance of the `Inventor` class or +create a boolean condition: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Create and set a calendar + GregorianCalendar c = new GregorianCalendar(); + c.set(1856, 7, 9); + + // The constructor arguments are name, birthday, and nationality. + Inventor tesla = new Inventor("Nikola Tesla", c.getTime(), "Serbian"); + + ExpressionParser parser = new SpelExpressionParser(); + + Expression exp = parser.parseExpression("name"); // Parse name as an expression + String name = (String) exp.getValue(tesla); + // name == "Nikola Tesla" + + exp = parser.parseExpression("name == 'Nikola Tesla'"); + boolean result = exp.getValue(tesla, Boolean.class); + // result == true +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Create and set a calendar + val c = GregorianCalendar() + c.set(1856, 7, 9) + + // The constructor arguments are name, birthday, and nationality. + val tesla = Inventor("Nikola Tesla", c.time, "Serbian") + + val parser = SpelExpressionParser() + + var exp = parser.parseExpression("name") // Parse name as an expression + val name = exp.getValue(tesla) as String + // name == "Nikola Tesla" + + exp = parser.parseExpression("name == 'Nikola Tesla'") + val result = exp.getValue(tesla, Boolean::class.java) + // result == true +---- + + + + +[[expressions-evaluation-context]] +== Understanding `EvaluationContext` + +The `EvaluationContext` interface is used when evaluating an expression to resolve +properties, methods, or fields and to help perform type conversion. Spring provides two +implementations. + +* `SimpleEvaluationContext`: Exposes a subset of essential SpEL language features and +configuration options, for categories of expressions that do not require the full extent +of the SpEL language syntax and should be meaningfully restricted. Examples include but +are not limited to data binding expressions and property-based filters. + +* `StandardEvaluationContext`: Exposes the full set of SpEL language features and +configuration options. You can use it to specify a default root object and to configure +every available evaluation-related strategy. + +`SimpleEvaluationContext` is designed to support only a subset of the SpEL language syntax. +It excludes Java type references, constructors, and bean references. It also requires +you to explicitly choose the level of support for properties and methods in expressions. +By default, the `create()` static factory method enables only read access to properties. +You can also obtain a builder to configure the exact level of support needed, targeting +one or some combination of the following: + +* Custom `PropertyAccessor` only (no reflection) +* Data binding properties for read-only access +* Data binding properties for read and write + + +[[expressions-type-conversion]] +=== Type Conversion + +By default, SpEL uses the conversion service available in Spring core +(`org.springframework.core.convert.ConversionService`). This conversion service comes +with many built-in converters for common conversions but is also fully extensible so that +you can add custom conversions between types. Additionally, it is +generics-aware. This means that, when you work with generic types in +expressions, SpEL attempts conversions to maintain type correctness for any objects +it encounters. + +What does this mean in practice? Suppose assignment, using `setValue()`, is being used +to set a `List` property. The type of the property is actually `List`. SpEL +recognizes that the elements of the list need to be converted to `Boolean` before +being placed in it. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + class Simple { + public List booleanList = new ArrayList<>(); + } + + Simple simple = new Simple(); + simple.booleanList.add(true); + + EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); + + // "false" is passed in here as a String. SpEL and the conversion service + // will recognize that it needs to be a Boolean and convert it accordingly. + parser.parseExpression("booleanList[0]").setValue(context, simple, "false"); + + // b is false + Boolean b = simple.booleanList.get(0); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class Simple { + var booleanList: MutableList = ArrayList() + } + + val simple = Simple() + simple.booleanList.add(true) + + val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() + + // "false" is passed in here as a String. SpEL and the conversion service + // will recognize that it needs to be a Boolean and convert it accordingly. + parser.parseExpression("booleanList[0]").setValue(context, simple, "false") + + // b is false + val b = simple.booleanList[0] +---- + + +[[expressions-parser-configuration]] +== Parser Configuration + +It is possible to configure the SpEL expression parser by using a parser configuration +object (`org.springframework.expression.spel.SpelParserConfiguration`). The configuration +object controls the behavior of some of the expression components. For example, if you +index into an array or collection and the element at the specified index is `null`, SpEL +can automatically create the element. This is useful when using expressions made up of a +chain of property references. If you index into an array or list and specify an index +that is beyond the end of the current size of the array or list, SpEL can automatically +grow the array or list to accommodate that index. In order to add an element at the +specified index, SpEL will try to create the element using the element type's default +constructor before setting the specified value. If the element type does not have a +default constructor, `null` will be added to the array or list. If there is no built-in +or custom converter that knows how to set the value, `null` will remain in the array or +list at the specified index. The following example demonstrates how to automatically grow +the list: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + class Demo { + public List list; + } + + // Turn on: + // - auto null reference initialization + // - auto collection growing + SpelParserConfiguration config = new SpelParserConfiguration(true, true); + + ExpressionParser parser = new SpelExpressionParser(config); + + Expression expression = parser.parseExpression("list[3]"); + + Demo demo = new Demo(); + + Object o = expression.getValue(demo); + + // demo.list will now be a real collection of 4 entries + // Each entry is a new empty String +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class Demo { + var list: List? = null + } + + // Turn on: + // - auto null reference initialization + // - auto collection growing + val config = SpelParserConfiguration(true, true) + + val parser = SpelExpressionParser(config) + + val expression = parser.parseExpression("list[3]") + + val demo = Demo() + + val o = expression.getValue(demo) + + // demo.list will now be a real collection of 4 entries + // Each entry is a new empty String +---- + + + +[[expressions-spel-compilation]] +== SpEL Compilation + +Spring Framework 4.1 includes a basic expression compiler. Expressions are usually +interpreted, which provides a lot of dynamic flexibility during evaluation but +does not provide optimum performance. For occasional expression usage, +this is fine, but, when used by other components such as Spring Integration, +performance can be very important, and there is no real need for the dynamism. + +The SpEL compiler is intended to address this need. During evaluation, the compiler +generates a Java class that embodies the expression behavior at runtime and uses that +class to achieve much faster expression evaluation. Due to the lack of typing around +expressions, the compiler uses information gathered during the interpreted evaluations +of an expression when performing compilation. For example, it does not know the type +of a property reference purely from the expression, but during the first interpreted +evaluation, it finds out what it is. Of course, basing compilation on such derived +information can cause trouble later if the types of the various expression elements +change over time. For this reason, compilation is best suited to expressions whose +type information is not going to change on repeated evaluations. + +Consider the following basic expression: + +---- +someArray[0].someProperty.someOtherProperty < 0.1 +---- + +Because the preceding expression involves array access, some property de-referencing, +and numeric operations, the performance gain can be very noticeable. In an example +micro benchmark run of 50000 iterations, it took 75ms to evaluate by using the +interpreter and only 3ms using the compiled version of the expression. + + +[[expressions-compiler-configuration]] +=== Compiler Configuration + +The compiler is not turned on by default, but you can turn it on in either of two +different ways. You can turn it on by using the parser configuration process +(<>) or by using a Spring property +when SpEL usage is embedded inside another component. This section discusses both of +these options. + +The compiler can operate in one of three modes, which are captured in the +`org.springframework.expression.spel.SpelCompilerMode` enum. The modes are as follows: + +* `OFF` (default): The compiler is switched off. +* `IMMEDIATE`: In immediate mode, the expressions are compiled as soon as possible. This +is typically after the first interpreted evaluation. If the compiled expression fails +(typically due to a type changing, as described earlier), the caller of the expression +evaluation receives an exception. +* `MIXED`: In mixed mode, the expressions silently switch between interpreted and compiled +mode over time. After some number of interpreted runs, they switch to compiled +form and, if something goes wrong with the compiled form (such as a type changing, as +described earlier), the expression automatically switches back to interpreted form +again. Sometime later, it may generate another compiled form and switch to it. Basically, +the exception that the user gets in `IMMEDIATE` mode is instead handled internally. + +`IMMEDIATE` mode exists because `MIXED` mode could cause issues for expressions that +have side effects. If a compiled expression blows up after partially succeeding, it +may have already done something that has affected the state of the system. If this +has happened, the caller may not want it to silently re-run in interpreted mode, +since part of the expression may be running twice. + +After selecting a mode, use the `SpelParserConfiguration` to configure the parser. The +following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + SpelParserConfiguration config = new SpelParserConfiguration(SpelCompilerMode.IMMEDIATE, + this.getClass().getClassLoader()); + + SpelExpressionParser parser = new SpelExpressionParser(config); + + Expression expr = parser.parseExpression("payload"); + + MyMessage message = new MyMessage(); + + Object payload = expr.getValue(message); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val config = SpelParserConfiguration(SpelCompilerMode.IMMEDIATE, + this.javaClass.classLoader) + + val parser = SpelExpressionParser(config) + + val expr = parser.parseExpression("payload") + + val message = MyMessage() + + val payload = expr.getValue(message) +---- + +When you specify the compiler mode, you can also specify a classloader (passing null is allowed). +Compiled expressions are defined in a child classloader created under any that is supplied. +It is important to ensure that, if a classloader is specified, it can see all the types involved in +the expression evaluation process. If you do not specify a classloader, a default classloader is used +(typically the context classloader for the thread that is running during expression evaluation). + +The second way to configure the compiler is for use when SpEL is embedded inside some +other component and it may not be possible to configure it through a configuration +object. In these cases, it is possible to set the `spring.expression.compiler.mode` +property via a JVM system property (or via the +<> mechanism) to one of the +`SpelCompilerMode` enum values (`off`, `immediate`, or `mixed`). + + +[[expressions-compiler-limitations]] +=== Compiler Limitations + +Since Spring Framework 4.1, the basic compilation framework is in place. However, the framework +does not yet support compiling every kind of expression. The initial focus has been on the +common expressions that are likely to be used in performance-critical contexts. The following +kinds of expression cannot be compiled at the moment: + +* Expressions involving assignment +* Expressions relying on the conversion service +* Expressions using custom resolvers or accessors +* Expressions using selection or projection + +More types of expressions will be compilable in the future. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/example-classes.adoc b/framework-docs/modules/ROOT/pages/core/expressions/example-classes.adoc new file mode 100644 index 000000000000..475029a08fc3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/example-classes.adoc @@ -0,0 +1,205 @@ +[[expressions-example-classes]] += Classes Used in the Examples + +This section lists the classes used in the examples throughout this chapter. + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Inventor.Java +---- + package org.spring.samples.spel.inventor; + + import java.util.Date; + import java.util.GregorianCalendar; + + public class Inventor { + + private String name; + private String nationality; + private String[] inventions; + private Date birthdate; + private PlaceOfBirth placeOfBirth; + + public Inventor(String name, String nationality) { + GregorianCalendar c= new GregorianCalendar(); + this.name = name; + this.nationality = nationality; + this.birthdate = c.getTime(); + } + + public Inventor(String name, Date birthdate, String nationality) { + this.name = name; + this.nationality = nationality; + this.birthdate = birthdate; + } + + public Inventor() { + } + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getNationality() { + return nationality; + } + + public void setNationality(String nationality) { + this.nationality = nationality; + } + + public Date getBirthdate() { + return birthdate; + } + + public void setBirthdate(Date birthdate) { + this.birthdate = birthdate; + } + + public PlaceOfBirth getPlaceOfBirth() { + return placeOfBirth; + } + + public void setPlaceOfBirth(PlaceOfBirth placeOfBirth) { + this.placeOfBirth = placeOfBirth; + } + + public void setInventions(String[] inventions) { + this.inventions = inventions; + } + + public String[] getInventions() { + return inventions; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Inventor.kt +---- + package org.spring.samples.spel.inventor + + class Inventor( + var name: String, + var nationality: String, + var inventions: Array? = null, + var birthdate: Date = GregorianCalendar().time, + var placeOfBirth: PlaceOfBirth? = null) +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.PlaceOfBirth.java +---- + package org.spring.samples.spel.inventor; + + public class PlaceOfBirth { + + private String city; + private String country; + + public PlaceOfBirth(String city) { + this.city=city; + } + + public PlaceOfBirth(String city, String country) { + this(city); + this.country = country; + } + + public String getCity() { + return city; + } + + public void setCity(String s) { + this.city = s; + } + + public String getCountry() { + return country; + } + + public void setCountry(String country) { + this.country = country; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.PlaceOfBirth.kt +---- + package org.spring.samples.spel.inventor + + class PlaceOfBirth(var city: String, var country: String? = null) { +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Society.java +---- + package org.spring.samples.spel.inventor; + + import java.util.*; + + public class Society { + + private String name; + + public static String Advisors = "advisors"; + public static String President = "president"; + + private List members = new ArrayList<>(); + private Map officers = new HashMap(); + + public List getMembers() { + return members; + } + + public Map getOfficers() { + return officers; + } + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public boolean isMember(String name) { + for (Inventor inventor : members) { + if (inventor.getName().equals(name)) { + return true; + } + } + return false; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Society.kt +---- + package org.spring.samples.spel.inventor + + import java.util.* + + class Society { + + val Advisors = "advisors" + val President = "president" + + var name: String? = null + + val members = ArrayList() + val officers = mapOf() + + fun isMember(name: String): Boolean { + for (inventor in members) { + if (inventor.name == name) { + return true + } + } + return false + } + } +---- diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc new file mode 100644 index 000000000000..2f17606729e9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc @@ -0,0 +1,24 @@ +[[expressions-language-ref]] += Language Reference + +This section describes how the Spring Expression Language works. It covers the following +topics: + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/array-construction.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/array-construction.adoc new file mode 100644 index 000000000000..aa1e52bfe17b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/array-construction.adoc @@ -0,0 +1,33 @@ +[[expressions-array-construction]] += Array Construction + +You can build arrays by using the familiar Java syntax, optionally supplying an initializer +to have the array populated at construction time. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + int[] numbers1 = (int[]) parser.parseExpression("new int[4]").getValue(context); + + // Array with initializer + int[] numbers2 = (int[]) parser.parseExpression("new int[]{1,2,3}").getValue(context); + + // Multi dimensional array + int[][] numbers3 = (int[][]) parser.parseExpression("new int[4][5]").getValue(context); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val numbers1 = parser.parseExpression("new int[4]").getValue(context) as IntArray + + // Array with initializer + val numbers2 = parser.parseExpression("new int[]{1,2,3}").getValue(context) as IntArray + + // Multi dimensional array + val numbers3 = parser.parseExpression("new int[4][5]").getValue(context) as Array +---- + +You cannot currently supply an initializer when you construct a multi-dimensional array. + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc new file mode 100644 index 000000000000..4ea79cd6319d --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc @@ -0,0 +1,53 @@ +[[expressions-bean-references]] += Bean References + +If the evaluation context has been configured with a bean resolver, you can +look up beans from an expression by using the `@` symbol. The following example shows how +to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + StandardEvaluationContext context = new StandardEvaluationContext(); + context.setBeanResolver(new MyBeanResolver()); + + // This will end up calling resolve(context,"something") on MyBeanResolver during evaluation + Object bean = parser.parseExpression("@something").getValue(context); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + val context = StandardEvaluationContext() + context.setBeanResolver(MyBeanResolver()) + + // This will end up calling resolve(context,"something") on MyBeanResolver during evaluation + val bean = parser.parseExpression("@something").getValue(context) +---- + +To access a factory bean itself, you should instead prefix the bean name with an `&` symbol. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + StandardEvaluationContext context = new StandardEvaluationContext(); + context.setBeanResolver(new MyBeanResolver()); + + // This will end up calling resolve(context,"&foo") on MyBeanResolver during evaluation + Object bean = parser.parseExpression("&foo").getValue(context); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + val context = StandardEvaluationContext() + context.setBeanResolver(MyBeanResolver()) + + // This will end up calling resolve(context,"&foo") on MyBeanResolver during evaluation + val bean = parser.parseExpression("&foo").getValue(context) +---- + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-projection.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-projection.adoc new file mode 100644 index 000000000000..bf2f229d7724 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-projection.adoc @@ -0,0 +1,30 @@ +[[expressions-collection-projection]] += Collection Projection + +Projection lets a collection drive the evaluation of a sub-expression, and the result is +a new collection. The syntax for projection is `.![projectionExpression]`. For example, +suppose we have a list of inventors but want the list of cities where they were born. +Effectively, we want to evaluate 'placeOfBirth.city' for every entry in the inventor +list. The following example uses projection to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // returns ['Smiljan', 'Idvor' ] + List placesOfBirth = (List)parser.parseExpression("members.![placeOfBirth.city]"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // returns ['Smiljan', 'Idvor' ] + val placesOfBirth = parser.parseExpression("members.![placeOfBirth.city]") as List<*> +---- + +Projection is supported for arrays and anything that implements `java.lang.Iterable` or +`java.util.Map`. When using a map to drive projection, the projection expression is +evaluated against each entry in the map (represented as a Java `Map.Entry`). The result +of a projection across a map is a list that consists of the evaluation of the projection +expression against each map entry. + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-selection.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-selection.adoc new file mode 100644 index 000000000000..90ade2b7c28b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-selection.adoc @@ -0,0 +1,50 @@ +[[expressions-collection-selection]] += Collection Selection + +Selection is a powerful expression language feature that lets you transform a +source collection into another collection by selecting from its entries. + +Selection uses a syntax of `.?[selectionExpression]`. It filters the collection and +returns a new collection that contains a subset of the original elements. For example, +selection lets us easily get a list of Serbian inventors, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + List list = (List) parser.parseExpression( + "members.?[nationality == 'Serbian']").getValue(societyContext); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val list = parser.parseExpression( + "members.?[nationality == 'Serbian']").getValue(societyContext) as List +---- + +Selection is supported for arrays and anything that implements `java.lang.Iterable` or +`java.util.Map`. For a list or array, the selection criteria is evaluated against each +individual element. Against a map, the selection criteria is evaluated against each map +entry (objects of the Java type `Map.Entry`). Each map entry has its `key` and `value` +accessible as properties for use in the selection. + +The following expression returns a new map that consists of those elements of the +original map where the entry's value is less than 27: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Map newMap = parser.parseExpression("map.?[value<27]").getValue(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val newMap = parser.parseExpression("map.?[value<27]").getValue() +---- + +In addition to returning all the selected elements, you can retrieve only the first or +the last element. To obtain the first element matching the selection, the syntax is +`.^[selectionExpression]`. To obtain the last matching selection, the syntax is +`.$[selectionExpression]`. + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/constructors.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/constructors.adoc new file mode 100644 index 000000000000..c99e0aada50e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/constructors.adoc @@ -0,0 +1,35 @@ +[[expressions-constructors]] += Constructors + +You can invoke constructors by using the `new` operator. You should use the fully +qualified class name for all types except those located in the `java.lang` package +(`Integer`, `Float`, `String`, and so on). The following example shows how to use the +`new` operator to invoke constructors: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Inventor einstein = p.parseExpression( + "new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German')") + .getValue(Inventor.class); + + // create new Inventor instance within the add() method of List + p.parseExpression( + "Members.add(new org.spring.samples.spel.inventor.Inventor( + 'Albert Einstein', 'German'))").getValue(societyContext); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val einstein = p.parseExpression( + "new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German')") + .getValue(Inventor::class.java) + + // create new Inventor instance within the add() method of List + p.parseExpression( + "Members.add(new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German'))") + .getValue(societyContext) +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/functions.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/functions.adoc new file mode 100644 index 000000000000..db24cf801fa0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/functions.adoc @@ -0,0 +1,80 @@ +[[expressions-ref-functions]] += Functions + +You can extend SpEL by registering user-defined functions that can be called within the +expression string. The function is registered through the `EvaluationContext`. The +following example shows how to register a user-defined function: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Method method = ...; + + EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); + context.setVariable("myFunction", method); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val method: Method = ... + + val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() + context.setVariable("myFunction", method) +---- + +For example, consider the following utility method that reverses a string: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public abstract class StringUtils { + + public static String reverseString(String input) { + StringBuilder backwards = new StringBuilder(input.length()); + for (int i = 0; i < input.length(); i++) { + backwards.append(input.charAt(input.length() - 1 - i)); + } + return backwards.toString(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun reverseString(input: String): String { + val backwards = StringBuilder(input.length) + for (i in 0 until input.length) { + backwards.append(input[input.length - 1 - i]) + } + return backwards.toString() + } +---- + +You can then register and use the preceding method, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + + EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); + context.setVariable("reverseString", + StringUtils.class.getDeclaredMethod("reverseString", String.class)); + + String helloWorldReversed = parser.parseExpression( + "#reverseString('hello')").getValue(context, String.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + + val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() + context.setVariable("reverseString", ::reverseString::javaMethod) + + val helloWorldReversed = parser.parseExpression( + "#reverseString('hello')").getValue(context, String::class.java) +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-lists.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-lists.adoc new file mode 100644 index 000000000000..0d23b7695c11 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-lists.adoc @@ -0,0 +1,28 @@ +[[expressions-inline-lists]] += Inline Lists + +You can directly express lists in an expression by using `{}` notation. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // evaluates to a Java list containing the four numbers + List numbers = (List) parser.parseExpression("{1,2,3,4}").getValue(context); + + List listOfLists = (List) parser.parseExpression("{{'a','b'},{'x','y'}}").getValue(context); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // evaluates to a Java list containing the four numbers + val numbers = parser.parseExpression("{1,2,3,4}").getValue(context) as List<*> + + val listOfLists = parser.parseExpression("{{'a','b'},{'x','y'}}").getValue(context) as List<*> +---- + +`{}` by itself means an empty list. For performance reasons, if the list is itself +entirely composed of fixed literals, a constant list is created to represent the +expression (rather than building a new list on each evaluation). + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-maps.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-maps.adoc new file mode 100644 index 000000000000..f20b26981939 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-maps.adoc @@ -0,0 +1,31 @@ +[[expressions-inline-maps]] += Inline Maps + +You can also directly express maps in an expression by using `{key:value}` notation. The +following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // evaluates to a Java map containing the two entries + Map inventorInfo = (Map) parser.parseExpression("{name:'Nikola',dob:'10-July-1856'}").getValue(context); + + Map mapOfMaps = (Map) parser.parseExpression("{name:{first:'Nikola',last:'Tesla'},dob:{day:10,month:'July',year:1856}}").getValue(context); +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + // evaluates to a Java map containing the two entries + val inventorInfo = parser.parseExpression("{name:'Nikola',dob:'10-July-1856'}").getValue(context) as Map<*, *> + + val mapOfMaps = parser.parseExpression("{name:{first:'Nikola',last:'Tesla'},dob:{day:10,month:'July',year:1856}}").getValue(context) as Map<*, *> +---- + +`{:}` by itself means an empty map. For performance reasons, if the map is itself +composed of fixed literals or other nested constant structures (lists or maps), a +constant map is created to represent the expression (rather than building a new map on +each evaluation). Quoting of the map keys is optional (unless the key contains a period +(`.`)). The examples above do not use quoted keys. + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/literal.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/literal.adoc new file mode 100644 index 000000000000..077f53aa0733 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/literal.adoc @@ -0,0 +1,68 @@ +[[expressions-ref-literal]] += Literal Expressions + +SpEL supports the following types of literal expressions. + +- strings +- numeric values: integer (`int` or `long`), hexadecimal (`int` or `long`), real (`float` + or `double`) +- boolean values: `true` or `false` +- null + +Strings can delimited by single quotation marks (`'`) or double quotation marks (`"`). To +include a single quotation mark within a string literal enclosed in single quotation +marks, use two adjacent single quotation mark characters. Similarly, to include a double +quotation mark within a string literal enclosed in double quotation marks, use two +adjacent double quotation mark characters. + +Numbers support the use of the negative sign, exponential notation, and decimal points. +By default, real numbers are parsed by using `Double.parseDouble()`. + +The following listing shows simple usage of literals. Typically, they are not used in +isolation like this but, rather, as part of a more complex expression -- for example, +using a literal on one side of a logical comparison operator or as an argument to a +method. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + + // evaluates to "Hello World" + String helloWorld = (String) parser.parseExpression("'Hello World'").getValue(); + + // evaluates to "Tony's Pizza" + String pizzaParlor = (String) parser.parseExpression("'Tony''s Pizza'").getValue(); + + double avogadrosNumber = (Double) parser.parseExpression("6.0221415E+23").getValue(); + + // evaluates to 2147483647 + int maxValue = (Integer) parser.parseExpression("0x7FFFFFFF").getValue(); + + boolean trueValue = (Boolean) parser.parseExpression("true").getValue(); + + Object nullValue = parser.parseExpression("null").getValue(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + + // evaluates to "Hello World" + val helloWorld = parser.parseExpression("'Hello World'").value as String + + // evaluates to "Tony's Pizza" + val pizzaParlor = parser.parseExpression("'Tony''s Pizza'").value as String + + val avogadrosNumber = parser.parseExpression("6.0221415E+23").value as Double + + // evaluates to 2147483647 + val maxValue = parser.parseExpression("0x7FFFFFFF").value as Int + + val trueValue = parser.parseExpression("true").value as Boolean + + val nullValue = parser.parseExpression("null").value +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/methods.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/methods.adoc new file mode 100644 index 000000000000..149d6a125770 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/methods.adoc @@ -0,0 +1,29 @@ +[[expressions-methods]] += Methods + +You can invoke methods by using typical Java programming syntax. You can also invoke methods +on literals. Variable arguments are also supported. The following examples show how to +invoke methods: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // string literal, evaluates to "bc" + String bc = parser.parseExpression("'abc'.substring(1, 3)").getValue(String.class); + + // evaluates to true + boolean isMember = parser.parseExpression("isMember('Mihajlo Pupin')").getValue( + societyContext, Boolean.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // string literal, evaluates to "bc" + val bc = parser.parseExpression("'abc'.substring(1, 3)").getValue(String::class.java) + + // evaluates to true + val isMember = parser.parseExpression("isMember('Mihajlo Pupin')").getValue( + societyContext, Boolean::class.java) +---- + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-elvis.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-elvis.adoc new file mode 100644 index 000000000000..199f131612e9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-elvis.adoc @@ -0,0 +1,79 @@ +[[expressions-operator-elvis]] += The Elvis Operator + +The Elvis operator is a shortening of the ternary operator syntax and is used in the +https://www.groovy-lang.org/operators.html#_elvis_operator[Groovy] language. +With the ternary operator syntax, you usually have to repeat a variable twice, as the +following example shows: + +[source,groovy,indent=0,subs="verbatim,quotes"] +---- + String name = "Elvis Presley"; + String displayName = (name != null ? name : "Unknown"); +---- + +Instead, you can use the Elvis operator (named for the resemblance to Elvis' hair style). +The following example shows how to use the Elvis operator: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + + String name = parser.parseExpression("name?:'Unknown'").getValue(new Inventor(), String.class); + System.out.println(name); // 'Unknown' +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + + val name = parser.parseExpression("name?:'Unknown'").getValue(Inventor(), String::class.java) + println(name) // 'Unknown' +---- + +The following listing shows a more complex example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); + + Inventor tesla = new Inventor("Nikola Tesla", "Serbian"); + String name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String.class); + System.out.println(name); // Nikola Tesla + + tesla.setName(null); + name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String.class); + System.out.println(name); // Elvis Presley +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() + + val tesla = Inventor("Nikola Tesla", "Serbian") + var name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String::class.java) + println(name) // Nikola Tesla + + tesla.setName(null) + name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String::class.java) + println(name) // Elvis Presley +---- + +[NOTE] +===== +You can use the Elvis operator to apply default values in expressions. The following +example shows how to use the Elvis operator in a `@Value` expression: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Value("#{systemProperties['pop3.port'] ?: 25}") +---- + +This will inject a system property `pop3.port` if it is defined or 25 if not. +===== + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-safe-navigation.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-safe-navigation.adoc new file mode 100644 index 000000000000..1398af00d0a0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-safe-navigation.adoc @@ -0,0 +1,45 @@ +[[expressions-operator-safe-navigation]] += Safe Navigation Operator + +The safe navigation operator is used to avoid a `NullPointerException` and comes from +the https://www.groovy-lang.org/operators.html#_safe_navigation_operator[Groovy] +language. Typically, when you have a reference to an object, you might need to verify that +it is not null before accessing methods or properties of the object. To avoid this, the +safe navigation operator returns null instead of throwing an exception. The following +example shows how to use the safe navigation operator: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); + + Inventor tesla = new Inventor("Nikola Tesla", "Serbian"); + tesla.setPlaceOfBirth(new PlaceOfBirth("Smiljan")); + + String city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String.class); + System.out.println(city); // Smiljan + + tesla.setPlaceOfBirth(null); + city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String.class); + System.out.println(city); // null - does not throw NullPointerException!!! +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() + + val tesla = Inventor("Nikola Tesla", "Serbian") + tesla.setPlaceOfBirth(PlaceOfBirth("Smiljan")) + + var city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String::class.java) + println(city) // Smiljan + + tesla.setPlaceOfBirth(null) + city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String::class.java) + println(city) // null - does not throw NullPointerException!!! +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-ternary.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-ternary.adoc new file mode 100644 index 000000000000..e843a1f582f0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-ternary.adoc @@ -0,0 +1,53 @@ +[[expressions-operator-ternary]] += Ternary Operator (If-Then-Else) + +You can use the ternary operator for performing if-then-else conditional logic inside +the expression. The following listing shows a minimal example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + String falseString = parser.parseExpression( + "false ? 'trueExp' : 'falseExp'").getValue(String.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val falseString = parser.parseExpression( + "false ? 'trueExp' : 'falseExp'").getValue(String::class.java) +---- + +In this case, the boolean `false` results in returning the string value `'falseExp'`. A more +realistic example follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + parser.parseExpression("name").setValue(societyContext, "IEEE"); + societyContext.setVariable("queryName", "Nikola Tesla"); + + expression = "isMember(#queryName)? #queryName + ' is a member of the ' " + + "+ Name + ' Society' : #queryName + ' is not a member of the ' + Name + ' Society'"; + + String queryResultString = parser.parseExpression(expression) + .getValue(societyContext, String.class); + // queryResultString = "Nikola Tesla is a member of the IEEE Society" +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + parser.parseExpression("name").setValue(societyContext, "IEEE") + societyContext.setVariable("queryName", "Nikola Tesla") + + expression = "isMember(#queryName)? #queryName + ' is a member of the ' " + "+ Name + ' Society' : #queryName + ' is not a member of the ' + Name + ' Society'" + + val queryResultString = parser.parseExpression(expression) + .getValue(societyContext, String::class.java) + // queryResultString = "Nikola Tesla is a member of the IEEE Society" +---- + +See the next section on the Elvis operator for an even shorter syntax for the +ternary operator. + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc new file mode 100644 index 000000000000..2f0e56c1a2c0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc @@ -0,0 +1,297 @@ +[[expressions-operators]] += Operators + +The Spring Expression Language supports the following kinds of operators: + +* <> +* <> +* <> +* <> + + +[[expressions-operators-relational]] +== Relational Operators + +The relational operators (equal, not equal, less than, less than or equal, greater than, +and greater than or equal) are supported by using standard operator notation. +These operators work on `Number` types as well as types implementing `Comparable`. +The following listing shows a few examples of operators: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // evaluates to true + boolean trueValue = parser.parseExpression("2 == 2").getValue(Boolean.class); + + // evaluates to false + boolean falseValue = parser.parseExpression("2 < -5.0").getValue(Boolean.class); + + // evaluates to true + boolean trueValue = parser.parseExpression("'black' < 'block'").getValue(Boolean.class); + + // uses CustomValue:::compareTo + boolean trueValue = parser.parseExpression("new CustomValue(1) < new CustomValue(2)").getValue(Boolean.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // evaluates to true + val trueValue = parser.parseExpression("2 == 2").getValue(Boolean::class.java) + + // evaluates to false + val falseValue = parser.parseExpression("2 < -5.0").getValue(Boolean::class.java) + + // evaluates to true + val trueValue = parser.parseExpression("'black' < 'block'").getValue(Boolean::class.java) + + // uses CustomValue:::compareTo + val trueValue = parser.parseExpression("new CustomValue(1) < new CustomValue(2)").getValue(Boolean::class.java); +---- + +[NOTE] +==== +Greater-than and less-than comparisons against `null` follow a simple rule: `null` is treated as +nothing (that is NOT as zero). As a consequence, any other value is always greater +than `null` (`X > null` is always `true`) and no other value is ever less than nothing +(`X < null` is always `false`). + +If you prefer numeric comparisons instead, avoid number-based `null` comparisons +in favor of comparisons against zero (for example, `X > 0` or `X < 0`). +==== + +In addition to the standard relational operators, SpEL supports the `instanceof` and regular +expression-based `matches` operator. The following listing shows examples of both: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // evaluates to false + boolean falseValue = parser.parseExpression( + "'xyz' instanceof T(Integer)").getValue(Boolean.class); + + // evaluates to true + boolean trueValue = parser.parseExpression( + "'5.00' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean.class); + + // evaluates to false + boolean falseValue = parser.parseExpression( + "'5.0067' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // evaluates to false + val falseValue = parser.parseExpression( + "'xyz' instanceof T(Integer)").getValue(Boolean::class.java) + + // evaluates to true + val trueValue = parser.parseExpression( + "'5.00' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean::class.java) + + // evaluates to false + val falseValue = parser.parseExpression( + "'5.0067' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean::class.java) +---- + +CAUTION: Be careful with primitive types, as they are immediately boxed up to their +wrapper types. For example, `1 instanceof T(int)` evaluates to `false`, while +`1 instanceof T(Integer)` evaluates to `true`, as expected. + +Each symbolic operator can also be specified as a purely alphabetic equivalent. This +avoids problems where the symbols used have special meaning for the document type in +which the expression is embedded (such as in an XML document). The textual equivalents are: + +* `lt` (`<`) +* `gt` (`>`) +* `le` (`\<=`) +* `ge` (`>=`) +* `eq` (`==`) +* `ne` (`!=`) +* `div` (`/`) +* `mod` (`%`) +* `not` (`!`). + +All of the textual operators are case-insensitive. + + +[[expressions-operators-logical]] +== Logical Operators + +SpEL supports the following logical operators: + +* `and` (`&&`) +* `or` (`||`) +* `not` (`!`) + +The following example shows how to use the logical operators: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // -- AND -- + + // evaluates to false + boolean falseValue = parser.parseExpression("true and false").getValue(Boolean.class); + + // evaluates to true + String expression = "isMember('Nikola Tesla') and isMember('Mihajlo Pupin')"; + boolean trueValue = parser.parseExpression(expression).getValue(societyContext, Boolean.class); + + // -- OR -- + + // evaluates to true + boolean trueValue = parser.parseExpression("true or false").getValue(Boolean.class); + + // evaluates to true + String expression = "isMember('Nikola Tesla') or isMember('Albert Einstein')"; + boolean trueValue = parser.parseExpression(expression).getValue(societyContext, Boolean.class); + + // -- NOT -- + + // evaluates to false + boolean falseValue = parser.parseExpression("!true").getValue(Boolean.class); + + // -- AND and NOT -- + String expression = "isMember('Nikola Tesla') and !isMember('Mihajlo Pupin')"; + boolean falseValue = parser.parseExpression(expression).getValue(societyContext, Boolean.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // -- AND -- + + // evaluates to false + val falseValue = parser.parseExpression("true and false").getValue(Boolean::class.java) + + // evaluates to true + val expression = "isMember('Nikola Tesla') and isMember('Mihajlo Pupin')" + val trueValue = parser.parseExpression(expression).getValue(societyContext, Boolean::class.java) + + // -- OR -- + + // evaluates to true + val trueValue = parser.parseExpression("true or false").getValue(Boolean::class.java) + + // evaluates to true + val expression = "isMember('Nikola Tesla') or isMember('Albert Einstein')" + val trueValue = parser.parseExpression(expression).getValue(societyContext, Boolean::class.java) + + // -- NOT -- + + // evaluates to false + val falseValue = parser.parseExpression("!true").getValue(Boolean::class.java) + + // -- AND and NOT -- + val expression = "isMember('Nikola Tesla') and !isMember('Mihajlo Pupin')" + val falseValue = parser.parseExpression(expression).getValue(societyContext, Boolean::class.java) +---- + + +[[expressions-operators-mathematical]] +== Mathematical Operators + +You can use the addition operator (`+`) on both numbers and strings. You can use the +subtraction (`-`), multiplication (`*`), and division (`/`) operators only on numbers. +You can also use the modulus (`%`) and exponential power (`^`) operators on numbers. +Standard operator precedence is enforced. The following example shows the mathematical +operators in use: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Addition + int two = parser.parseExpression("1 + 1").getValue(Integer.class); // 2 + + String testString = parser.parseExpression( + "'test' + ' ' + 'string'").getValue(String.class); // 'test string' + + // Subtraction + int four = parser.parseExpression("1 - -3").getValue(Integer.class); // 4 + + double d = parser.parseExpression("1000.00 - 1e4").getValue(Double.class); // -9000 + + // Multiplication + int six = parser.parseExpression("-2 * -3").getValue(Integer.class); // 6 + + double twentyFour = parser.parseExpression("2.0 * 3e0 * 4").getValue(Double.class); // 24.0 + + // Division + int minusTwo = parser.parseExpression("6 / -3").getValue(Integer.class); // -2 + + double one = parser.parseExpression("8.0 / 4e0 / 2").getValue(Double.class); // 1.0 + + // Modulus + int three = parser.parseExpression("7 % 4").getValue(Integer.class); // 3 + + int one = parser.parseExpression("8 / 5 % 2").getValue(Integer.class); // 1 + + // Operator precedence + int minusTwentyOne = parser.parseExpression("1+2-3*8").getValue(Integer.class); // -21 +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Addition + val two = parser.parseExpression("1 + 1").getValue(Int::class.java) // 2 + + val testString = parser.parseExpression( + "'test' + ' ' + 'string'").getValue(String::class.java) // 'test string' + + // Subtraction + val four = parser.parseExpression("1 - -3").getValue(Int::class.java) // 4 + + val d = parser.parseExpression("1000.00 - 1e4").getValue(Double::class.java) // -9000 + + // Multiplication + val six = parser.parseExpression("-2 * -3").getValue(Int::class.java) // 6 + + val twentyFour = parser.parseExpression("2.0 * 3e0 * 4").getValue(Double::class.java) // 24.0 + + // Division + val minusTwo = parser.parseExpression("6 / -3").getValue(Int::class.java) // -2 + + val one = parser.parseExpression("8.0 / 4e0 / 2").getValue(Double::class.java) // 1.0 + + // Modulus + val three = parser.parseExpression("7 % 4").getValue(Int::class.java) // 3 + + val one = parser.parseExpression("8 / 5 % 2").getValue(Int::class.java) // 1 + + // Operator precedence + val minusTwentyOne = parser.parseExpression("1+2-3*8").getValue(Int::class.java) // -21 +---- + + +[[expressions-assignment]] +== The Assignment Operator + +To set a property, use the assignment operator (`=`). This is typically done within a +call to `setValue` but can also be done inside a call to `getValue`. The following +listing shows both ways to use the assignment operator: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Inventor inventor = new Inventor(); + EvaluationContext context = SimpleEvaluationContext.forReadWriteDataBinding().build(); + + parser.parseExpression("name").setValue(context, inventor, "Aleksandar Seovic"); + + // alternatively + String aleks = parser.parseExpression( + "name = 'Aleksandar Seovic'").getValue(context, inventor, String.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val inventor = Inventor() + val context = SimpleEvaluationContext.forReadWriteDataBinding().build() + + parser.parseExpression("name").setValue(context, inventor, "Aleksandar Seovic") + + // alternatively + val aleks = parser.parseExpression( + "name = 'Aleksandar Seovic'").getValue(context, inventor, String::class.java) +---- + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc new file mode 100644 index 000000000000..5935065e403b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc @@ -0,0 +1,124 @@ +[[expressions-properties-arrays]] += Properties, Arrays, Lists, Maps, and Indexers + +Navigating with property references is easy. To do so, use a period to indicate a nested +property value. The instances of the `Inventor` class, `pupin` and `tesla`, were +populated with data listed in the <> section. To navigate "down" the object graph and get Tesla's year of birth and +Pupin's city of birth, we use the following expressions: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // evaluates to 1856 + int year = (Integer) parser.parseExpression("birthdate.year + 1900").getValue(context); + + String city = (String) parser.parseExpression("placeOfBirth.city").getValue(context); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // evaluates to 1856 + val year = parser.parseExpression("birthdate.year + 1900").getValue(context) as Int + + val city = parser.parseExpression("placeOfBirth.city").getValue(context) as String +---- + +[NOTE] +==== +Case insensitivity is allowed for the first letter of property names. Thus, the +expressions in the above example may be written as `Birthdate.Year + 1900` and +`PlaceOfBirth.City`, respectively. In addition, properties may optionally be accessed via +method invocations -- for example, `getPlaceOfBirth().getCity()` instead of +`placeOfBirth.city`. +==== + +The contents of arrays and lists are obtained by using square bracket notation, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ExpressionParser parser = new SpelExpressionParser(); + EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); + + // Inventions Array + + // evaluates to "Induction motor" + String invention = parser.parseExpression("inventions[3]").getValue( + context, tesla, String.class); + + // Members List + + // evaluates to "Nikola Tesla" + String name = parser.parseExpression("members[0].name").getValue( + context, ieee, String.class); + + // List and Array navigation + // evaluates to "Wireless communication" + String invention = parser.parseExpression("members[0].inventions[6]").getValue( + context, ieee, String.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val parser = SpelExpressionParser() + val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() + + // Inventions Array + + // evaluates to "Induction motor" + val invention = parser.parseExpression("inventions[3]").getValue( + context, tesla, String::class.java) + + // Members List + + // evaluates to "Nikola Tesla" + val name = parser.parseExpression("members[0].name").getValue( + context, ieee, String::class.java) + + // List and Array navigation + // evaluates to "Wireless communication" + val invention = parser.parseExpression("members[0].inventions[6]").getValue( + context, ieee, String::class.java) +---- + +The contents of maps are obtained by specifying the literal key value within the +brackets. In the following example, because keys for the `officers` map are strings, we can specify +string literals: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Officer's Dictionary + + Inventor pupin = parser.parseExpression("officers['president']").getValue( + societyContext, Inventor.class); + + // evaluates to "Idvor" + String city = parser.parseExpression("officers['president'].placeOfBirth.city").getValue( + societyContext, String.class); + + // setting values + parser.parseExpression("officers['advisors'][0].placeOfBirth.country").setValue( + societyContext, "Croatia"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Officer's Dictionary + + val pupin = parser.parseExpression("officers['president']").getValue( + societyContext, Inventor::class.java) + + // evaluates to "Idvor" + val city = parser.parseExpression("officers['president'].placeOfBirth.city").getValue( + societyContext, String::class.java) + + // setting values + parser.parseExpression("officers['advisors'][0].placeOfBirth.country").setValue( + societyContext, "Croatia") +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/templating.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/templating.adoc new file mode 100644 index 000000000000..6c521a8f0dc1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/templating.adoc @@ -0,0 +1,72 @@ +[[expressions-templating]] += Expression templating + +Expression templates allow mixing literal text with one or more evaluation blocks. +Each evaluation block is delimited with prefix and suffix characters that you can +define. A common choice is to use `#{ }` as the delimiters, as the following example +shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + String randomPhrase = parser.parseExpression( + "random number is #{T(java.lang.Math).random()}", + new TemplateParserContext()).getValue(String.class); + + // evaluates to "random number is 0.7038186818312008" +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val randomPhrase = parser.parseExpression( + "random number is #{T(java.lang.Math).random()}", + TemplateParserContext()).getValue(String::class.java) + + // evaluates to "random number is 0.7038186818312008" +---- + +The string is evaluated by concatenating the literal text `'random number is '` with the +result of evaluating the expression inside the `#{ }` delimiter (in this case, the result +of calling that `random()` method). The second argument to the `parseExpression()` method +is of the type `ParserContext`. The `ParserContext` interface is used to influence how +the expression is parsed in order to support the expression templating functionality. +The definition of `TemplateParserContext` follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class TemplateParserContext implements ParserContext { + + public String getExpressionPrefix() { + return "#{"; + } + + public String getExpressionSuffix() { + return "}"; + } + + public boolean isTemplate() { + return true; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class TemplateParserContext : ParserContext { + + override fun getExpressionPrefix(): String { + return "#{" + } + + override fun getExpressionSuffix(): String { + return "}" + } + + override fun isTemplate(): Boolean { + return true + } + } +---- + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/types.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/types.adoc new file mode 100644 index 000000000000..b74d96c606e7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/types.adoc @@ -0,0 +1,36 @@ +[[expressions-types]] += Types + +You can use the special `T` operator to specify an instance of `java.lang.Class` (the +type). Static methods are invoked by using this operator as well. The +`StandardEvaluationContext` uses a `TypeLocator` to find types, and the +`StandardTypeLocator` (which can be replaced) is built with an understanding of the +`java.lang` package. This means that `T()` references to types within the `java.lang` +package do not need to be fully qualified, but all other type references must be. The +following example shows how to use the `T` operator: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Class dateClass = parser.parseExpression("T(java.util.Date)").getValue(Class.class); + + Class stringClass = parser.parseExpression("T(String)").getValue(Class.class); + + boolean trueValue = parser.parseExpression( + "T(java.math.RoundingMode).CEILING < T(java.math.RoundingMode).FLOOR") + .getValue(Boolean.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val dateClass = parser.parseExpression("T(java.util.Date)").getValue(Class::class.java) + + val stringClass = parser.parseExpression("T(String)").getValue(Class::class.java) + + val trueValue = parser.parseExpression( + "T(java.math.RoundingMode).CEILING < T(java.math.RoundingMode).FLOOR") + .getValue(Boolean::class.java) +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/variables.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/variables.adoc new file mode 100644 index 000000000000..c3e88e624087 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/variables.adoc @@ -0,0 +1,89 @@ +[[expressions-ref-variables]] += Variables + +You can reference variables in the expression by using the `#variableName` syntax. Variables +are set by using the `setVariable` method on `EvaluationContext` implementations. + +[NOTE] +==== +Valid variable names must be composed of one or more of the following supported +characters. + +* letters: `A` to `Z` and `a` to `z` +* digits: `0` to `9` +* underscore: `_` +* dollar sign: `$` +==== + +The following example shows how to use variables. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Inventor tesla = new Inventor("Nikola Tesla", "Serbian"); + + EvaluationContext context = SimpleEvaluationContext.forReadWriteDataBinding().build(); + context.setVariable("newName", "Mike Tesla"); + + parser.parseExpression("name = #newName").getValue(context, tesla); + System.out.println(tesla.getName()) // "Mike Tesla" +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val tesla = Inventor("Nikola Tesla", "Serbian") + + val context = SimpleEvaluationContext.forReadWriteDataBinding().build() + context.setVariable("newName", "Mike Tesla") + + parser.parseExpression("name = #newName").getValue(context, tesla) + println(tesla.name) // "Mike Tesla" +---- + + +[[expressions-this-root]] +== The `#this` and `#root` Variables + +The `#this` variable is always defined and refers to the current evaluation object +(against which unqualified references are resolved). The `#root` variable is always +defined and refers to the root context object. Although `#this` may vary as components of +an expression are evaluated, `#root` always refers to the root. The following examples +show how to use the `#this` and `#root` variables: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // create an array of integers + List primes = new ArrayList<>(); + primes.addAll(Arrays.asList(2,3,5,7,11,13,17)); + + // create parser and set variable 'primes' as the array of integers + ExpressionParser parser = new SpelExpressionParser(); + EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataAccess(); + context.setVariable("primes", primes); + + // all prime numbers > 10 from the list (using selection ?{...}) + // evaluates to [11, 13, 17] + List primesGreaterThanTen = (List) parser.parseExpression( + "#primes.?[#this>10]").getValue(context); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // create an array of integers + val primes = ArrayList() + primes.addAll(listOf(2, 3, 5, 7, 11, 13, 17)) + + // create parser and set variable 'primes' as the array of integers + val parser = SpelExpressionParser() + val context = SimpleEvaluationContext.forReadOnlyDataAccess() + context.setVariable("primes", primes) + + // all prime numbers > 10 from the list (using selection ?{...}) + // evaluates to [11, 13, 17] + val primesGreaterThanTen = parser.parseExpression( + "#primes.?[#this>10]").getValue(context) as List +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/validation.adoc b/framework-docs/modules/ROOT/pages/core/validation.adoc index db72e48766a0..84bad43d2d14 100644 --- a/framework-docs/modules/ROOT/pages/core/validation.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation.adoc @@ -38,1976 +38,3 @@ be useful for plugging in custom validation logic. -[[validator]] -== Validation by Using Spring's Validator Interface - -Spring features a `Validator` interface that you can use to validate objects. The -`Validator` interface works by using an `Errors` object so that, while validating, -validators can report validation failures to the `Errors` object. - -Consider the following example of a small data object: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class Person { - - private String name; - private int age; - - // the usual getters and setters... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class Person(val name: String, val age: Int) ----- - -The next example provides validation behavior for the `Person` class by implementing the -following two methods of the `org.springframework.validation.Validator` interface: - -* `supports(Class)`: Can this `Validator` validate instances of the supplied `Class`? -* `validate(Object, org.springframework.validation.Errors)`: Validates the given object - and, in case of validation errors, registers those with the given `Errors` object. - -Implementing a `Validator` is fairly straightforward, especially when you know of the -`ValidationUtils` helper class that the Spring Framework also provides. The following -example implements `Validator` for `Person` instances: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class PersonValidator implements Validator { - - /** - * This Validator validates only Person instances - */ - public boolean supports(Class clazz) { - return Person.class.equals(clazz); - } - - public void validate(Object obj, Errors e) { - ValidationUtils.rejectIfEmpty(e, "name", "name.empty"); - Person p = (Person) obj; - if (p.getAge() < 0) { - e.rejectValue("age", "negativevalue"); - } else if (p.getAge() > 110) { - e.rejectValue("age", "too.darn.old"); - } - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class PersonValidator : Validator { - - /\** - * This Validator validates only Person instances - */ - override fun supports(clazz: Class<*>): Boolean { - return Person::class.java == clazz - } - - override fun validate(obj: Any, e: Errors) { - ValidationUtils.rejectIfEmpty(e, "name", "name.empty") - val p = obj as Person - if (p.age < 0) { - e.rejectValue("age", "negativevalue") - } else if (p.age > 110) { - e.rejectValue("age", "too.darn.old") - } - } - } ----- - -The `static` `rejectIfEmpty(..)` method on the `ValidationUtils` class is used to -reject the `name` property if it is `null` or the empty string. Have a look at the -{api-spring-framework}/validation/ValidationUtils.html[`ValidationUtils`] javadoc -to see what functionality it provides besides the example shown previously. - -While it is certainly possible to implement a single `Validator` class to validate each -of the nested objects in a rich object, it may be better to encapsulate the validation -logic for each nested class of object in its own `Validator` implementation. A simple -example of a "`rich`" object would be a `Customer` that is composed of two `String` -properties (a first and a second name) and a complex `Address` object. `Address` objects -may be used independently of `Customer` objects, so a distinct `AddressValidator` -has been implemented. If you want your `CustomerValidator` to reuse the logic contained -within the `AddressValidator` class without resorting to copy-and-paste, you can -dependency-inject or instantiate an `AddressValidator` within your `CustomerValidator`, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class CustomerValidator implements Validator { - - private final Validator addressValidator; - - public CustomerValidator(Validator addressValidator) { - if (addressValidator == null) { - throw new IllegalArgumentException("The supplied [Validator] is " + - "required and must not be null."); - } - if (!addressValidator.supports(Address.class)) { - throw new IllegalArgumentException("The supplied [Validator] must " + - "support the validation of [Address] instances."); - } - this.addressValidator = addressValidator; - } - - /** - * This Validator validates Customer instances, and any subclasses of Customer too - */ - public boolean supports(Class clazz) { - return Customer.class.isAssignableFrom(clazz); - } - - public void validate(Object target, Errors errors) { - ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "field.required"); - ValidationUtils.rejectIfEmptyOrWhitespace(errors, "surname", "field.required"); - Customer customer = (Customer) target; - try { - errors.pushNestedPath("address"); - ValidationUtils.invokeValidator(this.addressValidator, customer.getAddress(), errors); - } finally { - errors.popNestedPath(); - } - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class CustomerValidator(private val addressValidator: Validator) : Validator { - - init { - if (addressValidator == null) { - throw IllegalArgumentException("The supplied [Validator] is required and must not be null.") - } - if (!addressValidator.supports(Address::class.java)) { - throw IllegalArgumentException("The supplied [Validator] must support the validation of [Address] instances.") - } - } - - /** - * This Validator validates Customer instances, and any subclasses of Customer too - */ - override fun supports(clazz: Class<*>): Boolean { - return Customer::class.java.isAssignableFrom(clazz) - } - - override fun validate(target: Any, errors: Errors) { - ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "field.required") - ValidationUtils.rejectIfEmptyOrWhitespace(errors, "surname", "field.required") - val customer = target as Customer - try { - errors.pushNestedPath("address") - ValidationUtils.invokeValidator(this.addressValidator, customer.address, errors) - } finally { - errors.popNestedPath() - } - } - } ----- - -Validation errors are reported to the `Errors` object passed to the validator. In the case -of Spring Web MVC, you can use the `` tag to inspect the error messages, but -you can also inspect the `Errors` object yourself. More information about the -methods it offers can be found in the {api-spring-framework}/validation/Errors.html[javadoc]. - - - - -[[validation-conversion]] -== Resolving Codes to Error Messages - -We covered databinding and validation. This section covers outputting messages that correspond -to validation errors. In the example shown in the <>, -we rejected the `name` and `age` fields. If we want to output the error messages by using a -`MessageSource`, we can do so using the error code we provide when rejecting the field -('name' and 'age' in this case). When you call (either directly, or indirectly, by using, -for example, the `ValidationUtils` class) `rejectValue` or one of the other `reject` methods -from the `Errors` interface, the underlying implementation not only registers the code you -passed in but also registers a number of additional error codes. The `MessageCodesResolver` -determines which error codes the `Errors` interface registers. By default, the -`DefaultMessageCodesResolver` is used, which (for example) not only registers a message -with the code you gave but also registers messages that include the field name you passed -to the reject method. So, if you reject a field by using `rejectValue("age", "too.darn.old")`, -apart from the `too.darn.old` code, Spring also registers `too.darn.old.age` and -`too.darn.old.age.int` (the first includes the field name and the second includes the type -of the field). This is done as a convenience to aid developers when targeting error messages. - -More information on the `MessageCodesResolver` and the default strategy can be found -in the javadoc of -{api-spring-framework}/validation/MessageCodesResolver.html[`MessageCodesResolver`] and -{api-spring-framework}/validation/DefaultMessageCodesResolver.html[`DefaultMessageCodesResolver`], -respectively. - - - - -[[beans-beans]] -== Bean Manipulation and the `BeanWrapper` - -The `org.springframework.beans` package adheres to the JavaBeans standard. -A JavaBean is a class with a default no-argument constructor and that follows -a naming convention where (for example) a property named `bingoMadness` would -have a setter method `setBingoMadness(..)` and a getter method `getBingoMadness()`. For -more information about JavaBeans and the specification, see -https://docs.oracle.com/javase/8/docs/api/java/beans/package-summary.html[javabeans]. - -One quite important class in the beans package is the `BeanWrapper` interface and its -corresponding implementation (`BeanWrapperImpl`). As quoted from the javadoc, the -`BeanWrapper` offers functionality to set and get property values (individually or in -bulk), get property descriptors, and query properties to determine if they are -readable or writable. Also, the `BeanWrapper` offers support for nested properties, -enabling the setting of properties on sub-properties to an unlimited depth. The -`BeanWrapper` also supports the ability to add standard JavaBeans `PropertyChangeListeners` -and `VetoableChangeListeners`, without the need for supporting code in the target class. -Last but not least, the `BeanWrapper` provides support for setting indexed properties. -The `BeanWrapper` usually is not used by application code directly but is used by the -`DataBinder` and the `BeanFactory`. - -The way the `BeanWrapper` works is partly indicated by its name: it wraps a bean to -perform actions on that bean, such as setting and retrieving properties. - - - -[[beans-beans-conventions]] -=== Setting and Getting Basic and Nested Properties - -Setting and getting properties is done through the `setPropertyValue` and -`getPropertyValue` overloaded method variants of `BeanWrapper`. See their Javadoc for -details. The below table shows some examples of these conventions: - -[[beans-beans-conventions-properties-tbl]] -.Examples of properties -|=== -| Expression| Explanation - -| `name` -| Indicates the property `name` that corresponds to the `getName()` or `isName()` - and `setName(..)` methods. - -| `account.name` -| Indicates the nested property `name` of the property `account` that corresponds to - (for example) the `getAccount().setName()` or `getAccount().getName()` methods. - -| `account[2]` -| Indicates the _third_ element of the indexed property `account`. Indexed properties - can be of type `array`, `list`, or other naturally ordered collection. - -| `account[COMPANYNAME]` -| Indicates the value of the map entry indexed by the `COMPANYNAME` key of the `account` `Map` - property. -|=== - -(This next section is not vitally important to you if you do not plan to work with -the `BeanWrapper` directly. If you use only the `DataBinder` and the `BeanFactory` -and their default implementations, you should skip ahead to the -<>.) - -The following two example classes use the `BeanWrapper` to get and set -properties: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class Company { - - private String name; - private Employee managingDirector; - - public String getName() { - return this.name; - } - - public void setName(String name) { - this.name = name; - } - - public Employee getManagingDirector() { - return this.managingDirector; - } - - public void setManagingDirector(Employee managingDirector) { - this.managingDirector = managingDirector; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class Company { - var name: String? = null - var managingDirector: Employee? = null - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class Employee { - - private String name; - - private float salary; - - public String getName() { - return this.name; - } - - public void setName(String name) { - this.name = name; - } - - public float getSalary() { - return salary; - } - - public void setSalary(float salary) { - this.salary = salary; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class Employee { - var name: String? = null - var salary: Float? = null - } ----- - -The following code snippets show some examples of how to retrieve and manipulate some of -the properties of instantiated ``Company``s and ``Employee``s: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - BeanWrapper company = new BeanWrapperImpl(new Company()); - // setting the company name.. - company.setPropertyValue("name", "Some Company Inc."); - // ... can also be done like this: - PropertyValue value = new PropertyValue("name", "Some Company Inc."); - company.setPropertyValue(value); - - // ok, let's create the director and tie it to the company: - BeanWrapper jim = new BeanWrapperImpl(new Employee()); - jim.setPropertyValue("name", "Jim Stravinsky"); - company.setPropertyValue("managingDirector", jim.getWrappedInstance()); - - // retrieving the salary of the managingDirector through the company - Float salary = (Float) company.getPropertyValue("managingDirector.salary"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val company = BeanWrapperImpl(Company()) - // setting the company name.. - company.setPropertyValue("name", "Some Company Inc.") - // ... can also be done like this: - val value = PropertyValue("name", "Some Company Inc.") - company.setPropertyValue(value) - - // ok, let's create the director and tie it to the company: - val jim = BeanWrapperImpl(Employee()) - jim.setPropertyValue("name", "Jim Stravinsky") - company.setPropertyValue("managingDirector", jim.wrappedInstance) - - // retrieving the salary of the managingDirector through the company - val salary = company.getPropertyValue("managingDirector.salary") as Float? ----- - - - -[[beans-beans-conversion]] -=== Built-in `PropertyEditor` Implementations - -Spring uses the concept of a `PropertyEditor` to effect the conversion between an -`Object` and a `String`. It can be handy -to represent properties in a different way than the object itself. For example, a `Date` -can be represented in a human readable way (as the `String`: `'2007-14-09'`), while -we can still convert the human readable form back to the original date (or, even -better, convert any date entered in a human readable form back to `Date` objects). This -behavior can be achieved by registering custom editors of type -`java.beans.PropertyEditor`. Registering custom editors on a `BeanWrapper` or, -alternatively, in a specific IoC container (as mentioned in the previous chapter), gives it -the knowledge of how to convert properties to the desired type. For more about -`PropertyEditor`, see https://docs.oracle.com/javase/8/docs/api/java/beans/package-summary.html[the javadoc of the `java.beans` package from Oracle]. - -A couple of examples where property editing is used in Spring: - -* Setting properties on beans is done by using `PropertyEditor` implementations. - When you use `String` as the value of a property of some bean that you declare - in an XML file, Spring (if the setter of the corresponding property has a `Class` - parameter) uses `ClassEditor` to try to resolve the parameter to a `Class` object. -* Parsing HTTP request parameters in Spring's MVC framework is done by using all kinds - of `PropertyEditor` implementations that you can manually bind in all subclasses of the - `CommandController`. - -Spring has a number of built-in `PropertyEditor` implementations to make life easy. -They are all located in the `org.springframework.beans.propertyeditors` -package. Most, (but not all, as indicated in the following table) are, by default, registered by -`BeanWrapperImpl`. Where the property editor is configurable in some fashion, you can -still register your own variant to override the default one. The following table describes -the various `PropertyEditor` implementations that Spring provides: - -[[beans-beans-property-editors-tbl]] -.Built-in `PropertyEditor` Implementations -[cols="30%,70%"] -|=== -| Class| Explanation - -| `ByteArrayPropertyEditor` -| Editor for byte arrays. Converts strings to their corresponding byte - representations. Registered by default by `BeanWrapperImpl`. - -| `ClassEditor` -| Parses Strings that represent classes to actual classes and vice-versa. When a - class is not found, an `IllegalArgumentException` is thrown. By default, registered by - `BeanWrapperImpl`. - -| `CustomBooleanEditor` -| Customizable property editor for `Boolean` properties. By default, registered by - `BeanWrapperImpl` but can be overridden by registering a custom instance of it as a - custom editor. - -| `CustomCollectionEditor` -| Property editor for collections, converting any source `Collection` to a given target - `Collection` type. - -| `CustomDateEditor` -| Customizable property editor for `java.util.Date`, supporting a custom `DateFormat`. NOT - registered by default. Must be user-registered with the appropriate format as needed. - -| `CustomNumberEditor` -| Customizable property editor for any `Number` subclass, such as `Integer`, `Long`, `Float`, or - `Double`. By default, registered by `BeanWrapperImpl` but can be overridden by - registering a custom instance of it as a custom editor. - -| `FileEditor` -| Resolves strings to `java.io.File` objects. By default, registered by - `BeanWrapperImpl`. - -| `InputStreamEditor` -| One-way property editor that can take a string and produce (through an - intermediate `ResourceEditor` and `Resource`) an `InputStream` so that `InputStream` - properties may be directly set as strings. Note that the default usage does not close - the `InputStream` for you. By default, registered by `BeanWrapperImpl`. - -| `LocaleEditor` -| Can resolve strings to `Locale` objects and vice-versa (the string format is - `[language]\_[country]_[variant]`, same as the `toString()` method of - `Locale`). Also accepts spaces as separators, as an alternative to underscores. - By default, registered by `BeanWrapperImpl`. - -| `PatternEditor` -| Can resolve strings to `java.util.regex.Pattern` objects and vice-versa. - -| `PropertiesEditor` -| Can convert strings (formatted with the format defined in the javadoc of the - `java.util.Properties` class) to `Properties` objects. By default, registered - by `BeanWrapperImpl`. - -| `StringTrimmerEditor` -| Property editor that trims strings. Optionally allows transforming an empty string - into a `null` value. NOT registered by default -- must be user-registered. - -| `URLEditor` -| Can resolve a string representation of a URL to an actual `URL` object. - By default, registered by `BeanWrapperImpl`. -|=== - -Spring uses the `java.beans.PropertyEditorManager` to set the search path for property -editors that might be needed. The search path also includes `sun.bean.editors`, which -includes `PropertyEditor` implementations for types such as `Font`, `Color`, and most of -the primitive types. Note also that the standard JavaBeans infrastructure -automatically discovers `PropertyEditor` classes (without you having to register them -explicitly) if they are in the same package as the class they handle and have the same -name as that class, with `Editor` appended. For example, one could have the following -class and package structure, which would be sufficient for the `SomethingEditor` class to be -recognized and used as the `PropertyEditor` for `Something`-typed properties. - -[literal,subs="verbatim,quotes"] ----- -com - chank - pop - Something - SomethingEditor // the PropertyEditor for the Something class ----- - -Note that you can also use the standard `BeanInfo` JavaBeans mechanism here as well -(described to some extent -https://docs.oracle.com/javase/tutorial/javabeans/advanced/customization.html[here]). The -following example uses the `BeanInfo` mechanism to explicitly register one or more -`PropertyEditor` instances with the properties of an associated class: - -[literal,subs="verbatim,quotes"] ----- -com - chank - pop - Something - SomethingBeanInfo // the BeanInfo for the Something class ----- - -The following Java source code for the referenced `SomethingBeanInfo` class -associates a `CustomNumberEditor` with the `age` property of the `Something` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SomethingBeanInfo extends SimpleBeanInfo { - - public PropertyDescriptor[] getPropertyDescriptors() { - try { - final PropertyEditor numberPE = new CustomNumberEditor(Integer.class, true); - PropertyDescriptor ageDescriptor = new PropertyDescriptor("age", Something.class) { - @Override - public PropertyEditor createPropertyEditor(Object bean) { - return numberPE; - } - }; - return new PropertyDescriptor[] { ageDescriptor }; - } - catch (IntrospectionException ex) { - throw new Error(ex.toString()); - } - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SomethingBeanInfo : SimpleBeanInfo() { - - override fun getPropertyDescriptors(): Array { - try { - val numberPE = CustomNumberEditor(Int::class.java, true) - val ageDescriptor = object : PropertyDescriptor("age", Something::class.java) { - override fun createPropertyEditor(bean: Any): PropertyEditor { - return numberPE - } - } - return arrayOf(ageDescriptor) - } catch (ex: IntrospectionException) { - throw Error(ex.toString()) - } - - } - } ----- - - -[[beans-beans-conversion-customeditor-registration]] -==== Registering Additional Custom `PropertyEditor` Implementations - -When setting bean properties as string values, a Spring IoC container ultimately uses -standard JavaBeans `PropertyEditor` implementations to convert these strings to the complex type of the -property. Spring pre-registers a number of custom `PropertyEditor` implementations (for example, to -convert a class name expressed as a string into a `Class` object). Additionally, -Java's standard JavaBeans `PropertyEditor` lookup mechanism lets a `PropertyEditor` -for a class be named appropriately and placed in the same package as the class -for which it provides support, so that it can be found automatically. - -If there is a need to register other custom `PropertyEditors`, several mechanisms are -available. The most manual approach, which is not normally convenient or -recommended, is to use the `registerCustomEditor()` method of the -`ConfigurableBeanFactory` interface, assuming you have a `BeanFactory` reference. -Another (slightly more convenient) mechanism is to use a special bean factory -post-processor called `CustomEditorConfigurer`. Although you can use bean factory post-processors -with `BeanFactory` implementations, the `CustomEditorConfigurer` has a -nested property setup, so we strongly recommend that you use it with the -`ApplicationContext`, where you can deploy it in similar fashion to any other bean and -where it can be automatically detected and applied. - -Note that all bean factories and application contexts automatically use a number of -built-in property editors, through their use of a `BeanWrapper` to -handle property conversions. The standard property editors that the `BeanWrapper` -registers are listed in the <>. -Additionally, ``ApplicationContext``s also override or add additional editors to handle -resource lookups in a manner appropriate to the specific application context type. - -Standard JavaBeans `PropertyEditor` instances are used to convert property values -expressed as strings to the actual complex type of the property. You can use -`CustomEditorConfigurer`, a bean factory post-processor, to conveniently add -support for additional `PropertyEditor` instances to an `ApplicationContext`. - -Consider the following example, which defines a user class called `ExoticType` and -another class called `DependsOnExoticType`, which needs `ExoticType` set as a property: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package example; - - public class ExoticType { - - private String name; - - public ExoticType(String name) { - this.name = name; - } - } - - public class DependsOnExoticType { - - private ExoticType type; - - public void setType(ExoticType type) { - this.type = type; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package example - - class ExoticType(val name: String) - - class DependsOnExoticType { - - var type: ExoticType? = null - } ----- - -When things are properly set up, we want to be able to assign the type property as a -string, which a `PropertyEditor` converts into an actual -`ExoticType` instance. The following bean definition shows how to set up this relationship: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -The `PropertyEditor` implementation could look similar to the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package example; - - import java.beans.PropertyEditorSupport; - - // converts string representation to ExoticType object - public class ExoticTypeEditor extends PropertyEditorSupport { - - public void setAsText(String text) { - setValue(new ExoticType(text.toUpperCase())); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package example - - import java.beans.PropertyEditorSupport - - // converts string representation to ExoticType object - class ExoticTypeEditor : PropertyEditorSupport() { - - override fun setAsText(text: String) { - value = ExoticType(text.toUpperCase()) - } - } ----- - -Finally, the following example shows how to use `CustomEditorConfigurer` to register the new `PropertyEditor` with the -`ApplicationContext`, which will then be able to use it as needed: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -[[beans-beans-conversion-customeditor-registration-per]] -===== Using `PropertyEditorRegistrar` - -Another mechanism for registering property editors with the Spring container is to -create and use a `PropertyEditorRegistrar`. This interface is particularly useful when -you need to use the same set of property editors in several different situations. -You can write a corresponding registrar and reuse it in each case. -`PropertyEditorRegistrar` instances work in conjunction with an interface called -`PropertyEditorRegistry`, an interface that is implemented by the Spring `BeanWrapper` -(and `DataBinder`). `PropertyEditorRegistrar` instances are particularly convenient -when used in conjunction with `CustomEditorConfigurer` (described -<>), which exposes a property -called `setPropertyEditorRegistrars(..)`. `PropertyEditorRegistrar` instances added -to a `CustomEditorConfigurer` in this fashion can easily be shared with `DataBinder` and -Spring MVC controllers. Furthermore, it avoids the need for synchronization on custom -editors: A `PropertyEditorRegistrar` is expected to create fresh `PropertyEditor` -instances for each bean creation attempt. - -The following example shows how to create your own `PropertyEditorRegistrar` implementation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package com.foo.editors.spring; - - public final class CustomPropertyEditorRegistrar implements PropertyEditorRegistrar { - - public void registerCustomEditors(PropertyEditorRegistry registry) { - - // it is expected that new PropertyEditor instances are created - registry.registerCustomEditor(ExoticType.class, new ExoticTypeEditor()); - - // you could register as many custom property editors as are required here... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package com.foo.editors.spring - - import org.springframework.beans.PropertyEditorRegistrar - import org.springframework.beans.PropertyEditorRegistry - - class CustomPropertyEditorRegistrar : PropertyEditorRegistrar { - - override fun registerCustomEditors(registry: PropertyEditorRegistry) { - - // it is expected that new PropertyEditor instances are created - registry.registerCustomEditor(ExoticType::class.java, ExoticTypeEditor()) - - // you could register as many custom property editors as are required here... - } - } ----- - -See also the `org.springframework.beans.support.ResourceEditorRegistrar` for an example -`PropertyEditorRegistrar` implementation. Notice how in its implementation of the -`registerCustomEditors(..)` method, it creates new instances of each property editor. - -The next example shows how to configure a `CustomEditorConfigurer` and inject an instance -of our `CustomPropertyEditorRegistrar` into it: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - ----- - -Finally (and in a bit of a departure from the focus of this chapter) for those of you -using <>, using a `PropertyEditorRegistrar` in -conjunction with data-binding web controllers can be very convenient. The following -example uses a `PropertyEditorRegistrar` in the implementation of an `@InitBinder` method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class RegisterUserController { - - private final PropertyEditorRegistrar customPropertyEditorRegistrar; - - RegisterUserController(PropertyEditorRegistrar propertyEditorRegistrar) { - this.customPropertyEditorRegistrar = propertyEditorRegistrar; - } - - @InitBinder - void initBinder(WebDataBinder binder) { - this.customPropertyEditorRegistrar.registerCustomEditors(binder); - } - - // other methods related to registering a User - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class RegisterUserController( - private val customPropertyEditorRegistrar: PropertyEditorRegistrar) { - - @InitBinder - fun initBinder(binder: WebDataBinder) { - this.customPropertyEditorRegistrar.registerCustomEditors(binder) - } - - // other methods related to registering a User - } ----- - -This style of `PropertyEditor` registration can lead to concise code (the implementation -of the `@InitBinder` method is only one line long) and lets common `PropertyEditor` -registration code be encapsulated in a class and then shared amongst as many controllers -as needed. - - - - -[[core-convert]] -== Spring Type Conversion - -The `core.convert` package provides a general type conversion system. The system defines -an SPI to implement type conversion logic and an API to perform type conversions at -runtime. Within a Spring container, you can use this system as an alternative to -`PropertyEditor` implementations to convert externalized bean property value strings to -the required property types. You can also use the public API anywhere in your application -where type conversion is needed. - - - -[[core-convert-Converter-API]] -=== Converter SPI - -The SPI to implement type conversion logic is simple and strongly typed, as the following -interface definition shows: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.core.convert.converter; - - public interface Converter { - - T convert(S source); - } ----- - -To create your own converter, implement the `Converter` interface and parameterize `S` -as the type you are converting from and `T` as the type you are converting to. You can also transparently apply such a -converter if a collection or array of `S` needs to be -converted to an array or collection of `T`, provided that a delegating array or collection -converter has been registered as well (which `DefaultConversionService` does by default). - -For each call to `convert(S)`, the source argument is guaranteed to not be null. Your -`Converter` may throw any unchecked exception if conversion fails. Specifically, it should throw an -`IllegalArgumentException` to report an invalid source value. -Take care to ensure that your `Converter` implementation is thread-safe. - -Several converter implementations are provided in the `core.convert.support` package as -a convenience. These include converters from strings to numbers and other common types. -The following listing shows the `StringToInteger` class, which is a typical `Converter` implementation: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.core.convert.support; - - final class StringToInteger implements Converter { - - public Integer convert(String source) { - return Integer.valueOf(source); - } - } ----- - - - -[[core-convert-ConverterFactory-SPI]] -=== Using `ConverterFactory` - -When you need to centralize the conversion logic for an entire class hierarchy -(for example, when converting from `String` to `Enum` objects), you can implement -`ConverterFactory`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.core.convert.converter; - - public interface ConverterFactory { - - Converter getConverter(Class targetType); - } ----- - -Parameterize S to be the type you are converting from and R to be the base type defining -the __range__ of classes you can convert to. Then implement `getConverter(Class)`, -where T is a subclass of R. - -Consider the `StringToEnumConverterFactory` as an example: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.core.convert.support; - - final class StringToEnumConverterFactory implements ConverterFactory { - - public Converter getConverter(Class targetType) { - return new StringToEnumConverter(targetType); - } - - private final class StringToEnumConverter implements Converter { - - private Class enumType; - - public StringToEnumConverter(Class enumType) { - this.enumType = enumType; - } - - public T convert(String source) { - return (T) Enum.valueOf(this.enumType, source.trim()); - } - } - } ----- - - -[[core-convert-GenericConverter-SPI]] -=== Using `GenericConverter` - -When you require a sophisticated `Converter` implementation, consider using the -`GenericConverter` interface. With a more flexible but less strongly typed signature -than `Converter`, a `GenericConverter` supports converting between multiple source and -target types. In addition, a `GenericConverter` makes available source and target field -context that you can use when you implement your conversion logic. Such context lets a -type conversion be driven by a field annotation or by generic information declared on a -field signature. The following listing shows the interface definition of `GenericConverter`: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.core.convert.converter; - - public interface GenericConverter { - - public Set getConvertibleTypes(); - - Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType); - } ----- - -To implement a `GenericConverter`, have `getConvertibleTypes()` return the supported -source->target type pairs. Then implement `convert(Object, TypeDescriptor, -TypeDescriptor)` to contain your conversion logic. The source `TypeDescriptor` provides -access to the source field that holds the value being converted. The target `TypeDescriptor` -provides access to the target field where the converted value is to be set. - -A good example of a `GenericConverter` is a converter that converts between a Java array -and a collection. Such an `ArrayToCollectionConverter` introspects the field that declares -the target collection type to resolve the collection's element type. This lets each -element in the source array be converted to the collection element type before the -collection is set on the target field. - -NOTE: Because `GenericConverter` is a more complex SPI interface, you should use -it only when you need it. Favor `Converter` or `ConverterFactory` for basic type -conversion needs. - - -[[core-convert-ConditionalGenericConverter-SPI]] -==== Using `ConditionalGenericConverter` - -Sometimes, you want a `Converter` to run only if a specific condition holds true. For -example, you might want to run a `Converter` only if a specific annotation is present -on the target field, or you might want to run a `Converter` only if a specific method -(such as a `static valueOf` method) is defined on the target class. -`ConditionalGenericConverter` is the union of the `GenericConverter` and -`ConditionalConverter` interfaces that lets you define such custom matching criteria: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface ConditionalConverter { - - boolean matches(TypeDescriptor sourceType, TypeDescriptor targetType); - } - - public interface ConditionalGenericConverter extends GenericConverter, ConditionalConverter { - } ----- - -A good example of a `ConditionalGenericConverter` is an `IdToEntityConverter` that converts -between a persistent entity identifier and an entity reference. Such an `IdToEntityConverter` -might match only if the target entity type declares a static finder method (for example, -`findAccount(Long)`). You might perform such a finder method check in the implementation of -`matches(TypeDescriptor, TypeDescriptor)`. - - - -[[core-convert-ConversionService-API]] -=== The `ConversionService` API - -`ConversionService` defines a unified API for executing type conversion logic at -runtime. Converters are often run behind the following facade interface: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.core.convert; - - public interface ConversionService { - - boolean canConvert(Class sourceType, Class targetType); - - T convert(Object source, Class targetType); - - boolean canConvert(TypeDescriptor sourceType, TypeDescriptor targetType); - - Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType); - } ----- - -Most `ConversionService` implementations also implement `ConverterRegistry`, which -provides an SPI for registering converters. Internally, a `ConversionService` -implementation delegates to its registered converters to carry out type conversion logic. - -A robust `ConversionService` implementation is provided in the `core.convert.support` -package. `GenericConversionService` is the general-purpose implementation suitable for -use in most environments. `ConversionServiceFactory` provides a convenient factory for -creating common `ConversionService` configurations. - - - -[[core-convert-Spring-config]] -=== Configuring a `ConversionService` - -A `ConversionService` is a stateless object designed to be instantiated at application -startup and then shared between multiple threads. In a Spring application, you typically -configure a `ConversionService` instance for each Spring container (or `ApplicationContext`). -Spring picks up that `ConversionService` and uses it whenever a type -conversion needs to be performed by the framework. You can also inject this -`ConversionService` into any of your beans and invoke it directly. - -NOTE: If no `ConversionService` is registered with Spring, the original `PropertyEditor`-based -system is used. - -To register a default `ConversionService` with Spring, add the following bean definition -with an `id` of `conversionService`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -A default `ConversionService` can convert between strings, numbers, enums, collections, -maps, and other common types. To supplement or override the default converters with your -own custom converters, set the `converters` property. Property values can implement -any of the `Converter`, `ConverterFactory`, or `GenericConverter` interfaces. - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -It is also common to use a `ConversionService` within a Spring MVC application. See -<> in the Spring MVC chapter. - -In certain situations, you may wish to apply formatting during conversion. See -<> for details on using `FormattingConversionServiceFactoryBean`. - - - -[[core-convert-programmatic-usage]] -=== Using a `ConversionService` Programmatically - -To work with a `ConversionService` instance programmatically, you can inject a reference to -it like you would for any other bean. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Service - public class MyService { - - public MyService(ConversionService conversionService) { - this.conversionService = conversionService; - } - - public void doIt() { - this.conversionService.convert(...) - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Service - class MyService(private val conversionService: ConversionService) { - - fun doIt() { - conversionService.convert(...) - } - } ----- - -For most use cases, you can use the `convert` method that specifies the `targetType`, but it -does not work with more complex types, such as a collection of a parameterized element. -For example, if you want to convert a `List` of `Integer` to a `List` of `String` programmatically, -you need to provide a formal definition of the source and target types. - -Fortunately, `TypeDescriptor` provides various options to make doing so straightforward, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - DefaultConversionService cs = new DefaultConversionService(); - - List input = ... - cs.convert(input, - TypeDescriptor.forObject(input), // List type descriptor - TypeDescriptor.collection(List.class, TypeDescriptor.valueOf(String.class))); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val cs = DefaultConversionService() - - val input: List = ... - cs.convert(input, - TypeDescriptor.forObject(input), // List type descriptor - TypeDescriptor.collection(List::class.java, TypeDescriptor.valueOf(String::class.java))) ----- - -Note that `DefaultConversionService` automatically registers converters that are -appropriate for most environments. This includes collection converters, scalar -converters, and basic `Object`-to-`String` converters. You can register the same converters -with any `ConverterRegistry` by using the static `addDefaultConverters` -method on the `DefaultConversionService` class. - -Converters for value types are reused for arrays and collections, so there is -no need to create a specific converter to convert from a `Collection` of `S` to a -`Collection` of `T`, assuming that standard collection handling is appropriate. - - - - -[[format]] -== Spring Field Formatting - -As discussed in the previous section, <> is a -general-purpose type conversion system. It provides a unified `ConversionService` API as -well as a strongly typed `Converter` SPI for implementing conversion logic from one type -to another. A Spring container uses this system to bind bean property values. In -addition, both the Spring Expression Language (SpEL) and `DataBinder` use this system to -bind field values. For example, when SpEL needs to coerce a `Short` to a `Long` to -complete an `expression.setValue(Object bean, Object value)` attempt, the `core.convert` -system performs the coercion. - -Now consider the type conversion requirements of a typical client environment, such as a -web or desktop application. In such environments, you typically convert from `String` -to support the client postback process, as well as back to `String` to support the -view rendering process. In addition, you often need to localize `String` values. The more -general `core.convert` `Converter` SPI does not address such formatting requirements -directly. To directly address them, Spring provides a convenient `Formatter` SPI that -provides a simple and robust alternative to `PropertyEditor` implementations for client -environments. - -In general, you can use the `Converter` SPI when you need to implement general-purpose type -conversion logic -- for example, for converting between a `java.util.Date` and a `Long`. -You can use the `Formatter` SPI when you work in a client environment (such as a web -application) and need to parse and print localized field values. The `ConversionService` -provides a unified type conversion API for both SPIs. - - - -[[format-Formatter-SPI]] -=== The `Formatter` SPI - -The `Formatter` SPI to implement field formatting logic is simple and strongly typed. The -following listing shows the `Formatter` interface definition: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.format; - - public interface Formatter extends Printer, Parser { - } ----- - -`Formatter` extends from the `Printer` and `Parser` building-block interfaces. The -following listing shows the definitions of those two interfaces: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface Printer { - - String print(T fieldValue, Locale locale); - } ----- - -[source,java,indent=0,subs="verbatim,quotes"] ----- - import java.text.ParseException; - - public interface Parser { - - T parse(String clientValue, Locale locale) throws ParseException; - } ----- - -To create your own `Formatter`, implement the `Formatter` interface shown earlier. -Parameterize `T` to be the type of object you wish to format -- for example, -`java.util.Date`. Implement the `print()` operation to print an instance of `T` for -display in the client locale. Implement the `parse()` operation to parse an instance of -`T` from the formatted representation returned from the client locale. Your `Formatter` -should throw a `ParseException` or an `IllegalArgumentException` if a parse attempt fails. Take -care to ensure that your `Formatter` implementation is thread-safe. - -The `format` subpackages provide several `Formatter` implementations as a convenience. -The `number` package provides `NumberStyleFormatter`, `CurrencyStyleFormatter`, and -`PercentStyleFormatter` to format `Number` objects that use a `java.text.NumberFormat`. -The `datetime` package provides a `DateFormatter` to format `java.util.Date` objects with -a `java.text.DateFormat`. - -The following `DateFormatter` is an example `Formatter` implementation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package org.springframework.format.datetime; - - public final class DateFormatter implements Formatter { - - private String pattern; - - public DateFormatter(String pattern) { - this.pattern = pattern; - } - - public String print(Date date, Locale locale) { - if (date == null) { - return ""; - } - return getDateFormat(locale).format(date); - } - - public Date parse(String formatted, Locale locale) throws ParseException { - if (formatted.length() == 0) { - return null; - } - return getDateFormat(locale).parse(formatted); - } - - protected DateFormat getDateFormat(Locale locale) { - DateFormat dateFormat = new SimpleDateFormat(this.pattern, locale); - dateFormat.setLenient(false); - return dateFormat; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - class DateFormatter(private val pattern: String) : Formatter { - - override fun print(date: Date, locale: Locale) - = getDateFormat(locale).format(date) - - @Throws(ParseException::class) - override fun parse(formatted: String, locale: Locale) - = getDateFormat(locale).parse(formatted) - - protected fun getDateFormat(locale: Locale): DateFormat { - val dateFormat = SimpleDateFormat(this.pattern, locale) - dateFormat.isLenient = false - return dateFormat - } - } ----- - -The Spring team welcomes community-driven `Formatter` contributions. See -https://github.com/spring-projects/spring-framework/issues[GitHub Issues] to contribute. - - - -[[format-CustomFormatAnnotations]] -=== Annotation-driven Formatting - -Field formatting can be configured by field type or annotation. To bind -an annotation to a `Formatter`, implement `AnnotationFormatterFactory`. The following -listing shows the definition of the `AnnotationFormatterFactory` interface: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.format; - - public interface AnnotationFormatterFactory { - - Set> getFieldTypes(); - - Printer getPrinter(A annotation, Class fieldType); - - Parser getParser(A annotation, Class fieldType); - } ----- - -To create an implementation: - -. Parameterize `A` to be the field `annotationType` with which you wish to associate -formatting logic -- for example `org.springframework.format.annotation.DateTimeFormat`. -. Have `getFieldTypes()` return the types of fields on which the annotation can be used. -. Have `getPrinter()` return a `Printer` to print the value of an annotated field. -. Have `getParser()` return a `Parser` to parse a `clientValue` for an annotated field. - -The following example `AnnotationFormatterFactory` implementation binds the `@NumberFormat` -annotation to a formatter to let a number style or pattern be specified: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public final class NumberFormatAnnotationFormatterFactory - implements AnnotationFormatterFactory { - - private static final Set> FIELD_TYPES = Set.of(Short.class, - Integer.class, Long.class, Float.class, Double.class, - BigDecimal.class, BigInteger.class); - - public Set> getFieldTypes() { - return FIELD_TYPES; - } - - public Printer getPrinter(NumberFormat annotation, Class fieldType) { - return configureFormatterFrom(annotation, fieldType); - } - - public Parser getParser(NumberFormat annotation, Class fieldType) { - return configureFormatterFrom(annotation, fieldType); - } - - private Formatter configureFormatterFrom(NumberFormat annotation, Class fieldType) { - if (!annotation.pattern().isEmpty()) { - return new NumberStyleFormatter(annotation.pattern()); - } - // else - return switch(annotation.style()) { - case Style.PERCENT -> new PercentStyleFormatter(); - case Style.CURRENCY -> new CurrencyStyleFormatter(); - default -> new NumberStyleFormatter(); - }; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class NumberFormatAnnotationFormatterFactory : AnnotationFormatterFactory { - - override fun getFieldTypes(): Set> { - return setOf(Short::class.java, Int::class.java, Long::class.java, Float::class.java, Double::class.java, BigDecimal::class.java, BigInteger::class.java) - } - - override fun getPrinter(annotation: NumberFormat, fieldType: Class<*>): Printer { - return configureFormatterFrom(annotation, fieldType) - } - - override fun getParser(annotation: NumberFormat, fieldType: Class<*>): Parser { - return configureFormatterFrom(annotation, fieldType) - } - - private fun configureFormatterFrom(annotation: NumberFormat, fieldType: Class<*>): Formatter { - return if (annotation.pattern.isNotEmpty()) { - NumberStyleFormatter(annotation.pattern) - } else { - val style = annotation.style - when { - style === NumberFormat.Style.PERCENT -> PercentStyleFormatter() - style === NumberFormat.Style.CURRENCY -> CurrencyStyleFormatter() - else -> NumberStyleFormatter() - } - } - } - } ----- - -To trigger formatting, you can annotate fields with `@NumberFormat`, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MyModel { - - @NumberFormat(style=Style.CURRENCY) - private BigDecimal decimal; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyModel( - @field:NumberFormat(style = Style.CURRENCY) private val decimal: BigDecimal - ) ----- - - -[[format-annotations-api]] -==== Format Annotation API - -A portable format annotation API exists in the `org.springframework.format.annotation` -package. You can use `@NumberFormat` to format `Number` fields such as `Double` and -`Long`, and `@DateTimeFormat` to format `java.util.Date`, `java.util.Calendar`, `Long` -(for millisecond timestamps) as well as JSR-310 `java.time`. - -The following example uses `@DateTimeFormat` to format a `java.util.Date` as an ISO Date -(yyyy-MM-dd): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MyModel { - - @DateTimeFormat(iso=ISO.DATE) - private Date date; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyModel( - @DateTimeFormat(iso=ISO.DATE) private val date: Date - ) ----- - - -[[format-FormatterRegistry-SPI]] -=== The `FormatterRegistry` SPI - -The `FormatterRegistry` is an SPI for registering formatters and converters. -`FormattingConversionService` is an implementation of `FormatterRegistry` suitable for -most environments. You can programmatically or declaratively configure this variant -as a Spring bean, e.g. by using `FormattingConversionServiceFactoryBean`. Because this -implementation also implements `ConversionService`, you can directly configure it -for use with Spring's `DataBinder` and the Spring Expression Language (SpEL). - -The following listing shows the `FormatterRegistry` SPI: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.format; - - public interface FormatterRegistry extends ConverterRegistry { - - void addPrinter(Printer printer); - - void addParser(Parser parser); - - void addFormatter(Formatter formatter); - - void addFormatterForFieldType(Class fieldType, Formatter formatter); - - void addFormatterForFieldType(Class fieldType, Printer printer, Parser parser); - - void addFormatterForFieldAnnotation(AnnotationFormatterFactory annotationFormatterFactory); - } ----- - -As shown in the preceding listing, you can register formatters by field type or by annotation. - -The `FormatterRegistry` SPI lets you configure formatting rules centrally, instead of -duplicating such configuration across your controllers. For example, you might want to -enforce that all date fields are formatted a certain way or that fields with a specific -annotation are formatted in a certain way. With a shared `FormatterRegistry`, you define -these rules once, and they are applied whenever formatting is needed. - - - -[[format-FormatterRegistrar-SPI]] -=== The `FormatterRegistrar` SPI - -`FormatterRegistrar` is an SPI for registering formatters and converters through the -FormatterRegistry. The following listing shows its interface definition: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.format; - - public interface FormatterRegistrar { - - void registerFormatters(FormatterRegistry registry); - } ----- - -A `FormatterRegistrar` is useful when registering multiple related converters and -formatters for a given formatting category, such as date formatting. It can also be -useful where declarative registration is insufficient -- for example, when a formatter -needs to be indexed under a specific field type different from its own `` or when -registering a `Printer`/`Parser` pair. The next section provides more information on -converter and formatter registration. - - - -[[format-configuring-formatting-mvc]] -=== Configuring Formatting in Spring MVC - -See <> in the Spring MVC chapter. - - - - -[[format-configuring-formatting-globaldatetimeformat]] -== Configuring a Global Date and Time Format - -By default, date and time fields not annotated with `@DateTimeFormat` are converted from -strings by using the `DateFormat.SHORT` style. If you prefer, you can change this by -defining your own global format. - -To do that, ensure that Spring does not register default formatters. Instead, register -formatters manually with the help of: - -* `org.springframework.format.datetime.standard.DateTimeFormatterRegistrar` -* `org.springframework.format.datetime.DateFormatterRegistrar` - -For example, the following Java configuration registers a global `yyyyMMdd` format: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public FormattingConversionService conversionService() { - - // Use the DefaultFormattingConversionService but do not register defaults - DefaultFormattingConversionService conversionService = - new DefaultFormattingConversionService(false); - - // Ensure @NumberFormat is still supported - conversionService.addFormatterForFieldAnnotation( - new NumberFormatAnnotationFormatterFactory()); - - // Register JSR-310 date conversion with a specific global format - DateTimeFormatterRegistrar dateTimeRegistrar = new DateTimeFormatterRegistrar(); - dateTimeRegistrar.setDateFormatter(DateTimeFormatter.ofPattern("yyyyMMdd")); - dateTimeRegistrar.registerFormatters(conversionService); - - // Register date conversion with a specific global format - DateFormatterRegistrar dateRegistrar = new DateFormatterRegistrar(); - dateRegistrar.setFormatter(new DateFormatter("yyyyMMdd")); - dateRegistrar.registerFormatters(conversionService); - - return conversionService; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun conversionService(): FormattingConversionService { - // Use the DefaultFormattingConversionService but do not register defaults - return DefaultFormattingConversionService(false).apply { - - // Ensure @NumberFormat is still supported - addFormatterForFieldAnnotation(NumberFormatAnnotationFormatterFactory()) - - // Register JSR-310 date conversion with a specific global format - val dateTimeRegistrar = DateTimeFormatterRegistrar() - dateTimeRegistrar.setDateFormatter(DateTimeFormatter.ofPattern("yyyyMMdd")) - dateTimeRegistrar.registerFormatters(this) - - // Register date conversion with a specific global format - val dateRegistrar = DateFormatterRegistrar() - dateRegistrar.setFormatter(DateFormatter("yyyyMMdd")) - dateRegistrar.registerFormatters(this) - } - } - } ----- - -If you prefer XML-based configuration, you can use a -`FormattingConversionServiceFactoryBean`. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - - - - - - ----- - -Note there are extra considerations when configuring date and time formats in web -applications. Please see -<> or -<>. - - - -[[validation-beanvalidation]] -== Java Bean Validation - -The Spring Framework provides support for the -https://beanvalidation.org/[Java Bean Validation] API. - - - -[[validation-beanvalidation-overview]] -=== Overview of Bean Validation - -Bean Validation provides a common way of validation through constraint declaration and -metadata for Java applications. To use it, you annotate domain model properties with -declarative validation constraints which are then enforced by the runtime. There are -built-in constraints, and you can also define your own custom constraints. - -Consider the following example, which shows a simple `PersonForm` model with two properties: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class PersonForm { - private String name; - private int age; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class PersonForm( - private val name: String, - private val age: Int - ) ----- - -Bean Validation lets you declare constraints as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class PersonForm { - - @NotNull - @Size(max=64) - private String name; - - @Min(0) - private int age; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class PersonForm( - @get:NotNull @get:Size(max=64) - private val name: String, - @get:Min(0) - private val age: Int - ) ----- - -A Bean Validation validator then validates instances of this class based on the declared -constraints. See https://beanvalidation.org/[Bean Validation] for general information about -the API. See the https://hibernate.org/validator/[Hibernate Validator] documentation for -specific constraints. To learn how to set up a bean validation provider as a Spring -bean, keep reading. - - - -[[validation-beanvalidation-spring]] -=== Configuring a Bean Validation Provider - -Spring provides full support for the Bean Validation API including the bootstrapping of a -Bean Validation provider as a Spring bean. This lets you inject a -`jakarta.validation.ValidatorFactory` or `jakarta.validation.Validator` wherever validation -is needed in your application. - -You can use the `LocalValidatorFactoryBean` to configure a default Validator as a Spring -bean, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import org.springframework.validation.beanvalidation.LocalValidatorFactoryBean; - - @Configuration - public class AppConfig { - - @Bean - public LocalValidatorFactoryBean validator() { - return new LocalValidatorFactoryBean(); - } - } ----- -[source,xml,indent=0,subs="verbatim,quotes",role="secondary"] -.XML ----- - ----- - -The basic configuration in the preceding example triggers bean validation to initialize by -using its default bootstrap mechanism. A Bean Validation provider, such as the Hibernate -Validator, is expected to be present in the classpath and is automatically detected. - - -[[validation-beanvalidation-spring-inject]] -==== Injecting a Validator - -`LocalValidatorFactoryBean` implements both `jakarta.validation.ValidatorFactory` and -`jakarta.validation.Validator`, as well as Spring's `org.springframework.validation.Validator`. -You can inject a reference to either of these interfaces into beans that need to invoke -validation logic. - -You can inject a reference to `jakarta.validation.Validator` if you prefer to work with the Bean -Validation API directly, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import jakarta.validation.Validator; - - @Service - public class MyService { - - @Autowired - private Validator validator; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import jakarta.validation.Validator; - - @Service - class MyService(@Autowired private val validator: Validator) ----- - -You can inject a reference to `org.springframework.validation.Validator` if your bean -requires the Spring Validation API, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import org.springframework.validation.Validator; - - @Service - public class MyService { - - @Autowired - private Validator validator; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.validation.Validator - - @Service - class MyService(@Autowired private val validator: Validator) ----- - - -[[validation-beanvalidation-spring-constraints]] -==== Configuring Custom Constraints - -Each bean validation constraint consists of two parts: - -* A `@Constraint` annotation that declares the constraint and its configurable properties. -* An implementation of the `jakarta.validation.ConstraintValidator` interface that implements -the constraint's behavior. - -To associate a declaration with an implementation, each `@Constraint` annotation -references a corresponding `ConstraintValidator` implementation class. At runtime, a -`ConstraintValidatorFactory` instantiates the referenced implementation when the -constraint annotation is encountered in your domain model. - -By default, the `LocalValidatorFactoryBean` configures a `SpringConstraintValidatorFactory` -that uses Spring to create `ConstraintValidator` instances. This lets your custom -`ConstraintValidators` benefit from dependency injection like any other Spring bean. - -The following example shows a custom `@Constraint` declaration followed by an associated -`ConstraintValidator` implementation that uses Spring for dependency injection: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target({ElementType.METHOD, ElementType.FIELD}) - @Retention(RetentionPolicy.RUNTIME) - @Constraint(validatedBy=MyConstraintValidator.class) - public @interface MyConstraint { - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.FUNCTION, AnnotationTarget.FIELD) - @Retention(AnnotationRetention.RUNTIME) - @Constraint(validatedBy = MyConstraintValidator::class) - annotation class MyConstraint ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import jakarta.validation.ConstraintValidator; - - public class MyConstraintValidator implements ConstraintValidator { - - @Autowired; - private Foo aDependency; - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import jakarta.validation.ConstraintValidator - - class MyConstraintValidator(private val aDependency: Foo) : ConstraintValidator { - - // ... - } ----- - - -As the preceding example shows, a `ConstraintValidator` implementation can have its dependencies -`@Autowired` as any other Spring bean. - - -[[validation-beanvalidation-spring-method]] -==== Spring-driven Method Validation - -You can integrate the method validation feature supported by Bean Validation 1.1 (and, as -a custom extension, also by Hibernate Validator 4.3) into a Spring context through a -`MethodValidationPostProcessor` bean definition: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import org.springframework.validation.beanvalidation.MethodValidationPostProcessor; - - @Configuration - public class AppConfig { - - @Bean - public MethodValidationPostProcessor validationPostProcessor() { - return new MethodValidationPostProcessor(); - } - } - ----- -[source,xml,indent=0,subs="verbatim,quotes",role="secondary"] -.XML ----- - ----- - -To be eligible for Spring-driven method validation, all target classes need to be annotated -with Spring's `@Validated` annotation, which can optionally also declare the validation -groups to use. See -{api-spring-framework}/validation/beanvalidation/MethodValidationPostProcessor.html[`MethodValidationPostProcessor`] -for setup details with the Hibernate Validator and Bean Validation 1.1 providers. - -[TIP] -==== -Method validation relies on <> around the -target classes, either JDK dynamic proxies for methods on interfaces or CGLIB proxies. -There are certain limitations with the use of proxies, some of which are described in -<>. In addition remember -to always use methods and accessors on proxied classes; direct field access will not work. -==== - - - - -[[validation-beanvalidation-spring-other]] -==== Additional Configuration Options - -The default `LocalValidatorFactoryBean` configuration suffices for most -cases. There are a number of configuration options for various Bean Validation -constructs, from message interpolation to traversal resolution. See the -{api-spring-framework}/validation/beanvalidation/LocalValidatorFactoryBean.html[`LocalValidatorFactoryBean`] -javadoc for more information on these options. - - - -[[validation-binder]] -=== Configuring a `DataBinder` - -You can configure a `DataBinder` instance with a `Validator`. Once configured, you can -invoke the `Validator` by calling `binder.validate()`. Any validation `Errors` are -automatically added to the binder's `BindingResult`. - -The following example shows how to use a `DataBinder` programmatically to invoke validation -logic after binding to a target object: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Foo target = new Foo(); - DataBinder binder = new DataBinder(target); - binder.setValidator(new FooValidator()); - - // bind to the target object - binder.bind(propertyValues); - - // validate the target object - binder.validate(); - - // get BindingResult that includes any validation errors - BindingResult results = binder.getBindingResult(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val target = Foo() - val binder = DataBinder(target) - binder.validator = FooValidator() - - // bind to the target object - binder.bind(propertyValues) - - // validate the target object - binder.validate() - - // get BindingResult that includes any validation errors - val results = binder.bindingResult ----- - -You can also configure a `DataBinder` with multiple `Validator` instances through -`dataBinder.addValidators` and `dataBinder.replaceValidators`. This is useful when -combining globally configured bean validation with a Spring `Validator` configured -locally on a DataBinder instance. See -<>. - - - -[[validation-mvc]] -=== Spring MVC 3 Validation - -See <> in the Spring MVC chapter. diff --git a/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc b/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc new file mode 100644 index 000000000000..439125a3cb03 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc @@ -0,0 +1,612 @@ +[[beans-beans]] += Bean Manipulation and the `BeanWrapper` + +The `org.springframework.beans` package adheres to the JavaBeans standard. +A JavaBean is a class with a default no-argument constructor and that follows +a naming convention where (for example) a property named `bingoMadness` would +have a setter method `setBingoMadness(..)` and a getter method `getBingoMadness()`. For +more information about JavaBeans and the specification, see +https://docs.oracle.com/javase/8/docs/api/java/beans/package-summary.html[javabeans]. + +One quite important class in the beans package is the `BeanWrapper` interface and its +corresponding implementation (`BeanWrapperImpl`). As quoted from the javadoc, the +`BeanWrapper` offers functionality to set and get property values (individually or in +bulk), get property descriptors, and query properties to determine if they are +readable or writable. Also, the `BeanWrapper` offers support for nested properties, +enabling the setting of properties on sub-properties to an unlimited depth. The +`BeanWrapper` also supports the ability to add standard JavaBeans `PropertyChangeListeners` +and `VetoableChangeListeners`, without the need for supporting code in the target class. +Last but not least, the `BeanWrapper` provides support for setting indexed properties. +The `BeanWrapper` usually is not used by application code directly but is used by the +`DataBinder` and the `BeanFactory`. + +The way the `BeanWrapper` works is partly indicated by its name: it wraps a bean to +perform actions on that bean, such as setting and retrieving properties. + + + +[[beans-beans-conventions]] +== Setting and Getting Basic and Nested Properties + +Setting and getting properties is done through the `setPropertyValue` and +`getPropertyValue` overloaded method variants of `BeanWrapper`. See their Javadoc for +details. The below table shows some examples of these conventions: + +[[beans-beans-conventions-properties-tbl]] +.Examples of properties +|=== +| Expression| Explanation + +| `name` +| Indicates the property `name` that corresponds to the `getName()` or `isName()` + and `setName(..)` methods. + +| `account.name` +| Indicates the nested property `name` of the property `account` that corresponds to + (for example) the `getAccount().setName()` or `getAccount().getName()` methods. + +| `account[2]` +| Indicates the _third_ element of the indexed property `account`. Indexed properties + can be of type `array`, `list`, or other naturally ordered collection. + +| `account[COMPANYNAME]` +| Indicates the value of the map entry indexed by the `COMPANYNAME` key of the `account` `Map` + property. +|=== + +(This next section is not vitally important to you if you do not plan to work with +the `BeanWrapper` directly. If you use only the `DataBinder` and the `BeanFactory` +and their default implementations, you should skip ahead to the +<>.) + +The following two example classes use the `BeanWrapper` to get and set +properties: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class Company { + + private String name; + private Employee managingDirector; + + public String getName() { + return this.name; + } + + public void setName(String name) { + this.name = name; + } + + public Employee getManagingDirector() { + return this.managingDirector; + } + + public void setManagingDirector(Employee managingDirector) { + this.managingDirector = managingDirector; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class Company { + var name: String? = null + var managingDirector: Employee? = null + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class Employee { + + private String name; + + private float salary; + + public String getName() { + return this.name; + } + + public void setName(String name) { + this.name = name; + } + + public float getSalary() { + return salary; + } + + public void setSalary(float salary) { + this.salary = salary; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class Employee { + var name: String? = null + var salary: Float? = null + } +---- + +The following code snippets show some examples of how to retrieve and manipulate some of +the properties of instantiated ``Company``s and ``Employee``s: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + BeanWrapper company = new BeanWrapperImpl(new Company()); + // setting the company name.. + company.setPropertyValue("name", "Some Company Inc."); + // ... can also be done like this: + PropertyValue value = new PropertyValue("name", "Some Company Inc."); + company.setPropertyValue(value); + + // ok, let's create the director and tie it to the company: + BeanWrapper jim = new BeanWrapperImpl(new Employee()); + jim.setPropertyValue("name", "Jim Stravinsky"); + company.setPropertyValue("managingDirector", jim.getWrappedInstance()); + + // retrieving the salary of the managingDirector through the company + Float salary = (Float) company.getPropertyValue("managingDirector.salary"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val company = BeanWrapperImpl(Company()) + // setting the company name.. + company.setPropertyValue("name", "Some Company Inc.") + // ... can also be done like this: + val value = PropertyValue("name", "Some Company Inc.") + company.setPropertyValue(value) + + // ok, let's create the director and tie it to the company: + val jim = BeanWrapperImpl(Employee()) + jim.setPropertyValue("name", "Jim Stravinsky") + company.setPropertyValue("managingDirector", jim.wrappedInstance) + + // retrieving the salary of the managingDirector through the company + val salary = company.getPropertyValue("managingDirector.salary") as Float? +---- + + + +[[beans-beans-conversion]] +== Built-in `PropertyEditor` Implementations + +Spring uses the concept of a `PropertyEditor` to effect the conversion between an +`Object` and a `String`. It can be handy +to represent properties in a different way than the object itself. For example, a `Date` +can be represented in a human readable way (as the `String`: `'2007-14-09'`), while +we can still convert the human readable form back to the original date (or, even +better, convert any date entered in a human readable form back to `Date` objects). This +behavior can be achieved by registering custom editors of type +`java.beans.PropertyEditor`. Registering custom editors on a `BeanWrapper` or, +alternatively, in a specific IoC container (as mentioned in the previous chapter), gives it +the knowledge of how to convert properties to the desired type. For more about +`PropertyEditor`, see https://docs.oracle.com/javase/8/docs/api/java/beans/package-summary.html[the javadoc of the `java.beans` package from Oracle]. + +A couple of examples where property editing is used in Spring: + +* Setting properties on beans is done by using `PropertyEditor` implementations. + When you use `String` as the value of a property of some bean that you declare + in an XML file, Spring (if the setter of the corresponding property has a `Class` + parameter) uses `ClassEditor` to try to resolve the parameter to a `Class` object. +* Parsing HTTP request parameters in Spring's MVC framework is done by using all kinds + of `PropertyEditor` implementations that you can manually bind in all subclasses of the + `CommandController`. + +Spring has a number of built-in `PropertyEditor` implementations to make life easy. +They are all located in the `org.springframework.beans.propertyeditors` +package. Most, (but not all, as indicated in the following table) are, by default, registered by +`BeanWrapperImpl`. Where the property editor is configurable in some fashion, you can +still register your own variant to override the default one. The following table describes +the various `PropertyEditor` implementations that Spring provides: + +[[beans-beans-property-editors-tbl]] +.Built-in `PropertyEditor` Implementations +[cols="30%,70%"] +|=== +| Class| Explanation + +| `ByteArrayPropertyEditor` +| Editor for byte arrays. Converts strings to their corresponding byte + representations. Registered by default by `BeanWrapperImpl`. + +| `ClassEditor` +| Parses Strings that represent classes to actual classes and vice-versa. When a + class is not found, an `IllegalArgumentException` is thrown. By default, registered by + `BeanWrapperImpl`. + +| `CustomBooleanEditor` +| Customizable property editor for `Boolean` properties. By default, registered by + `BeanWrapperImpl` but can be overridden by registering a custom instance of it as a + custom editor. + +| `CustomCollectionEditor` +| Property editor for collections, converting any source `Collection` to a given target + `Collection` type. + +| `CustomDateEditor` +| Customizable property editor for `java.util.Date`, supporting a custom `DateFormat`. NOT + registered by default. Must be user-registered with the appropriate format as needed. + +| `CustomNumberEditor` +| Customizable property editor for any `Number` subclass, such as `Integer`, `Long`, `Float`, or + `Double`. By default, registered by `BeanWrapperImpl` but can be overridden by + registering a custom instance of it as a custom editor. + +| `FileEditor` +| Resolves strings to `java.io.File` objects. By default, registered by + `BeanWrapperImpl`. + +| `InputStreamEditor` +| One-way property editor that can take a string and produce (through an + intermediate `ResourceEditor` and `Resource`) an `InputStream` so that `InputStream` + properties may be directly set as strings. Note that the default usage does not close + the `InputStream` for you. By default, registered by `BeanWrapperImpl`. + +| `LocaleEditor` +| Can resolve strings to `Locale` objects and vice-versa (the string format is + `[language]\_[country]_[variant]`, same as the `toString()` method of + `Locale`). Also accepts spaces as separators, as an alternative to underscores. + By default, registered by `BeanWrapperImpl`. + +| `PatternEditor` +| Can resolve strings to `java.util.regex.Pattern` objects and vice-versa. + +| `PropertiesEditor` +| Can convert strings (formatted with the format defined in the javadoc of the + `java.util.Properties` class) to `Properties` objects. By default, registered + by `BeanWrapperImpl`. + +| `StringTrimmerEditor` +| Property editor that trims strings. Optionally allows transforming an empty string + into a `null` value. NOT registered by default -- must be user-registered. + +| `URLEditor` +| Can resolve a string representation of a URL to an actual `URL` object. + By default, registered by `BeanWrapperImpl`. +|=== + +Spring uses the `java.beans.PropertyEditorManager` to set the search path for property +editors that might be needed. The search path also includes `sun.bean.editors`, which +includes `PropertyEditor` implementations for types such as `Font`, `Color`, and most of +the primitive types. Note also that the standard JavaBeans infrastructure +automatically discovers `PropertyEditor` classes (without you having to register them +explicitly) if they are in the same package as the class they handle and have the same +name as that class, with `Editor` appended. For example, one could have the following +class and package structure, which would be sufficient for the `SomethingEditor` class to be +recognized and used as the `PropertyEditor` for `Something`-typed properties. + +[literal,subs="verbatim,quotes"] +---- +com + chank + pop + Something + SomethingEditor // the PropertyEditor for the Something class +---- + +Note that you can also use the standard `BeanInfo` JavaBeans mechanism here as well +(described to some extent +https://docs.oracle.com/javase/tutorial/javabeans/advanced/customization.html[here]). The +following example uses the `BeanInfo` mechanism to explicitly register one or more +`PropertyEditor` instances with the properties of an associated class: + +[literal,subs="verbatim,quotes"] +---- +com + chank + pop + Something + SomethingBeanInfo // the BeanInfo for the Something class +---- + +The following Java source code for the referenced `SomethingBeanInfo` class +associates a `CustomNumberEditor` with the `age` property of the `Something` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SomethingBeanInfo extends SimpleBeanInfo { + + public PropertyDescriptor[] getPropertyDescriptors() { + try { + final PropertyEditor numberPE = new CustomNumberEditor(Integer.class, true); + PropertyDescriptor ageDescriptor = new PropertyDescriptor("age", Something.class) { + @Override + public PropertyEditor createPropertyEditor(Object bean) { + return numberPE; + } + }; + return new PropertyDescriptor[] { ageDescriptor }; + } + catch (IntrospectionException ex) { + throw new Error(ex.toString()); + } + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SomethingBeanInfo : SimpleBeanInfo() { + + override fun getPropertyDescriptors(): Array { + try { + val numberPE = CustomNumberEditor(Int::class.java, true) + val ageDescriptor = object : PropertyDescriptor("age", Something::class.java) { + override fun createPropertyEditor(bean: Any): PropertyEditor { + return numberPE + } + } + return arrayOf(ageDescriptor) + } catch (ex: IntrospectionException) { + throw Error(ex.toString()) + } + + } + } +---- + + +[[beans-beans-conversion-customeditor-registration]] +=== Registering Additional Custom `PropertyEditor` Implementations + +When setting bean properties as string values, a Spring IoC container ultimately uses +standard JavaBeans `PropertyEditor` implementations to convert these strings to the complex type of the +property. Spring pre-registers a number of custom `PropertyEditor` implementations (for example, to +convert a class name expressed as a string into a `Class` object). Additionally, +Java's standard JavaBeans `PropertyEditor` lookup mechanism lets a `PropertyEditor` +for a class be named appropriately and placed in the same package as the class +for which it provides support, so that it can be found automatically. + +If there is a need to register other custom `PropertyEditors`, several mechanisms are +available. The most manual approach, which is not normally convenient or +recommended, is to use the `registerCustomEditor()` method of the +`ConfigurableBeanFactory` interface, assuming you have a `BeanFactory` reference. +Another (slightly more convenient) mechanism is to use a special bean factory +post-processor called `CustomEditorConfigurer`. Although you can use bean factory post-processors +with `BeanFactory` implementations, the `CustomEditorConfigurer` has a +nested property setup, so we strongly recommend that you use it with the +`ApplicationContext`, where you can deploy it in similar fashion to any other bean and +where it can be automatically detected and applied. + +Note that all bean factories and application contexts automatically use a number of +built-in property editors, through their use of a `BeanWrapper` to +handle property conversions. The standard property editors that the `BeanWrapper` +registers are listed in the <>. +Additionally, ``ApplicationContext``s also override or add additional editors to handle +resource lookups in a manner appropriate to the specific application context type. + +Standard JavaBeans `PropertyEditor` instances are used to convert property values +expressed as strings to the actual complex type of the property. You can use +`CustomEditorConfigurer`, a bean factory post-processor, to conveniently add +support for additional `PropertyEditor` instances to an `ApplicationContext`. + +Consider the following example, which defines a user class called `ExoticType` and +another class called `DependsOnExoticType`, which needs `ExoticType` set as a property: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package example; + + public class ExoticType { + + private String name; + + public ExoticType(String name) { + this.name = name; + } + } + + public class DependsOnExoticType { + + private ExoticType type; + + public void setType(ExoticType type) { + this.type = type; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package example + + class ExoticType(val name: String) + + class DependsOnExoticType { + + var type: ExoticType? = null + } +---- + +When things are properly set up, we want to be able to assign the type property as a +string, which a `PropertyEditor` converts into an actual +`ExoticType` instance. The following bean definition shows how to set up this relationship: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +The `PropertyEditor` implementation could look similar to the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package example; + + import java.beans.PropertyEditorSupport; + + // converts string representation to ExoticType object + public class ExoticTypeEditor extends PropertyEditorSupport { + + public void setAsText(String text) { + setValue(new ExoticType(text.toUpperCase())); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package example + + import java.beans.PropertyEditorSupport + + // converts string representation to ExoticType object + class ExoticTypeEditor : PropertyEditorSupport() { + + override fun setAsText(text: String) { + value = ExoticType(text.toUpperCase()) + } + } +---- + +Finally, the following example shows how to use `CustomEditorConfigurer` to register the new `PropertyEditor` with the +`ApplicationContext`, which will then be able to use it as needed: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +[[beans-beans-conversion-customeditor-registration-per]] +==== Using `PropertyEditorRegistrar` + +Another mechanism for registering property editors with the Spring container is to +create and use a `PropertyEditorRegistrar`. This interface is particularly useful when +you need to use the same set of property editors in several different situations. +You can write a corresponding registrar and reuse it in each case. +`PropertyEditorRegistrar` instances work in conjunction with an interface called +`PropertyEditorRegistry`, an interface that is implemented by the Spring `BeanWrapper` +(and `DataBinder`). `PropertyEditorRegistrar` instances are particularly convenient +when used in conjunction with `CustomEditorConfigurer` (described +<>), which exposes a property +called `setPropertyEditorRegistrars(..)`. `PropertyEditorRegistrar` instances added +to a `CustomEditorConfigurer` in this fashion can easily be shared with `DataBinder` and +Spring MVC controllers. Furthermore, it avoids the need for synchronization on custom +editors: A `PropertyEditorRegistrar` is expected to create fresh `PropertyEditor` +instances for each bean creation attempt. + +The following example shows how to create your own `PropertyEditorRegistrar` implementation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package com.foo.editors.spring; + + public final class CustomPropertyEditorRegistrar implements PropertyEditorRegistrar { + + public void registerCustomEditors(PropertyEditorRegistry registry) { + + // it is expected that new PropertyEditor instances are created + registry.registerCustomEditor(ExoticType.class, new ExoticTypeEditor()); + + // you could register as many custom property editors as are required here... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package com.foo.editors.spring + + import org.springframework.beans.PropertyEditorRegistrar + import org.springframework.beans.PropertyEditorRegistry + + class CustomPropertyEditorRegistrar : PropertyEditorRegistrar { + + override fun registerCustomEditors(registry: PropertyEditorRegistry) { + + // it is expected that new PropertyEditor instances are created + registry.registerCustomEditor(ExoticType::class.java, ExoticTypeEditor()) + + // you could register as many custom property editors as are required here... + } + } +---- + +See also the `org.springframework.beans.support.ResourceEditorRegistrar` for an example +`PropertyEditorRegistrar` implementation. Notice how in its implementation of the +`registerCustomEditors(..)` method, it creates new instances of each property editor. + +The next example shows how to configure a `CustomEditorConfigurer` and inject an instance +of our `CustomPropertyEditorRegistrar` into it: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + +---- + +Finally (and in a bit of a departure from the focus of this chapter) for those of you +using <>, using a `PropertyEditorRegistrar` in +conjunction with data-binding web controllers can be very convenient. The following +example uses a `PropertyEditorRegistrar` in the implementation of an `@InitBinder` method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class RegisterUserController { + + private final PropertyEditorRegistrar customPropertyEditorRegistrar; + + RegisterUserController(PropertyEditorRegistrar propertyEditorRegistrar) { + this.customPropertyEditorRegistrar = propertyEditorRegistrar; + } + + @InitBinder + void initBinder(WebDataBinder binder) { + this.customPropertyEditorRegistrar.registerCustomEditors(binder); + } + + // other methods related to registering a User + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class RegisterUserController( + private val customPropertyEditorRegistrar: PropertyEditorRegistrar) { + + @InitBinder + fun initBinder(binder: WebDataBinder) { + this.customPropertyEditorRegistrar.registerCustomEditors(binder) + } + + // other methods related to registering a User + } +---- + +This style of `PropertyEditor` registration can lead to concise code (the implementation +of the `@InitBinder` method is only one line long) and lets common `PropertyEditor` +registration code be encapsulated in a class and then shared amongst as many controllers +as needed. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc b/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc new file mode 100644 index 000000000000..9a7978e5bdb6 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc @@ -0,0 +1,343 @@ +[[validation-beanvalidation]] += Java Bean Validation + +The Spring Framework provides support for the +https://beanvalidation.org/[Java Bean Validation] API. + + + +[[validation-beanvalidation-overview]] +== Overview of Bean Validation + +Bean Validation provides a common way of validation through constraint declaration and +metadata for Java applications. To use it, you annotate domain model properties with +declarative validation constraints which are then enforced by the runtime. There are +built-in constraints, and you can also define your own custom constraints. + +Consider the following example, which shows a simple `PersonForm` model with two properties: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class PersonForm { + private String name; + private int age; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class PersonForm( + private val name: String, + private val age: Int + ) +---- + +Bean Validation lets you declare constraints as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class PersonForm { + + @NotNull + @Size(max=64) + private String name; + + @Min(0) + private int age; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class PersonForm( + @get:NotNull @get:Size(max=64) + private val name: String, + @get:Min(0) + private val age: Int + ) +---- + +A Bean Validation validator then validates instances of this class based on the declared +constraints. See https://beanvalidation.org/[Bean Validation] for general information about +the API. See the https://hibernate.org/validator/[Hibernate Validator] documentation for +specific constraints. To learn how to set up a bean validation provider as a Spring +bean, keep reading. + + + +[[validation-beanvalidation-spring]] +== Configuring a Bean Validation Provider + +Spring provides full support for the Bean Validation API including the bootstrapping of a +Bean Validation provider as a Spring bean. This lets you inject a +`jakarta.validation.ValidatorFactory` or `jakarta.validation.Validator` wherever validation +is needed in your application. + +You can use the `LocalValidatorFactoryBean` to configure a default Validator as a Spring +bean, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import org.springframework.validation.beanvalidation.LocalValidatorFactoryBean; + + @Configuration + public class AppConfig { + + @Bean + public LocalValidatorFactoryBean validator() { + return new LocalValidatorFactoryBean(); + } + } +---- +[source,xml,indent=0,subs="verbatim,quotes",role="secondary"] +.XML +---- + +---- + +The basic configuration in the preceding example triggers bean validation to initialize by +using its default bootstrap mechanism. A Bean Validation provider, such as the Hibernate +Validator, is expected to be present in the classpath and is automatically detected. + + +[[validation-beanvalidation-spring-inject]] +=== Injecting a Validator + +`LocalValidatorFactoryBean` implements both `jakarta.validation.ValidatorFactory` and +`jakarta.validation.Validator`, as well as Spring's `org.springframework.validation.Validator`. +You can inject a reference to either of these interfaces into beans that need to invoke +validation logic. + +You can inject a reference to `jakarta.validation.Validator` if you prefer to work with the Bean +Validation API directly, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import jakarta.validation.Validator; + + @Service + public class MyService { + + @Autowired + private Validator validator; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import jakarta.validation.Validator; + + @Service + class MyService(@Autowired private val validator: Validator) +---- + +You can inject a reference to `org.springframework.validation.Validator` if your bean +requires the Spring Validation API, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import org.springframework.validation.Validator; + + @Service + public class MyService { + + @Autowired + private Validator validator; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.validation.Validator + + @Service + class MyService(@Autowired private val validator: Validator) +---- + + +[[validation-beanvalidation-spring-constraints]] +=== Configuring Custom Constraints + +Each bean validation constraint consists of two parts: + +* A `@Constraint` annotation that declares the constraint and its configurable properties. +* An implementation of the `jakarta.validation.ConstraintValidator` interface that implements +the constraint's behavior. + +To associate a declaration with an implementation, each `@Constraint` annotation +references a corresponding `ConstraintValidator` implementation class. At runtime, a +`ConstraintValidatorFactory` instantiates the referenced implementation when the +constraint annotation is encountered in your domain model. + +By default, the `LocalValidatorFactoryBean` configures a `SpringConstraintValidatorFactory` +that uses Spring to create `ConstraintValidator` instances. This lets your custom +`ConstraintValidators` benefit from dependency injection like any other Spring bean. + +The following example shows a custom `@Constraint` declaration followed by an associated +`ConstraintValidator` implementation that uses Spring for dependency injection: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target({ElementType.METHOD, ElementType.FIELD}) + @Retention(RetentionPolicy.RUNTIME) + @Constraint(validatedBy=MyConstraintValidator.class) + public @interface MyConstraint { + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.FUNCTION, AnnotationTarget.FIELD) + @Retention(AnnotationRetention.RUNTIME) + @Constraint(validatedBy = MyConstraintValidator::class) + annotation class MyConstraint +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import jakarta.validation.ConstraintValidator; + + public class MyConstraintValidator implements ConstraintValidator { + + @Autowired; + private Foo aDependency; + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import jakarta.validation.ConstraintValidator + + class MyConstraintValidator(private val aDependency: Foo) : ConstraintValidator { + + // ... + } +---- + + +As the preceding example shows, a `ConstraintValidator` implementation can have its dependencies +`@Autowired` as any other Spring bean. + + +[[validation-beanvalidation-spring-method]] +=== Spring-driven Method Validation + +You can integrate the method validation feature supported by Bean Validation 1.1 (and, as +a custom extension, also by Hibernate Validator 4.3) into a Spring context through a +`MethodValidationPostProcessor` bean definition: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import org.springframework.validation.beanvalidation.MethodValidationPostProcessor; + + @Configuration + public class AppConfig { + + @Bean + public MethodValidationPostProcessor validationPostProcessor() { + return new MethodValidationPostProcessor(); + } + } + +---- +[source,xml,indent=0,subs="verbatim,quotes",role="secondary"] +.XML +---- + +---- + +To be eligible for Spring-driven method validation, all target classes need to be annotated +with Spring's `@Validated` annotation, which can optionally also declare the validation +groups to use. See +{api-spring-framework}/validation/beanvalidation/MethodValidationPostProcessor.html[`MethodValidationPostProcessor`] +for setup details with the Hibernate Validator and Bean Validation 1.1 providers. + +[TIP] +==== +Method validation relies on <> around the +target classes, either JDK dynamic proxies for methods on interfaces or CGLIB proxies. +There are certain limitations with the use of proxies, some of which are described in +<>. In addition remember +to always use methods and accessors on proxied classes; direct field access will not work. +==== + + + + +[[validation-beanvalidation-spring-other]] +=== Additional Configuration Options + +The default `LocalValidatorFactoryBean` configuration suffices for most +cases. There are a number of configuration options for various Bean Validation +constructs, from message interpolation to traversal resolution. See the +{api-spring-framework}/validation/beanvalidation/LocalValidatorFactoryBean.html[`LocalValidatorFactoryBean`] +javadoc for more information on these options. + + + +[[validation-binder]] +== Configuring a `DataBinder` + +You can configure a `DataBinder` instance with a `Validator`. Once configured, you can +invoke the `Validator` by calling `binder.validate()`. Any validation `Errors` are +automatically added to the binder's `BindingResult`. + +The following example shows how to use a `DataBinder` programmatically to invoke validation +logic after binding to a target object: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Foo target = new Foo(); + DataBinder binder = new DataBinder(target); + binder.setValidator(new FooValidator()); + + // bind to the target object + binder.bind(propertyValues); + + // validate the target object + binder.validate(); + + // get BindingResult that includes any validation errors + BindingResult results = binder.getBindingResult(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val target = Foo() + val binder = DataBinder(target) + binder.validator = FooValidator() + + // bind to the target object + binder.bind(propertyValues) + + // validate the target object + binder.validate() + + // get BindingResult that includes any validation errors + val results = binder.bindingResult +---- + +You can also configure a `DataBinder` with multiple `Validator` instances through +`dataBinder.addValidators` and `dataBinder.replaceValidators`. This is useful when +combining globally configured bean validation with a Spring `Validator` configured +locally on a DataBinder instance. See +<>. + + + +[[validation-mvc]] +== Spring MVC 3 Validation + +See <> in the Spring MVC chapter. diff --git a/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc b/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc new file mode 100644 index 000000000000..07bc88f06436 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc @@ -0,0 +1,28 @@ +[[validation-conversion]] += Resolving Codes to Error Messages + +We covered databinding and validation. This section covers outputting messages that correspond +to validation errors. In the example shown in the <>, +we rejected the `name` and `age` fields. If we want to output the error messages by using a +`MessageSource`, we can do so using the error code we provide when rejecting the field +('name' and 'age' in this case). When you call (either directly, or indirectly, by using, +for example, the `ValidationUtils` class) `rejectValue` or one of the other `reject` methods +from the `Errors` interface, the underlying implementation not only registers the code you +passed in but also registers a number of additional error codes. The `MessageCodesResolver` +determines which error codes the `Errors` interface registers. By default, the +`DefaultMessageCodesResolver` is used, which (for example) not only registers a message +with the code you gave but also registers messages that include the field name you passed +to the reject method. So, if you reject a field by using `rejectValue("age", "too.darn.old")`, +apart from the `too.darn.old` code, Spring also registers `too.darn.old.age` and +`too.darn.old.age.int` (the first includes the field name and the second includes the type +of the field). This is done as a convenience to aid developers when targeting error messages. + +More information on the `MessageCodesResolver` and the default strategy can be found +in the javadoc of +{api-spring-framework}/validation/MessageCodesResolver.html[`MessageCodesResolver`] and +{api-spring-framework}/validation/DefaultMessageCodesResolver.html[`DefaultMessageCodesResolver`], +respectively. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/validation/convert.adoc b/framework-docs/modules/ROOT/pages/core/validation/convert.adoc new file mode 100644 index 000000000000..fd5fc3af68bf --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/validation/convert.adoc @@ -0,0 +1,330 @@ +[[core-convert]] += Spring Type Conversion + +The `core.convert` package provides a general type conversion system. The system defines +an SPI to implement type conversion logic and an API to perform type conversions at +runtime. Within a Spring container, you can use this system as an alternative to +`PropertyEditor` implementations to convert externalized bean property value strings to +the required property types. You can also use the public API anywhere in your application +where type conversion is needed. + + + +[[core-convert-Converter-API]] +== Converter SPI + +The SPI to implement type conversion logic is simple and strongly typed, as the following +interface definition shows: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.core.convert.converter; + + public interface Converter { + + T convert(S source); + } +---- + +To create your own converter, implement the `Converter` interface and parameterize `S` +as the type you are converting from and `T` as the type you are converting to. You can also transparently apply such a +converter if a collection or array of `S` needs to be +converted to an array or collection of `T`, provided that a delegating array or collection +converter has been registered as well (which `DefaultConversionService` does by default). + +For each call to `convert(S)`, the source argument is guaranteed to not be null. Your +`Converter` may throw any unchecked exception if conversion fails. Specifically, it should throw an +`IllegalArgumentException` to report an invalid source value. +Take care to ensure that your `Converter` implementation is thread-safe. + +Several converter implementations are provided in the `core.convert.support` package as +a convenience. These include converters from strings to numbers and other common types. +The following listing shows the `StringToInteger` class, which is a typical `Converter` implementation: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.core.convert.support; + + final class StringToInteger implements Converter { + + public Integer convert(String source) { + return Integer.valueOf(source); + } + } +---- + + + +[[core-convert-ConverterFactory-SPI]] +== Using `ConverterFactory` + +When you need to centralize the conversion logic for an entire class hierarchy +(for example, when converting from `String` to `Enum` objects), you can implement +`ConverterFactory`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.core.convert.converter; + + public interface ConverterFactory { + + Converter getConverter(Class targetType); + } +---- + +Parameterize S to be the type you are converting from and R to be the base type defining +the __range__ of classes you can convert to. Then implement `getConverter(Class)`, +where T is a subclass of R. + +Consider the `StringToEnumConverterFactory` as an example: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.core.convert.support; + + final class StringToEnumConverterFactory implements ConverterFactory { + + public Converter getConverter(Class targetType) { + return new StringToEnumConverter(targetType); + } + + private final class StringToEnumConverter implements Converter { + + private Class enumType; + + public StringToEnumConverter(Class enumType) { + this.enumType = enumType; + } + + public T convert(String source) { + return (T) Enum.valueOf(this.enumType, source.trim()); + } + } + } +---- + + +[[core-convert-GenericConverter-SPI]] +== Using `GenericConverter` + +When you require a sophisticated `Converter` implementation, consider using the +`GenericConverter` interface. With a more flexible but less strongly typed signature +than `Converter`, a `GenericConverter` supports converting between multiple source and +target types. In addition, a `GenericConverter` makes available source and target field +context that you can use when you implement your conversion logic. Such context lets a +type conversion be driven by a field annotation or by generic information declared on a +field signature. The following listing shows the interface definition of `GenericConverter`: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.core.convert.converter; + + public interface GenericConverter { + + public Set getConvertibleTypes(); + + Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType); + } +---- + +To implement a `GenericConverter`, have `getConvertibleTypes()` return the supported +source->target type pairs. Then implement `convert(Object, TypeDescriptor, +TypeDescriptor)` to contain your conversion logic. The source `TypeDescriptor` provides +access to the source field that holds the value being converted. The target `TypeDescriptor` +provides access to the target field where the converted value is to be set. + +A good example of a `GenericConverter` is a converter that converts between a Java array +and a collection. Such an `ArrayToCollectionConverter` introspects the field that declares +the target collection type to resolve the collection's element type. This lets each +element in the source array be converted to the collection element type before the +collection is set on the target field. + +NOTE: Because `GenericConverter` is a more complex SPI interface, you should use +it only when you need it. Favor `Converter` or `ConverterFactory` for basic type +conversion needs. + + +[[core-convert-ConditionalGenericConverter-SPI]] +=== Using `ConditionalGenericConverter` + +Sometimes, you want a `Converter` to run only if a specific condition holds true. For +example, you might want to run a `Converter` only if a specific annotation is present +on the target field, or you might want to run a `Converter` only if a specific method +(such as a `static valueOf` method) is defined on the target class. +`ConditionalGenericConverter` is the union of the `GenericConverter` and +`ConditionalConverter` interfaces that lets you define such custom matching criteria: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface ConditionalConverter { + + boolean matches(TypeDescriptor sourceType, TypeDescriptor targetType); + } + + public interface ConditionalGenericConverter extends GenericConverter, ConditionalConverter { + } +---- + +A good example of a `ConditionalGenericConverter` is an `IdToEntityConverter` that converts +between a persistent entity identifier and an entity reference. Such an `IdToEntityConverter` +might match only if the target entity type declares a static finder method (for example, +`findAccount(Long)`). You might perform such a finder method check in the implementation of +`matches(TypeDescriptor, TypeDescriptor)`. + + + +[[core-convert-ConversionService-API]] +== The `ConversionService` API + +`ConversionService` defines a unified API for executing type conversion logic at +runtime. Converters are often run behind the following facade interface: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.core.convert; + + public interface ConversionService { + + boolean canConvert(Class sourceType, Class targetType); + + T convert(Object source, Class targetType); + + boolean canConvert(TypeDescriptor sourceType, TypeDescriptor targetType); + + Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType); + } +---- + +Most `ConversionService` implementations also implement `ConverterRegistry`, which +provides an SPI for registering converters. Internally, a `ConversionService` +implementation delegates to its registered converters to carry out type conversion logic. + +A robust `ConversionService` implementation is provided in the `core.convert.support` +package. `GenericConversionService` is the general-purpose implementation suitable for +use in most environments. `ConversionServiceFactory` provides a convenient factory for +creating common `ConversionService` configurations. + + + +[[core-convert-Spring-config]] +== Configuring a `ConversionService` + +A `ConversionService` is a stateless object designed to be instantiated at application +startup and then shared between multiple threads. In a Spring application, you typically +configure a `ConversionService` instance for each Spring container (or `ApplicationContext`). +Spring picks up that `ConversionService` and uses it whenever a type +conversion needs to be performed by the framework. You can also inject this +`ConversionService` into any of your beans and invoke it directly. + +NOTE: If no `ConversionService` is registered with Spring, the original `PropertyEditor`-based +system is used. + +To register a default `ConversionService` with Spring, add the following bean definition +with an `id` of `conversionService`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +A default `ConversionService` can convert between strings, numbers, enums, collections, +maps, and other common types. To supplement or override the default converters with your +own custom converters, set the `converters` property. Property values can implement +any of the `Converter`, `ConverterFactory`, or `GenericConverter` interfaces. + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + +---- + +It is also common to use a `ConversionService` within a Spring MVC application. See +<> in the Spring MVC chapter. + +In certain situations, you may wish to apply formatting during conversion. See +<> for details on using `FormattingConversionServiceFactoryBean`. + + + +[[core-convert-programmatic-usage]] +== Using a `ConversionService` Programmatically + +To work with a `ConversionService` instance programmatically, you can inject a reference to +it like you would for any other bean. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Service + public class MyService { + + public MyService(ConversionService conversionService) { + this.conversionService = conversionService; + } + + public void doIt() { + this.conversionService.convert(...) + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Service + class MyService(private val conversionService: ConversionService) { + + fun doIt() { + conversionService.convert(...) + } + } +---- + +For most use cases, you can use the `convert` method that specifies the `targetType`, but it +does not work with more complex types, such as a collection of a parameterized element. +For example, if you want to convert a `List` of `Integer` to a `List` of `String` programmatically, +you need to provide a formal definition of the source and target types. + +Fortunately, `TypeDescriptor` provides various options to make doing so straightforward, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + DefaultConversionService cs = new DefaultConversionService(); + + List input = ... + cs.convert(input, + TypeDescriptor.forObject(input), // List type descriptor + TypeDescriptor.collection(List.class, TypeDescriptor.valueOf(String.class))); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val cs = DefaultConversionService() + + val input: List = ... + cs.convert(input, + TypeDescriptor.forObject(input), // List type descriptor + TypeDescriptor.collection(List::class.java, TypeDescriptor.valueOf(String::class.java))) +---- + +Note that `DefaultConversionService` automatically registers converters that are +appropriate for most environments. This includes collection converters, scalar +converters, and basic `Object`-to-`String` converters. You can register the same converters +with any `ConverterRegistry` by using the static `addDefaultConverters` +method on the `DefaultConversionService` class. + +Converters for value types are reused for arrays and collections, so there is +no need to create a specific converter to convert from a `Collection` of `S` to a +`Collection` of `T`, assuming that standard collection handling is appropriate. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc b/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc new file mode 100644 index 000000000000..90eb0f374f39 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc @@ -0,0 +1,115 @@ +[[format-configuring-formatting-globaldatetimeformat]] += Configuring a Global Date and Time Format + +By default, date and time fields not annotated with `@DateTimeFormat` are converted from +strings by using the `DateFormat.SHORT` style. If you prefer, you can change this by +defining your own global format. + +To do that, ensure that Spring does not register default formatters. Instead, register +formatters manually with the help of: + +* `org.springframework.format.datetime.standard.DateTimeFormatterRegistrar` +* `org.springframework.format.datetime.DateFormatterRegistrar` + +For example, the following Java configuration registers a global `yyyyMMdd` format: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public FormattingConversionService conversionService() { + + // Use the DefaultFormattingConversionService but do not register defaults + DefaultFormattingConversionService conversionService = + new DefaultFormattingConversionService(false); + + // Ensure @NumberFormat is still supported + conversionService.addFormatterForFieldAnnotation( + new NumberFormatAnnotationFormatterFactory()); + + // Register JSR-310 date conversion with a specific global format + DateTimeFormatterRegistrar dateTimeRegistrar = new DateTimeFormatterRegistrar(); + dateTimeRegistrar.setDateFormatter(DateTimeFormatter.ofPattern("yyyyMMdd")); + dateTimeRegistrar.registerFormatters(conversionService); + + // Register date conversion with a specific global format + DateFormatterRegistrar dateRegistrar = new DateFormatterRegistrar(); + dateRegistrar.setFormatter(new DateFormatter("yyyyMMdd")); + dateRegistrar.registerFormatters(conversionService); + + return conversionService; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun conversionService(): FormattingConversionService { + // Use the DefaultFormattingConversionService but do not register defaults + return DefaultFormattingConversionService(false).apply { + + // Ensure @NumberFormat is still supported + addFormatterForFieldAnnotation(NumberFormatAnnotationFormatterFactory()) + + // Register JSR-310 date conversion with a specific global format + val dateTimeRegistrar = DateTimeFormatterRegistrar() + dateTimeRegistrar.setDateFormatter(DateTimeFormatter.ofPattern("yyyyMMdd")) + dateTimeRegistrar.registerFormatters(this) + + // Register date conversion with a specific global format + val dateRegistrar = DateFormatterRegistrar() + dateRegistrar.setFormatter(DateFormatter("yyyyMMdd")) + dateRegistrar.registerFormatters(this) + } + } + } +---- + +If you prefer XML-based configuration, you can use a +`FormattingConversionServiceFactoryBean`. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + + + + + + + + +---- + +Note there are extra considerations when configuring date and time formats in web +applications. Please see +<> or +<>. + + + diff --git a/framework-docs/modules/ROOT/pages/core/validation/format.adoc b/framework-docs/modules/ROOT/pages/core/validation/format.adoc new file mode 100644 index 000000000000..b636cb094399 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/validation/format.adoc @@ -0,0 +1,363 @@ +[[format]] += Spring Field Formatting + +As discussed in the previous section, <> is a +general-purpose type conversion system. It provides a unified `ConversionService` API as +well as a strongly typed `Converter` SPI for implementing conversion logic from one type +to another. A Spring container uses this system to bind bean property values. In +addition, both the Spring Expression Language (SpEL) and `DataBinder` use this system to +bind field values. For example, when SpEL needs to coerce a `Short` to a `Long` to +complete an `expression.setValue(Object bean, Object value)` attempt, the `core.convert` +system performs the coercion. + +Now consider the type conversion requirements of a typical client environment, such as a +web or desktop application. In such environments, you typically convert from `String` +to support the client postback process, as well as back to `String` to support the +view rendering process. In addition, you often need to localize `String` values. The more +general `core.convert` `Converter` SPI does not address such formatting requirements +directly. To directly address them, Spring provides a convenient `Formatter` SPI that +provides a simple and robust alternative to `PropertyEditor` implementations for client +environments. + +In general, you can use the `Converter` SPI when you need to implement general-purpose type +conversion logic -- for example, for converting between a `java.util.Date` and a `Long`. +You can use the `Formatter` SPI when you work in a client environment (such as a web +application) and need to parse and print localized field values. The `ConversionService` +provides a unified type conversion API for both SPIs. + + + +[[format-Formatter-SPI]] +== The `Formatter` SPI + +The `Formatter` SPI to implement field formatting logic is simple and strongly typed. The +following listing shows the `Formatter` interface definition: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.format; + + public interface Formatter extends Printer, Parser { + } +---- + +`Formatter` extends from the `Printer` and `Parser` building-block interfaces. The +following listing shows the definitions of those two interfaces: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface Printer { + + String print(T fieldValue, Locale locale); + } +---- + +[source,java,indent=0,subs="verbatim,quotes"] +---- + import java.text.ParseException; + + public interface Parser { + + T parse(String clientValue, Locale locale) throws ParseException; + } +---- + +To create your own `Formatter`, implement the `Formatter` interface shown earlier. +Parameterize `T` to be the type of object you wish to format -- for example, +`java.util.Date`. Implement the `print()` operation to print an instance of `T` for +display in the client locale. Implement the `parse()` operation to parse an instance of +`T` from the formatted representation returned from the client locale. Your `Formatter` +should throw a `ParseException` or an `IllegalArgumentException` if a parse attempt fails. Take +care to ensure that your `Formatter` implementation is thread-safe. + +The `format` subpackages provide several `Formatter` implementations as a convenience. +The `number` package provides `NumberStyleFormatter`, `CurrencyStyleFormatter`, and +`PercentStyleFormatter` to format `Number` objects that use a `java.text.NumberFormat`. +The `datetime` package provides a `DateFormatter` to format `java.util.Date` objects with +a `java.text.DateFormat`. + +The following `DateFormatter` is an example `Formatter` implementation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package org.springframework.format.datetime; + + public final class DateFormatter implements Formatter { + + private String pattern; + + public DateFormatter(String pattern) { + this.pattern = pattern; + } + + public String print(Date date, Locale locale) { + if (date == null) { + return ""; + } + return getDateFormat(locale).format(date); + } + + public Date parse(String formatted, Locale locale) throws ParseException { + if (formatted.length() == 0) { + return null; + } + return getDateFormat(locale).parse(formatted); + } + + protected DateFormat getDateFormat(Locale locale) { + DateFormat dateFormat = new SimpleDateFormat(this.pattern, locale); + dateFormat.setLenient(false); + return dateFormat; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + class DateFormatter(private val pattern: String) : Formatter { + + override fun print(date: Date, locale: Locale) + = getDateFormat(locale).format(date) + + @Throws(ParseException::class) + override fun parse(formatted: String, locale: Locale) + = getDateFormat(locale).parse(formatted) + + protected fun getDateFormat(locale: Locale): DateFormat { + val dateFormat = SimpleDateFormat(this.pattern, locale) + dateFormat.isLenient = false + return dateFormat + } + } +---- + +The Spring team welcomes community-driven `Formatter` contributions. See +https://github.com/spring-projects/spring-framework/issues[GitHub Issues] to contribute. + + + +[[format-CustomFormatAnnotations]] +== Annotation-driven Formatting + +Field formatting can be configured by field type or annotation. To bind +an annotation to a `Formatter`, implement `AnnotationFormatterFactory`. The following +listing shows the definition of the `AnnotationFormatterFactory` interface: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.format; + + public interface AnnotationFormatterFactory { + + Set> getFieldTypes(); + + Printer getPrinter(A annotation, Class fieldType); + + Parser getParser(A annotation, Class fieldType); + } +---- + +To create an implementation: + +. Parameterize `A` to be the field `annotationType` with which you wish to associate +formatting logic -- for example `org.springframework.format.annotation.DateTimeFormat`. +. Have `getFieldTypes()` return the types of fields on which the annotation can be used. +. Have `getPrinter()` return a `Printer` to print the value of an annotated field. +. Have `getParser()` return a `Parser` to parse a `clientValue` for an annotated field. + +The following example `AnnotationFormatterFactory` implementation binds the `@NumberFormat` +annotation to a formatter to let a number style or pattern be specified: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public final class NumberFormatAnnotationFormatterFactory + implements AnnotationFormatterFactory { + + private static final Set> FIELD_TYPES = Set.of(Short.class, + Integer.class, Long.class, Float.class, Double.class, + BigDecimal.class, BigInteger.class); + + public Set> getFieldTypes() { + return FIELD_TYPES; + } + + public Printer getPrinter(NumberFormat annotation, Class fieldType) { + return configureFormatterFrom(annotation, fieldType); + } + + public Parser getParser(NumberFormat annotation, Class fieldType) { + return configureFormatterFrom(annotation, fieldType); + } + + private Formatter configureFormatterFrom(NumberFormat annotation, Class fieldType) { + if (!annotation.pattern().isEmpty()) { + return new NumberStyleFormatter(annotation.pattern()); + } + // else + return switch(annotation.style()) { + case Style.PERCENT -> new PercentStyleFormatter(); + case Style.CURRENCY -> new CurrencyStyleFormatter(); + default -> new NumberStyleFormatter(); + }; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class NumberFormatAnnotationFormatterFactory : AnnotationFormatterFactory { + + override fun getFieldTypes(): Set> { + return setOf(Short::class.java, Int::class.java, Long::class.java, Float::class.java, Double::class.java, BigDecimal::class.java, BigInteger::class.java) + } + + override fun getPrinter(annotation: NumberFormat, fieldType: Class<*>): Printer { + return configureFormatterFrom(annotation, fieldType) + } + + override fun getParser(annotation: NumberFormat, fieldType: Class<*>): Parser { + return configureFormatterFrom(annotation, fieldType) + } + + private fun configureFormatterFrom(annotation: NumberFormat, fieldType: Class<*>): Formatter { + return if (annotation.pattern.isNotEmpty()) { + NumberStyleFormatter(annotation.pattern) + } else { + val style = annotation.style + when { + style === NumberFormat.Style.PERCENT -> PercentStyleFormatter() + style === NumberFormat.Style.CURRENCY -> CurrencyStyleFormatter() + else -> NumberStyleFormatter() + } + } + } + } +---- + +To trigger formatting, you can annotate fields with `@NumberFormat`, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MyModel { + + @NumberFormat(style=Style.CURRENCY) + private BigDecimal decimal; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyModel( + @field:NumberFormat(style = Style.CURRENCY) private val decimal: BigDecimal + ) +---- + + +[[format-annotations-api]] +=== Format Annotation API + +A portable format annotation API exists in the `org.springframework.format.annotation` +package. You can use `@NumberFormat` to format `Number` fields such as `Double` and +`Long`, and `@DateTimeFormat` to format `java.util.Date`, `java.util.Calendar`, `Long` +(for millisecond timestamps) as well as JSR-310 `java.time`. + +The following example uses `@DateTimeFormat` to format a `java.util.Date` as an ISO Date +(yyyy-MM-dd): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MyModel { + + @DateTimeFormat(iso=ISO.DATE) + private Date date; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyModel( + @DateTimeFormat(iso=ISO.DATE) private val date: Date + ) +---- + + +[[format-FormatterRegistry-SPI]] +== The `FormatterRegistry` SPI + +The `FormatterRegistry` is an SPI for registering formatters and converters. +`FormattingConversionService` is an implementation of `FormatterRegistry` suitable for +most environments. You can programmatically or declaratively configure this variant +as a Spring bean, e.g. by using `FormattingConversionServiceFactoryBean`. Because this +implementation also implements `ConversionService`, you can directly configure it +for use with Spring's `DataBinder` and the Spring Expression Language (SpEL). + +The following listing shows the `FormatterRegistry` SPI: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.format; + + public interface FormatterRegistry extends ConverterRegistry { + + void addPrinter(Printer printer); + + void addParser(Parser parser); + + void addFormatter(Formatter formatter); + + void addFormatterForFieldType(Class fieldType, Formatter formatter); + + void addFormatterForFieldType(Class fieldType, Printer printer, Parser parser); + + void addFormatterForFieldAnnotation(AnnotationFormatterFactory annotationFormatterFactory); + } +---- + +As shown in the preceding listing, you can register formatters by field type or by annotation. + +The `FormatterRegistry` SPI lets you configure formatting rules centrally, instead of +duplicating such configuration across your controllers. For example, you might want to +enforce that all date fields are formatted a certain way or that fields with a specific +annotation are formatted in a certain way. With a shared `FormatterRegistry`, you define +these rules once, and they are applied whenever formatting is needed. + + + +[[format-FormatterRegistrar-SPI]] +== The `FormatterRegistrar` SPI + +`FormatterRegistrar` is an SPI for registering formatters and converters through the +FormatterRegistry. The following listing shows its interface definition: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.format; + + public interface FormatterRegistrar { + + void registerFormatters(FormatterRegistry registry); + } +---- + +A `FormatterRegistrar` is useful when registering multiple related converters and +formatters for a given formatting category, such as date formatting. It can also be +useful where declarative registration is insufficient -- for example, when a formatter +needs to be indexed under a specific field type different from its own `` or when +registering a `Printer`/`Parser` pair. The next section provides more information on +converter and formatter registration. + + + +[[format-configuring-formatting-mvc]] +== Configuring Formatting in Spring MVC + +See <> in the Spring MVC chapter. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/validation/validator.adoc b/framework-docs/modules/ROOT/pages/core/validation/validator.adoc new file mode 100644 index 000000000000..aa78fd755ce7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/validation/validator.adoc @@ -0,0 +1,182 @@ +[[validator]] += Validation by Using Spring's Validator Interface + +Spring features a `Validator` interface that you can use to validate objects. The +`Validator` interface works by using an `Errors` object so that, while validating, +validators can report validation failures to the `Errors` object. + +Consider the following example of a small data object: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class Person { + + private String name; + private int age; + + // the usual getters and setters... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class Person(val name: String, val age: Int) +---- + +The next example provides validation behavior for the `Person` class by implementing the +following two methods of the `org.springframework.validation.Validator` interface: + +* `supports(Class)`: Can this `Validator` validate instances of the supplied `Class`? +* `validate(Object, org.springframework.validation.Errors)`: Validates the given object + and, in case of validation errors, registers those with the given `Errors` object. + +Implementing a `Validator` is fairly straightforward, especially when you know of the +`ValidationUtils` helper class that the Spring Framework also provides. The following +example implements `Validator` for `Person` instances: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class PersonValidator implements Validator { + + /** + * This Validator validates only Person instances + */ + public boolean supports(Class clazz) { + return Person.class.equals(clazz); + } + + public void validate(Object obj, Errors e) { + ValidationUtils.rejectIfEmpty(e, "name", "name.empty"); + Person p = (Person) obj; + if (p.getAge() < 0) { + e.rejectValue("age", "negativevalue"); + } else if (p.getAge() > 110) { + e.rejectValue("age", "too.darn.old"); + } + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class PersonValidator : Validator { + + /\** + * This Validator validates only Person instances + */ + override fun supports(clazz: Class<*>): Boolean { + return Person::class.java == clazz + } + + override fun validate(obj: Any, e: Errors) { + ValidationUtils.rejectIfEmpty(e, "name", "name.empty") + val p = obj as Person + if (p.age < 0) { + e.rejectValue("age", "negativevalue") + } else if (p.age > 110) { + e.rejectValue("age", "too.darn.old") + } + } + } +---- + +The `static` `rejectIfEmpty(..)` method on the `ValidationUtils` class is used to +reject the `name` property if it is `null` or the empty string. Have a look at the +{api-spring-framework}/validation/ValidationUtils.html[`ValidationUtils`] javadoc +to see what functionality it provides besides the example shown previously. + +While it is certainly possible to implement a single `Validator` class to validate each +of the nested objects in a rich object, it may be better to encapsulate the validation +logic for each nested class of object in its own `Validator` implementation. A simple +example of a "`rich`" object would be a `Customer` that is composed of two `String` +properties (a first and a second name) and a complex `Address` object. `Address` objects +may be used independently of `Customer` objects, so a distinct `AddressValidator` +has been implemented. If you want your `CustomerValidator` to reuse the logic contained +within the `AddressValidator` class without resorting to copy-and-paste, you can +dependency-inject or instantiate an `AddressValidator` within your `CustomerValidator`, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class CustomerValidator implements Validator { + + private final Validator addressValidator; + + public CustomerValidator(Validator addressValidator) { + if (addressValidator == null) { + throw new IllegalArgumentException("The supplied [Validator] is " + + "required and must not be null."); + } + if (!addressValidator.supports(Address.class)) { + throw new IllegalArgumentException("The supplied [Validator] must " + + "support the validation of [Address] instances."); + } + this.addressValidator = addressValidator; + } + + /** + * This Validator validates Customer instances, and any subclasses of Customer too + */ + public boolean supports(Class clazz) { + return Customer.class.isAssignableFrom(clazz); + } + + public void validate(Object target, Errors errors) { + ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "field.required"); + ValidationUtils.rejectIfEmptyOrWhitespace(errors, "surname", "field.required"); + Customer customer = (Customer) target; + try { + errors.pushNestedPath("address"); + ValidationUtils.invokeValidator(this.addressValidator, customer.getAddress(), errors); + } finally { + errors.popNestedPath(); + } + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class CustomerValidator(private val addressValidator: Validator) : Validator { + + init { + if (addressValidator == null) { + throw IllegalArgumentException("The supplied [Validator] is required and must not be null.") + } + if (!addressValidator.supports(Address::class.java)) { + throw IllegalArgumentException("The supplied [Validator] must support the validation of [Address] instances.") + } + } + + /** + * This Validator validates Customer instances, and any subclasses of Customer too + */ + override fun supports(clazz: Class<*>): Boolean { + return Customer::class.java.isAssignableFrom(clazz) + } + + override fun validate(target: Any, errors: Errors) { + ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "field.required") + ValidationUtils.rejectIfEmptyOrWhitespace(errors, "surname", "field.required") + val customer = target as Customer + try { + errors.pushNestedPath("address") + ValidationUtils.invokeValidator(this.addressValidator, customer.address, errors) + } finally { + errors.popNestedPath() + } + } + } +---- + +Validation errors are reported to the `Errors` object passed to the validator. In the case +of Spring Web MVC, you can use the `` tag to inspect the error messages, but +you can also inspect the `Errors` object yourself. More information about the +methods it offers can be found in the {api-spring-framework}/validation/Errors.html[javadoc]. + + + + diff --git a/framework-docs/modules/ROOT/pages/data-access.adoc b/framework-docs/modules/ROOT/pages/data-access.adoc index 13fb9a203409..90adba00db30 100644 --- a/framework-docs/modules/ROOT/pages/data-access.adoc +++ b/framework-docs/modules/ROOT/pages/data-access.adoc @@ -13,9127 +13,3 @@ with which the Spring Framework integrates. -[[transaction]] -== Transaction Management - -Comprehensive transaction support is among the most compelling reasons to use the Spring -Framework. The Spring Framework provides a consistent abstraction for transaction -management that delivers the following benefits: - -* A consistent programming model across different transaction APIs, such as Java - Transaction API (JTA), JDBC, Hibernate, and the Java Persistence API (JPA). -* Support for <>. -* A simpler API for <> transaction management - than complex transaction APIs, such as JTA. -* Excellent integration with Spring's data access abstractions. - -The following sections describe the Spring Framework's transaction features and -technologies: - -* <> describes why you would use the Spring Framework's transaction abstraction - instead of EJB Container-Managed Transactions (CMT) or choosing to drive local - transactions through a proprietary API, such as Hibernate. -* <> - outlines the core classes and describes how to configure and obtain `DataSource` - instances from a variety of sources. -* <> describes - how the application code ensures that resources are created, reused, and cleaned up - properly. -* <> describes support for - declarative transaction management. -* <> covers support for - programmatic (that is, explicitly coded) transaction management. -* <> describes how you could use application - events within a transaction. - -The chapter also includes discussions of best practices, -<>, -and <>. - - - -[[transaction-motivation]] -=== Advantages of the Spring Framework's Transaction Support Model - -Traditionally, EE application developers have had two choices for transaction management: -global or local transactions, both of which have profound limitations. Global -and local transaction management is reviewed in the next two sections, followed by a -discussion of how the Spring Framework's transaction management support addresses the -limitations of the global and local transaction models. - - -[[transaction-global]] -==== Global Transactions - -Global transactions let you work with multiple transactional resources, typically -relational databases and message queues. The application server manages global -transactions through the JTA, which is a cumbersome API (partly due to its -exception model). Furthermore, a JTA `UserTransaction` normally needs to be sourced from -JNDI, meaning that you also need to use JNDI in order to use JTA. The use -of global transactions limits any potential reuse of application code, as JTA is -normally only available in an application server environment. - -Previously, the preferred way to use global transactions was through EJB CMT -(Container Managed Transaction). CMT is a form of declarative transaction -management (as distinguished from programmatic transaction management). EJB CMT -removes the need for transaction-related JNDI lookups, although the use of EJB -itself necessitates the use of JNDI. It removes most but not all of the need to write -Java code to control transactions. The significant downside is that CMT is tied to JTA -and an application server environment. Also, it is only available if one chooses to -implement business logic in EJBs (or at least behind a transactional EJB facade). The -negatives of EJB in general are so great that this is not an attractive proposition, -especially in the face of compelling alternatives for declarative transaction management. - - -[[transaction-local]] -==== Local Transactions - -Local transactions are resource-specific, such as a transaction associated with a JDBC -connection. Local transactions may be easier to use but have a significant disadvantage: -They cannot work across multiple transactional resources. For example, code that manages -transactions by using a JDBC connection cannot run within a global JTA transaction. Because -the application server is not involved in transaction management, it cannot help ensure -correctness across multiple resources. (It is worth noting that most applications use a -single transaction resource.) Another downside is that local transactions are invasive -to the programming model. - - -[[transaction-programming-model]] -==== Spring Framework's Consistent Programming Model - -Spring resolves the disadvantages of global and local transactions. It lets -application developers use a consistent programming model in any environment. -You write your code once, and it can benefit from different transaction management -strategies in different environments. The Spring Framework provides both declarative and -programmatic transaction management. Most users prefer declarative transaction -management, which we recommend in most cases. - -With programmatic transaction management, developers work with the Spring Framework -transaction abstraction, which can run over any underlying transaction infrastructure. -With the preferred declarative model, developers typically write little or no code -related to transaction management and, hence, do not depend on the Spring Framework -transaction API or any other transaction API. - -.Do you need an application server for transaction management? -**** -The Spring Framework's transaction management support changes traditional rules as to -when an enterprise Java application requires an application server. - -In particular, you do not need an application server purely for declarative transactions -through EJBs. In fact, even if your application server has powerful JTA capabilities, -you may decide that the Spring Framework's declarative transactions offer more power and -a more productive programming model than EJB CMT. - -Typically, you need an application server's JTA capability only if your application needs -to handle transactions across multiple resources, which is not a requirement for many -applications. Many high-end applications use a single, highly scalable database (such as -Oracle RAC) instead. Stand-alone transaction managers (such as -https://www.atomikos.com/[Atomikos Transactions]) -are other options. Of course, you may need other application server capabilities, such as -Java Message Service (JMS) and Jakarta EE Connector Architecture (JCA). - -The Spring Framework gives you the choice of when to scale your application to a fully -loaded application server. Gone are the days when the only alternative to using EJB -CMT or JTA was to write code with local transactions (such as those on JDBC connections) -and face a hefty rework if you need that code to run within global, container-managed -transactions. With the Spring Framework, only some of the bean definitions in your -configuration file need to change (rather than your code). -**** - - - -[[transaction-strategies]] -=== Understanding the Spring Framework Transaction Abstraction - -The key to the Spring transaction abstraction is the notion of a transaction strategy. A -transaction strategy is defined by a `TransactionManager`, specifically the -`org.springframework.transaction.PlatformTransactionManager` interface for imperative -transaction management and the -`org.springframework.transaction.ReactiveTransactionManager` interface for reactive -transaction management. The following listing shows the definition of the -`PlatformTransactionManager` API: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface PlatformTransactionManager extends TransactionManager { - - TransactionStatus getTransaction(TransactionDefinition definition) throws TransactionException; - - void commit(TransactionStatus status) throws TransactionException; - - void rollback(TransactionStatus status) throws TransactionException; - } ----- - -This is primarily a service provider interface (SPI), although you can use it -<> from your application code. Because -`PlatformTransactionManager` is an interface, it can be easily mocked or stubbed as -necessary. It is not tied to a lookup strategy, such as JNDI. -`PlatformTransactionManager` implementations are defined like any other object (or bean) -in the Spring Framework IoC container. This benefit alone makes Spring Framework -transactions a worthwhile abstraction, even when you work with JTA. You can test -transactional code much more easily than if it used JTA directly. - -Again, in keeping with Spring's philosophy, the `TransactionException` that can be thrown -by any of the `PlatformTransactionManager` interface's methods is unchecked (that -is, it extends the `java.lang.RuntimeException` class). Transaction infrastructure -failures are almost invariably fatal. In rare cases where application code can actually -recover from a transaction failure, the application developer can still choose to catch -and handle `TransactionException`. The salient point is that developers are not -_forced_ to do so. - -The `getTransaction(..)` method returns a `TransactionStatus` object, depending on a -`TransactionDefinition` parameter. The returned `TransactionStatus` might represent a -new transaction or can represent an existing transaction, if a matching transaction -exists in the current call stack. The implication in this latter case is that, as with -Jakarta EE transaction contexts, a `TransactionStatus` is associated with a thread of -execution. - -As of Spring Framework 5.2, Spring also provides a transaction management abstraction for -reactive applications that make use of reactive types or Kotlin Coroutines. The following -listing shows the transaction strategy defined by -`org.springframework.transaction.ReactiveTransactionManager`: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface ReactiveTransactionManager extends TransactionManager { - - Mono getReactiveTransaction(TransactionDefinition definition) throws TransactionException; - - Mono commit(ReactiveTransaction status) throws TransactionException; - - Mono rollback(ReactiveTransaction status) throws TransactionException; - } ----- - -The reactive transaction manager is primarily a service provider interface (SPI), -although you can use it <> from your -application code. Because `ReactiveTransactionManager` is an interface, it can be easily -mocked or stubbed as necessary. - -The `TransactionDefinition` interface specifies: - -* Propagation: Typically, all code within a transaction scope runs in - that transaction. However, you can specify the behavior if - a transactional method is run when a transaction context already exists. For - example, code can continue running in the existing transaction (the common case), or - the existing transaction can be suspended and a new transaction created. Spring - offers all of the transaction propagation options familiar from EJB CMT. To read - about the semantics of transaction propagation in Spring, see <>. -* Isolation: The degree to which this transaction is isolated from the work of other - transactions. For example, can this transaction see uncommitted writes from other - transactions? -* Timeout: How long this transaction runs before timing out and being automatically rolled back - by the underlying transaction infrastructure. -* Read-only status: You can use a read-only transaction when your code reads but - does not modify data. Read-only transactions can be a useful optimization in some - cases, such as when you use Hibernate. - -These settings reflect standard transactional concepts. If necessary, refer to resources -that discuss transaction isolation levels and other core transaction concepts. -Understanding these concepts is essential to using the Spring Framework or any -transaction management solution. - -The `TransactionStatus` interface provides a simple way for transactional code to -control transaction execution and query transaction status. The concepts should be -familiar, as they are common to all transaction APIs. The following listing shows the -`TransactionStatus` interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface TransactionStatus extends TransactionExecution, SavepointManager, Flushable { - - @Override - boolean isNewTransaction(); - - boolean hasSavepoint(); - - @Override - void setRollbackOnly(); - - @Override - boolean isRollbackOnly(); - - void flush(); - - @Override - boolean isCompleted(); - } ----- - -Regardless of whether you opt for declarative or programmatic transaction management in -Spring, defining the correct `TransactionManager` implementation is absolutely essential. -You typically define this implementation through dependency injection. - -`TransactionManager` implementations normally require knowledge of the environment in -which they work: JDBC, JTA, Hibernate, and so on. The following examples show how you can -define a local `PlatformTransactionManager` implementation (in this case, with plain -JDBC.) - -You can define a JDBC `DataSource` by creating a bean similar to the following: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -The related `PlatformTransactionManager` bean definition then has a reference to the -`DataSource` definition. It should resemble the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -If you use JTA in a Jakarta EE container, then you use a container `DataSource`, obtained -through JNDI, in conjunction with Spring's `JtaTransactionManager`. The following example -shows what the JTA and JNDI lookup version would look like: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - ----- - -The `JtaTransactionManager` does not need to know about the `DataSource` (or any other -specific resources) because it uses the container's global transaction management -infrastructure. - -NOTE: The preceding definition of the `dataSource` bean uses the `` tag -from the `jee` namespace. For more information see -<>. - -NOTE: If you use JTA, your transaction manager definition should look the same, regardless -of what data access technology you use, be it JDBC, Hibernate JPA, or any other supported -technology. This is due to the fact that JTA transactions are global transactions, which -can enlist any transactional resource. - -In all Spring transaction setups, application code does not need to change. You can change -how transactions are managed merely by changing configuration, even if that change means -moving from local to global transactions or vice versa. - - -[[transaction-strategies-hibernate]] -==== Hibernate Transaction Setup - -You can also easily use Hibernate local transactions, as shown in the following examples. -In this case, you need to define a Hibernate `LocalSessionFactoryBean`, which your -application code can use to obtain Hibernate `Session` instances. - -The `DataSource` bean definition is similar to the local JDBC example shown previously -and, thus, is not shown in the following example. - -NOTE: If the `DataSource` (used by any non-JTA transaction manager) is looked up through -JNDI and managed by a Jakarta EE container, it should be non-transactional, because the -Spring Framework (rather than the Jakarta EE container) manages the transactions. - -The `txManager` bean in this case is of the `HibernateTransactionManager` type. In the -same way as the `DataSourceTransactionManager` needs a reference to the `DataSource`, the -`HibernateTransactionManager` needs a reference to the `SessionFactory`. The following -example declares `sessionFactory` and `txManager` beans: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - org/springframework/samples/petclinic/hibernate/petclinic.hbm.xml - - - - - hibernate.dialect=${hibernate.dialect} - - - - - - - ----- - -If you use Hibernate and Jakarta EE container-managed JTA transactions, you should use the -same `JtaTransactionManager` as in the previous JTA example for JDBC, as the following -example shows. Also, it is recommended to make Hibernate aware of JTA through its -transaction coordinator and possibly also its connection release mode configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - org/springframework/samples/petclinic/hibernate/petclinic.hbm.xml - - - - - hibernate.dialect=${hibernate.dialect} - hibernate.transaction.coordinator_class=jta - hibernate.connection.handling_mode=DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT - - - - - ----- - -Or alternatively, you may pass the `JtaTransactionManager` into your `LocalSessionFactoryBean` -for enforcing the same defaults: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - org/springframework/samples/petclinic/hibernate/petclinic.hbm.xml - - - - - hibernate.dialect=${hibernate.dialect} - - - - - - ----- - - - -[[tx-resource-synchronization]] -=== Synchronizing Resources with Transactions - -How to create different transaction managers and how they are linked to related resources -that need to be synchronized to transactions (for example `DataSourceTransactionManager` -to a JDBC `DataSource`, `HibernateTransactionManager` to a Hibernate `SessionFactory`, -and so forth) should now be clear. This section describes how the application code -(directly or indirectly, by using a persistence API such as JDBC, Hibernate, or JPA) -ensures that these resources are created, reused, and cleaned up properly. The section -also discusses how transaction synchronization is (optionally) triggered through the -relevant `TransactionManager`. - - -[[tx-resource-synchronization-high]] -==== High-level Synchronization Approach - -The preferred approach is to use Spring's highest-level template-based persistence -integration APIs or to use native ORM APIs with transaction-aware factory beans or -proxies for managing the native resource factories. These transaction-aware solutions -internally handle resource creation and reuse, cleanup, optional transaction -synchronization of the resources, and exception mapping. Thus, user data access code does -not have to address these tasks but can focus purely on non-boilerplate -persistence logic. Generally, you use the native ORM API or take a template approach -for JDBC access by using the `JdbcTemplate`. These solutions are detailed in subsequent -sections of this reference documentation. - - -[[tx-resource-synchronization-low]] -==== Low-level Synchronization Approach - -Classes such as `DataSourceUtils` (for JDBC), `EntityManagerFactoryUtils` (for JPA), -`SessionFactoryUtils` (for Hibernate), and so on exist at a lower level. When you want the -application code to deal directly with the resource types of the native persistence APIs, -you use these classes to ensure that proper Spring Framework-managed instances are obtained, -transactions are (optionally) synchronized, and exceptions that occur in the process are -properly mapped to a consistent API. - -For example, in the case of JDBC, instead of the traditional JDBC approach of calling -the `getConnection()` method on the `DataSource`, you can instead use Spring's -`org.springframework.jdbc.datasource.DataSourceUtils` class, as follows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - Connection conn = DataSourceUtils.getConnection(dataSource); ----- - -If an existing transaction already has a connection synchronized (linked) to it, that -instance is returned. Otherwise, the method call triggers the creation of a new -connection, which is (optionally) synchronized to any existing transaction and made -available for subsequent reuse in that same transaction. As mentioned earlier, any -`SQLException` is wrapped in a Spring Framework `CannotGetJdbcConnectionException`, one -of the Spring Framework's hierarchy of unchecked `DataAccessException` types. This approach -gives you more information than can be obtained easily from the `SQLException` and -ensures portability across databases and even across different persistence technologies. - -This approach also works without Spring transaction management (transaction -synchronization is optional), so you can use it whether or not you use Spring for -transaction management. - -Of course, once you have used Spring's JDBC support, JPA support, or Hibernate support, -you generally prefer not to use `DataSourceUtils` or the other helper classes, -because you are much happier working through the Spring abstraction than directly -with the relevant APIs. For example, if you use the Spring `JdbcTemplate` or -`jdbc.object` package to simplify your use of JDBC, correct connection retrieval occurs -behind the scenes and you need not write any special code. - - -[[tx-resource-synchronization-tadsp]] -==== `TransactionAwareDataSourceProxy` - -At the very lowest level exists the `TransactionAwareDataSourceProxy` class. This is a -proxy for a target `DataSource`, which wraps the target `DataSource` to add awareness of -Spring-managed transactions. In this respect, it is similar to a transactional JNDI -`DataSource`, as provided by a Jakarta EE server. - -You should almost never need or want to use this class, except when existing -code must be called and passed a standard JDBC `DataSource` interface implementation. In -that case, it is possible that this code is usable but is participating in Spring-managed -transactions. You can write your new code by using the higher-level -abstractions mentioned earlier. - - - -[[transaction-declarative]] -=== Declarative Transaction Management - -NOTE: Most Spring Framework users choose declarative transaction management. This option has -the least impact on application code and, hence, is most consistent with the ideals of a -non-invasive lightweight container. - -The Spring Framework's declarative transaction management is made possible with Spring -aspect-oriented programming (AOP). However, as the transactional aspects code comes -with the Spring Framework distribution and may be used in a boilerplate fashion, AOP -concepts do not generally have to be understood to make effective use of this code. - -The Spring Framework's declarative transaction management is similar to EJB CMT, in that -you can specify transaction behavior (or lack of it) down to the individual method level. -You can make a `setRollbackOnly()` call within a transaction context, if -necessary. The differences between the two types of transaction management are: - -* Unlike EJB CMT, which is tied to JTA, the Spring Framework's declarative transaction - management works in any environment. It can work with JTA transactions or local - transactions by using JDBC, JPA, or Hibernate by adjusting the configuration - files. -* You can apply the Spring Framework declarative transaction management to any class, - not merely special classes such as EJBs. -* The Spring Framework offers declarative - <>, a feature with no EJB - equivalent. Both programmatic and declarative support for rollback rules is provided. -* The Spring Framework lets you customize transactional behavior by using AOP. - For example, you can insert custom behavior in the case of transaction rollback. You - can also add arbitrary advice, along with transactional advice. With EJB CMT, you - cannot influence the container's transaction management, except with - `setRollbackOnly()`. -* The Spring Framework does not support propagation of transaction contexts across - remote calls, as high-end application servers do. If you need this feature, we - recommend that you use EJB. However, consider carefully before using such a feature, - because, normally, one does not want transactions to span remote calls. - -The concept of rollback rules is important. They let you specify which exceptions -(and throwables) should cause automatic rollback. You can specify this declaratively, in -configuration, not in Java code. So, although you can still call `setRollbackOnly()` on -the `TransactionStatus` object to roll back the current transaction back, most often you -can specify a rule that `MyApplicationException` must always result in rollback. The -significant advantage to this option is that business objects do not depend on the -transaction infrastructure. For example, they typically do not need to import Spring -transaction APIs or other Spring APIs. - -Although EJB container default behavior automatically rolls back the transaction on a -system exception (usually a runtime exception), EJB CMT does not roll back the -transaction automatically on an application exception (that is, a checked exception -other than `java.rmi.RemoteException`). While the Spring default behavior for -declarative transaction management follows EJB convention (roll back is automatic only -on unchecked exceptions), it is often useful to customize this behavior. - - -[[tx-decl-explained]] -==== Understanding the Spring Framework's Declarative Transaction Implementation - -It is not sufficient merely to tell you to annotate your classes with the -`@Transactional` annotation, add `@EnableTransactionManagement` to your configuration, -and expect you to understand how it all works. To provide a deeper understanding, this -section explains the inner workings of the Spring Framework's declarative transaction -infrastructure in the context of transaction-related issues. - -The most important concepts to grasp with regard to the Spring Framework's declarative -transaction support are that this support is enabled -<> and that the transactional -advice is driven by metadata (currently XML- or annotation-based). The combination of AOP -with transactional metadata yields an AOP proxy that uses a `TransactionInterceptor` in -conjunction with an appropriate `TransactionManager` implementation to drive transactions -around method invocations. - -NOTE: Spring AOP is covered in <>. - -Spring Framework's `TransactionInterceptor` provides transaction management for -imperative and reactive programming models. The interceptor detects the desired flavor of -transaction management by inspecting the method return type. Methods returning a reactive -type such as `Publisher` or Kotlin `Flow` (or a subtype of those) qualify for reactive -transaction management. All other return types including `void` use the code path for -imperative transaction management. - -Transaction management flavors impact which transaction manager is required. Imperative -transactions require a `PlatformTransactionManager`, while reactive transactions use -`ReactiveTransactionManager` implementations. - -[NOTE] -==== -`@Transactional` commonly works with thread-bound transactions managed by -`PlatformTransactionManager`, exposing a transaction to all data access operations within -the current execution thread. Note: This does _not_ propagate to newly started threads -within the method. - -A reactive transaction managed by `ReactiveTransactionManager` uses the Reactor context -instead of thread-local attributes. As a consequence, all participating data access -operations need to execute within the same Reactor context in the same reactive pipeline. -==== - -The following image shows a conceptual view of calling a method on a transactional proxy: - -image::tx.png[] - - -[[transaction-declarative-first-example]] -==== Example of Declarative Transaction Implementation - -Consider the following interface and its attendant implementation. This example uses -`Foo` and `Bar` classes as placeholders so that you can concentrate on the transaction -usage without focusing on a particular domain model. For the purposes of this example, -the fact that the `DefaultFooService` class throws `UnsupportedOperationException` -instances in the body of each implemented method is good. That behavior lets you see -transactions being created and then rolled back in response to the -`UnsupportedOperationException` instance. The following listing shows the `FooService` -interface: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - // the service interface that we want to make transactional - - package x.y.service; - - public interface FooService { - - Foo getFoo(String fooName); - - Foo getFoo(String fooName, String barName); - - void insertFoo(Foo foo); - - void updateFoo(Foo foo); - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - // the service interface that we want to make transactional - - package x.y.service - - interface FooService { - - fun getFoo(fooName: String): Foo - - fun getFoo(fooName: String, barName: String): Foo - - fun insertFoo(foo: Foo) - - fun updateFoo(foo: Foo) - } ----- - -The following example shows an implementation of the preceding interface: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package x.y.service; - - public class DefaultFooService implements FooService { - - @Override - public Foo getFoo(String fooName) { - // ... - } - - @Override - public Foo getFoo(String fooName, String barName) { - // ... - } - - @Override - public void insertFoo(Foo foo) { - // ... - } - - @Override - public void updateFoo(Foo foo) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package x.y.service - - class DefaultFooService : FooService { - - override fun getFoo(fooName: String): Foo { - // ... - } - - override fun getFoo(fooName: String, barName: String): Foo { - // ... - } - - override fun insertFoo(foo: Foo) { - // ... - } - - override fun updateFoo(foo: Foo) { - // ... - } - } ----- - -Assume that the first two methods of the `FooService` interface, `getFoo(String)` and -`getFoo(String, String)`, must run in the context of a transaction with read-only -semantics and that the other methods, `insertFoo(Foo)` and `updateFoo(Foo)`, must -run in the context of a transaction with read-write semantics. The following -configuration is explained in detail in the next few paragraphs: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----- - -Examine the preceding configuration. It assumes that you want to make a service object, -the `fooService` bean, transactional. The transaction semantics to apply are encapsulated -in the `` definition. The `` definition reads as "all methods -starting with `get` are to run in the context of a read-only transaction, and all -other methods are to run with the default transaction semantics". The -`transaction-manager` attribute of the `` tag is set to the name of the -`TransactionManager` bean that is going to drive the transactions (in this case, the -`txManager` bean). - -TIP: You can omit the `transaction-manager` attribute in the transactional advice -(``) if the bean name of the `TransactionManager` that you want to -wire in has the name `transactionManager`. If the `TransactionManager` bean that -you want to wire in has any other name, you must use the `transaction-manager` -attribute explicitly, as in the preceding example. - -The `` definition ensures that the transactional advice defined by the -`txAdvice` bean runs at the appropriate points in the program. First, you define a -pointcut that matches the execution of any operation defined in the `FooService` interface -(`fooServiceOperation`). Then you associate the pointcut with the `txAdvice` by using an -advisor. The result indicates that, at the execution of a `fooServiceOperation`, -the advice defined by `txAdvice` is run. - -The expression defined within the `` element is an AspectJ pointcut -expression. See <> for more details on pointcut -expressions in Spring. - -A common requirement is to make an entire service layer transactional. The best way to -do this is to change the pointcut expression to match any operation in your -service layer. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - ----- - -NOTE: In the preceding example, it is assumed that all your service interfaces are defined -in the `x.y.service` package. See <> for more details. - -Now that we have analyzed the configuration, you may be asking yourself, -"What does all this configuration actually do?" - -The configuration shown earlier is used to create a transactional proxy around the object -that is created from the `fooService` bean definition. The proxy is configured with -the transactional advice so that, when an appropriate method is invoked on the proxy, -a transaction is started, suspended, marked as read-only, and so on, depending on the -transaction configuration associated with that method. Consider the following program -that test drives the configuration shown earlier: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public final class Boot { - - public static void main(final String[] args) throws Exception { - ApplicationContext ctx = new ClassPathXmlApplicationContext("context.xml"); - FooService fooService = ctx.getBean(FooService.class); - fooService.insertFoo(new Foo()); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - fun main() { - val ctx = ClassPathXmlApplicationContext("context.xml") - val fooService = ctx.getBean("fooService") - fooService.insertFoo(Foo()) - } ----- - -The output from running the preceding program should resemble the following (the Log4J -output and the stack trace from the `UnsupportedOperationException` thrown by the -`insertFoo(..)` method of the `DefaultFooService` class have been truncated for clarity): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - [AspectJInvocationContextExposingAdvisorAutoProxyCreator] - Creating implicit proxy for bean 'fooService' with 0 common interceptors and 1 specific interceptors - - - [JdkDynamicAopProxy] - Creating JDK dynamic proxy for [x.y.service.DefaultFooService] - - - [TransactionInterceptor] - Getting transaction for x.y.service.FooService.insertFoo - - - [DataSourceTransactionManager] - Creating new transaction with name [x.y.service.FooService.insertFoo] - [DataSourceTransactionManager] - Acquired Connection [org.apache.commons.dbcp.PoolableConnection@a53de4] for JDBC transaction - - - [RuleBasedTransactionAttribute] - Applying rules to determine whether transaction should rollback on java.lang.UnsupportedOperationException - [TransactionInterceptor] - Invoking rollback for transaction on x.y.service.FooService.insertFoo due to throwable [java.lang.UnsupportedOperationException] - - - [DataSourceTransactionManager] - Rolling back JDBC transaction on Connection [org.apache.commons.dbcp.PoolableConnection@a53de4] - [DataSourceTransactionManager] - Releasing JDBC Connection after transaction - [DataSourceUtils] - Returning JDBC Connection to DataSource - - Exception in thread "main" java.lang.UnsupportedOperationException at x.y.service.DefaultFooService.insertFoo(DefaultFooService.java:14) - - at $Proxy0.insertFoo(Unknown Source) - at Boot.main(Boot.java:11) ----- - -To use reactive transaction management the code has to use reactive types. - -NOTE: Spring Framework uses the `ReactiveAdapterRegistry` to determine whether a method -return type is reactive. - -The following listing shows a modified version of the previously used `FooService`, but -this time the code uses reactive types: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - // the reactive service interface that we want to make transactional - - package x.y.service; - - public interface FooService { - - Flux getFoo(String fooName); - - Publisher getFoo(String fooName, String barName); - - Mono insertFoo(Foo foo); - - Mono updateFoo(Foo foo); - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - // the reactive service interface that we want to make transactional - - package x.y.service - - interface FooService { - - fun getFoo(fooName: String): Flow - - fun getFoo(fooName: String, barName: String): Publisher - - fun insertFoo(foo: Foo) : Mono - - fun updateFoo(foo: Foo) : Mono - } ----- - -The following example shows an implementation of the preceding interface: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package x.y.service; - - public class DefaultFooService implements FooService { - - @Override - public Flux getFoo(String fooName) { - // ... - } - - @Override - public Publisher getFoo(String fooName, String barName) { - // ... - } - - @Override - public Mono insertFoo(Foo foo) { - // ... - } - - @Override - public Mono updateFoo(Foo foo) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ----- - package x.y.service - - class DefaultFooService : FooService { - - override fun getFoo(fooName: String): Flow { - // ... - } - - override fun getFoo(fooName: String, barName: String): Publisher { - // ... - } - - override fun insertFoo(foo: Foo): Mono { - // ... - } - - override fun updateFoo(foo: Foo): Mono { - // ... - } - } ----- - -Imperative and reactive transaction management share the same semantics for transaction -boundary and transaction attribute definitions. The main difference between imperative -and reactive transactions is the deferred nature of the latter. `TransactionInterceptor` -decorates the returned reactive type with a transactional operator to begin and clean up -the transaction. Therefore, calling a transactional reactive method defers the actual -transaction management to a subscription type that activates processing of the reactive -type. - -Another aspect of reactive transaction management relates to data escaping which is a -natural consequence of the programming model. - -Method return values of imperative transactions are returned from transactional methods -upon successful termination of a method so that partially computed results do not escape -the method closure. - -Reactive transaction methods return a reactive wrapper type which represents a -computation sequence along with a promise to begin and complete the computation. - -A `Publisher` can emit data while a transaction is ongoing but not necessarily completed. -Therefore, methods that depend upon successful completion of an entire transaction need -to ensure completion and buffer results in the calling code. - - -[[transaction-declarative-rolling-back]] -==== Rolling Back a Declarative Transaction - -The previous section outlined the basics of how to specify transactional settings for -classes, typically service layer classes, declaratively in your application. This section -describes how you can control the rollback of transactions in a simple, declarative -fashion in XML configuration. For details on controlling rollback semantics declaratively -with the `@Transactional` annotation, see -<>. - -The recommended way to indicate to the Spring Framework's transaction infrastructure -that a transaction's work is to be rolled back is to throw an `Exception` from code that -is currently executing in the context of a transaction. The Spring Framework's -transaction infrastructure code catches any unhandled `Exception` as it bubbles up -the call stack and makes a determination whether to mark the transaction for rollback. - -In its default configuration, the Spring Framework's transaction infrastructure code -marks a transaction for rollback only in the case of runtime, unchecked exceptions. -That is, when the thrown exception is an instance or subclass of `RuntimeException`. -(`Error` instances also, by default, result in a rollback). - -As of Spring Framework 5.2, the default configuration also provides support for -Vavr's `Try` method to trigger transaction rollbacks when it returns a 'Failure'. -This allows you to handle functional-style errors using Try and have the transaction -automatically rolled back in case of a failure. For more information on Vavr's Try, -refer to the [official Vavr documentation](https://www.vavr.io/vavr-docs/#_try). - -Here's an example of how to use Vavr's Try with a transactional method: -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Transactional - public Try myTransactionalMethod() { - // If myDataAccessOperation throws an exception, it will be caught by the - // Try instance created with Try.of() and wrapped inside the Failure class - // which can be checked using the isFailure() method on the Try instance. - return Try.of(delegate::myDataAccessOperation); - } ----- - -Checked exceptions that are thrown from a transactional method do not result in a rollback -in the default configuration. You can configure exactly which `Exception` types mark a -transaction for rollback, including checked exceptions by specifying _rollback rules_. - -.Rollback rules -[[transaction-declarative-rollback-rules]] -[NOTE] -==== -Rollback rules determine if a transaction should be rolled back when a given exception is -thrown, and the rules are based on exception types or exception patterns. - -Rollback rules may be configured in XML via the `rollback-for` and `no-rollback-for` -attributes, which allow rules to be defined as patterns. When using -<>, rollback rules may -be configured via the `rollbackFor`/`noRollbackFor` and -`rollbackForClassName`/`noRollbackForClassName` attributes, which allow rules to be -defined based on exception types or patterns, respectively. - -When a rollback rule is defined with an exception type, that type will be used to match -against the type of a thrown exception and its super types, providing type safety and -avoiding any unintentional matches that may occur when using a pattern. For example, a -value of `jakarta.servlet.ServletException.class` will only match thrown exceptions of -type `jakarta.servlet.ServletException` and its subclasses. - -When a rollback rule is defined with an exception pattern, the pattern can be a fully -qualified class name or a substring of a fully qualified class name for an exception type -(which must be a subclass of `Throwable`), with no wildcard support at present. For -example, a value of `"jakarta.servlet.ServletException"` or `"ServletException"` will -match `jakarta.servlet.ServletException` and its subclasses. - -[WARNING] -===== -You must carefully consider how specific a pattern is and whether to include package -information (which isn't mandatory). For example, `"Exception"` will match nearly -anything and will probably hide other rules. `"java.lang.Exception"` would be correct if -`"Exception"` were meant to define a rule for all checked exceptions. With more unique -exception names such as `"BaseBusinessException"` there is likely no need to use the -fully qualified class name for the exception pattern. - -Furthermore, pattern-based rollback rules may result in unintentional matches for -similarly named exceptions and nested classes. This is due to the fact that a thrown -exception is considered to be a match for a given pattern-based rollback rule if the name -of the thrown exception contains the exception pattern configured for the rollback rule. -For example, given a rule configured to match on `"com.example.CustomException"`, that -rule will match against an exception named `com.example.CustomExceptionV2` (an exception -in the same package as `CustomException` but with an additional suffix) or an exception -named `com.example.CustomException$AnotherException` (an exception declared as a nested -class in `CustomException`). -===== -==== - -The following XML snippet demonstrates how to configure rollback for a checked, -application-specific `Exception` type by supplying an _exception pattern_ via the -`rollback-for` attribute: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -If you do not want a transaction rolled back when an exception is thrown, you can also -specify 'no rollback' rules. The following example tells the Spring Framework's -transaction infrastructure to commit the attendant transaction even in the face of an -unhandled `InstrumentNotFoundException`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -When the Spring Framework's transaction infrastructure catches an exception and consults -the configured rollback rules to determine whether to mark the transaction for rollback, -the strongest matching rule wins. So, in the case of the following configuration, any -exception other than an `InstrumentNotFoundException` results in a rollback of the -attendant transaction: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - -You can also indicate a required rollback programmatically. Although simple, this process -is quite invasive and tightly couples your code to the Spring Framework's transaction -infrastructure. The following example shows how to programmatically indicate a required -rollback: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public void resolvePosition() { - try { - // some business logic... - } catch (NoProductInStockException ex) { - // trigger rollback programmatically - TransactionAspectSupport.currentTransactionStatus().setRollbackOnly(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun resolvePosition() { - try { - // some business logic... - } catch (ex: NoProductInStockException) { - // trigger rollback programmatically - TransactionAspectSupport.currentTransactionStatus().setRollbackOnly(); - } - } ----- - -You are strongly encouraged to use the declarative approach to rollback, if at all -possible. Programmatic rollback is available should you absolutely need it, but its -usage flies in the face of achieving a clean POJO-based architecture. - - -[[transaction-declarative-diff-tx]] -==== Configuring Different Transactional Semantics for Different Beans - -Consider the scenario where you have a number of service layer objects, and you want to -apply a totally different transactional configuration to each of them. You can do so -by defining distinct `` elements with differing `pointcut` and -`advice-ref` attribute values. - -As a point of comparison, first assume that all of your service layer classes are -defined in a root `x.y.service` package. To make all beans that are instances of classes -defined in that package (or in subpackages) and that have names ending in `Service` have -the default transactional configuration, you could write the following: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----- - -The following example shows how to configure two distinct beans with totally different -transactional settings: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----- - - -[[transaction-declarative-txadvice-settings]] -==== Settings - -This section summarizes the various transactional settings that you can specify by using -the `` tag. The default `` settings are: - -* The <> is `REQUIRED.` -* The isolation level is `DEFAULT.` -* The transaction is read-write. -* The transaction timeout defaults to the default timeout of the underlying transaction - system or none if timeouts are not supported. -* Any `RuntimeException` triggers rollback, and any checked `Exception` does not. - -You can change these default settings. The following table summarizes the various attributes of the `` tags -that are nested within `` and `` tags: - -[[tx-method-settings]] -. settings -|=== -| Attribute| Required?| Default| Description - -| `name` -| Yes -| -| Method names with which the transaction attributes are to be associated. The - wildcard ({asterisk}) character can be used to associate the same transaction attribute - settings with a number of methods (for example, `get*`, `handle*`, `on*Event`, and so - forth). - -| `propagation` -| No -| `REQUIRED` -| Transaction propagation behavior. - -| `isolation` -| No -| `DEFAULT` -| Transaction isolation level. Only applicable to propagation settings of `REQUIRED` or `REQUIRES_NEW`. - -| `timeout` -| No -| -1 -| Transaction timeout (seconds). Only applicable to propagation `REQUIRED` or `REQUIRES_NEW`. - -| `read-only` -| No -| false -| Read-write versus read-only transaction. Applies only to `REQUIRED` or `REQUIRES_NEW`. - -| `rollback-for` -| No -| -| Comma-delimited list of `Exception` instances that trigger rollback. For example, - `com.foo.MyBusinessException,ServletException`. - -| `no-rollback-for` -| No -| -| Comma-delimited list of `Exception` instances that do not trigger rollback. For example, - `com.foo.MyBusinessException,ServletException`. -|=== - - -[[transaction-declarative-annotations]] -==== Using `@Transactional` - -In addition to the XML-based declarative approach to transaction configuration, you can -use an annotation-based approach. Declaring transaction semantics directly in the Java -source code puts the declarations much closer to the affected code. There is not much -danger of undue coupling, because code that is meant to be used transactionally is -almost always deployed that way anyway. - -NOTE: The standard `jakarta.transaction.Transactional` annotation is also supported as -a drop-in replacement to Spring's own annotation. Please refer to the JTA documentation -for more details. - -The ease-of-use afforded by the use of the `@Transactional` annotation is best -illustrated with an example, which is explained in the text that follows. -Consider the following class definition: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // the service class that we want to make transactional - @Transactional - public class DefaultFooService implements FooService { - - @Override - public Foo getFoo(String fooName) { - // ... - } - - @Override - public Foo getFoo(String fooName, String barName) { - // ... - } - - @Override - public void insertFoo(Foo foo) { - // ... - } - - @Override - public void updateFoo(Foo foo) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // the service class that we want to make transactional - @Transactional - class DefaultFooService : FooService { - - override fun getFoo(fooName: String): Foo { - // ... - } - - override fun getFoo(fooName: String, barName: String): Foo { - // ... - } - - override fun insertFoo(foo: Foo) { - // ... - } - - override fun updateFoo(foo: Foo) { - // ... - } - } ----- - -Used at the class level as above, the annotation indicates a default for all methods of -the declaring class (as well as its subclasses). Alternatively, each method can be -annotated individually. See <> for -further details on which methods Spring considers transactional. Note that a class-level -annotation does not apply to ancestor classes up the class hierarchy; in such a scenario, -inherited methods need to be locally redeclared in order to participate in a -subclass-level annotation. - -When a POJO class such as the one above is defined as a bean in a Spring context, -you can make the bean instance transactional through an `@EnableTransactionManagement` -annotation in a `@Configuration` class. See the -{api-spring-framework}/transaction/annotation/EnableTransactionManagement.html[javadoc] -for full details. - -In XML configuration, the `` tag provides similar convenience: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - <1> - - - - - - - - - ----- -<1> The line that makes the bean instance transactional. - - -TIP: You can omit the `transaction-manager` attribute in the `` -tag if the bean name of the `TransactionManager` that you want to wire in has the name -`transactionManager`. If the `TransactionManager` bean that you want to dependency-inject -has any other name, you have to use the `transaction-manager` attribute, as in the -preceding example. - -Reactive transactional methods use reactive return types in contrast to imperative -programming arrangements as the following listing shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // the reactive service class that we want to make transactional - @Transactional - public class DefaultFooService implements FooService { - - @Override - public Publisher getFoo(String fooName) { - // ... - } - - @Override - public Mono getFoo(String fooName, String barName) { - // ... - } - - @Override - public Mono insertFoo(Foo foo) { - // ... - } - - @Override - public Mono updateFoo(Foo foo) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // the reactive service class that we want to make transactional - @Transactional - class DefaultFooService : FooService { - - override fun getFoo(fooName: String): Flow { - // ... - } - - override fun getFoo(fooName: String, barName: String): Mono { - // ... - } - - override fun insertFoo(foo: Foo): Mono { - // ... - } - - override fun updateFoo(foo: Foo): Mono { - // ... - } - } ----- - -Note that there are special considerations for the returned `Publisher` with regards to -Reactive Streams cancellation signals. See the <> section under -"Using the TransactionalOperator" for more details. - - -[[transaction-declarative-annotations-method-visibility]] -.Method visibility and `@Transactional` -[NOTE] -==== -When you use transactional proxies with Spring's standard configuration, you should apply -the `@Transactional` annotation only to methods with `public` visibility. If you do -annotate `protected`, `private`, or package-visible methods with the `@Transactional` -annotation, no error is raised, but the annotated method does not exhibit the configured -transactional settings. If you need to annotate non-public methods, consider the tip in -the following paragraph for class-based proxies or consider using AspectJ compile-time or -load-time weaving (described later). - -When using `@EnableTransactionManagement` in a `@Configuration` class, `protected` or -package-visible methods can also be made transactional for class-based proxies by -registering a custom `transactionAttributeSource` bean like in the following example. -Note, however, that transactional methods in interface-based proxies must always be -`public` and defined in the proxied interface. - -[source,java,indent=0,subs="verbatim,quotes"] ----- - /** - * Register a custom AnnotationTransactionAttributeSource with the - * publicMethodsOnly flag set to false to enable support for - * protected and package-private @Transactional methods in - * class-based proxies. - * - * @see ProxyTransactionManagementConfiguration#transactionAttributeSource() - */ - @Bean - TransactionAttributeSource transactionAttributeSource() { - return new AnnotationTransactionAttributeSource(false); - } ----- - -The _Spring TestContext Framework_ supports non-private `@Transactional` test methods by -default. See <> in the testing -chapter for examples. -==== - -You can apply the `@Transactional` annotation to an interface definition, a method -on an interface, a class definition, or a method on a class. However, the -mere presence of the `@Transactional` annotation is not enough to activate the -transactional behavior. The `@Transactional` annotation is merely metadata that can -be consumed by some runtime infrastructure that is `@Transactional`-aware and that -can use the metadata to configure the appropriate beans with transactional behavior. -In the preceding example, the `` element switches on the -transactional behavior. - -TIP: The Spring team recommends that you annotate only concrete classes (and methods of -concrete classes) with the `@Transactional` annotation, as opposed to annotating interfaces. -You certainly can place the `@Transactional` annotation on an interface (or an interface -method), but this works only as you would expect it to if you use interface-based -proxies. The fact that Java annotations are not inherited from interfaces means that, -if you use class-based proxies (`proxy-target-class="true"`) or the weaving-based -aspect (`mode="aspectj"`), the transaction settings are not recognized by the proxying -and weaving infrastructure, and the object is not wrapped in a transactional proxy. - -NOTE: In proxy mode (which is the default), only external method calls coming in through -the proxy are intercepted. This means that self-invocation (in effect, a method within -the target object calling another method of the target object) does not lead to an actual -transaction at runtime even if the invoked method is marked with `@Transactional`. Also, -the proxy must be fully initialized to provide the expected behavior, so you should not -rely on this feature in your initialization code -- for example, in a `@PostConstruct` -method. - -Consider using AspectJ mode (see the `mode` attribute in the following table) if you -expect self-invocations to be wrapped with transactions as well. In this case, there is -no proxy in the first place. Instead, the target class is woven (that is, its byte code -is modified) to support `@Transactional` runtime behavior on any kind of method. - -[[tx-annotation-driven-settings]] -.Annotation driven transaction settings -|=== -| XML Attribute| Annotation Attribute| Default| Description - -| `transaction-manager` -| N/A (see {api-spring-framework}/transaction/annotation/TransactionManagementConfigurer.html[`TransactionManagementConfigurer`] javadoc) -| `transactionManager` -| Name of the transaction manager to use. Required only if the name of the transaction - manager is not `transactionManager`, as in the preceding example. - -| `mode` -| `mode` -| `proxy` -| The default mode (`proxy`) processes annotated beans to be proxied by using Spring's AOP - framework (following proxy semantics, as discussed earlier, applying to method calls - coming in through the proxy only). The alternative mode (`aspectj`) instead weaves the - affected classes with Spring's AspectJ transaction aspect, modifying the target class - byte code to apply to any kind of method call. AspectJ weaving requires - `spring-aspects.jar` in the classpath as well as having load-time weaving (or compile-time - weaving) enabled. (See <> - for details on how to set up load-time weaving.) - -| `proxy-target-class` -| `proxyTargetClass` -| `false` -| Applies to `proxy` mode only. Controls what type of transactional proxies are created - for classes annotated with the `@Transactional` annotation. If the - `proxy-target-class` attribute is set to `true`, class-based proxies are created. - If `proxy-target-class` is `false` or if the attribute is omitted, then standard JDK - interface-based proxies are created. (See <> - for a detailed examination of the different proxy types.) - -| `order` -| `order` -| `Ordered.LOWEST_PRECEDENCE` -| Defines the order of the transaction advice that is applied to beans annotated with - `@Transactional`. (For more information about the rules related to ordering of AOP - advice, see <>.) - No specified ordering means that the AOP subsystem determines the order of the advice. -|=== - -NOTE: The default advice mode for processing `@Transactional` annotations is `proxy`, -which allows for interception of calls through the proxy only. Local calls within the -same class cannot get intercepted that way. For a more advanced mode of interception, -consider switching to `aspectj` mode in combination with compile-time or load-time weaving. - -NOTE: The `proxy-target-class` attribute controls what type of transactional proxies are -created for classes annotated with the `@Transactional` annotation. If -`proxy-target-class` is set to `true`, class-based proxies are created. If -`proxy-target-class` is `false` or if the attribute is omitted, standard JDK -interface-based proxies are created. (See <> -for a discussion of the different proxy types.) - -NOTE: `@EnableTransactionManagement` and `` look for -`@Transactional` only on beans in the same application context in which they are defined. -This means that, if you put annotation-driven configuration in a `WebApplicationContext` -for a `DispatcherServlet`, it checks for `@Transactional` beans only in your controllers -and not in your services. See <> for more information. - -The most derived location takes precedence when evaluating the transactional settings -for a method. In the case of the following example, the `DefaultFooService` class is -annotated at the class level with the settings for a read-only transaction, but the -`@Transactional` annotation on the `updateFoo(Foo)` method in the same class takes -precedence over the transactional settings defined at the class level. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Transactional(readOnly = true) - public class DefaultFooService implements FooService { - - public Foo getFoo(String fooName) { - // ... - } - - // these settings have precedence for this method - @Transactional(readOnly = false, propagation = Propagation.REQUIRES_NEW) - public void updateFoo(Foo foo) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Transactional(readOnly = true) - class DefaultFooService : FooService { - - override fun getFoo(fooName: String): Foo { - // ... - } - - // these settings have precedence for this method - @Transactional(readOnly = false, propagation = Propagation.REQUIRES_NEW) - override fun updateFoo(foo: Foo) { - // ... - } - } ----- - - -[[transaction-declarative-attransactional-settings]] -===== `@Transactional` Settings - -The `@Transactional` annotation is metadata that specifies that an interface, class, -or method must have transactional semantics (for example, "start a brand new read-only -transaction when this method is invoked, suspending any existing transaction"). -The default `@Transactional` settings are as follows: - -* The propagation setting is `PROPAGATION_REQUIRED.` -* The isolation level is `ISOLATION_DEFAULT.` -* The transaction is read-write. -* The transaction timeout defaults to the default timeout of the underlying transaction - system, or to none if timeouts are not supported. -* Any `RuntimeException` or `Error` triggers rollback, and any checked `Exception` does - not. - -You can change these default settings. The following table summarizes the various -properties of the `@Transactional` annotation: - -[[tx-attransactional-properties]] -.@Transactional Settings -|=== -| Property| Type| Description - -| <> -| `String` -| Optional qualifier that specifies the transaction manager to be used. - -| `transactionManager` -| `String` -| Alias for `value`. - -| `label` -| Array of `String` labels to add an expressive description to the transaction. -| Labels may be evaluated by transaction managers to associate implementation-specific behavior with the actual transaction. - -| <> -| `enum`: `Propagation` -| Optional propagation setting. - -| `isolation` -| `enum`: `Isolation` -| Optional isolation level. Applies only to propagation values of `REQUIRED` or `REQUIRES_NEW`. - -| `timeout` -| `int` (in seconds of granularity) -| Optional transaction timeout. Applies only to propagation values of `REQUIRED` or `REQUIRES_NEW`. - -| `timeoutString` -| `String` (in seconds of granularity) -| Alternative for specifying the `timeout` in seconds as a `String` value -- for example, as a placeholder. - -| `readOnly` -| `boolean` -| Read-write versus read-only transaction. Only applicable to values of `REQUIRED` or `REQUIRES_NEW`. - -| `rollbackFor` -| Array of `Class` objects, which must be derived from `Throwable.` -| Optional array of exception types that must cause rollback. - -| `rollbackForClassName` -| Array of exception name patterns. -| Optional array of exception name patterns that must cause rollback. - -| `noRollbackFor` -| Array of `Class` objects, which must be derived from `Throwable.` -| Optional array of exception types that must not cause rollback. - -| `noRollbackForClassName` -| Array of exception name patterns. -| Optional array of exception name patterns that must not cause rollback. -|=== - -TIP: See <> for further details -on rollback rule semantics, patterns, and warnings regarding possible unintentional -matches for pattern-based rollback rules. - -Currently, you cannot have explicit control over the name of a transaction, where 'name' -means the transaction name that appears in a transaction monitor, if applicable -(for example, WebLogic's transaction monitor), and in logging output. For declarative -transactions, the transaction name is always the fully-qualified class name + `.` -+ the method name of the transactionally advised class. For example, if the -`handlePayment(..)` method of the `BusinessService` class started a transaction, the -name of the transaction would be: `com.example.BusinessService.handlePayment`. - -[[tx-multiple-tx-mgrs-with-attransactional]] -===== Multiple Transaction Managers with `@Transactional` - -Most Spring applications need only a single transaction manager, but there may be -situations where you want multiple independent transaction managers in a single -application. You can use the `value` or `transactionManager` attribute of the -`@Transactional` annotation to optionally specify the identity of the -`TransactionManager` to be used. This can either be the bean name or the qualifier value -of the transaction manager bean. For example, using the qualifier notation, you can -combine the following Java code with the following transaction manager bean declarations -in the application context: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class TransactionalService { - - @Transactional("order") - public void setSomething(String name) { ... } - - @Transactional("account") - public void doSomething() { ... } - - @Transactional("reactive-account") - public Mono doSomethingReactive() { ... } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - class TransactionalService { - - @Transactional("order") - fun setSomething(name: String) { - // ... - } - - @Transactional("account") - fun doSomething() { - // ... - } - - @Transactional("reactive-account") - fun doSomethingReactive(): Mono { - // ... - } - } ----- - -The following listing shows the bean declarations: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ... - - - - - ... - - - - - ... - - ----- - -In this case, the individual methods on `TransactionalService` run under separate -transaction managers, differentiated by the `order`, `account`, and `reactive-account` -qualifiers. The default `` target bean name, `transactionManager`, -is still used if no specifically qualified `TransactionManager` bean is found. - -[[tx-custom-attributes]] -===== Custom Composed Annotations - -If you find you repeatedly use the same attributes with `@Transactional` on many different -methods, <> lets you -define custom composed annotations for your specific use cases. For example, consider the -following annotation definitions: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target({ElementType.METHOD, ElementType.TYPE}) - @Retention(RetentionPolicy.RUNTIME) - @Transactional(transactionManager = "order", label = "causal-consistency") - public @interface OrderTx { - } - - @Target({ElementType.METHOD, ElementType.TYPE}) - @Retention(RetentionPolicy.RUNTIME) - @Transactional(transactionManager = "account", label = "retryable") - public @interface AccountTx { - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.FUNCTION, AnnotationTarget.TYPE) - @Retention(AnnotationRetention.RUNTIME) - @Transactional(transactionManager = "order", label = ["causal-consistency"]) - annotation class OrderTx - - @Target(AnnotationTarget.FUNCTION, AnnotationTarget.TYPE) - @Retention(AnnotationRetention.RUNTIME) - @Transactional(transactionManager = "account", label = ["retryable"]) - annotation class AccountTx ----- - -The preceding annotations let us write the example from the previous section as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class TransactionalService { - - @OrderTx - public void setSomething(String name) { - // ... - } - - @AccountTx - public void doSomething() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - class TransactionalService { - - @OrderTx - fun setSomething(name: String) { - // ... - } - - @AccountTx - fun doSomething() { - // ... - } - } ----- - -In the preceding example, we used the syntax to define the transaction manager qualifier -and transactional labels, but we could also have included propagation behavior, -rollback rules, timeouts, and other features. - - -[[tx-propagation]] -==== Transaction Propagation - -This section describes some semantics of transaction propagation in Spring. Note -that this section is not a proper introduction to transaction propagation. Rather, it -details some of the semantics regarding transaction propagation in Spring. - -In Spring-managed transactions, be aware of the difference between physical and -logical transactions, and how the propagation setting applies to this difference. - -[[tx-propagation-required]] -===== Understanding `PROPAGATION_REQUIRED` - -image::tx_prop_required.png[] - -`PROPAGATION_REQUIRED` enforces a physical transaction, either locally for the current -scope if no transaction exists yet or participating in an existing 'outer' transaction -defined for a larger scope. This is a fine default in common call stack arrangements -within the same thread (for example, a service facade that delegates to several repository methods -where all the underlying resources have to participate in the service-level transaction). - -NOTE: By default, a participating transaction joins the characteristics of the outer scope, -silently ignoring the local isolation level, timeout value, or read-only flag (if any). -Consider switching the `validateExistingTransactions` flag to `true` on your transaction -manager if you want isolation level declarations to be rejected when participating in -an existing transaction with a different isolation level. This non-lenient mode also -rejects read-only mismatches (that is, an inner read-write transaction that tries to participate -in a read-only outer scope). - -When the propagation setting is `PROPAGATION_REQUIRED`, a logical transaction scope -is created for each method upon which the setting is applied. Each such logical -transaction scope can determine rollback-only status individually, with an outer -transaction scope being logically independent from the inner transaction scope. -In the case of standard `PROPAGATION_REQUIRED` behavior, all these scopes are -mapped to the same physical transaction. So a rollback-only marker set in the inner -transaction scope does affect the outer transaction's chance to actually commit. - -However, in the case where an inner transaction scope sets the rollback-only marker, the -outer transaction has not decided on the rollback itself, so the rollback (silently -triggered by the inner transaction scope) is unexpected. A corresponding -`UnexpectedRollbackException` is thrown at that point. This is expected behavior so -that the caller of a transaction can never be misled to assume that a commit was -performed when it really was not. So, if an inner transaction (of which the outer caller -is not aware) silently marks a transaction as rollback-only, the outer caller still -calls commit. The outer caller needs to receive an `UnexpectedRollbackException` to -indicate clearly that a rollback was performed instead. - -[[tx-propagation-requires_new]] -===== Understanding `PROPAGATION_REQUIRES_NEW` - -image::tx_prop_requires_new.png[] - -`PROPAGATION_REQUIRES_NEW`, in contrast to `PROPAGATION_REQUIRED`, always uses an -independent physical transaction for each affected transaction scope, never -participating in an existing transaction for an outer scope. In such an arrangement, -the underlying resource transactions are different and, hence, can commit or roll back -independently, with an outer transaction not affected by an inner transaction's rollback -status and with an inner transaction's locks released immediately after its completion. -Such an independent inner transaction can also declare its own isolation level, timeout, -and read-only settings and not inherit an outer transaction's characteristics. - -[[tx-propagation-nested]] -===== Understanding `PROPAGATION_NESTED` - -`PROPAGATION_NESTED` uses a single physical transaction with multiple savepoints -that it can roll back to. Such partial rollbacks let an inner transaction scope -trigger a rollback for its scope, with the outer transaction being able to continue -the physical transaction despite some operations having been rolled back. This setting -is typically mapped onto JDBC savepoints, so it works only with JDBC resource -transactions. See Spring's {api-spring-framework}/jdbc/datasource/DataSourceTransactionManager.html[`DataSourceTransactionManager`]. - - -[[transaction-declarative-applying-more-than-just-tx-advice]] -==== Advising Transactional Operations - -Suppose you want to run both transactional operations and some basic profiling advice. -How do you effect this in the context of ``? - -When you invoke the `updateFoo(Foo)` method, you want to see the following actions: - -* The configured profiling aspect starts. -* The transactional advice runs. -* The method on the advised object runs. -* The transaction commits. -* The profiling aspect reports the exact duration of the whole transactional method invocation. - -NOTE: This chapter is not concerned with explaining AOP in any great detail (except as it -applies to transactions). See <> for detailed coverage of the AOP -configuration and AOP in general. - -The following code shows the simple profiling aspect discussed earlier: - -[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ----- - package x.y; - - import org.aspectj.lang.ProceedingJoinPoint; - import org.springframework.util.StopWatch; - import org.springframework.core.Ordered; - - public class SimpleProfiler implements Ordered { - - private int order; - - // allows us to control the ordering of advice - public int getOrder() { - return this.order; - } - - public void setOrder(int order) { - this.order = order; - } - - // this method is the around advice - public Object profile(ProceedingJoinPoint call) throws Throwable { - Object returnValue; - StopWatch clock = new StopWatch(getClass().getName()); - try { - clock.start(call.toShortString()); - returnValue = call.proceed(); - } finally { - clock.stop(); - System.out.println(clock.prettyPrint()); - } - return returnValue; - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ----- - package x.y - - import org.aspectj.lang.ProceedingJoinPoint - import org.springframework.util.StopWatch - import org.springframework.core.Ordered - - class SimpleProfiler : Ordered { - - private var order: Int = 0 - - // allows us to control the ordering of advice - override fun getOrder(): Int { - return this.order - } - - fun setOrder(order: Int) { - this.order = order - } - - // this method is the around advice - fun profile(call: ProceedingJoinPoint): Any { - var returnValue: Any - val clock = StopWatch(javaClass.name) - try { - clock.start(call.toShortString()) - returnValue = call.proceed() - } finally { - clock.stop() - println(clock.prettyPrint()) - } - return returnValue - } - } ----- - -The ordering of advice -is controlled through the `Ordered` interface. For full details on advice ordering, see -<>. - -The following configuration creates a `fooService` bean that has profiling and -transactional aspects applied to it in the desired order: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----- - -You can configure any number -of additional aspects in similar fashion. - -The following example creates the same setup as the previous two examples but uses the purely XML -declarative approach: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ----- - -The result of the preceding configuration is a `fooService` bean that has profiling and -transactional aspects applied to it in that order. If you want the profiling advice -to run after the transactional advice on the way in and before the -transactional advice on the way out, you can swap the value of the profiling -aspect bean's `order` property so that it is higher than the transactional advice's -order value. - -You can configure additional aspects in similar fashion. - - -[[transaction-declarative-aspectj]] -==== Using `@Transactional` with AspectJ - -You can also use the Spring Framework's `@Transactional` support outside of a Spring -container by means of an AspectJ aspect. To do so, first annotate your classes -(and optionally your classes' methods) with the `@Transactional` annotation, -and then link (weave) your application with the -`org.springframework.transaction.aspectj.AnnotationTransactionAspect` defined in the -`spring-aspects.jar` file. You must also configure the aspect with a transaction -manager. You can use the Spring Framework's IoC container to take care of -dependency-injecting the aspect. The simplest way to configure the transaction -management aspect is to use the `` element and specify the `mode` -attribute to `aspectj` as described in <>. Because -we focus here on applications that run outside of a Spring container, we show -you how to do it programmatically. - -NOTE: Prior to continuing, you may want to read <> and -<> respectively. - -The following example shows how to create a transaction manager and configure the -`AnnotationTransactionAspect` to use it: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // construct an appropriate transaction manager - DataSourceTransactionManager txManager = new DataSourceTransactionManager(getDataSource()); - - // configure the AnnotationTransactionAspect to use it; this must be done before executing any transactional methods - AnnotationTransactionAspect.aspectOf().setTransactionManager(txManager); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // construct an appropriate transaction manager - val txManager = DataSourceTransactionManager(getDataSource()) - - // configure the AnnotationTransactionAspect to use it; this must be done before executing any transactional methods - AnnotationTransactionAspect.aspectOf().transactionManager = txManager ----- - -NOTE: When you use this aspect, you must annotate the implementation class (or the methods -within that class or both), not the interface (if any) that the class implements. AspectJ -follows Java's rule that annotations on interfaces are not inherited. - -The `@Transactional` annotation on a class specifies the default transaction semantics -for the execution of any public method in the class. - -The `@Transactional` annotation on a method within the class overrides the default -transaction semantics given by the class annotation (if present). You can annotate any method, -regardless of visibility. - -To weave your applications with the `AnnotationTransactionAspect`, you must either build -your application with AspectJ (see the -https://www.eclipse.org/aspectj/doc/released/devguide/index.html[AspectJ Development -Guide]) or use load-time weaving. See <> for a discussion of load-time weaving with AspectJ. - - - -[[transaction-programmatic]] -=== Programmatic Transaction Management - -The Spring Framework provides two means of programmatic transaction management, by using: - -* The `TransactionTemplate` or `TransactionalOperator`. -* A `TransactionManager` implementation directly. - -The Spring team generally recommends the `TransactionTemplate` for programmatic -transaction management in imperative flows and `TransactionalOperator` for reactive code. -The second approach is similar to using the JTA `UserTransaction` API, although exception -handling is less cumbersome. - - -[[tx-prog-template]] -==== Using the `TransactionTemplate` - -The `TransactionTemplate` adopts the same approach as other Spring templates, such as -the `JdbcTemplate`. It uses a callback approach (to free application code from having to -do the boilerplate acquisition and release transactional resources) and results in -code that is intention driven, in that your code focuses solely on what -you want to do. - -NOTE: As the examples that follow show, using the `TransactionTemplate` absolutely -couples you to Spring's transaction infrastructure and APIs. Whether or not programmatic -transaction management is suitable for your development needs is a decision that you -have to make yourself. - -Application code that must run in a transactional context and that explicitly uses the -`TransactionTemplate` resembles the next example. You, as an application -developer, can write a `TransactionCallback` implementation (typically expressed as an -anonymous inner class) that contains the code that you need to run in the context of -a transaction. You can then pass an instance of your custom `TransactionCallback` to the -`execute(..)` method exposed on the `TransactionTemplate`. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleService implements Service { - - // single TransactionTemplate shared amongst all methods in this instance - private final TransactionTemplate transactionTemplate; - - // use constructor-injection to supply the PlatformTransactionManager - public SimpleService(PlatformTransactionManager transactionManager) { - this.transactionTemplate = new TransactionTemplate(transactionManager); - } - - public Object someServiceMethod() { - return transactionTemplate.execute(new TransactionCallback() { - // the code in this method runs in a transactional context - public Object doInTransaction(TransactionStatus status) { - updateOperation1(); - return resultOfUpdateOperation2(); - } - }); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // use constructor-injection to supply the PlatformTransactionManager - class SimpleService(transactionManager: PlatformTransactionManager) : Service { - - // single TransactionTemplate shared amongst all methods in this instance - private val transactionTemplate = TransactionTemplate(transactionManager) - - fun someServiceMethod() = transactionTemplate.execute { - updateOperation1() - resultOfUpdateOperation2() - } - } ----- - - -If there is no return value, you can use the convenient `TransactionCallbackWithoutResult` class -with an anonymous class, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - transactionTemplate.execute(new TransactionCallbackWithoutResult() { - protected void doInTransactionWithoutResult(TransactionStatus status) { - updateOperation1(); - updateOperation2(); - } - }); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - transactionTemplate.execute(object : TransactionCallbackWithoutResult() { - override fun doInTransactionWithoutResult(status: TransactionStatus) { - updateOperation1() - updateOperation2() - } - }) ----- - - -Code within the callback can roll the transaction back by calling the -`setRollbackOnly()` method on the supplied `TransactionStatus` object, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - transactionTemplate.execute(new TransactionCallbackWithoutResult() { - - protected void doInTransactionWithoutResult(TransactionStatus status) { - try { - updateOperation1(); - updateOperation2(); - } catch (SomeBusinessException ex) { - status.setRollbackOnly(); - } - } - }); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - transactionTemplate.execute(object : TransactionCallbackWithoutResult() { - - override fun doInTransactionWithoutResult(status: TransactionStatus) { - try { - updateOperation1() - updateOperation2() - } catch (ex: SomeBusinessException) { - status.setRollbackOnly() - } - } - }) ----- - -[[tx-prog-template-settings]] -===== Specifying Transaction Settings - -You can specify transaction settings (such as the propagation mode, the isolation level, -the timeout, and so forth) on the `TransactionTemplate` either programmatically or in -configuration. By default, `TransactionTemplate` instances have the -<>. The -following example shows the programmatic customization of the transactional settings for -a specific `TransactionTemplate:` - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleService implements Service { - - private final TransactionTemplate transactionTemplate; - - public SimpleService(PlatformTransactionManager transactionManager) { - this.transactionTemplate = new TransactionTemplate(transactionManager); - - // the transaction settings can be set here explicitly if so desired - this.transactionTemplate.setIsolationLevel(TransactionDefinition.ISOLATION_READ_UNCOMMITTED); - this.transactionTemplate.setTimeout(30); // 30 seconds - // and so forth... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SimpleService(transactionManager: PlatformTransactionManager) : Service { - - private val transactionTemplate = TransactionTemplate(transactionManager).apply { - // the transaction settings can be set here explicitly if so desired - isolationLevel = TransactionDefinition.ISOLATION_READ_UNCOMMITTED - timeout = 30 // 30 seconds - // and so forth... - } - } ----- - -The following example defines a `TransactionTemplate` with some custom transactional -settings by using Spring XML configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - -You can then inject the `sharedTransactionTemplate` -into as many services as are required. - -Finally, instances of the `TransactionTemplate` class are thread-safe, in that instances -do not maintain any conversational state. `TransactionTemplate` instances do, however, -maintain configuration state. So, while a number of classes may share a single instance -of a `TransactionTemplate`, if a class needs to use a `TransactionTemplate` with -different settings (for example, a different isolation level), you need to create -two distinct `TransactionTemplate` instances. - -[[tx-prog-operator]] -==== Using the `TransactionalOperator` - -The `TransactionalOperator` follows an operator design that is similar to other reactive -operators. It uses a callback approach (to free application code from having to do the -boilerplate acquisition and release transactional resources) and results in code that is -intention driven, in that your code focuses solely on what you want to do. - -NOTE: As the examples that follow show, using the `TransactionalOperator` absolutely -couples you to Spring's transaction infrastructure and APIs. Whether or not programmatic -transaction management is suitable for your development needs is a decision that you have -to make yourself. - -Application code that must run in a transactional context and that explicitly uses -the `TransactionalOperator` resembles the next example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleService implements Service { - - // single TransactionalOperator shared amongst all methods in this instance - private final TransactionalOperator transactionalOperator; - - // use constructor-injection to supply the ReactiveTransactionManager - public SimpleService(ReactiveTransactionManager transactionManager) { - this.transactionalOperator = TransactionalOperator.create(transactionManager); - } - - public Mono someServiceMethod() { - - // the code in this method runs in a transactional context - - Mono update = updateOperation1(); - - return update.then(resultOfUpdateOperation2).as(transactionalOperator::transactional); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // use constructor-injection to supply the ReactiveTransactionManager - class SimpleService(transactionManager: ReactiveTransactionManager) : Service { - - // single TransactionalOperator shared amongst all methods in this instance - private val transactionalOperator = TransactionalOperator.create(transactionManager) - - suspend fun someServiceMethod() = transactionalOperator.executeAndAwait { - updateOperation1() - resultOfUpdateOperation2() - } - } ----- - -`TransactionalOperator` can be used in two ways: - -* Operator-style using Project Reactor types (`mono.as(transactionalOperator::transactional)`) -* Callback-style for every other case (`transactionalOperator.execute(TransactionCallback)`) - -Code within the callback can roll the transaction back by calling the `setRollbackOnly()` -method on the supplied `ReactiveTransaction` object, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - transactionalOperator.execute(new TransactionCallback<>() { - - public Mono doInTransaction(ReactiveTransaction status) { - return updateOperation1().then(updateOperation2) - .doOnError(SomeBusinessException.class, e -> status.setRollbackOnly()); - } - } - }); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - transactionalOperator.execute(object : TransactionCallback() { - - override fun doInTransactionWithoutResult(status: ReactiveTransaction) { - updateOperation1().then(updateOperation2) - .doOnError(SomeBusinessException.class, e -> status.setRollbackOnly()) - } - }) ----- - -[[tx-prog-operator-cancel]] -===== Cancel Signals - -In Reactive Streams, a `Subscriber` can cancel its `Subscription` and stop its -`Publisher`. Operators in Project Reactor, as well as in other libraries, such as `next()`, -`take(long)`, `timeout(Duration)`, and others can issue cancellations. There is no way to -know the reason for the cancellation, whether it is due to an error or a simply lack of -interest to consume further. Since version 5.3 cancel signals lead to a roll back. -As a result it is important to consider the operators used downstream from a transaction -`Publisher`. In particular in the case of a `Flux` or other multi-value `Publisher`, -the full output must be consumed to allow the transaction to complete. - - -[[tx-prog-operator-settings]] -===== Specifying Transaction Settings - -You can specify transaction settings (such as the propagation mode, the isolation level, -the timeout, and so forth) for the `TransactionalOperator`. By default, -`TransactionalOperator` instances have -<>. The -following example shows customization of the transactional settings for a specific -`TransactionalOperator:` - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleService implements Service { - - private final TransactionalOperator transactionalOperator; - - public SimpleService(ReactiveTransactionManager transactionManager) { - DefaultTransactionDefinition definition = new DefaultTransactionDefinition(); - - // the transaction settings can be set here explicitly if so desired - definition.setIsolationLevel(TransactionDefinition.ISOLATION_READ_UNCOMMITTED); - definition.setTimeout(30); // 30 seconds - // and so forth... - - this.transactionalOperator = TransactionalOperator.create(transactionManager, definition); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SimpleService(transactionManager: ReactiveTransactionManager) : Service { - - private val definition = DefaultTransactionDefinition().apply { - // the transaction settings can be set here explicitly if so desired - isolationLevel = TransactionDefinition.ISOLATION_READ_UNCOMMITTED - timeout = 30 // 30 seconds - // and so forth... - } - private val transactionalOperator = TransactionalOperator(transactionManager, definition) - } ----- - -[[transaction-programmatic-tm]] -==== Using the `TransactionManager` - -The following sections explain programmatic usage of imperative and reactive transaction -managers. - -[[transaction-programmatic-ptm]] -===== Using the `PlatformTransactionManager` - -For imperative transactions, you can use a -`org.springframework.transaction.PlatformTransactionManager` directly to manage your -transaction. To do so, pass the implementation of the `PlatformTransactionManager` you -use to your bean through a bean reference. Then, by using the `TransactionDefinition` and -`TransactionStatus` objects, you can initiate transactions, roll back, and commit. The -following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - DefaultTransactionDefinition def = new DefaultTransactionDefinition(); - // explicitly setting the transaction name is something that can be done only programmatically - def.setName("SomeTxName"); - def.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRED); - - TransactionStatus status = txManager.getTransaction(def); - try { - // put your business logic here - } catch (MyException ex) { - txManager.rollback(status); - throw ex; - } - txManager.commit(status); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val def = DefaultTransactionDefinition() - // explicitly setting the transaction name is something that can be done only programmatically - def.setName("SomeTxName") - def.propagationBehavior = TransactionDefinition.PROPAGATION_REQUIRED - - val status = txManager.getTransaction(def) - try { - // put your business logic here - } catch (ex: MyException) { - txManager.rollback(status) - throw ex - } - - txManager.commit(status) ----- - - -[[transaction-programmatic-rtm]] -===== Using the `ReactiveTransactionManager` - -When working with reactive transactions, you can use a -`org.springframework.transaction.ReactiveTransactionManager` directly to manage your -transaction. To do so, pass the implementation of the `ReactiveTransactionManager` you -use to your bean through a bean reference. Then, by using the `TransactionDefinition` and -`ReactiveTransaction` objects, you can initiate transactions, roll back, and commit. The -following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - DefaultTransactionDefinition def = new DefaultTransactionDefinition(); - // explicitly setting the transaction name is something that can be done only programmatically - def.setName("SomeTxName"); - def.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRED); - - Mono reactiveTx = txManager.getReactiveTransaction(def); - - reactiveTx.flatMap(status -> { - - Mono tx = ...; // put your business logic here - - return tx.then(txManager.commit(status)) - .onErrorResume(ex -> txManager.rollback(status).then(Mono.error(ex))); - }); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val def = DefaultTransactionDefinition() - // explicitly setting the transaction name is something that can be done only programmatically - def.setName("SomeTxName") - def.propagationBehavior = TransactionDefinition.PROPAGATION_REQUIRED - - val reactiveTx = txManager.getReactiveTransaction(def) - reactiveTx.flatMap { status -> - - val tx = ... // put your business logic here - - tx.then(txManager.commit(status)) - .onErrorResume { ex -> txManager.rollback(status).then(Mono.error(ex)) } - } ----- - - -[[tx-decl-vs-prog]] -=== Choosing Between Programmatic and Declarative Transaction Management - -Programmatic transaction management is usually a good idea only if you have a small -number of transactional operations. For example, if you have a web application that -requires transactions only for certain update operations, you may not want to set up -transactional proxies by using Spring or any other technology. In this case, using the -`TransactionTemplate` may be a good approach. Being able to set the transaction name -explicitly is also something that can be done only by using the programmatic approach -to transaction management. - -On the other hand, if your application has numerous transactional operations, -declarative transaction management is usually worthwhile. It keeps transaction -management out of business logic and is not difficult to configure. When using the -Spring Framework, rather than EJB CMT, the configuration cost of declarative transaction -management is greatly reduced. - - - -[[transaction-event]] -=== Transaction-bound Events - -As of Spring 4.2, the listener of an event can be bound to a phase of the transaction. -The typical example is to handle the event when the transaction has completed successfully. -Doing so lets events be used with more flexibility when the outcome of the current -transaction actually matters to the listener. - -You can register a regular event listener by using the `@EventListener` annotation. -If you need to bind it to the transaction, use `@TransactionalEventListener`. -When you do so, the listener is bound to the commit phase of the transaction by default. - -The next example shows this concept. Assume that a component publishes an order-created -event and that we want to define a listener that should only handle that event once the -transaction in which it has been published has committed successfully. The following -example sets up such an event listener: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - public class MyComponent { - - @TransactionalEventListener - public void handleOrderCreatedEvent(CreationEvent creationEvent) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - class MyComponent { - - @TransactionalEventListener - fun handleOrderCreatedEvent(creationEvent: CreationEvent) { - // ... - } - } ----- - -The `@TransactionalEventListener` annotation exposes a `phase` attribute that lets you -customize the phase of the transaction to which the listener should be bound. -The valid phases are `BEFORE_COMMIT`, `AFTER_COMMIT` (default), `AFTER_ROLLBACK`, as well as -`AFTER_COMPLETION` which aggregates the transaction completion (be it a commit or a rollback). - -If no transaction is running, the listener is not invoked at all, since we cannot honor the -required semantics. You can, however, override that behavior by setting the `fallbackExecution` -attribute of the annotation to `true`. - -[NOTE] -==== -`@TransactionalEventListener` only works with thread-bound transactions managed by -`PlatformTransactionManager`. A reactive transaction managed by `ReactiveTransactionManager` -uses the Reactor context instead of thread-local attributes, so from the perspective of -an event listener, there is no compatible active transaction that it can participate in. -==== - - - -[[transaction-application-server-integration]] -=== Application server-specific integration - -Spring's transaction abstraction is generally application server-agnostic. Additionally, -Spring's `JtaTransactionManager` class (which can optionally perform a JNDI lookup for -the JTA `UserTransaction` and `TransactionManager` objects) autodetects the location for -the latter object, which varies by application server. Having access to the JTA -`TransactionManager` allows for enhanced transaction semantics -- in particular, -supporting transaction suspension. See the -{api-spring-framework}/transaction/jta/JtaTransactionManager.html[`JtaTransactionManager`] -javadoc for details. - -Spring's `JtaTransactionManager` is the standard choice to run on Jakarta EE application -servers and is known to work on all common servers. Advanced functionality, such as -transaction suspension, works on many servers as well (including GlassFish, JBoss and -Geronimo) without any special configuration required. However, for fully supported -transaction suspension and further advanced integration, Spring includes special adapters -for WebLogic Server and WebSphere. These adapters are discussed in the following -sections. - -For standard scenarios, including WebLogic Server and WebSphere, consider using the -convenient `` configuration element. When configured, -this element automatically detects the underlying server and chooses the best -transaction manager available for the platform. This means that you need not explicitly -configure server-specific adapter classes (as discussed in the following sections). -Rather, they are chosen automatically, with the standard -`JtaTransactionManager` as the default fallback. - - -[[transaction-application-server-integration-websphere]] -==== IBM WebSphere - -On WebSphere 6.1.0.9 and above, the recommended Spring JTA transaction manager to use is -`WebSphereUowTransactionManager`. This special adapter uses IBM's `UOWManager` API, -which is available in WebSphere Application Server 6.1.0.9 and later. With this adapter, -Spring-driven transaction suspension (suspend and resume as initiated by -`PROPAGATION_REQUIRES_NEW`) is officially supported by IBM. - - -[[transaction-application-server-integration-weblogic]] -==== Oracle WebLogic Server - -On WebLogic Server 9.0 or above, you would typically use the -`WebLogicJtaTransactionManager` instead of the stock `JtaTransactionManager` class. This -special WebLogic-specific subclass of the normal `JtaTransactionManager` supports the -full power of Spring's transaction definitions in a WebLogic-managed transaction -environment, beyond standard JTA semantics. Features include transaction names, -per-transaction isolation levels, and proper resuming of transactions in all cases. - - - -[[transaction-solutions-to-common-problems]] -=== Solutions to Common Problems - -This section describes solutions to some common problems. - - -[[transaction-solutions-to-common-problems-wrong-ptm]] -==== Using the Wrong Transaction Manager for a Specific `DataSource` - -Use the correct `PlatformTransactionManager` implementation based on your choice of -transactional technologies and requirements. Used properly, the Spring Framework merely -provides a straightforward and portable abstraction. If you use global -transactions, you must use the -`org.springframework.transaction.jta.JtaTransactionManager` class (or an -<> of -it) for all your transactional operations. Otherwise, the transaction infrastructure -tries to perform local transactions on such resources as container `DataSource` -instances. Such local transactions do not make sense, and a good application server -treats them as errors. - - - -[[transaction-resources]] -=== Further Resources - -For more information about the Spring Framework's transaction support, see: - -* https://www.infoworld.com/article/2077963/distributed-transactions-in-spring--with-and-without-xa.html[Distributed - transactions in Spring, with and without XA] is a JavaWorld presentation in which - Spring's David Syer guides you through seven patterns for distributed - transactions in Spring applications, three of them with XA and four without. -* https://www.infoq.com/minibooks/JTDS[_Java Transaction Design Strategies_] is a book - available from https://www.infoq.com/[InfoQ] that provides a well-paced introduction - to transactions in Java. It also includes side-by-side examples of how to configure - and use transactions with both the Spring Framework and EJB3. - - - - -[[dao]] -== DAO Support - -The Data Access Object (DAO) support in Spring is aimed at making it easy to work with -data access technologies (such as JDBC, Hibernate, or JPA) in a consistent way. This -lets you switch between the aforementioned persistence technologies fairly easily, -and it also lets you code without worrying about catching exceptions that are -specific to each technology. - - - -[[dao-exceptions]] -=== Consistent Exception Hierarchy - -Spring provides a convenient translation from technology-specific exceptions, such as -`SQLException` to its own exception class hierarchy, which has `DataAccessException` as -the root exception. These exceptions wrap the original exception so that there is never -any risk that you might lose any information about what might have gone wrong. - -In addition to JDBC exceptions, Spring can also wrap JPA- and Hibernate-specific exceptions, -converting them to a set of focused runtime exceptions. This lets you handle most -non-recoverable persistence exceptions in only the appropriate layers, without having -annoying boilerplate catch-and-throw blocks and exception declarations in your DAOs. -(You can still trap and handle exceptions anywhere you need to though.) As mentioned above, -JDBC exceptions (including database-specific dialects) are also converted to the same -hierarchy, meaning that you can perform some operations with JDBC within a consistent -programming model. - -The preceding discussion holds true for the various template classes in Spring's support -for various ORM frameworks. If you use the interceptor-based classes, the application must -care about handling `HibernateExceptions` and `PersistenceExceptions` itself, preferably by -delegating to the `convertHibernateAccessException(..)` or `convertJpaAccessException(..)` -methods, respectively, of `SessionFactoryUtils`. These methods convert the exceptions -to exceptions that are compatible with the exceptions in the `org.springframework.dao` -exception hierarchy. As `PersistenceExceptions` are unchecked, they can get thrown, too -(sacrificing generic DAO abstraction in terms of exceptions, though). - -The following image shows the exception hierarchy that Spring provides. -(Note that the class hierarchy detailed in the image shows only a subset of the entire -`DataAccessException` hierarchy.) - -image::DataAccessException.png[] - - - -[[dao-annotations]] -=== Annotations Used to Configure DAO or Repository Classes - -The best way to guarantee that your Data Access Objects (DAOs) or repositories provide -exception translation is to use the `@Repository` annotation. This annotation also -lets the component scanning support find and configure your DAOs and repositories -without having to provide XML configuration entries for them. The following example shows -how to use the `@Repository` annotation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Repository // <1> - public class SomeMovieFinder implements MovieFinder { - // ... - } ----- -<1> The `@Repository` annotation. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Repository // <1> - class SomeMovieFinder : MovieFinder { - // ... - } ----- -<1> The `@Repository` annotation. - - -Any DAO or repository implementation needs access to a persistence resource, -depending on the persistence technology used. For example, a JDBC-based repository -needs access to a JDBC `DataSource`, and a JPA-based repository needs access to an -`EntityManager`. The easiest way to accomplish this is to have this resource dependency -injected by using one of the `@Autowired`, `@Inject`, `@Resource` or `@PersistenceContext` -annotations. The following example works for a JPA repository: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Repository - public class JpaMovieFinder implements MovieFinder { - - @PersistenceContext - private EntityManager entityManager; - - // ... - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Repository - class JpaMovieFinder : MovieFinder { - - @PersistenceContext - private lateinit var entityManager: EntityManager - - // ... - } ----- - - -If you use the classic Hibernate APIs, you can inject `SessionFactory`, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Repository - public class HibernateMovieFinder implements MovieFinder { - - private SessionFactory sessionFactory; - - @Autowired - public void setSessionFactory(SessionFactory sessionFactory) { - this.sessionFactory = sessionFactory; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Repository - class HibernateMovieFinder(private val sessionFactory: SessionFactory) : MovieFinder { - // ... - } ----- - -The last example we show here is for typical JDBC support. You could have the -`DataSource` injected into an initialization method or a constructor, where you would create a -`JdbcTemplate` and other data access support classes (such as `SimpleJdbcCall` and others) by using -this `DataSource`. The following example autowires a `DataSource`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Repository - public class JdbcMovieFinder implements MovieFinder { - - private JdbcTemplate jdbcTemplate; - - @Autowired - public void init(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Repository - class JdbcMovieFinder(dataSource: DataSource) : MovieFinder { - - private val jdbcTemplate = JdbcTemplate(dataSource) - - // ... - } ----- - -NOTE: See the specific coverage of each persistence technology for details on how to -configure the application context to take advantage of these annotations. - - - - -[[jdbc]] -== Data Access with JDBC - -The value provided by the Spring Framework JDBC abstraction is perhaps best shown by -the sequence of actions outlined in the following table below. The table shows which actions Spring -takes care of and which actions are your responsibility. - -[[jdbc-who-does-what]] -.Spring JDBC - who does what? -|=== -| Action| Spring| You - -| Define connection parameters. -| -| X - -| Open the connection. -| X -| - -| Specify the SQL statement. -| -| X - -| Declare parameters and provide parameter values -| -| X - -| Prepare and run the statement. -| X -| - -| Set up the loop to iterate through the results (if any). -| X -| - -| Do the work for each iteration. -| -| X - -| Process any exception. -| X -| - -| Handle transactions. -| X -| - -| Close the connection, the statement, and the resultset. -| X -| -|=== - -The Spring Framework takes care of all the low-level details that can make JDBC such a -tedious API. - - - -[[jdbc-choose-style]] -=== Choosing an Approach for JDBC Database Access - -You can choose among several approaches to form the basis for your JDBC database access. -In addition to three flavors of `JdbcTemplate`, a new `SimpleJdbcInsert` and -`SimpleJdbcCall` approach optimizes database metadata, and the RDBMS Object style takes a -more object-oriented approach similar to that of JDO Query design. Once you start using -one of these approaches, you can still mix and match to include a feature from a -different approach. All approaches require a JDBC 2.0-compliant driver, and some -advanced features require a JDBC 3.0 driver. - -* `JdbcTemplate` is the classic and most popular Spring JDBC approach. This - "`lowest-level`" approach and all others use a JdbcTemplate under the covers. -* `NamedParameterJdbcTemplate` wraps a `JdbcTemplate` to provide named parameters - instead of the traditional JDBC `?` placeholders. This approach provides better - documentation and ease of use when you have multiple parameters for an SQL statement. -* `SimpleJdbcInsert` and `SimpleJdbcCall` optimize database metadata to limit the amount - of necessary configuration. This approach simplifies coding so that you need to - provide only the name of the table or procedure and provide a map of parameters matching - the column names. This works only if the database provides adequate metadata. If the - database does not provide this metadata, you have to provide explicit - configuration of the parameters. -* RDBMS objects — including `MappingSqlQuery`, `SqlUpdate`, and `StoredProcedure` — - require you to create reusable and thread-safe objects during initialization of your - data-access layer. This approach is modeled after JDO Query, wherein you define your - query string, declare parameters, and compile the query. Once you do that, - `execute(...)`, `update(...)`, and `findObject(...)` methods can be called multiple - times with various parameter values. - - - -[[jdbc-packages]] -=== Package Hierarchy - -The Spring Framework's JDBC abstraction framework consists of four different packages: - -* `core`: The `org.springframework.jdbc.core` package contains the `JdbcTemplate` class and its -various callback interfaces, plus a variety of related classes. A subpackage named -`org.springframework.jdbc.core.simple` contains the `SimpleJdbcInsert` and -`SimpleJdbcCall` classes. Another subpackage named -`org.springframework.jdbc.core.namedparam` contains the `NamedParameterJdbcTemplate` -class and the related support classes. See <>, <>, and -<>. - -* `datasource`: The `org.springframework.jdbc.datasource` package contains a utility class for easy -`DataSource` access and various simple `DataSource` implementations that you can use for -testing and running unmodified JDBC code outside of a Jakarta EE container. A subpackage -named `org.springfamework.jdbc.datasource.embedded` provides support for creating -embedded databases by using Java database engines, such as HSQL, H2, and Derby. See -<> and <>. - -* `object`: The `org.springframework.jdbc.object` package contains classes that represent RDBMS -queries, updates, and stored procedures as thread-safe, reusable objects. See -<>. This approach is modeled by JDO, although objects returned by queries -are naturally disconnected from the database. This higher-level of JDBC abstraction -depends on the lower-level abstraction in the `org.springframework.jdbc.core` package. - -* `support`: The `org.springframework.jdbc.support` package provides `SQLException` translation -functionality and some utility classes. Exceptions thrown during JDBC processing are -translated to exceptions defined in the `org.springframework.dao` package. This means -that code using the Spring JDBC abstraction layer does not need to implement JDBC or -RDBMS-specific error handling. All translated exceptions are unchecked, which gives you -the option of catching the exceptions from which you can recover while letting other -exceptions be propagated to the caller. See <>. - - - -[[jdbc-core]] -=== Using the JDBC Core Classes to Control Basic JDBC Processing and Error Handling - -This section covers how to use the JDBC core classes to control basic JDBC processing, -including error handling. It includes the following topics: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> - - -[[jdbc-JdbcTemplate]] -==== Using `JdbcTemplate` - -`JdbcTemplate` is the central class in the JDBC core package. It handles the -creation and release of resources, which helps you avoid common errors, such as -forgetting to close the connection. It performs the basic tasks of the core JDBC -workflow (such as statement creation and execution), leaving application code to provide -SQL and extract results. The `JdbcTemplate` class: - -* Runs SQL queries -* Updates statements and stored procedure calls -* Performs iteration over `ResultSet` instances and extraction of returned parameter values. -* Catches JDBC exceptions and translates them to the generic, more informative, exception -hierarchy defined in the `org.springframework.dao` package. (See <>.) - -When you use the `JdbcTemplate` for your code, you need only to implement callback -interfaces, giving them a clearly defined contract. Given a `Connection` provided by the -`JdbcTemplate` class, the `PreparedStatementCreator` callback interface creates a prepared -statement, providing SQL and any necessary parameters. The same is true for the -`CallableStatementCreator` interface, which creates callable statements. The -`RowCallbackHandler` interface extracts values from each row of a `ResultSet`. - -You can use `JdbcTemplate` within a DAO implementation through direct instantiation -with a `DataSource` reference, or you can configure it in a Spring IoC container and give it to -DAOs as a bean reference. - -NOTE: The `DataSource` should always be configured as a bean in the Spring IoC container. In -the first case the bean is given to the service directly; in the second case it is given -to the prepared template. - -All SQL issued by this class is logged at the `DEBUG` level under the category -corresponding to the fully qualified class name of the template instance (typically -`JdbcTemplate`, but it may be different if you use a custom subclass of the -`JdbcTemplate` class). - -The following sections provide some examples of `JdbcTemplate` usage. These examples -are not an exhaustive list of all of the functionality exposed by the `JdbcTemplate`. -See the attendant {api-spring-framework}/jdbc/core/JdbcTemplate.html[javadoc] for that. - -[[jdbc-JdbcTemplate-examples-query]] -===== Querying (`SELECT`) - -The following query gets the number of rows in a relation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - int rowCount = this.jdbcTemplate.queryForObject("select count(*) from t_actor", Integer.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val rowCount = jdbcTemplate.queryForObject("select count(*) from t_actor")!! ----- - -The following query uses a bind variable: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - int countOfActorsNamedJoe = this.jdbcTemplate.queryForObject( - "select count(*) from t_actor where first_name = ?", Integer.class, "Joe"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val countOfActorsNamedJoe = jdbcTemplate.queryForObject( - "select count(*) from t_actor where first_name = ?", arrayOf("Joe"))!! ----- - - -The following query looks for a `String`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - String lastName = this.jdbcTemplate.queryForObject( - "select last_name from t_actor where id = ?", - String.class, 1212L); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val lastName = this.jdbcTemplate.queryForObject( - "select last_name from t_actor where id = ?", - arrayOf(1212L))!! ----- - -The following query finds and populates a single domain object: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Actor actor = jdbcTemplate.queryForObject( - "select first_name, last_name from t_actor where id = ?", - (resultSet, rowNum) -> { - Actor newActor = new Actor(); - newActor.setFirstName(resultSet.getString("first_name")); - newActor.setLastName(resultSet.getString("last_name")); - return newActor; - }, - 1212L); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val actor = jdbcTemplate.queryForObject( - "select first_name, last_name from t_actor where id = ?", - arrayOf(1212L)) { rs, _ -> - Actor(rs.getString("first_name"), rs.getString("last_name")) - } ----- - -The following query finds and populates a list of domain objects: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - List actors = this.jdbcTemplate.query( - "select first_name, last_name from t_actor", - (resultSet, rowNum) -> { - Actor actor = new Actor(); - actor.setFirstName(resultSet.getString("first_name")); - actor.setLastName(resultSet.getString("last_name")); - return actor; - }); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val actors = jdbcTemplate.query("select first_name, last_name from t_actor") { rs, _ -> - Actor(rs.getString("first_name"), rs.getString("last_name")) ----- - -If the last two snippets of code actually existed in the same application, it would make -sense to remove the duplication present in the two `RowMapper` lambda expressions and -extract them out into a single field that could then be referenced by DAO methods as needed. -For example, it may be better to write the preceding code snippet as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - private final RowMapper actorRowMapper = (resultSet, rowNum) -> { - Actor actor = new Actor(); - actor.setFirstName(resultSet.getString("first_name")); - actor.setLastName(resultSet.getString("last_name")); - return actor; - }; - - public List findAllActors() { - return this.jdbcTemplate.query("select first_name, last_name from t_actor", actorRowMapper); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val actorMapper = RowMapper { rs: ResultSet, rowNum: Int -> - Actor(rs.getString("first_name"), rs.getString("last_name")) - } - - fun findAllActors(): List { - return jdbcTemplate.query("select first_name, last_name from t_actor", actorMapper) - } ----- - -[[jdbc-JdbcTemplate-examples-update]] -===== Updating (`INSERT`, `UPDATE`, and `DELETE`) with `JdbcTemplate` - -You can use the `update(..)` method to perform insert, update, and delete operations. -Parameter values are usually provided as variable arguments or, alternatively, as an object array. - -The following example inserts a new entry: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - this.jdbcTemplate.update( - "insert into t_actor (first_name, last_name) values (?, ?)", - "Leonor", "Watling"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - jdbcTemplate.update( - "insert into t_actor (first_name, last_name) values (?, ?)", - "Leonor", "Watling") ----- - -The following example updates an existing entry: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - this.jdbcTemplate.update( - "update t_actor set last_name = ? where id = ?", - "Banjo", 5276L); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - jdbcTemplate.update( - "update t_actor set last_name = ? where id = ?", - "Banjo", 5276L) ----- - -The following example deletes an entry: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - this.jdbcTemplate.update( - "delete from t_actor where id = ?", - Long.valueOf(actorId)); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - jdbcTemplate.update("delete from t_actor where id = ?", actorId.toLong()) ----- - -[[jdbc-JdbcTemplate-examples-other]] -===== Other `JdbcTemplate` Operations - -You can use the `execute(..)` method to run any arbitrary SQL. Consequently, the -method is often used for DDL statements. It is heavily overloaded with variants that take -callback interfaces, binding variable arrays, and so on. The following example creates a -table: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - this.jdbcTemplate.execute("create table mytable (id integer, name varchar(100))"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - jdbcTemplate.execute("create table mytable (id integer, name varchar(100))") ----- - -The following example invokes a stored procedure: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - this.jdbcTemplate.update( - "call SUPPORT.REFRESH_ACTORS_SUMMARY(?)", - Long.valueOf(unionId)); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - jdbcTemplate.update( - "call SUPPORT.REFRESH_ACTORS_SUMMARY(?)", - unionId.toLong()) ----- - - -More sophisticated stored procedure support is <>. - -[[jdbc-JdbcTemplate-idioms]] -===== `JdbcTemplate` Best Practices - -Instances of the `JdbcTemplate` class are thread-safe, once configured. This is -important because it means that you can configure a single instance of a `JdbcTemplate` -and then safely inject this shared reference into multiple DAOs (or repositories). -The `JdbcTemplate` is stateful, in that it maintains a reference to a `DataSource`, but -this state is not conversational state. - -A common practice when using the `JdbcTemplate` class (and the associated -<> class) is to -configure a `DataSource` in your Spring configuration file and then dependency-inject -that shared `DataSource` bean into your DAO classes. The `JdbcTemplate` is created in -the setter for the `DataSource`. This leads to DAOs that resemble the following: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcCorporateEventDao implements CorporateEventDao { - - private JdbcTemplate jdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - // JDBC-backed implementations of the methods on the CorporateEventDao follow... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcCorporateEventDao(dataSource: DataSource) : CorporateEventDao { - - private val jdbcTemplate = JdbcTemplate(dataSource) - - // JDBC-backed implementations of the methods on the CorporateEventDao follow... - } ----- --- - -The following example shows the corresponding XML configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - ----- - -An alternative to explicit configuration is to use component-scanning and annotation -support for dependency injection. In this case, you can annotate the class with `@Repository` -(which makes it a candidate for component-scanning) and annotate the `DataSource` setter -method with `@Autowired`. The following example shows how to do so: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Repository // <1> - public class JdbcCorporateEventDao implements CorporateEventDao { - - private JdbcTemplate jdbcTemplate; - - @Autowired // <2> - public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); // <3> - } - - // JDBC-backed implementations of the methods on the CorporateEventDao follow... - } ----- -<1> Annotate the class with `@Repository`. -<2> Annotate the `DataSource` setter method with `@Autowired`. -<3> Create a new `JdbcTemplate` with the `DataSource`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Repository // <1> - class JdbcCorporateEventDao(dataSource: DataSource) : CorporateEventDao { // <2> - - private val jdbcTemplate = JdbcTemplate(dataSource) // <3> - - // JDBC-backed implementations of the methods on the CorporateEventDao follow... - } ----- -<1> Annotate the class with `@Repository`. -<2> Constructor injection of the `DataSource`. -<3> Create a new `JdbcTemplate` with the `DataSource`. --- - - -The following example shows the corresponding XML configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - ----- - -If you use Spring's `JdbcDaoSupport` class and your various JDBC-backed DAO classes -extend from it, your sub-class inherits a `setDataSource(..)` method from the -`JdbcDaoSupport` class. You can choose whether to inherit from this class. The -`JdbcDaoSupport` class is provided as a convenience only. - -Regardless of which of the above template initialization styles you choose to use (or -not), it is seldom necessary to create a new instance of a `JdbcTemplate` class each -time you want to run SQL. Once configured, a `JdbcTemplate` instance is thread-safe. -If your application accesses multiple -databases, you may want multiple `JdbcTemplate` instances, which requires multiple `DataSources` and, subsequently, multiple differently -configured `JdbcTemplate` instances. - - -[[jdbc-NamedParameterJdbcTemplate]] -==== Using `NamedParameterJdbcTemplate` - -The `NamedParameterJdbcTemplate` class adds support for programming JDBC statements -by using named parameters, as opposed to programming JDBC statements using only classic -placeholder ( `'?'`) arguments. The `NamedParameterJdbcTemplate` class wraps a -`JdbcTemplate` and delegates to the wrapped `JdbcTemplate` to do much of its work. This -section describes only those areas of the `NamedParameterJdbcTemplate` class that differ -from the `JdbcTemplate` itself -- namely, programming JDBC statements by using named -parameters. The following example shows how to use `NamedParameterJdbcTemplate`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // some JDBC-backed DAO class... - private NamedParameterJdbcTemplate namedParameterJdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.namedParameterJdbcTemplate = new NamedParameterJdbcTemplate(dataSource); - } - - public int countOfActorsByFirstName(String firstName) { - - String sql = "select count(*) from T_ACTOR where first_name = :first_name"; - - SqlParameterSource namedParameters = new MapSqlParameterSource("first_name", firstName); - - return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) - - fun countOfActorsByFirstName(firstName: String): Int { - val sql = "select count(*) from T_ACTOR where first_name = :first_name" - val namedParameters = MapSqlParameterSource("first_name", firstName) - return namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Int::class.java)!! - } ----- - -Notice the use of the named parameter notation in the value assigned to the `sql` -variable and the corresponding value that is plugged into the `namedParameters` -variable (of type `MapSqlParameterSource`). - -Alternatively, you can pass along named parameters and their corresponding values to a -`NamedParameterJdbcTemplate` instance by using the `Map`-based style. The remaining -methods exposed by the `NamedParameterJdbcOperations` and implemented by the -`NamedParameterJdbcTemplate` class follow a similar pattern and are not covered here. - -The following example shows the use of the `Map`-based style: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // some JDBC-backed DAO class... - private NamedParameterJdbcTemplate namedParameterJdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.namedParameterJdbcTemplate = new NamedParameterJdbcTemplate(dataSource); - } - - public int countOfActorsByFirstName(String firstName) { - - String sql = "select count(*) from T_ACTOR where first_name = :first_name"; - - Map namedParameters = Collections.singletonMap("first_name", firstName); - - return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // some JDBC-backed DAO class... - private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) - - fun countOfActorsByFirstName(firstName: String): Int { - val sql = "select count(*) from T_ACTOR where first_name = :first_name" - val namedParameters = mapOf("first_name" to firstName) - return namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Int::class.java)!! - } ----- - -One nice feature related to the `NamedParameterJdbcTemplate` (and existing in the same -Java package) is the `SqlParameterSource` interface. You have already seen an example of -an implementation of this interface in one of the previous code snippets (the -`MapSqlParameterSource` class). An `SqlParameterSource` is a source of named parameter -values to a `NamedParameterJdbcTemplate`. The `MapSqlParameterSource` class is a -simple implementation that is an adapter around a `java.util.Map`, where the keys -are the parameter names and the values are the parameter values. - -Another `SqlParameterSource` implementation is the `BeanPropertySqlParameterSource` -class. This class wraps an arbitrary JavaBean (that is, an instance of a class that -adheres to https://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html[the -JavaBean conventions]) and uses the properties of the wrapped JavaBean as the source -of named parameter values. - -The following example shows a typical JavaBean: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class Actor { - - private Long id; - private String firstName; - private String lastName; - - public String getFirstName() { - return this.firstName; - } - - public String getLastName() { - return this.lastName; - } - - public Long getId() { - return this.id; - } - - // setters omitted... - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - data class Actor(val id: Long, val firstName: String, val lastName: String) ----- - -The following example uses a `NamedParameterJdbcTemplate` to return the count of the -members of the class shown in the preceding example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // some JDBC-backed DAO class... - private NamedParameterJdbcTemplate namedParameterJdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.namedParameterJdbcTemplate = new NamedParameterJdbcTemplate(dataSource); - } - - public int countOfActors(Actor exampleActor) { - - // notice how the named parameters match the properties of the above 'Actor' class - String sql = "select count(*) from T_ACTOR where first_name = :firstName and last_name = :lastName"; - - SqlParameterSource namedParameters = new BeanPropertySqlParameterSource(exampleActor); - - return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // some JDBC-backed DAO class... - private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) - - private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) - - fun countOfActors(exampleActor: Actor): Int { - // notice how the named parameters match the properties of the above 'Actor' class - val sql = "select count(*) from T_ACTOR where first_name = :firstName and last_name = :lastName" - val namedParameters = BeanPropertySqlParameterSource(exampleActor) - return namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Int::class.java)!! - } ----- - -Remember that the `NamedParameterJdbcTemplate` class wraps a classic `JdbcTemplate` -template. If you need access to the wrapped `JdbcTemplate` instance to access -functionality that is present only in the `JdbcTemplate` class, you can use the -`getJdbcOperations()` method to access the wrapped `JdbcTemplate` through the -`JdbcOperations` interface. - -See also <> for guidelines on using the -`NamedParameterJdbcTemplate` class in the context of an application. - - -[[jdbc-SQLExceptionTranslator]] -==== Using `SQLExceptionTranslator` - -`SQLExceptionTranslator` is an interface to be implemented by classes that can translate -between ``SQLException``s and Spring's own `org.springframework.dao.DataAccessException`, -which is agnostic in regard to data access strategy. Implementations can be generic (for -example, using SQLState codes for JDBC) or proprietary (for example, using Oracle error -codes) for greater precision. - -`SQLErrorCodeSQLExceptionTranslator` is the implementation of `SQLExceptionTranslator` -that is used by default. This implementation uses specific vendor codes. It is more -precise than the `SQLState` implementation. The error code translations are based on -codes held in a JavaBean type class called `SQLErrorCodes`. This class is created and -populated by an `SQLErrorCodesFactory`, which (as the name suggests) is a factory for -creating `SQLErrorCodes` based on the contents of a configuration file named -`sql-error-codes.xml`. This file is populated with vendor codes and based on the -`DatabaseProductName` taken from `DatabaseMetaData`. The codes for the actual -database you are using are used. - -The `SQLErrorCodeSQLExceptionTranslator` applies matching rules in the following sequence: - -. Any custom translation implemented by a subclass. Normally, the provided concrete - `SQLErrorCodeSQLExceptionTranslator` is used, so this rule does not apply. It - applies only if you have actually provided a subclass implementation. -. Any custom implementation of the `SQLExceptionTranslator` interface that is provided - as the `customSqlExceptionTranslator` property of the `SQLErrorCodes` class. -. The list of instances of the `CustomSQLErrorCodesTranslation` class (provided for the - `customTranslations` property of the `SQLErrorCodes` class) are searched for a match. -. Error code matching is applied. -. Use the fallback translator. `SQLExceptionSubclassTranslator` is the default fallback - translator. If this translation is not available, the next fallback translator is - the `SQLStateSQLExceptionTranslator`. - -NOTE: The `SQLErrorCodesFactory` is used by default to define `Error` codes and custom exception -translations. They are looked up in a file named `sql-error-codes.xml` from the -classpath, and the matching `SQLErrorCodes` instance is located based on the database -name from the database metadata of the database in use. - -You can extend `SQLErrorCodeSQLExceptionTranslator`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class CustomSQLErrorCodesTranslator extends SQLErrorCodeSQLExceptionTranslator { - - protected DataAccessException customTranslate(String task, String sql, SQLException sqlEx) { - if (sqlEx.getErrorCode() == -12345) { - return new DeadlockLoserDataAccessException(task, sqlEx); - } - return null; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class CustomSQLErrorCodesTranslator : SQLErrorCodeSQLExceptionTranslator() { - - override fun customTranslate(task: String, sql: String?, sqlEx: SQLException): DataAccessException? { - if (sqlEx.errorCode == -12345) { - return DeadlockLoserDataAccessException(task, sqlEx) - } - return null - } - } ----- - -In the preceding example, the specific error code (`-12345`) is translated, while other errors are -left to be translated by the default translator implementation. To use this custom -translator, you must pass it to the `JdbcTemplate` through the method -`setExceptionTranslator`, and you must use this `JdbcTemplate` for all of the data access -processing where this translator is needed. The following example shows how you can use this custom -translator: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - private JdbcTemplate jdbcTemplate; - - public void setDataSource(DataSource dataSource) { - - // create a JdbcTemplate and set data source - this.jdbcTemplate = new JdbcTemplate(); - this.jdbcTemplate.setDataSource(dataSource); - - // create a custom translator and set the DataSource for the default translation lookup - CustomSQLErrorCodesTranslator tr = new CustomSQLErrorCodesTranslator(); - tr.setDataSource(dataSource); - this.jdbcTemplate.setExceptionTranslator(tr); - - } - - public void updateShippingCharge(long orderId, long pct) { - // use the prepared JdbcTemplate for this update - this.jdbcTemplate.update("update orders" + - " set shipping_charge = shipping_charge * ? / 100" + - " where id = ?", pct, orderId); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // create a JdbcTemplate and set data source - private val jdbcTemplate = JdbcTemplate(dataSource).apply { - // create a custom translator and set the DataSource for the default translation lookup - exceptionTranslator = CustomSQLErrorCodesTranslator().apply { - this.dataSource = dataSource - } - } - - fun updateShippingCharge(orderId: Long, pct: Long) { - // use the prepared JdbcTemplate for this update - this.jdbcTemplate!!.update("update orders" + - " set shipping_charge = shipping_charge * ? / 100" + - " where id = ?", pct, orderId) - } ----- - -The custom translator is passed a data source in order to look up the error codes in -`sql-error-codes.xml`. - - -[[jdbc-statements-executing]] -==== Running Statements - -Running an SQL statement requires very little code. You need a `DataSource` and a -`JdbcTemplate`, including the convenience methods that are provided with the -`JdbcTemplate`. The following example shows what you need to include for a minimal but -fully functional class that creates a new table: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import javax.sql.DataSource; - import org.springframework.jdbc.core.JdbcTemplate; - - public class ExecuteAStatement { - - private JdbcTemplate jdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - public void doExecute() { - this.jdbcTemplate.execute("create table mytable (id integer, name varchar(100))"); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import javax.sql.DataSource - import org.springframework.jdbc.core.JdbcTemplate - - class ExecuteAStatement(dataSource: DataSource) { - - private val jdbcTemplate = JdbcTemplate(dataSource) - - fun doExecute() { - jdbcTemplate.execute("create table mytable (id integer, name varchar(100))") - } - } ----- - - -[[jdbc-statements-querying]] -==== Running Queries - -Some query methods return a single value. To retrieve a count or a specific value from -one row, use `queryForObject(..)`. The latter converts the returned JDBC `Type` to the -Java class that is passed in as an argument. If the type conversion is invalid, an -`InvalidDataAccessApiUsageException` is thrown. The following example contains two -query methods, one for an `int` and one that queries for a `String`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import javax.sql.DataSource; - import org.springframework.jdbc.core.JdbcTemplate; - - public class RunAQuery { - - private JdbcTemplate jdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - public int getCount() { - return this.jdbcTemplate.queryForObject("select count(*) from mytable", Integer.class); - } - - public String getName() { - return this.jdbcTemplate.queryForObject("select name from mytable", String.class); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -import javax.sql.DataSource -import org.springframework.jdbc.core.JdbcTemplate - -class RunAQuery(dataSource: DataSource) { - - private val jdbcTemplate = JdbcTemplate(dataSource) - - val count: Int - get() = jdbcTemplate.queryForObject("select count(*) from mytable")!! - - val name: String? - get() = jdbcTemplate.queryForObject("select name from mytable") -} ----- - -In addition to the single result query methods, several methods return a list with an -entry for each row that the query returned. The most generic method is `queryForList(..)`, -which returns a `List` where each element is a `Map` containing one entry for each column, -using the column name as the key. If you add a method to the preceding example to retrieve a -list of all the rows, it might be as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - private JdbcTemplate jdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - public List> getList() { - return this.jdbcTemplate.queryForList("select * from mytable"); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - private val jdbcTemplate = JdbcTemplate(dataSource) - - fun getList(): List> { - return jdbcTemplate.queryForList("select * from mytable") - } ----- - -The returned list would resemble the following: - -[literal,subs="verbatim,quotes"] ----- -[{name=Bob, id=1}, {name=Mary, id=2}] ----- - - -[[jdbc-updates]] -==== Updating the Database - -The following example updates a column for a certain primary key: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import javax.sql.DataSource; - import org.springframework.jdbc.core.JdbcTemplate; - - public class ExecuteAnUpdate { - - private JdbcTemplate jdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - public void setName(int id, String name) { - this.jdbcTemplate.update("update mytable set name = ? where id = ?", name, id); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import javax.sql.DataSource - import org.springframework.jdbc.core.JdbcTemplate - - class ExecuteAnUpdate(dataSource: DataSource) { - - private val jdbcTemplate = JdbcTemplate(dataSource) - - fun setName(id: Int, name: String) { - jdbcTemplate.update("update mytable set name = ? where id = ?", name, id) - } - } ----- - -In the preceding example, -an SQL statement has placeholders for row parameters. You can pass the parameter values -in as varargs or, alternatively, as an array of objects. Thus, you should explicitly wrap primitives -in the primitive wrapper classes, or you should use auto-boxing. - - -[[jdbc-auto-generated-keys]] -==== Retrieving Auto-generated Keys - -An `update()` convenience method supports the retrieval of primary keys generated by the -database. This support is part of the JDBC 3.0 standard. See Chapter 13.6 of the -specification for details. The method takes a `PreparedStatementCreator` as its first -argument, and this is the way the required insert statement is specified. The other -argument is a `KeyHolder`, which contains the generated key on successful return from the -update. There is no standard single way to create an appropriate `PreparedStatement` -(which explains why the method signature is the way it is). The following example works -on Oracle but may not work on other platforms: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - final String INSERT_SQL = "insert into my_test (name) values(?)"; - final String name = "Rob"; - - KeyHolder keyHolder = new GeneratedKeyHolder(); - jdbcTemplate.update(connection -> { - PreparedStatement ps = connection.prepareStatement(INSERT_SQL, new String[] { "id" }); - ps.setString(1, name); - return ps; - }, keyHolder); - - // keyHolder.getKey() now contains the generated key ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val INSERT_SQL = "insert into my_test (name) values(?)" - val name = "Rob" - - val keyHolder = GeneratedKeyHolder() - jdbcTemplate.update({ - it.prepareStatement (INSERT_SQL, arrayOf("id")).apply { setString(1, name) } - }, keyHolder) - - // keyHolder.getKey() now contains the generated key ----- - - - -[[jdbc-connections]] -=== Controlling Database Connections - -This section covers: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - - -[[jdbc-datasource]] -==== Using `DataSource` - -Spring obtains a connection to the database through a `DataSource`. A `DataSource` is -part of the JDBC specification and is a generalized connection factory. It lets a -container or a framework hide connection pooling and transaction management issues -from the application code. As a developer, you need not know details about how to -connect to the database. That is the responsibility of the administrator who sets up -the datasource. You most likely fill both roles as you develop and test code, but you -do not necessarily have to know how the production data source is configured. - -When you use Spring's JDBC layer, you can obtain a data source from JNDI, or you can -configure your own with a connection pool implementation provided by a third party. -Traditional choices are Apache Commons DBCP and C3P0 with bean-style `DataSource` classes; -for a modern JDBC connection pool, consider HikariCP with its builder-style API instead. - -NOTE: You should use the `DriverManagerDataSource` and `SimpleDriverDataSource` classes -(as included in the Spring distribution) only for testing purposes! Those variants do not -provide pooling and perform poorly when multiple requests for a connection are made. - -The following section uses Spring's `DriverManagerDataSource` implementation. -Several other `DataSource` variants are covered later. - -To configure a `DriverManagerDataSource`: - -. Obtain a connection with `DriverManagerDataSource` as you typically obtain a JDBC - connection. -. Specify the fully qualified class name of the JDBC driver so that the `DriverManager` - can load the driver class. -. Provide a URL that varies between JDBC drivers. (See the documentation for your driver - for the correct value.) -. Provide a username and a password to connect to the database. - -The following example shows how to configure a `DriverManagerDataSource` in Java: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - DriverManagerDataSource dataSource = new DriverManagerDataSource(); - dataSource.setDriverClassName("org.hsqldb.jdbcDriver"); - dataSource.setUrl("jdbc:hsqldb:hsql://localhost:"); - dataSource.setUsername("sa"); - dataSource.setPassword(""); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val dataSource = DriverManagerDataSource().apply { - setDriverClassName("org.hsqldb.jdbcDriver") - url = "jdbc:hsqldb:hsql://localhost:" - username = "sa" - password = "" - } ----- - -The following example shows the corresponding XML configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -The next two examples show the basic connectivity and configuration for DBCP and C3P0. -To learn about more options that help control the pooling features, see the product -documentation for the respective connection pooling implementations. - -The following example shows DBCP configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -The following example shows C3P0 configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - - -[[jdbc-DataSourceUtils]] -==== Using `DataSourceUtils` - -The `DataSourceUtils` class is a convenient and powerful helper class that provides -`static` methods to obtain connections from JNDI and close connections if necessary. It -supports thread-bound connections with, for example, `DataSourceTransactionManager`. - - -[[jdbc-SmartDataSource]] -==== Implementing `SmartDataSource` - -The `SmartDataSource` interface should be implemented by classes that can provide a -connection to a relational database. It extends the `DataSource` interface to let -classes that use it query whether the connection should be closed after a given -operation. This usage is efficient when you know that you need to reuse a connection. - - -[[jdbc-AbstractDataSource]] -==== Extending `AbstractDataSource` - -`AbstractDataSource` is an `abstract` base class for Spring's `DataSource` -implementations. It implements code that is common to all `DataSource` implementations. -You should extend the `AbstractDataSource` class if you write your own `DataSource` -implementation. - - -[[jdbc-SingleConnectionDataSource]] -==== Using `SingleConnectionDataSource` - -The `SingleConnectionDataSource` class is an implementation of the `SmartDataSource` -interface that wraps a single `Connection` that is not closed after each use. -This is not multi-threading capable. - -If any client code calls `close` on the assumption of a pooled connection (as when using -persistence tools), you should set the `suppressClose` property to `true`. This setting -returns a close-suppressing proxy that wraps the physical connection. Note that you can -no longer cast this to a native Oracle `Connection` or a similar object. - -`SingleConnectionDataSource` is primarily a test class. It typically enables easy testing -of code outside an application server, in conjunction with a simple JNDI environment. -In contrast to `DriverManagerDataSource`, it reuses the same connection all the time, -avoiding excessive creation of physical connections. - - - -[[jdbc-DriverManagerDataSource]] -==== Using `DriverManagerDataSource` - -The `DriverManagerDataSource` class is an implementation of the standard `DataSource` -interface that configures a plain JDBC driver through bean properties and returns a new -`Connection` every time. - -This implementation is useful for test and stand-alone environments outside of a Jakarta EE -container, either as a `DataSource` bean in a Spring IoC container or in conjunction -with a simple JNDI environment. Pool-assuming `Connection.close()` calls -close the connection, so any `DataSource`-aware persistence code should work. However, -using JavaBean-style connection pools (such as `commons-dbcp`) is so easy, even in a test -environment, that it is almost always preferable to use such a connection pool over -`DriverManagerDataSource`. - - -[[jdbc-TransactionAwareDataSourceProxy]] -==== Using `TransactionAwareDataSourceProxy` - -`TransactionAwareDataSourceProxy` is a proxy for a target `DataSource`. The proxy wraps that -target `DataSource` to add awareness of Spring-managed transactions. In this respect, it -is similar to a transactional JNDI `DataSource`, as provided by a Jakarta EE server. - -NOTE: It is rarely desirable to use this class, except when already existing code must be -called and passed a standard JDBC `DataSource` interface implementation. In this case, -you can still have this code be usable and, at the same time, have this code -participating in Spring managed transactions. It is generally preferable to write your -own new code by using the higher level abstractions for resource management, such as -`JdbcTemplate` or `DataSourceUtils`. - -See the {api-spring-framework}/jdbc/datasource/TransactionAwareDataSourceProxy.html[`TransactionAwareDataSourceProxy`] -javadoc for more details. - - -[[jdbc-DataSourceTransactionManager]] -==== Using `DataSourceTransactionManager` - -The `DataSourceTransactionManager` class is a `PlatformTransactionManager` -implementation for single JDBC data sources. It binds a JDBC connection from the -specified data source to the currently executing thread, potentially allowing for one -thread connection per data source. - -Application code is required to retrieve the JDBC connection through -`DataSourceUtils.getConnection(DataSource)` instead of Jakarta EE's standard -`DataSource.getConnection`. It throws unchecked `org.springframework.dao` exceptions -instead of checked `SQLExceptions`. All framework classes (such as `JdbcTemplate`) use this -strategy implicitly. If not used with this transaction manager, the lookup strategy -behaves exactly like the common one. Thus, it can be used in any case. - -The `DataSourceTransactionManager` class supports custom isolation levels and timeouts -that get applied as appropriate JDBC statement query timeouts. To support the latter, -application code must either use `JdbcTemplate` or call the -`DataSourceUtils.applyTransactionTimeout(..)` method for each created statement. - -You can use this implementation instead of `JtaTransactionManager` in the single-resource -case, as it does not require the container to support JTA. Switching between -both is just a matter of configuration, provided you stick to the required connection lookup -pattern. JTA does not support custom isolation levels. - - - -[[jdbc-advanced-jdbc]] -=== JDBC Batch Operations - -Most JDBC drivers provide improved performance if you batch multiple calls to the same -prepared statement. By grouping updates into batches, you limit the number of round trips -to the database. - - -[[jdbc-batch-classic]] -==== Basic Batch Operations with `JdbcTemplate` - -You accomplish `JdbcTemplate` batch processing by implementing two methods of a special -interface, `BatchPreparedStatementSetter`, and passing that implementation in as the second parameter -in your `batchUpdate` method call. You can use the `getBatchSize` method to provide the size of -the current batch. You can use the `setValues` method to set the values for the parameters of -the prepared statement. This method is called the number of times that you -specified in the `getBatchSize` call. The following example updates the `t_actor` table -based on entries in a list, and the entire list is used as the batch: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private JdbcTemplate jdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - public int[] batchUpdate(final List actors) { - return this.jdbcTemplate.batchUpdate( - "update t_actor set first_name = ?, last_name = ? where id = ?", - new BatchPreparedStatementSetter() { - public void setValues(PreparedStatement ps, int i) throws SQLException { - Actor actor = actors.get(i); - ps.setString(1, actor.getFirstName()); - ps.setString(2, actor.getLastName()); - ps.setLong(3, actor.getId().longValue()); - } - public int getBatchSize() { - return actors.size(); - } - }); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val jdbcTemplate = JdbcTemplate(dataSource) - - fun batchUpdate(actors: List): IntArray { - return jdbcTemplate.batchUpdate( - "update t_actor set first_name = ?, last_name = ? where id = ?", - object: BatchPreparedStatementSetter { - override fun setValues(ps: PreparedStatement, i: Int) { - ps.setString(1, actors[i].firstName) - ps.setString(2, actors[i].lastName) - ps.setLong(3, actors[i].id) - } - - override fun getBatchSize() = actors.size - }) - } - - // ... additional methods - } ----- - -If you process a stream of updates or reading from a file, you might have a -preferred batch size, but the last batch might not have that number of entries. In this -case, you can use the `InterruptibleBatchPreparedStatementSetter` interface, which lets -you interrupt a batch once the input source is exhausted. The `isBatchExhausted` method -lets you signal the end of the batch. - - -[[jdbc-batch-list]] -==== Batch Operations with a List of Objects - -Both the `JdbcTemplate` and the `NamedParameterJdbcTemplate` provides an alternate way -of providing the batch update. Instead of implementing a special batch interface, you -provide all parameter values in the call as a list. The framework loops over these -values and uses an internal prepared statement setter. The API varies, depending on -whether you use named parameters. For the named parameters, you provide an array of -`SqlParameterSource`, one entry for each member of the batch. You can use the -`SqlParameterSourceUtils.createBatch` convenience methods to create this array, passing -in an array of bean-style objects (with getter methods corresponding to parameters), -`String`-keyed `Map` instances (containing the corresponding parameters as values), or a mix of both. - -The following example shows a batch update using named parameters: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private NamedParameterTemplate namedParameterJdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.namedParameterJdbcTemplate = new NamedParameterJdbcTemplate(dataSource); - } - - public int[] batchUpdate(List actors) { - return this.namedParameterJdbcTemplate.batchUpdate( - "update t_actor set first_name = :firstName, last_name = :lastName where id = :id", - SqlParameterSourceUtils.createBatch(actors)); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) - - fun batchUpdate(actors: List): IntArray { - return this.namedParameterJdbcTemplate.batchUpdate( - "update t_actor set first_name = :firstName, last_name = :lastName where id = :id", - SqlParameterSourceUtils.createBatch(actors)); - } - - // ... additional methods - } ----- - -For an SQL statement that uses the classic `?` placeholders, you pass in a list -containing an object array with the update values. This object array must have one entry -for each placeholder in the SQL statement, and they must be in the same order as they are -defined in the SQL statement. - -The following example is the same as the preceding example, except that it uses classic -JDBC `?` placeholders: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private JdbcTemplate jdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - public int[] batchUpdate(final List actors) { - List batch = new ArrayList<>(); - for (Actor actor : actors) { - Object[] values = new Object[] { - actor.getFirstName(), actor.getLastName(), actor.getId()}; - batch.add(values); - } - return this.jdbcTemplate.batchUpdate( - "update t_actor set first_name = ?, last_name = ? where id = ?", - batch); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val jdbcTemplate = JdbcTemplate(dataSource) - - fun batchUpdate(actors: List): IntArray { - val batch = mutableListOf>() - for (actor in actors) { - batch.add(arrayOf(actor.firstName, actor.lastName, actor.id)) - } - return jdbcTemplate.batchUpdate( - "update t_actor set first_name = ?, last_name = ? where id = ?", batch) - } - - // ... additional methods - } ----- - -All of the batch update methods that we described earlier return an `int` array -containing the number of affected rows for each batch entry. This count is reported by -the JDBC driver. If the count is not available, the JDBC driver returns a value of `-2`. - -[NOTE] -==== -In such a scenario, with automatic setting of values on an underlying `PreparedStatement`, -the corresponding JDBC type for each value needs to be derived from the given Java type. -While this usually works well, there is a potential for issues (for example, with Map-contained -`null` values). Spring, by default, calls `ParameterMetaData.getParameterType` in such a -case, which can be expensive with your JDBC driver. You should use a recent driver -version and consider setting the `spring.jdbc.getParameterType.ignore` property to `true` -(as a JVM system property or via the -<> mechanism) if you encounter -a performance issue (as reported on Oracle 12c, JBoss, and PostgreSQL). - -Alternatively, you might consider specifying the corresponding JDBC types explicitly, -either through a `BatchPreparedStatementSetter` (as shown earlier), through an explicit type -array given to a `List` based call, through `registerSqlType` calls on a -custom `MapSqlParameterSource` instance, or through a `BeanPropertySqlParameterSource` -that derives the SQL type from the Java-declared property type even for a null value. -==== - - -[[jdbc-batch-multi]] -==== Batch Operations with Multiple Batches - -The preceding example of a batch update deals with batches that are so large that you want to -break them up into several smaller batches. You can do this with the methods -mentioned earlier by making multiple calls to the `batchUpdate` method, but there is now a -more convenient method. This method takes, in addition to the SQL statement, a -`Collection` of objects that contain the parameters, the number of updates to make for each -batch, and a `ParameterizedPreparedStatementSetter` to set the values for the parameters -of the prepared statement. The framework loops over the provided values and breaks the -update calls into batches of the size specified. - -The following example shows a batch update that uses a batch size of 100: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private JdbcTemplate jdbcTemplate; - - public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - public int[][] batchUpdate(final Collection actors) { - int[][] updateCounts = jdbcTemplate.batchUpdate( - "update t_actor set first_name = ?, last_name = ? where id = ?", - actors, - 100, - (PreparedStatement ps, Actor actor) -> { - ps.setString(1, actor.getFirstName()); - ps.setString(2, actor.getLastName()); - ps.setLong(3, actor.getId().longValue()); - }); - return updateCounts; - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val jdbcTemplate = JdbcTemplate(dataSource) - - fun batchUpdate(actors: List): Array { - return jdbcTemplate.batchUpdate( - "update t_actor set first_name = ?, last_name = ? where id = ?", - actors, 100) { ps, argument -> - ps.setString(1, argument.firstName) - ps.setString(2, argument.lastName) - ps.setLong(3, argument.id) - } - } - - // ... additional methods - } ----- - -The batch update method for this call returns an array of `int` arrays that contains an -array entry for each batch with an array of the number of affected rows for each update. -The top-level array's length indicates the number of batches run, and the second level -array's length indicates the number of updates in that batch. The number of updates in -each batch should be the batch size provided for all batches (except that the last one -that might be less), depending on the total number of update objects provided. The update -count for each update statement is the one reported by the JDBC driver. If the count is -not available, the JDBC driver returns a value of `-2`. - - - -[[jdbc-simple-jdbc]] -=== Simplifying JDBC Operations with the `SimpleJdbc` Classes - -The `SimpleJdbcInsert` and `SimpleJdbcCall` classes provide a simplified configuration -by taking advantage of database metadata that can be retrieved through the JDBC driver. -This means that you have less to configure up front, although you can override or turn off -the metadata processing if you prefer to provide all the details in your code. - - -[[jdbc-simple-jdbc-insert-1]] -==== Inserting Data by Using `SimpleJdbcInsert` - -We start by looking at the `SimpleJdbcInsert` class with the minimal amount of -configuration options. You should instantiate the `SimpleJdbcInsert` in the data access -layer's initialization method. For this example, the initializing method is the -`setDataSource` method. You do not need to subclass the `SimpleJdbcInsert` class. Instead, -you can create a new instance and set the table name by using the `withTableName` method. -Configuration methods for this class follow the `fluid` style that returns the instance -of the `SimpleJdbcInsert`, which lets you chain all configuration methods. The following -example uses only one configuration method (we show examples of multiple methods later): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcInsert insertActor; - - public void setDataSource(DataSource dataSource) { - this.insertActor = new SimpleJdbcInsert(dataSource).withTableName("t_actor"); - } - - public void add(Actor actor) { - Map parameters = new HashMap<>(3); - parameters.put("id", actor.getId()); - parameters.put("first_name", actor.getFirstName()); - parameters.put("last_name", actor.getLastName()); - insertActor.execute(parameters); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val insertActor = SimpleJdbcInsert(dataSource).withTableName("t_actor") - - fun add(actor: Actor) { - val parameters = mutableMapOf() - parameters["id"] = actor.id - parameters["first_name"] = actor.firstName - parameters["last_name"] = actor.lastName - insertActor.execute(parameters) - } - - // ... additional methods - } ----- - -The `execute` method used here takes a plain `java.util.Map` as its only parameter. The -important thing to note here is that the keys used for the `Map` must match the column -names of the table, as defined in the database. This is because we read the metadata -to construct the actual insert statement. - - -[[jdbc-simple-jdbc-insert-2]] -==== Retrieving Auto-generated Keys by Using `SimpleJdbcInsert` - -The next example uses the same insert as the preceding example, but, instead of passing in the `id`, it -retrieves the auto-generated key and sets it on the new `Actor` object. When it creates -the `SimpleJdbcInsert`, in addition to specifying the table name, it specifies the name -of the generated key column with the `usingGeneratedKeyColumns` method. The following -listing shows how it works: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcInsert insertActor; - - public void setDataSource(DataSource dataSource) { - this.insertActor = new SimpleJdbcInsert(dataSource) - .withTableName("t_actor") - .usingGeneratedKeyColumns("id"); - } - - public void add(Actor actor) { - Map parameters = new HashMap<>(2); - parameters.put("first_name", actor.getFirstName()); - parameters.put("last_name", actor.getLastName()); - Number newId = insertActor.executeAndReturnKey(parameters); - actor.setId(newId.longValue()); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val insertActor = SimpleJdbcInsert(dataSource) - .withTableName("t_actor").usingGeneratedKeyColumns("id") - - fun add(actor: Actor): Actor { - val parameters = mapOf( - "first_name" to actor.firstName, - "last_name" to actor.lastName) - val newId = insertActor.executeAndReturnKey(parameters); - return actor.copy(id = newId.toLong()) - } - - // ... additional methods - } ----- - -The main difference when you run the insert by using this second approach is that you do not -add the `id` to the `Map`, and you call the `executeAndReturnKey` method. This returns a -`java.lang.Number` object with which you can create an instance of the numerical type that -is used in your domain class. You cannot rely on all databases to return a specific Java -class here. `java.lang.Number` is the base class that you can rely on. If you have -multiple auto-generated columns or the generated values are non-numeric, you can -use a `KeyHolder` that is returned from the `executeAndReturnKeyHolder` method. - - -[[jdbc-simple-jdbc-insert-3]] -==== Specifying Columns for a `SimpleJdbcInsert` - -You can limit the columns for an insert by specifying a list of column names with the -`usingColumns` method, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcInsert insertActor; - - public void setDataSource(DataSource dataSource) { - this.insertActor = new SimpleJdbcInsert(dataSource) - .withTableName("t_actor") - .usingColumns("first_name", "last_name") - .usingGeneratedKeyColumns("id"); - } - - public void add(Actor actor) { - Map parameters = new HashMap<>(2); - parameters.put("first_name", actor.getFirstName()); - parameters.put("last_name", actor.getLastName()); - Number newId = insertActor.executeAndReturnKey(parameters); - actor.setId(newId.longValue()); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val insertActor = SimpleJdbcInsert(dataSource) - .withTableName("t_actor") - .usingColumns("first_name", "last_name") - .usingGeneratedKeyColumns("id") - - fun add(actor: Actor): Actor { - val parameters = mapOf( - "first_name" to actor.firstName, - "last_name" to actor.lastName) - val newId = insertActor.executeAndReturnKey(parameters); - return actor.copy(id = newId.toLong()) - } - - // ... additional methods - } ----- - -The execution of the insert is the same as if you had relied on the metadata to determine -which columns to use. - - -[[jdbc-simple-jdbc-parameters]] -==== Using `SqlParameterSource` to Provide Parameter Values - -Using a `Map` to provide parameter values works fine, but it is not the most convenient -class to use. Spring provides a couple of implementations of the `SqlParameterSource` -interface that you can use instead. The first one is `BeanPropertySqlParameterSource`, -which is a very convenient class if you have a JavaBean-compliant class that contains -your values. It uses the corresponding getter method to extract the parameter -values. The following example shows how to use `BeanPropertySqlParameterSource`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcInsert insertActor; - - public void setDataSource(DataSource dataSource) { - this.insertActor = new SimpleJdbcInsert(dataSource) - .withTableName("t_actor") - .usingGeneratedKeyColumns("id"); - } - - public void add(Actor actor) { - SqlParameterSource parameters = new BeanPropertySqlParameterSource(actor); - Number newId = insertActor.executeAndReturnKey(parameters); - actor.setId(newId.longValue()); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val insertActor = SimpleJdbcInsert(dataSource) - .withTableName("t_actor") - .usingGeneratedKeyColumns("id") - - fun add(actor: Actor): Actor { - val parameters = BeanPropertySqlParameterSource(actor) - val newId = insertActor.executeAndReturnKey(parameters) - return actor.copy(id = newId.toLong()) - } - - // ... additional methods - } ----- - -Another option is the `MapSqlParameterSource` that resembles a `Map` but provides a more -convenient `addValue` method that can be chained. The following example shows how to use it: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcInsert insertActor; - - public void setDataSource(DataSource dataSource) { - this.insertActor = new SimpleJdbcInsert(dataSource) - .withTableName("t_actor") - .usingGeneratedKeyColumns("id"); - } - - public void add(Actor actor) { - SqlParameterSource parameters = new MapSqlParameterSource() - .addValue("first_name", actor.getFirstName()) - .addValue("last_name", actor.getLastName()); - Number newId = insertActor.executeAndReturnKey(parameters); - actor.setId(newId.longValue()); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val insertActor = SimpleJdbcInsert(dataSource) - .withTableName("t_actor") - .usingGeneratedKeyColumns("id") - - fun add(actor: Actor): Actor { - val parameters = MapSqlParameterSource() - .addValue("first_name", actor.firstName) - .addValue("last_name", actor.lastName) - val newId = insertActor.executeAndReturnKey(parameters) - return actor.copy(id = newId.toLong()) - } - - // ... additional methods - } ----- - -As you can see, the configuration is the same. Only the executing code has to change to -use these alternative input classes. - - -[[jdbc-simple-jdbc-call-1]] -==== Calling a Stored Procedure with `SimpleJdbcCall` - -The `SimpleJdbcCall` class uses metadata in the database to look up names of `in` -and `out` parameters so that you do not have to explicitly declare them. You can -declare parameters if you prefer to do that or if you have parameters (such as `ARRAY` -or `STRUCT`) that do not have an automatic mapping to a Java class. The first example -shows a simple procedure that returns only scalar values in `VARCHAR` and `DATE` format -from a MySQL database. The example procedure reads a specified actor entry and returns -`first_name`, `last_name`, and `birth_date` columns in the form of `out` parameters. -The following listing shows the first example: - -[source,sql,indent=0,subs="verbatim,quotes"] ----- - CREATE PROCEDURE read_actor ( - IN in_id INTEGER, - OUT out_first_name VARCHAR(100), - OUT out_last_name VARCHAR(100), - OUT out_birth_date DATE) - BEGIN - SELECT first_name, last_name, birth_date - INTO out_first_name, out_last_name, out_birth_date - FROM t_actor where id = in_id; - END; ----- - -The `in_id` parameter contains the `id` of the actor that you are looking up. The `out` -parameters return the data read from the table. - -You can declare `SimpleJdbcCall` in a manner similar to declaring `SimpleJdbcInsert`. You -should instantiate and configure the class in the initialization method of your data-access -layer. Compared to the `StoredProcedure` class, you need not create a subclass -and you need not to declare parameters that can be looked up in the database metadata. -The following example of a `SimpleJdbcCall` configuration uses the preceding stored -procedure (the only configuration option, in addition to the `DataSource`, is the name -of the stored procedure): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcCall procReadActor; - - public void setDataSource(DataSource dataSource) { - this.procReadActor = new SimpleJdbcCall(dataSource) - .withProcedureName("read_actor"); - } - - public Actor readActor(Long id) { - SqlParameterSource in = new MapSqlParameterSource() - .addValue("in_id", id); - Map out = procReadActor.execute(in); - Actor actor = new Actor(); - actor.setId(id); - actor.setFirstName((String) out.get("out_first_name")); - actor.setLastName((String) out.get("out_last_name")); - actor.setBirthDate((Date) out.get("out_birth_date")); - return actor; - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val procReadActor = SimpleJdbcCall(dataSource) - .withProcedureName("read_actor") - - - fun readActor(id: Long): Actor { - val source = MapSqlParameterSource().addValue("in_id", id) - val output = procReadActor.execute(source) - return Actor( - id, - output["out_first_name"] as String, - output["out_last_name"] as String, - output["out_birth_date"] as Date) - } - - // ... additional methods - } ----- - -The code you write for the execution of the call involves creating an `SqlParameterSource` -containing the IN parameter. You must match the name provided for the input value -with that of the parameter name declared in the stored procedure. The case does not have -to match because you use metadata to determine how database objects should be referred to -in a stored procedure. What is specified in the source for the stored procedure is not -necessarily the way it is stored in the database. Some databases transform names to all -upper case, while others use lower case or use the case as specified. - -The `execute` method takes the IN parameters and returns a `Map` that contains any `out` -parameters keyed by the name, as specified in the stored procedure. In this case, they are -`out_first_name`, `out_last_name`, and `out_birth_date`. - -The last part of the `execute` method creates an `Actor` instance to use to return the -data retrieved. Again, it is important to use the names of the `out` parameters as they -are declared in the stored procedure. Also, the case in the names of the `out` -parameters stored in the results map matches that of the `out` parameter names in the -database, which could vary between databases. To make your code more portable, you should -do a case-insensitive lookup or instruct Spring to use a `LinkedCaseInsensitiveMap`. -To do the latter, you can create your own `JdbcTemplate` and set the `setResultsMapCaseInsensitive` -property to `true`. Then you can pass this customized `JdbcTemplate` instance into -the constructor of your `SimpleJdbcCall`. The following example shows this configuration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcCall procReadActor; - - public void setDataSource(DataSource dataSource) { - JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); - jdbcTemplate.setResultsMapCaseInsensitive(true); - this.procReadActor = new SimpleJdbcCall(jdbcTemplate) - .withProcedureName("read_actor"); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private var procReadActor = SimpleJdbcCall(JdbcTemplate(dataSource).apply { - isResultsMapCaseInsensitive = true - }).withProcedureName("read_actor") - - // ... additional methods - } ----- - -By taking this action, you avoid conflicts in the case used for the names of your -returned `out` parameters. - - -[[jdbc-simple-jdbc-call-2]] -==== Explicitly Declaring Parameters to Use for a `SimpleJdbcCall` - -Earlier in this chapter, we described how parameters are deduced from metadata, but you can declare them -explicitly if you wish. You can do so by creating and configuring `SimpleJdbcCall` with -the `declareParameters` method, which takes a variable number of `SqlParameter` objects -as input. See the <> for details on how to define an `SqlParameter`. - -NOTE: Explicit declarations are necessary if the database you use is not a Spring-supported -database. Currently, Spring supports metadata lookup of stored procedure calls for the -following databases: Apache Derby, DB2, MySQL, Microsoft SQL Server, Oracle, and Sybase. -We also support metadata lookup of stored functions for MySQL, Microsoft SQL Server, -and Oracle. - -You can opt to explicitly declare one, some, or all of the parameters. The parameter -metadata is still used where you do not explicitly declare parameters. To bypass all -processing of metadata lookups for potential parameters and use only the declared -parameters, you can call the method `withoutProcedureColumnMetaDataAccess` as part of the -declaration. Suppose that you have two or more different call signatures declared for a -database function. In this case, you call `useInParameterNames` to specify the list -of IN parameter names to include for a given signature. - -The following example shows a fully declared procedure call and uses the information from -the preceding example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcCall procReadActor; - - public void setDataSource(DataSource dataSource) { - JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); - jdbcTemplate.setResultsMapCaseInsensitive(true); - this.procReadActor = new SimpleJdbcCall(jdbcTemplate) - .withProcedureName("read_actor") - .withoutProcedureColumnMetaDataAccess() - .useInParameterNames("in_id") - .declareParameters( - new SqlParameter("in_id", Types.NUMERIC), - new SqlOutParameter("out_first_name", Types.VARCHAR), - new SqlOutParameter("out_last_name", Types.VARCHAR), - new SqlOutParameter("out_birth_date", Types.DATE) - ); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val procReadActor = SimpleJdbcCall(JdbcTemplate(dataSource).apply { - isResultsMapCaseInsensitive = true - }).withProcedureName("read_actor") - .withoutProcedureColumnMetaDataAccess() - .useInParameterNames("in_id") - .declareParameters( - SqlParameter("in_id", Types.NUMERIC), - SqlOutParameter("out_first_name", Types.VARCHAR), - SqlOutParameter("out_last_name", Types.VARCHAR), - SqlOutParameter("out_birth_date", Types.DATE) - ) - - // ... additional methods - } ----- - -The execution and end results of the two examples are the same. The second example specifies all -details explicitly rather than relying on metadata. - - -[[jdbc-params]] -==== How to Define `SqlParameters` - -To define a parameter for the `SimpleJdbc` classes and also for the RDBMS operations -classes (covered in <>) you can use `SqlParameter` or one of its subclasses. -To do so, you typically specify the parameter name and SQL type in the constructor. The SQL type -is specified by using the `java.sql.Types` constants. Earlier in this chapter, we saw declarations -similar to the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - new SqlParameter("in_id", Types.NUMERIC), - new SqlOutParameter("out_first_name", Types.VARCHAR), ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - SqlParameter("in_id", Types.NUMERIC), - SqlOutParameter("out_first_name", Types.VARCHAR), ----- - -The first line with the `SqlParameter` declares an IN parameter. You can use IN parameters -for both stored procedure calls and for queries by using the `SqlQuery` and its -subclasses (covered in <>). - -The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in a -stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters -(parameters that provide an IN value to the procedure and that also return a value). - -NOTE: Only parameters declared as `SqlParameter` and `SqlInOutParameter` are used to -provide input values. This is different from the `StoredProcedure` class, which (for -backwards compatibility reasons) lets input values be provided for parameters -declared as `SqlOutParameter`. - -For IN parameters, in addition to the name and the SQL type, you can specify a scale for -numeric data or a type name for custom database types. For `out` parameters, you can -provide a `RowMapper` to handle mapping of rows returned from a `REF` cursor. Another -option is to specify an `SqlReturnType` that provides an opportunity to define -customized handling of the return values. - - -[[jdbc-simple-jdbc-call-3]] -==== Calling a Stored Function by Using `SimpleJdbcCall` - -You can call a stored function in almost the same way as you call a stored procedure, except -that you provide a function name rather than a procedure name. You use the -`withFunctionName` method as part of the configuration to indicate that you want to make -a call to a function, and the corresponding string for a function call is generated. A -specialized call (`executeFunction`) is used to run the function, and it -returns the function return value as an object of a specified type, which means you do -not have to retrieve the return value from the results map. A similar convenience method -(named `executeObject`) is also available for stored procedures that have only one `out` -parameter. The following example (for MySQL) is based on a stored function named `get_actor_name` -that returns an actor's full name: - -[source,sql,indent=0,subs="verbatim,quotes"] ----- - CREATE FUNCTION get_actor_name (in_id INTEGER) - RETURNS VARCHAR(200) READS SQL DATA - BEGIN - DECLARE out_name VARCHAR(200); - SELECT concat(first_name, ' ', last_name) - INTO out_name - FROM t_actor where id = in_id; - RETURN out_name; - END; ----- - -To call this function, we again create a `SimpleJdbcCall` in the initialization method, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcCall funcGetActorName; - - public void setDataSource(DataSource dataSource) { - JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); - jdbcTemplate.setResultsMapCaseInsensitive(true); - this.funcGetActorName = new SimpleJdbcCall(jdbcTemplate) - .withFunctionName("get_actor_name"); - } - - public String getActorName(Long id) { - SqlParameterSource in = new MapSqlParameterSource() - .addValue("in_id", id); - String name = funcGetActorName.executeFunction(String.class, in); - return name; - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val jdbcTemplate = JdbcTemplate(dataSource).apply { - isResultsMapCaseInsensitive = true - } - private val funcGetActorName = SimpleJdbcCall(jdbcTemplate) - .withFunctionName("get_actor_name") - - fun getActorName(id: Long): String { - val source = MapSqlParameterSource().addValue("in_id", id) - return funcGetActorName.executeFunction(String::class.java, source) - } - - // ... additional methods - } ----- - -The `executeFunction` method used returns a `String` that contains the return value from the -function call. - - -[[jdbc-simple-jdbc-call-4]] -==== Returning a `ResultSet` or REF Cursor from a `SimpleJdbcCall` - -Calling a stored procedure or function that returns a result set is a bit tricky. Some -databases return result sets during the JDBC results processing, while others require an -explicitly registered `out` parameter of a specific type. Both approaches need -additional processing to loop over the result set and process the returned rows. With -the `SimpleJdbcCall`, you can use the `returningResultSet` method and declare a `RowMapper` -implementation to be used for a specific parameter. If the result set is -returned during the results processing, there are no names defined, so the returned -results must match the order in which you declare the `RowMapper` -implementations. The name specified is still used to store the processed list of results -in the results map that is returned from the `execute` statement. - -The next example (for MySQL) uses a stored procedure that takes no IN parameters and returns -all rows from the `t_actor` table: - -[source,sql,indent=0,subs="verbatim,quotes"] ----- - CREATE PROCEDURE read_all_actors() - BEGIN - SELECT a.id, a.first_name, a.last_name, a.birth_date FROM t_actor a; - END; ----- - -To call this procedure, you can declare the `RowMapper`. Because the class to which you want -to map follows the JavaBean rules, you can use a `BeanPropertyRowMapper` that is created by -passing in the required class to map to in the `newInstance` method. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class JdbcActorDao implements ActorDao { - - private SimpleJdbcCall procReadAllActors; - - public void setDataSource(DataSource dataSource) { - JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); - jdbcTemplate.setResultsMapCaseInsensitive(true); - this.procReadAllActors = new SimpleJdbcCall(jdbcTemplate) - .withProcedureName("read_all_actors") - .returningResultSet("actors", - BeanPropertyRowMapper.newInstance(Actor.class)); - } - - public List getActorsList() { - Map m = procReadAllActors.execute(new HashMap(0)); - return (List) m.get("actors"); - } - - // ... additional methods - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class JdbcActorDao(dataSource: DataSource) : ActorDao { - - private val procReadAllActors = SimpleJdbcCall(JdbcTemplate(dataSource).apply { - isResultsMapCaseInsensitive = true - }).withProcedureName("read_all_actors") - .returningResultSet("actors", - BeanPropertyRowMapper.newInstance(Actor::class.java)) - - fun getActorsList(): List { - val m = procReadAllActors.execute(mapOf()) - return m["actors"] as List - } - - // ... additional methods - } ----- - -The `execute` call passes in an empty `Map`, because this call does not take any parameters. -The list of actors is then retrieved from the results map and returned to the caller. - - - -[[jdbc-object]] -=== Modeling JDBC Operations as Java Objects - -The `org.springframework.jdbc.object` package contains classes that let you access -the database in a more object-oriented manner. As an example, you can run queries -and get the results back as a list that contains business objects with the relational -column data mapped to the properties of the business object. You can also run stored -procedures and run update, delete, and insert statements. - -[NOTE] -==== -Many Spring developers believe that the various RDBMS operation classes described below -(with the exception of the <> class) can often -be replaced with straight `JdbcTemplate` calls. Often, it is simpler to write a DAO -method that calls a method on a `JdbcTemplate` directly (as opposed to -encapsulating a query as a full-blown class). - -However, if you are getting measurable value from using the RDBMS operation classes, -you should continue to use these classes. -==== - - -[[jdbc-SqlQuery]] -==== Understanding `SqlQuery` - -`SqlQuery` is a reusable, thread-safe class that encapsulates an SQL query. Subclasses -must implement the `newRowMapper(..)` method to provide a `RowMapper` instance that can -create one object per row obtained from iterating over the `ResultSet` that is created -during the execution of the query. The `SqlQuery` class is rarely used directly, because -the `MappingSqlQuery` subclass provides a much more convenient implementation for -mapping rows to Java classes. Other implementations that extend `SqlQuery` are -`MappingSqlQueryWithParameters` and `UpdatableSqlQuery`. - - -[[jdbc-MappingSqlQuery]] -==== Using `MappingSqlQuery` - -`MappingSqlQuery` is a reusable query in which concrete subclasses must implement the -abstract `mapRow(..)` method to convert each row of the supplied `ResultSet` into an -object of the type specified. The following example shows a custom query that maps the -data from the `t_actor` relation to an instance of the `Actor` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ActorMappingQuery extends MappingSqlQuery { - - public ActorMappingQuery(DataSource ds) { - super(ds, "select id, first_name, last_name from t_actor where id = ?"); - declareParameter(new SqlParameter("id", Types.INTEGER)); - compile(); - } - - @Override - protected Actor mapRow(ResultSet rs, int rowNumber) throws SQLException { - Actor actor = new Actor(); - actor.setId(rs.getLong("id")); - actor.setFirstName(rs.getString("first_name")); - actor.setLastName(rs.getString("last_name")); - return actor; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ActorMappingQuery(ds: DataSource) : MappingSqlQuery(ds, "select id, first_name, last_name from t_actor where id = ?") { - - init { - declareParameter(SqlParameter("id", Types.INTEGER)) - compile() - } - - override fun mapRow(rs: ResultSet, rowNumber: Int) = Actor( - rs.getLong("id"), - rs.getString("first_name"), - rs.getString("last_name") - ) - } - ----- - -The class extends `MappingSqlQuery` parameterized with the `Actor` type. The constructor -for this customer query takes a `DataSource` as the only parameter. In this -constructor, you can call the constructor on the superclass with the `DataSource` and the SQL -that should be run to retrieve the rows for this query. This SQL is used to -create a `PreparedStatement`, so it may contain placeholders for any parameters to be -passed in during execution. You must declare each parameter by using the `declareParameter` -method passing in an `SqlParameter`. The `SqlParameter` takes a name, and the JDBC type -as defined in `java.sql.Types`. After you define all parameters, you can call the -`compile()` method so that the statement can be prepared and later run. This class is -thread-safe after it is compiled, so, as long as these instances are created when the DAO -is initialized, they can be kept as instance variables and be reused. The following -example shows how to define such a class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - private ActorMappingQuery actorMappingQuery; - - @Autowired - public void setDataSource(DataSource dataSource) { - this.actorMappingQuery = new ActorMappingQuery(dataSource); - } - - public Customer getCustomer(Long id) { - return actorMappingQuery.findObject(id); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - private val actorMappingQuery = ActorMappingQuery(dataSource) - - fun getCustomer(id: Long) = actorMappingQuery.findObject(id) ----- - -The method in the preceding example retrieves the customer with the `id` that is passed in as the -only parameter. Since we want only one object to be returned, we call the `findObject` convenience -method with the `id` as the parameter. If we had instead a query that returned a -list of objects and took additional parameters, we would use one of the `execute` -methods that takes an array of parameter values passed in as varargs. The following -example shows such a method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public List searchForActors(int age, String namePattern) { - return actorSearchMappingQuery.execute(age, namePattern); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun searchForActors(age: Int, namePattern: String) = - actorSearchMappingQuery.execute(age, namePattern) ----- - - -[[jdbc-SqlUpdate]] -==== Using `SqlUpdate` - -The `SqlUpdate` class encapsulates an SQL update. As with a query, an update object is -reusable, and, as with all `RdbmsOperation` classes, an update can have parameters and is -defined in SQL. This class provides a number of `update(..)` methods analogous to the -`execute(..)` methods of query objects. The `SqlUpdate` class is concrete. It can be -subclassed -- for example, to add a custom update method. -However, you do not have to subclass the `SqlUpdate` -class, since it can easily be parameterized by setting SQL and declaring parameters. -The following example creates a custom update method named `execute`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import java.sql.Types; - import javax.sql.DataSource; - import org.springframework.jdbc.core.SqlParameter; - import org.springframework.jdbc.object.SqlUpdate; - - public class UpdateCreditRating extends SqlUpdate { - - public UpdateCreditRating(DataSource ds) { - setDataSource(ds); - setSql("update customer set credit_rating = ? where id = ?"); - declareParameter(new SqlParameter("creditRating", Types.NUMERIC)); - declareParameter(new SqlParameter("id", Types.NUMERIC)); - compile(); - } - - /** - * @param id for the Customer to be updated - * @param rating the new value for credit rating - * @return number of rows updated - */ - public int execute(int id, int rating) { - return update(rating, id); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import java.sql.Types - import javax.sql.DataSource - import org.springframework.jdbc.core.SqlParameter - import org.springframework.jdbc.`object`.SqlUpdate - - class UpdateCreditRating(ds: DataSource) : SqlUpdate() { - - init { - setDataSource(ds) - sql = "update customer set credit_rating = ? where id = ?" - declareParameter(SqlParameter("creditRating", Types.NUMERIC)) - declareParameter(SqlParameter("id", Types.NUMERIC)) - compile() - } - - /** - * @param id for the Customer to be updated - * @param rating the new value for credit rating - * @return number of rows updated - */ - fun execute(id: Int, rating: Int): Int { - return update(rating, id) - } - } ----- - - -[[jdbc-StoredProcedure]] -==== Using `StoredProcedure` - -The `StoredProcedure` class is an `abstract` superclass for object abstractions of RDBMS -stored procedures. - -The inherited `sql` property is the name of the stored procedure in the RDBMS. - -To define a parameter for the `StoredProcedure` class, you can use an `SqlParameter` or one -of its subclasses. You must specify the parameter name and SQL type in the constructor, -as the following code snippet shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - new SqlParameter("in_id", Types.NUMERIC), - new SqlOutParameter("out_first_name", Types.VARCHAR), ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - SqlParameter("in_id", Types.NUMERIC), - SqlOutParameter("out_first_name", Types.VARCHAR), ----- - -The SQL type is specified using the `java.sql.Types` constants. - -The first line (with the `SqlParameter`) declares an IN parameter. You can use IN parameters -both for stored procedure calls and for queries using the `SqlQuery` and its -subclasses (covered in <>). - -The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in the -stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters -(parameters that provide an `in` value to the procedure and that also return a value). - -For `in` parameters, in addition to the name and the SQL type, you can specify a -scale for numeric data or a type name for custom database types. For `out` parameters, -you can provide a `RowMapper` to handle mapping of rows returned from a `REF` cursor. -Another option is to specify an `SqlReturnType` that lets you define customized -handling of the return values. - -The next example of a simple DAO uses a `StoredProcedure` to call a function -(`sysdate()`), which comes with any Oracle database. To use the stored procedure -functionality, you have to create a class that extends `StoredProcedure`. In this -example, the `StoredProcedure` class is an inner class. However, if you need to reuse the -`StoredProcedure`, you can declare it as a top-level class. This example has no input -parameters, but an output parameter is declared as a date type by using the -`SqlOutParameter` class. The `execute()` method runs the procedure and extracts the -returned date from the results `Map`. The results `Map` has an entry for each declared -output parameter (in this case, only one) by using the parameter name as the key. -The following listing shows our custom StoredProcedure class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import java.sql.Types; - import java.util.Date; - import java.util.HashMap; - import java.util.Map; - import javax.sql.DataSource; - import org.springframework.beans.factory.annotation.Autowired; - import org.springframework.jdbc.core.SqlOutParameter; - import org.springframework.jdbc.object.StoredProcedure; - - public class StoredProcedureDao { - - private GetSysdateProcedure getSysdate; - - @Autowired - public void init(DataSource dataSource) { - this.getSysdate = new GetSysdateProcedure(dataSource); - } - - public Date getSysdate() { - return getSysdate.execute(); - } - - private class GetSysdateProcedure extends StoredProcedure { - - private static final String SQL = "sysdate"; - - public GetSysdateProcedure(DataSource dataSource) { - setDataSource(dataSource); - setFunction(true); - setSql(SQL); - declareParameter(new SqlOutParameter("date", Types.DATE)); - compile(); - } - - public Date execute() { - // the 'sysdate' sproc has no input parameters, so an empty Map is supplied... - Map results = execute(new HashMap()); - Date sysdate = (Date) results.get("date"); - return sysdate; - } - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import java.sql.Types - import java.util.Date - import java.util.Map - import javax.sql.DataSource - import org.springframework.jdbc.core.SqlOutParameter - import org.springframework.jdbc.object.StoredProcedure - - class StoredProcedureDao(dataSource: DataSource) { - - private val SQL = "sysdate" - - private val getSysdate = GetSysdateProcedure(dataSource) - - val sysdate: Date - get() = getSysdate.execute() - - private inner class GetSysdateProcedure(dataSource: DataSource) : StoredProcedure() { - - init { - setDataSource(dataSource) - isFunction = true - sql = SQL - declareParameter(SqlOutParameter("date", Types.DATE)) - compile() - } - - fun execute(): Date { - // the 'sysdate' sproc has no input parameters, so an empty Map is supplied... - val results = execute(mutableMapOf()) - return results["date"] as Date - } - } - } ----- - -The following example of a `StoredProcedure` has two output parameters (in this case, -Oracle REF cursors): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import java.util.HashMap; - import java.util.Map; - import javax.sql.DataSource; - import oracle.jdbc.OracleTypes; - import org.springframework.jdbc.core.SqlOutParameter; - import org.springframework.jdbc.object.StoredProcedure; - - public class TitlesAndGenresStoredProcedure extends StoredProcedure { - - private static final String SPROC_NAME = "AllTitlesAndGenres"; - - public TitlesAndGenresStoredProcedure(DataSource dataSource) { - super(dataSource, SPROC_NAME); - declareParameter(new SqlOutParameter("titles", OracleTypes.CURSOR, new TitleMapper())); - declareParameter(new SqlOutParameter("genres", OracleTypes.CURSOR, new GenreMapper())); - compile(); - } - - public Map execute() { - // again, this sproc has no input parameters, so an empty Map is supplied - return super.execute(new HashMap()); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import java.util.HashMap - import javax.sql.DataSource - import oracle.jdbc.OracleTypes - import org.springframework.jdbc.core.SqlOutParameter - import org.springframework.jdbc.`object`.StoredProcedure - - class TitlesAndGenresStoredProcedure(dataSource: DataSource) : StoredProcedure(dataSource, SPROC_NAME) { - - companion object { - private const val SPROC_NAME = "AllTitlesAndGenres" - } - - init { - declareParameter(SqlOutParameter("titles", OracleTypes.CURSOR, TitleMapper())) - declareParameter(SqlOutParameter("genres", OracleTypes.CURSOR, GenreMapper())) - compile() - } - - fun execute(): Map { - // again, this sproc has no input parameters, so an empty Map is supplied - return super.execute(HashMap()) - } - } ----- - -Notice how the overloaded variants of the `declareParameter(..)` method that have been -used in the `TitlesAndGenresStoredProcedure` constructor are passed `RowMapper` -implementation instances. This is a very convenient and powerful way to reuse existing -functionality. The next two examples provide code for the two `RowMapper` implementations. - -The `TitleMapper` class maps a `ResultSet` to a `Title` domain object for each row in -the supplied `ResultSet`, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import java.sql.ResultSet; - import java.sql.SQLException; - import com.foo.domain.Title; - import org.springframework.jdbc.core.RowMapper; - - public final class TitleMapper implements RowMapper { - - public Title mapRow(ResultSet rs, int rowNum) throws SQLException { - Title title = new Title(); - title.setId(rs.getLong("id")); - title.setName(rs.getString("name")); - return title; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import java.sql.ResultSet - import com.foo.domain.Title - import org.springframework.jdbc.core.RowMapper - - class TitleMapper : RowMapper<Title> { - - override fun mapRow(rs: ResultSet, rowNum: Int) = - Title(rs.getLong("id"), rs.getString("name")) - } ----- - -The `GenreMapper` class maps a `ResultSet` to a `Genre` domain object for each row in -the supplied `ResultSet`, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import java.sql.ResultSet; - import java.sql.SQLException; - import com.foo.domain.Genre; - import org.springframework.jdbc.core.RowMapper; - - public final class GenreMapper implements RowMapper<Genre> { - - public Genre mapRow(ResultSet rs, int rowNum) throws SQLException { - return new Genre(rs.getString("name")); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import java.sql.ResultSet - import com.foo.domain.Genre - import org.springframework.jdbc.core.RowMapper - - class GenreMapper : RowMapper<Genre> { - - override fun mapRow(rs: ResultSet, rowNum: Int): Genre { - return Genre(rs.getString("name")) - } - } ----- - -To pass parameters to a stored procedure that has one or more input parameters in its -definition in the RDBMS, you can code a strongly typed `execute(..)` method that would -delegate to the untyped `execute(Map)` method in the superclass, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import java.sql.Types; - import java.util.Date; - import java.util.HashMap; - import java.util.Map; - import javax.sql.DataSource; - import oracle.jdbc.OracleTypes; - import org.springframework.jdbc.core.SqlOutParameter; - import org.springframework.jdbc.core.SqlParameter; - import org.springframework.jdbc.object.StoredProcedure; - - public class TitlesAfterDateStoredProcedure extends StoredProcedure { - - private static final String SPROC_NAME = "TitlesAfterDate"; - private static final String CUTOFF_DATE_PARAM = "cutoffDate"; - - public TitlesAfterDateStoredProcedure(DataSource dataSource) { - super(dataSource, SPROC_NAME); - declareParameter(new SqlParameter(CUTOFF_DATE_PARAM, Types.DATE); - declareParameter(new SqlOutParameter("titles", OracleTypes.CURSOR, new TitleMapper())); - compile(); - } - - public Map<String, Object> execute(Date cutoffDate) { - Map<String, Object> inputs = new HashMap<String, Object>(); - inputs.put(CUTOFF_DATE_PARAM, cutoffDate); - return super.execute(inputs); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import java.sql.Types - import java.util.Date - import javax.sql.DataSource - import oracle.jdbc.OracleTypes - import org.springframework.jdbc.core.SqlOutParameter - import org.springframework.jdbc.core.SqlParameter - import org.springframework.jdbc.`object`.StoredProcedure - - class TitlesAfterDateStoredProcedure(dataSource: DataSource) : StoredProcedure(dataSource, SPROC_NAME) { - - companion object { - private const val SPROC_NAME = "TitlesAfterDate" - private const val CUTOFF_DATE_PARAM = "cutoffDate" - } - - init { - declareParameter(SqlParameter(CUTOFF_DATE_PARAM, Types.DATE)) - declareParameter(SqlOutParameter("titles", OracleTypes.CURSOR, TitleMapper())) - compile() - } - - fun execute(cutoffDate: Date) = super.execute( - mapOf<String, Any>(CUTOFF_DATE_PARAM to cutoffDate)) - } ----- - - - -[[jdbc-parameter-handling]] -=== Common Problems with Parameter and Data Value Handling - -Common problems with parameters and data values exist in the different approaches -provided by Spring Framework's JDBC support. This section covers how to address them. - - -[[jdbc-type-information]] -==== Providing SQL Type Information for Parameters - -Usually, Spring determines the SQL type of the parameters based on the type of parameter -passed in. It is possible to explicitly provide the SQL type to be used when setting -parameter values. This is sometimes necessary to correctly set `NULL` values. - -You can provide SQL type information in several ways: - -* Many update and query methods of the `JdbcTemplate` take an additional parameter in - the form of an `int` array. This array is used to indicate the SQL type of the - corresponding parameter by using constant values from the `java.sql.Types` class. Provide - one entry for each parameter. -* You can use the `SqlParameterValue` class to wrap the parameter value that needs this - additional information. To do so, create a new instance for each value and pass in the SQL type - and the parameter value in the constructor. You can also provide an optional scale - parameter for numeric values. -* For methods that work with named parameters, you can use the `SqlParameterSource` classes, - `BeanPropertySqlParameterSource` or `MapSqlParameterSource`. They both have methods - for registering the SQL type for any of the named parameter values. - - -[[jdbc-lob]] -==== Handling BLOB and CLOB objects - -You can store images, other binary data, and large chunks of text in the database. These -large objects are called BLOBs (Binary Large OBject) for binary data and CLOBs (Character -Large OBject) for character data. In Spring, you can handle these large objects by using -the `JdbcTemplate` directly and also when using the higher abstractions provided by RDBMS -Objects and the `SimpleJdbc` classes. All of these approaches use an implementation of -the `LobHandler` interface for the actual management of the LOB (Large OBject) data. -`LobHandler` provides access to a `LobCreator` class, through the `getLobCreator` method, -that is used for creating new LOB objects to be inserted. - -`LobCreator` and `LobHandler` provide the following support for LOB input and output: - -* BLOB -** `byte[]`: `getBlobAsBytes` and `setBlobAsBytes` -** `InputStream`: `getBlobAsBinaryStream` and `setBlobAsBinaryStream` -* CLOB -** `String`: `getClobAsString` and `setClobAsString` -** `InputStream`: `getClobAsAsciiStream` and `setClobAsAsciiStream` -** `Reader`: `getClobAsCharacterStream` and `setClobAsCharacterStream` - -The next example shows how to create and insert a BLOB. Later we show how to read -it back from the database. - -This example uses a `JdbcTemplate` and an implementation of the -`AbstractLobCreatingPreparedStatementCallback`. It implements one method, -`setValues`. This method provides a `LobCreator` that we use to set the values for the -LOB columns in your SQL insert statement. - -For this example, we assume that there is a variable, `lobHandler`, that is already -set to an instance of a `DefaultLobHandler`. You typically set this value through -dependency injection. - -The following example shows how to create and insert a BLOB: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - final File blobIn = new File("spring2004.jpg"); - final InputStream blobIs = new FileInputStream(blobIn); - final File clobIn = new File("large.txt"); - final InputStream clobIs = new FileInputStream(clobIn); - final InputStreamReader clobReader = new InputStreamReader(clobIs); - - jdbcTemplate.execute( - "INSERT INTO lob_table (id, a_clob, a_blob) VALUES (?, ?, ?)", - new AbstractLobCreatingPreparedStatementCallback(lobHandler) { // <1> - protected void setValues(PreparedStatement ps, LobCreator lobCreator) throws SQLException { - ps.setLong(1, 1L); - lobCreator.setClobAsCharacterStream(ps, 2, clobReader, (int)clobIn.length()); // <2> - lobCreator.setBlobAsBinaryStream(ps, 3, blobIs, (int)blobIn.length()); // <3> - } - } - ); - - blobIs.close(); - clobReader.close(); ----- -<1> Pass in the `lobHandler` that (in this example) is a plain `DefaultLobHandler`. -<2> Using the method `setClobAsCharacterStream` to pass in the contents of the CLOB. -<3> Using the method `setBlobAsBinaryStream` to pass in the contents of the BLOB. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val blobIn = File("spring2004.jpg") - val blobIs = FileInputStream(blobIn) - val clobIn = File("large.txt") - val clobIs = FileInputStream(clobIn) - val clobReader = InputStreamReader(clobIs) - - jdbcTemplate.execute( - "INSERT INTO lob_table (id, a_clob, a_blob) VALUES (?, ?, ?)", - object: AbstractLobCreatingPreparedStatementCallback(lobHandler) { // <1> - override fun setValues(ps: PreparedStatement, lobCreator: LobCreator) { - ps.setLong(1, 1L) - lobCreator.setClobAsCharacterStream(ps, 2, clobReader, clobIn.length().toInt()) // <2> - lobCreator.setBlobAsBinaryStream(ps, 3, blobIs, blobIn.length().toInt()) // <3> - } - } - ) - blobIs.close() - clobReader.close() ----- -<1> Pass in the `lobHandler` that (in this example) is a plain `DefaultLobHandler`. -<2> Using the method `setClobAsCharacterStream` to pass in the contents of the CLOB. -<3> Using the method `setBlobAsBinaryStream` to pass in the contents of the BLOB. - - -[NOTE] -==== -If you invoke the `setBlobAsBinaryStream`, `setClobAsAsciiStream`, or -`setClobAsCharacterStream` method on the `LobCreator` returned from -`DefaultLobHandler.getLobCreator()`, you can optionally specify a negative value for the -`contentLength` argument. If the specified content length is negative, the -`DefaultLobHandler` uses the JDBC 4.0 variants of the set-stream methods without a -length parameter. Otherwise, it passes the specified length on to the driver. - -See the documentation for the JDBC driver you use to verify that it supports streaming a -LOB without providing the content length. -==== - -Now it is time to read the LOB data from the database. Again, you use a `JdbcTemplate` -with the same instance variable `lobHandler` and a reference to a `DefaultLobHandler`. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - List<Map<String, Object>> l = jdbcTemplate.query("select id, a_clob, a_blob from lob_table", - new RowMapper<Map<String, Object>>() { - public Map<String, Object> mapRow(ResultSet rs, int i) throws SQLException { - Map<String, Object> results = new HashMap<String, Object>(); - String clobText = lobHandler.getClobAsString(rs, "a_clob"); // <1> - results.put("CLOB", clobText); - byte[] blobBytes = lobHandler.getBlobAsBytes(rs, "a_blob"); // <2> - results.put("BLOB", blobBytes); - return results; - } - }); ----- -<1> Using the method `getClobAsString` to retrieve the contents of the CLOB. -<2> Using the method `getBlobAsBytes` to retrieve the contents of the BLOB. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val l = jdbcTemplate.query("select id, a_clob, a_blob from lob_table") { rs, _ -> - val clobText = lobHandler.getClobAsString(rs, "a_clob") // <1> - val blobBytes = lobHandler.getBlobAsBytes(rs, "a_blob") // <2> - mapOf("CLOB" to clobText, "BLOB" to blobBytes) - } ----- -<1> Using the method `getClobAsString` to retrieve the contents of the CLOB. -<2> Using the method `getBlobAsBytes` to retrieve the contents of the BLOB. - - -[[jdbc-in-clause]] -==== Passing in Lists of Values for IN Clause - -The SQL standard allows for selecting rows based on an expression that includes a -variable list of values. A typical example would be `select * from T_ACTOR where id in -(1, 2, 3)`. This variable list is not directly supported for prepared statements by the -JDBC standard. You cannot declare a variable number of placeholders. You need a number -of variations with the desired number of placeholders prepared, or you need to generate -the SQL string dynamically once you know how many placeholders are required. The named -parameter support provided in the `NamedParameterJdbcTemplate` and `JdbcTemplate` takes -the latter approach. You can pass in the values as a `java.util.List` of primitive objects. This -list is used to insert the required placeholders and pass in the values during -statement execution. - -NOTE: Be careful when passing in many values. The JDBC standard does not guarantee that you -can use more than 100 values for an `in` expression list. Various databases exceed this -number, but they usually have a hard limit for how many values are allowed. For example, Oracle's -limit is 1000. - -In addition to the primitive values in the value list, you can create a `java.util.List` -of object arrays. This list can support multiple expressions being defined for the `in` -clause, such as `+++select * from T_ACTOR where (id, last_name) in ((1, 'Johnson'), (2, -'Harrop'))+++`. This, of course, requires that your database supports this syntax. - - -[[jdbc-complex-types]] -==== Handling Complex Types for Stored Procedure Calls - -When you call stored procedures, you can sometimes use complex types specific to the -database. To accommodate these types, Spring provides a `SqlReturnType` for handling -them when they are returned from the stored procedure call and `SqlTypeValue` when they -are passed in as a parameter to the stored procedure. - -The `SqlReturnType` interface has a single method (named `getTypeValue`) that must be -implemented. This interface is used as part of the declaration of an `SqlOutParameter`. -The following example shows returning the value of an Oracle `STRUCT` object of the user -declared type `ITEM_TYPE`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class TestItemStoredProcedure extends StoredProcedure { - - public TestItemStoredProcedure(DataSource dataSource) { - // ... - declareParameter(new SqlOutParameter("item", OracleTypes.STRUCT, "ITEM_TYPE", - (CallableStatement cs, int colIndx, int sqlType, String typeName) -> { - STRUCT struct = (STRUCT) cs.getObject(colIndx); - Object[] attr = struct.getAttributes(); - TestItem item = new TestItem(); - item.setId(((Number) attr[0]).longValue()); - item.setDescription((String) attr[1]); - item.setExpirationDate((java.util.Date) attr[2]); - return item; - })); - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class TestItemStoredProcedure(dataSource: DataSource) : StoredProcedure() { - - init { - // ... - declareParameter(SqlOutParameter("item", OracleTypes.STRUCT, "ITEM_TYPE") { cs, colIndx, sqlType, typeName -> - val struct = cs.getObject(colIndx) as STRUCT - val attr = struct.getAttributes() - TestItem((attr[0] as Long, attr[1] as String, attr[2] as Date) - }) - // ... - } - } ----- - -You can use `SqlTypeValue` to pass the value of a Java object (such as `TestItem`) to a -stored procedure. The `SqlTypeValue` interface has a single method (named -`createTypeValue`) that you must implement. The active connection is passed in, and you -can use it to create database-specific objects, such as `StructDescriptor` instances -or `ArrayDescriptor` instances. The following example creates a `StructDescriptor` instance: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - final TestItem testItem = new TestItem(123L, "A test item", - new SimpleDateFormat("yyyy-M-d").parse("2010-12-31")); - - SqlTypeValue value = new AbstractSqlTypeValue() { - protected Object createTypeValue(Connection conn, int sqlType, String typeName) throws SQLException { - StructDescriptor itemDescriptor = new StructDescriptor(typeName, conn); - Struct item = new STRUCT(itemDescriptor, conn, - new Object[] { - testItem.getId(), - testItem.getDescription(), - new java.sql.Date(testItem.getExpirationDate().getTime()) - }); - return item; - } - }; ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val (id, description, expirationDate) = TestItem(123L, "A test item", - SimpleDateFormat("yyyy-M-d").parse("2010-12-31")) - - val value = object : AbstractSqlTypeValue() { - override fun createTypeValue(conn: Connection, sqlType: Int, typeName: String?): Any { - val itemDescriptor = StructDescriptor(typeName, conn) - return STRUCT(itemDescriptor, conn, - arrayOf(id, description, java.sql.Date(expirationDate.time))) - } - } ----- - -You can now add this `SqlTypeValue` to the `Map` that contains the input parameters for the -`execute` call of the stored procedure. - -Another use for the `SqlTypeValue` is passing in an array of values to an Oracle stored -procedure. Oracle has its own internal `ARRAY` class that must be used in this case, and -you can use the `SqlTypeValue` to create an instance of the Oracle `ARRAY` and populate -it with values from the Java `ARRAY`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - final Long[] ids = new Long[] {1L, 2L}; - - SqlTypeValue value = new AbstractSqlTypeValue() { - protected Object createTypeValue(Connection conn, int sqlType, String typeName) throws SQLException { - ArrayDescriptor arrayDescriptor = new ArrayDescriptor(typeName, conn); - ARRAY idArray = new ARRAY(arrayDescriptor, conn, ids); - return idArray; - } - }; ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class TestItemStoredProcedure(dataSource: DataSource) : StoredProcedure() { - - init { - val ids = arrayOf(1L, 2L) - val value = object : AbstractSqlTypeValue() { - override fun createTypeValue(conn: Connection, sqlType: Int, typeName: String?): Any { - val arrayDescriptor = ArrayDescriptor(typeName, conn) - return ARRAY(arrayDescriptor, conn, ids) - } - } - } - } ----- - - - -[[jdbc-embedded-database-support]] -=== Embedded Database Support - -The `org.springframework.jdbc.datasource.embedded` package provides support for embedded -Java database engines. Support for https://www.hsqldb.org[HSQL], -https://www.h2database.com[H2], and https://db.apache.org/derby[Derby] is provided -natively. You can also use an extensible API to plug in new embedded database types and -`DataSource` implementations. - - -[[jdbc-why-embedded-database]] -==== Why Use an Embedded Database? - -An embedded database can be useful during the development phase of a project because of its -lightweight nature. Benefits include ease of configuration, quick startup time, -testability, and the ability to rapidly evolve your SQL during development. - - -[[jdbc-embedded-database-xml]] -==== Creating an Embedded Database by Using Spring XML - -If you want to expose an embedded database instance as a bean in a Spring -`ApplicationContext`, you can use the `embedded-database` tag in the `spring-jdbc` namespace: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <jdbc:embedded-database id="dataSource" generate-name="true"> - <jdbc:script location="classpath:schema.sql"/> - <jdbc:script location="classpath:test-data.sql"/> - </jdbc:embedded-database> ----- - -The preceding configuration creates an embedded HSQL database that is populated with SQL from -the `schema.sql` and `test-data.sql` resources in the root of the classpath. In addition, as -a best practice, the embedded database is assigned a uniquely generated name. The -embedded database is made available to the Spring container as a bean of type -`javax.sql.DataSource` that can then be injected into data access objects as needed. - - -[[jdbc-embedded-database-java]] -==== Creating an Embedded Database Programmatically - -The `EmbeddedDatabaseBuilder` class provides a fluent API for constructing an embedded -database programmatically. You can use this when you need to create an embedded database in a -stand-alone environment or in a stand-alone integration test, as in the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - EmbeddedDatabase db = new EmbeddedDatabaseBuilder() - .generateUniqueName(true) - .setType(H2) - .setScriptEncoding("UTF-8") - .ignoreFailedDrops(true) - .addScript("schema.sql") - .addScripts("user_data.sql", "country_data.sql") - .build(); - - // perform actions against the db (EmbeddedDatabase extends javax.sql.DataSource) - - db.shutdown() ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val db = EmbeddedDatabaseBuilder() - .generateUniqueName(true) - .setType(H2) - .setScriptEncoding("UTF-8") - .ignoreFailedDrops(true) - .addScript("schema.sql") - .addScripts("user_data.sql", "country_data.sql") - .build() - - // perform actions against the db (EmbeddedDatabase extends javax.sql.DataSource) - - db.shutdown() ----- - -See the {api-spring-framework}/jdbc/datasource/embedded/EmbeddedDatabaseBuilder.html[javadoc for `EmbeddedDatabaseBuilder`] -for further details on all supported options. - -You can also use the `EmbeddedDatabaseBuilder` to create an embedded database by using Java -configuration, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class DataSourceConfig { - - @Bean - public DataSource dataSource() { - return new EmbeddedDatabaseBuilder() - .generateUniqueName(true) - .setType(H2) - .setScriptEncoding("UTF-8") - .ignoreFailedDrops(true) - .addScript("schema.sql") - .addScripts("user_data.sql", "country_data.sql") - .build(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class DataSourceConfig { - - @Bean - fun dataSource(): DataSource { - return EmbeddedDatabaseBuilder() - .generateUniqueName(true) - .setType(H2) - .setScriptEncoding("UTF-8") - .ignoreFailedDrops(true) - .addScript("schema.sql") - .addScripts("user_data.sql", "country_data.sql") - .build() - } - } ----- - - -[[jdbc-embedded-database-types]] -==== Selecting the Embedded Database Type - -This section covers how to select one of the three embedded databases that Spring -supports. It includes the following topics: - -* <<jdbc-embedded-database-using-HSQL>> -* <<jdbc-embedded-database-using-H2>> -* <<jdbc-embedded-database-using-Derby>> - -[[jdbc-embedded-database-using-HSQL]] -===== Using HSQL - -Spring supports HSQL 1.8.0 and above. HSQL is the default embedded database if no type is -explicitly specified. To specify HSQL explicitly, set the `type` attribute of the -`embedded-database` tag to `HSQL`. If you use the builder API, call the -`setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.HSQL`. - -[[jdbc-embedded-database-using-H2]] -===== Using H2 - -Spring supports the H2 database. To enable H2, set the `type` attribute of the -`embedded-database` tag to `H2`. If you use the builder API, call the -`setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.H2`. - -[[jdbc-embedded-database-using-Derby]] -===== Using Derby - -Spring supports Apache Derby 10.5 and above. To enable Derby, set the `type` -attribute of the `embedded-database` tag to `DERBY`. If you use the builder API, -call the `setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.DERBY`. - - -[[jdbc-embedded-database-dao-testing]] -==== Testing Data Access Logic with an Embedded Database - -Embedded databases provide a lightweight way to test data access code. The next example is a -data access integration test template that uses an embedded database. Using such a template -can be useful for one-offs when the embedded database does not need to be reused across test -classes. However, if you wish to create an embedded database that is shared within a test suite, -consider using the <<testing.adoc#testcontext-framework, Spring TestContext Framework>> and -configuring the embedded database as a bean in the Spring `ApplicationContext` as described -in <<jdbc-embedded-database-xml>> and <<jdbc-embedded-database-java>>. The following listing -shows the test template: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class DataAccessIntegrationTestTemplate { - - private EmbeddedDatabase db; - - @BeforeEach - public void setUp() { - // creates an HSQL in-memory database populated from default scripts - // classpath:schema.sql and classpath:data.sql - db = new EmbeddedDatabaseBuilder() - .generateUniqueName(true) - .addDefaultScripts() - .build(); - } - - @Test - public void testDataAccess() { - JdbcTemplate template = new JdbcTemplate(db); - template.query( /* ... */ ); - } - - @AfterEach - public void tearDown() { - db.shutdown(); - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class DataAccessIntegrationTestTemplate { - - private lateinit var db: EmbeddedDatabase - - @BeforeEach - fun setUp() { - // creates an HSQL in-memory database populated from default scripts - // classpath:schema.sql and classpath:data.sql - db = EmbeddedDatabaseBuilder() - .generateUniqueName(true) - .addDefaultScripts() - .build() - } - - @Test - fun testDataAccess() { - val template = JdbcTemplate(db) - template.query( /* ... */) - } - - @AfterEach - fun tearDown() { - db.shutdown() - } - } ----- - - -[[jdbc-embedded-database-unique-names]] -==== Generating Unique Names for Embedded Databases - -Development teams often encounter errors with embedded databases if their test suite -inadvertently attempts to recreate additional instances of the same database. This can -happen quite easily if an XML configuration file or `@Configuration` class is responsible -for creating an embedded database and the corresponding configuration is then reused -across multiple testing scenarios within the same test suite (that is, within the same JVM -process) -- for example, integration tests against embedded databases whose -`ApplicationContext` configuration differs only with regard to which bean definition -profiles are active. - -The root cause of such errors is the fact that Spring's `EmbeddedDatabaseFactory` (used -internally by both the `<jdbc:embedded-database>` XML namespace element and the -`EmbeddedDatabaseBuilder` for Java configuration) sets the name of the embedded database to -`testdb` if not otherwise specified. For the case of `<jdbc:embedded-database>`, the -embedded database is typically assigned a name equal to the bean's `id` (often, -something like `dataSource`). Thus, subsequent attempts to create an embedded database -do not result in a new database. Instead, the same JDBC connection URL is reused, -and attempts to create a new embedded database actually point to an existing -embedded database created from the same configuration. - -To address this common issue, Spring Framework 4.2 provides support for generating -unique names for embedded databases. To enable the use of generated names, use one of -the following options. - -* `EmbeddedDatabaseFactory.setGenerateUniqueDatabaseName()` -* `EmbeddedDatabaseBuilder.generateUniqueName()` -* `<jdbc:embedded-database generate-name="true" ... >` - - -[[jdbc-embedded-database-extension]] -==== Extending the Embedded Database Support - -You can extend Spring JDBC embedded database support in two ways: - -* Implement `EmbeddedDatabaseConfigurer` to support a new embedded database type. -* Implement `DataSourceFactory` to support a new `DataSource` implementation, such as a - connection pool to manage embedded database connections. - -We encourage you to contribute extensions to the Spring community at -https://github.com/spring-projects/spring-framework/issues[GitHub Issues]. - - - -[[jdbc-initializing-datasource]] -=== Initializing a `DataSource` - -The `org.springframework.jdbc.datasource.init` package provides support for initializing -an existing `DataSource`. The embedded database support provides one option for creating -and initializing a `DataSource` for an application. However, you may sometimes need to initialize -an instance that runs on a server somewhere. - - -[[jdbc-initializing-datasource-xml]] -==== Initializing a Database by Using Spring XML - -If you want to initialize a database and you can provide a reference to a `DataSource` -bean, you can use the `initialize-database` tag in the `spring-jdbc` namespace: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <jdbc:initialize-database data-source="dataSource"> - <jdbc:script location="classpath:com/foo/sql/db-schema.sql"/> - <jdbc:script location="classpath:com/foo/sql/db-test-data.sql"/> - </jdbc:initialize-database> ----- - -The preceding example runs the two specified scripts against the database. The first -script creates a schema, and the second populates tables with a test data set. The script -locations can also be patterns with wildcards in the usual Ant style used for resources -in Spring (for example, -`classpath{asterisk}:/com/foo/{asterisk}{asterisk}/sql/{asterisk}-data.sql`). If you use a -pattern, the scripts are run in the lexical order of their URL or filename. - -The default behavior of the database initializer is to unconditionally run the provided -scripts. This may not always be what you want -- for instance, if you run -the scripts against a database that already has test data in it. The likelihood -of accidentally deleting data is reduced by following the common pattern (shown earlier) -of creating the tables first and then inserting the data. The first step fails if -the tables already exist. - -However, to gain more control over the creation and deletion of existing data, the XML -namespace provides a few additional options. The first is a flag to switch the -initialization on and off. You can set this according to the environment (such as pulling a -boolean value from system properties or from an environment bean). The following example gets a value from a system property: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <jdbc:initialize-database data-source="dataSource" - enabled="#{systemProperties.INITIALIZE_DATABASE}"> <1> - <jdbc:script location="..."/> - </jdbc:initialize-database> ----- -<1> Get the value for `enabled` from a system property called `INITIALIZE_DATABASE`. - - -The second option to control what happens with existing data is to be more tolerant of -failures. To this end, you can control the ability of the initializer to ignore certain -errors in the SQL it runs from the scripts, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <jdbc:initialize-database data-source="dataSource" ignore-failures="DROPS"> - <jdbc:script location="..."/> - </jdbc:initialize-database> ----- - -In the preceding example, we are saying that we expect that, sometimes, the scripts are run -against an empty database, and there are some `DROP` statements in the scripts that -would, therefore, fail. So failed SQL `DROP` statements will be ignored, but other failures -will cause an exception. This is useful if your SQL dialect doesn't support `DROP ... IF -EXISTS` (or similar) but you want to unconditionally remove all test data before -re-creating it. In that case the first script is usually a set of `DROP` statements, -followed by a set of `CREATE` statements. - -The `ignore-failures` option can be set to `NONE` (the default), `DROPS` (ignore failed -drops), or `ALL` (ignore all failures). - -Each statement should be separated by `;` or a new line if the `;` character is not -present at all in the script. You can control that globally or script by script, as the -following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <jdbc:initialize-database data-source="dataSource" separator="@@"> <1> - <jdbc:script location="classpath:com/myapp/sql/db-schema.sql" separator=";"/> <2> - <jdbc:script location="classpath:com/myapp/sql/db-test-data-1.sql"/> - <jdbc:script location="classpath:com/myapp/sql/db-test-data-2.sql"/> - </jdbc:initialize-database> ----- -<1> Set the separator scripts to `@@`. -<2> Set the separator for `db-schema.sql` to `;`. - -In this example, the two `test-data` scripts use `@@` as statement separator and only -the `db-schema.sql` uses `;`. This configuration specifies that the default separator -is `@@` and overrides that default for the `db-schema` script. - -If you need more control than you get from the XML namespace, you can use the -`DataSourceInitializer` directly and define it as a component in your application. - -[[jdbc-client-component-initialization]] -===== Initialization of Other Components that Depend on the Database - -A large class of applications (those that do not use the database until after the Spring context has -started) can use the database initializer with no further -complications. If your application is not one of those, you might need to read the rest -of this section. - -The database initializer depends on a `DataSource` instance and runs the scripts -provided in its initialization callback (analogous to an `init-method` in an XML bean -definition, a `@PostConstruct` method in a component, or the `afterPropertiesSet()` -method in a component that implements `InitializingBean`). If other beans depend on the -same data source and use the data source in an initialization callback, there -might be a problem because the data has not yet been initialized. A common example of -this is a cache that initializes eagerly and loads data from the database on application -startup. - -To get around this issue, you have two options: change your cache initialization strategy -to a later phase or ensure that the database initializer is initialized first. - -Changing your cache initialization strategy might be easy if the application is in your control and not otherwise. -Some suggestions for how to implement this include: - -* Make the cache initialize lazily on first usage, which improves application startup - time. -* Have your cache or a separate component that initializes the cache implement - `Lifecycle` or `SmartLifecycle`. When the application context starts, you can - automatically start a `SmartLifecycle` by setting its `autoStartup` flag, and you can - manually start a `Lifecycle` by calling `ConfigurableApplicationContext.start()` - on the enclosing context. -* Use a Spring `ApplicationEvent` or similar custom observer mechanism to trigger the - cache initialization. `ContextRefreshedEvent` is always published by the context when - it is ready for use (after all beans have been initialized), so that is often a useful - hook (this is how the `SmartLifecycle` works by default). - -Ensuring that the database initializer is initialized first can also be easy. Some suggestions on how to implement this include: - -* Rely on the default behavior of the Spring `BeanFactory`, which is that beans are - initialized in registration order. You can easily arrange that by adopting the common - practice of a set of `<import/>` elements in XML configuration that order your - application modules and ensuring that the database and database initialization are - listed first. -* Separate the `DataSource` and the business components that use it and control their - startup order by putting them in separate `ApplicationContext` instances (for example, the - parent context contains the `DataSource`, and the child context contains the business - components). This structure is common in Spring web applications but can be more - generally applied. - - - -[[r2dbc]] -== Data Access with R2DBC - -https://r2dbc.io[R2DBC] ("Reactive Relational Database Connectivity") is a community-driven -specification effort to standardize access to SQL databases using reactive patterns. - - -[[r2dbc-packages]] -=== Package Hierarchy - -The Spring Framework's R2DBC abstraction framework consists of two different packages: - -* `core`: The `org.springframework.r2dbc.core` package contains the `DatabaseClient` -class plus a variety of related classes. See <<r2dbc-core>>. - -* `connection`: The `org.springframework.r2dbc.connection` package contains a utility class -for easy `ConnectionFactory` access and various simple `ConnectionFactory` implementations -that you can use for testing and running unmodified R2DBC. See <<r2dbc-connections>>. - - -[[r2dbc-core]] -=== Using the R2DBC Core Classes to Control Basic R2DBC Processing and Error Handling - -This section covers how to use the R2DBC core classes to control basic R2DBC processing, -including error handling. It includes the following topics: - -* <<r2dbc-DatabaseClient>> -* <<r2dbc-DatabaseClient-examples-statement>> -* <<r2dbc-DatabaseClient-examples-query>> -* <<r2dbc-DatabaseClient-examples-update>> -* <<r2dbc-DatabaseClient-filter>> -* <<r2dbc-auto-generated-keys>> - -[[r2dbc-DatabaseClient]] -==== Using `DatabaseClient` - -`DatabaseClient` is the central class in the R2DBC core package. It handles the -creation and release of resources, which helps to avoid common errors, such as -forgetting to close the connection. It performs the basic tasks of the core R2DBC -workflow (such as statement creation and execution), leaving application code to provide -SQL and extract results. The `DatabaseClient` class: - -* Runs SQL queries -* Update statements and stored procedure calls -* Performs iteration over `Result` instances -* Catches R2DBC exceptions and translates them to the generic, more informative, exception -hierarchy defined in the `org.springframework.dao` package. (See <<dao-exceptions>>.) - -The client has a functional, fluent API using reactive types for declarative composition. - -When you use the `DatabaseClient` for your code, you need only to implement -`java.util.function` interfaces, giving them a clearly defined contract. -Given a `Connection` provided by the `DatabaseClient` class, a `Function` -callback creates a `Publisher`. The same is true for mapping functions that -extract a `Row` result. - -You can use `DatabaseClient` within a DAO implementation through direct instantiation -with a `ConnectionFactory` reference, or you can configure it in a Spring IoC container -and give it to DAOs as a bean reference. - -The simplest way to create a `DatabaseClient` object is through a static factory method, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - DatabaseClient client = DatabaseClient.create(connectionFactory); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val client = DatabaseClient.create(connectionFactory) ----- - -NOTE: The `ConnectionFactory` should always be configured as a bean in the Spring IoC -container. - -The preceding method creates a `DatabaseClient` with default settings. - -You can also obtain a `Builder` instance from `DatabaseClient.builder()`. -You can customize the client by calling the following methods: - -* `….bindMarkers(…)`: Supply a specific `BindMarkersFactory` to configure named -parameter to database bind marker translation. -* `….executeFunction(…)`: Set the `ExecuteFunction` how `Statement` objects get - run. -* `….namedParameters(false)`: Disable named parameter expansion. Enabled by default. - -TIP: Dialects are resolved by {api-spring-framework}/r2dbc/core/binding/BindMarkersFactoryResolver.html[`BindMarkersFactoryResolver`] - from a `ConnectionFactory`, typically by inspecting `ConnectionFactoryMetadata`. - + -You can let Spring auto-discover your `BindMarkersFactory` by registering a -class that implements `org.springframework.r2dbc.core.binding.BindMarkersFactoryResolver$BindMarkerFactoryProvider` -through `META-INF/spring.factories`. -`BindMarkersFactoryResolver` discovers bind marker provider implementations from -the class path using Spring's `SpringFactoriesLoader`. - + - -Currently supported databases are: - -* H2 -* MariaDB -* Microsoft SQL Server -* MySQL -* Postgres - -All SQL issued by this class is logged at the `DEBUG` level under the category -corresponding to the fully qualified class name of the client instance (typically -`DefaultDatabaseClient`). Additionally, each execution registers a checkpoint in -the reactive sequence to aid debugging. - -The following sections provide some examples of `DatabaseClient` usage. These examples -are not an exhaustive list of all of the functionality exposed by the `DatabaseClient`. -See the attendant {api-spring-framework}/r2dbc/core/DatabaseClient.html[javadoc] for that. - -[[r2dbc-DatabaseClient-examples-statement]] -===== Executing Statements - -`DatabaseClient` provides the basic functionality of running a statement. -The following example shows what you need to include for minimal but fully functional -code that creates a new table: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<Void> completion = client.sql("CREATE TABLE person (id VARCHAR(255) PRIMARY KEY, name VARCHAR(255), age INTEGER);") - .then(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - client.sql("CREATE TABLE person (id VARCHAR(255) PRIMARY KEY, name VARCHAR(255), age INTEGER);") - .await() ----- - -`DatabaseClient` is designed for convenient, fluent usage. -It exposes intermediate, continuation, and terminal methods at each stage of the -execution specification. The preceding example above uses `then()` to return a completion -`Publisher` that completes as soon as the query (or queries, if the SQL query contains -multiple statements) completes. - -NOTE: `execute(…)` accepts either the SQL query string or a query `Supplier<String>` -to defer the actual query creation until execution. - -[[r2dbc-DatabaseClient-examples-query]] -===== Querying (`SELECT`) - -SQL queries can return values through `Row` objects or the number of affected rows. -`DatabaseClient` can return the number of updated rows or the rows themselves, -depending on the issued query. - -The following query gets the `id` and `name` columns from a table: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<Map<String, Object>> first = client.sql("SELECT id, name FROM person") - .fetch().first(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val first = client.sql("SELECT id, name FROM person") - .fetch().awaitSingle() ----- - -The following query uses a bind variable: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<Map<String, Object>> first = client.sql("SELECT id, name FROM person WHERE first_name = :fn") - .bind("fn", "Joe") - .fetch().first(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val first = client.sql("SELECT id, name FROM person WHERE first_name = :fn") - .bind("fn", "Joe") - .fetch().awaitSingle() ----- - -You might have noticed the use of `fetch()` in the example above. `fetch()` is a -continuation operator that lets you specify how much data you want to consume. - -Calling `first()` returns the first row from the result and discards remaining rows. -You can consume data with the following operators: - -* `first()` return the first row of the entire result. Its Kotlin Coroutine variant -is named `awaitSingle()` for non-nullable return values and `awaitSingleOrNull()` -if the value is optional. -* `one()` returns exactly one result and fails if the result contains more rows. -Using Kotlin Coroutines, `awaitOne()` for exactly one value or `awaitOneOrNull()` -if the value may be `null`. -* `all()` returns all rows of the result. When using Kotlin Coroutines, use `flow()`. -* `rowsUpdated()` returns the number of affected rows (`INSERT`/`UPDATE`/`DELETE` -count). Its Kotlin Coroutine variant is named `awaitRowsUpdated()`. - -Without specifying further mapping details, queries return tabular results -as `Map` whose keys are case-insensitive column names that map to their column value. - -You can take control over result mapping by supplying a `Function<Row, T>` that gets -called for each `Row` so it can return arbitrary values (singular values, -collections and maps, and objects). - -The following example extracts the `name` column and emits its value: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Flux<String> names = client.sql("SELECT name FROM person") - .map(row -> row.get("name", String.class)) - .all(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val names = client.sql("SELECT name FROM person") - .map{ row: Row -> row.get("name", String.class) } - .flow() ----- - - -[[r2dbc-DatabaseClient-mapping-null]] -.What about `null`? -**** -Relational database results can contain `null` values. -The Reactive Streams specification forbids the emission of `null` values. -That requirement mandates proper `null` handling in the extractor function. -While you can obtain `null` values from a `Row`, you must not emit a `null` -value. You must wrap any `null` values in an object (for example, `Optional` -for singular values) to make sure a `null` value is never returned directly -by your extractor function. -**** - -[[r2dbc-DatabaseClient-examples-update]] -===== Updating (`INSERT`, `UPDATE`, and `DELETE`) with `DatabaseClient` - -The only difference of modifying statements is that these statements typically -do not return tabular data so you use `rowsUpdated()` to consume results. - -The following example shows an `UPDATE` statement that returns the number -of updated rows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<Integer> affectedRows = client.sql("UPDATE person SET first_name = :fn") - .bind("fn", "Joe") - .fetch().rowsUpdated(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val affectedRows = client.sql("UPDATE person SET first_name = :fn") - .bind("fn", "Joe") - .fetch().awaitRowsUpdated() ----- - -[[r2dbc-DatabaseClient-named-parameters]] -===== Binding Values to Queries - -A typical application requires parameterized SQL statements to select or -update rows according to some input. These are typically `SELECT` statements -constrained by a `WHERE` clause or `INSERT` and `UPDATE` statements that accept -input parameters. Parameterized statements bear the risk of SQL injection if -parameters are not escaped properly. `DatabaseClient` leverages R2DBC's -`bind` API to eliminate the risk of SQL injection for query parameters. -You can provide a parameterized SQL statement with the `execute(…)` operator -and bind parameters to the actual `Statement`. Your R2DBC driver then runs -the statement by using prepared statements and parameter substitution. - -Parameter binding supports two binding strategies: - -* By Index, using zero-based parameter indexes. -* By Name, using the placeholder name. - -The following example shows parameter binding for a query: - -==== -[source,java] ----- -db.sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)") - .bind("id", "joe") - .bind("name", "Joe") - .bind("age", 34); ----- -==== - -.R2DBC Native Bind Markers -**** -R2DBC uses database-native bind markers that depend on the actual database vendor. -As an example, Postgres uses indexed markers, such as `$1`, `$2`, `$n`. -Another example is SQL Server, which uses named bind markers prefixed with `@`. - -This is different from JDBC, which requires `?` as bind markers. -In JDBC, the actual drivers translate `?` bind markers to database-native -markers as part of their statement execution. - -Spring Framework's R2DBC support lets you use native bind markers or named bind -markers with the `:name` syntax. - -Named parameter support leverages a `BindMarkersFactory` instance to expand named -parameters to native bind markers at the time of query execution, which gives you -a certain degree of query portability across various database vendors. -**** - -The query-preprocessor unrolls named `Collection` parameters into a series of bind -markers to remove the need of dynamic query creation based on the number of arguments. -Nested object arrays are expanded to allow usage of (for example) select lists. - -Consider the following query: - -[source,sql] ----- -SELECT id, name, state FROM table WHERE (name, age) IN (('John', 35), ('Ann', 50)) ----- - -The preceding query can be parameterized and run as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - List<Object[]> tuples = new ArrayList<>(); - tuples.add(new Object[] {"John", 35}); - tuples.add(new Object[] {"Ann", 50}); - - client.sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)") - .bind("tuples", tuples); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val tuples: MutableList<Array<Any>> = ArrayList() - tuples.add(arrayOf("John", 35)) - tuples.add(arrayOf("Ann", 50)) - - client.sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)") - .bind("tuples", tuples) ----- - -NOTE: Usage of select lists is vendor-dependent. - -The following example shows a simpler variant using `IN` predicates: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - client.sql("SELECT id, name, state FROM table WHERE age IN (:ages)") - .bind("ages", Arrays.asList(35, 50)); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val tuples: MutableList<Array<Any>> = ArrayList() - tuples.add(arrayOf("John", 35)) - tuples.add(arrayOf("Ann", 50)) - - client.sql("SELECT id, name, state FROM table WHERE age IN (:ages)") - .bind("tuples", arrayOf(35, 50)) ----- - -NOTE: R2DBC itself does not support Collection-like values. Nevertheless, -expanding a given `List` in the example above works for named parameters -in Spring's R2DBC support, e.g. for use in `IN` clauses as shown above. -However, inserting or updating array-typed columns (e.g. in Postgres) -requires an array type that is supported by the underlying R2DBC driver: -typically a Java array, e.g. `String[]` to update a `text[]` column. -Do not pass `Collection<String>` or the like as an array parameter. - -[[r2dbc-DatabaseClient-filter]] -===== Statement Filters - -Sometimes it you need to fine-tune options on the actual `Statement` -before it gets run. Register a `Statement` filter -(`StatementFilterFunction`) through `DatabaseClient` to intercept and -modify statements in their execution, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") - .filter((s, next) -> next.execute(s.returnGeneratedValues("id"))) - .bind("name", …) - .bind("state", …); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") - .filter { s: Statement, next: ExecuteFunction -> next.execute(s.returnGeneratedValues("id")) } - .bind("name", …) - .bind("state", …) ----- - -`DatabaseClient` exposes also simplified `filter(…)` overload accepting `Function<Statement, Statement>`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") - .filter(statement -> s.returnGeneratedValues("id")); - - client.sql("SELECT id, name, state FROM table") - .filter(statement -> s.fetchSize(25)); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") - .filter { statement -> s.returnGeneratedValues("id") } - - client.sql("SELECT id, name, state FROM table") - .filter { statement -> s.fetchSize(25) } ----- - -`StatementFilterFunction` implementations allow filtering of the -`Statement` and filtering of `Result` objects. - -[[r2dbc-DatabaseClient-idioms]] -===== `DatabaseClient` Best Practices - -Instances of the `DatabaseClient` class are thread-safe, once configured. This is -important because it means that you can configure a single instance of a `DatabaseClient` -and then safely inject this shared reference into multiple DAOs (or repositories). -The `DatabaseClient` is stateful, in that it maintains a reference to a `ConnectionFactory`, -but this state is not conversational state. - -A common practice when using the `DatabaseClient` class is to configure a `ConnectionFactory` -in your Spring configuration file and then dependency-inject -that shared `ConnectionFactory` bean into your DAO classes. The `DatabaseClient` is created in -the setter for the `ConnectionFactory`. This leads to DAOs that resemble the following: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class R2dbcCorporateEventDao implements CorporateEventDao { - - private DatabaseClient databaseClient; - - public void setConnectionFactory(ConnectionFactory connectionFactory) { - this.databaseClient = DatabaseClient.create(connectionFactory); - } - - // R2DBC-backed implementations of the methods on the CorporateEventDao follow... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class R2dbcCorporateEventDao(connectionFactory: ConnectionFactory) : CorporateEventDao { - - private val databaseClient = DatabaseClient.create(connectionFactory) - - // R2DBC-backed implementations of the methods on the CorporateEventDao follow... - } ----- --- - -An alternative to explicit configuration is to use component-scanning and annotation -support for dependency injection. In this case, you can annotate the class with `@Component` -(which makes it a candidate for component-scanning) and annotate the `ConnectionFactory` setter -method with `@Autowired`. The following example shows how to do so: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component // <1> - public class R2dbcCorporateEventDao implements CorporateEventDao { - - private DatabaseClient databaseClient; - - @Autowired // <2> - public void setConnectionFactory(ConnectionFactory connectionFactory) { - this.databaseClient = DatabaseClient.create(connectionFactory); // <3> - } - - // R2DBC-backed implementations of the methods on the CorporateEventDao follow... - } ----- -<1> Annotate the class with `@Component`. -<2> Annotate the `ConnectionFactory` setter method with `@Autowired`. -<3> Create a new `DatabaseClient` with the `ConnectionFactory`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component // <1> - class R2dbcCorporateEventDao(connectionFactory: ConnectionFactory) : CorporateEventDao { // <2> - - private val databaseClient = DatabaseClient(connectionFactory) // <3> - - // R2DBC-backed implementations of the methods on the CorporateEventDao follow... - } ----- -<1> Annotate the class with `@Component`. -<2> Constructor injection of the `ConnectionFactory`. -<3> Create a new `DatabaseClient` with the `ConnectionFactory`. --- - -Regardless of which of the above template initialization styles you choose to use (or -not), it is seldom necessary to create a new instance of a `DatabaseClient` class each -time you want to run SQL. Once configured, a `DatabaseClient` instance is thread-safe. -If your application accesses multiple -databases, you may want multiple `DatabaseClient` instances, which requires multiple -`ConnectionFactory` and, subsequently, multiple differently configured `DatabaseClient` -instances. - -[[r2dbc-auto-generated-keys]] -=== Retrieving Auto-generated Keys - -`INSERT` statements may generate keys when inserting rows into a table -that defines an auto-increment or identity column. To get full control over -the column name to generate, simply register a `StatementFilterFunction` that -requests the generated key for the desired column. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<Integer> generatedId = client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") - .filter(statement -> s.returnGeneratedValues("id")) - .map(row -> row.get("id", Integer.class)) - .first(); - - // generatedId emits the generated key once the INSERT statement has finished ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val generatedId = client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") - .filter { statement -> s.returnGeneratedValues("id") } - .map { row -> row.get("id", Integer.class) } - .awaitOne() - - // generatedId emits the generated key once the INSERT statement has finished ----- - - -[[r2dbc-connections]] -=== Controlling Database Connections - -This section covers: - -* <<r2dbc-ConnectionFactory>> -* <<r2dbc-ConnectionFactoryUtils>> -* <<r2dbc-SingleConnectionFactory>> -* <<r2dbc-TransactionAwareConnectionFactoryProxy>> -* <<r2dbc-R2dbcTransactionManager>> - - -[[r2dbc-ConnectionFactory]] -==== Using `ConnectionFactory` - -Spring obtains an R2DBC connection to the database through a `ConnectionFactory`. -A `ConnectionFactory` is part of the R2DBC specification and is a common entry-point -for drivers. It lets a container or a framework hide connection pooling -and transaction management issues from the application code. As a developer, -you need not know details about how to connect to the database. That is the -responsibility of the administrator who sets up the `ConnectionFactory`. You -most likely fill both roles as you develop and test code, but you do not -necessarily have to know how the production data source is configured. - -When you use Spring's R2DBC layer, you can configure your own with a -connection pool implementation provided by a third party. A popular -implementation is R2DBC Pool (`r2dbc-pool`). Implementations in the Spring -distribution are meant only for testing purposes and do not provide pooling. - -To configure a `ConnectionFactory`: - -. Obtain a connection with `ConnectionFactory` as you typically obtain an R2DBC `ConnectionFactory`. -. Provide an R2DBC URL -(See the documentation for your driver for the correct value). - -The following example shows how to configure a `ConnectionFactory`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ConnectionFactory factory = ConnectionFactories.get("r2dbc:h2:mem:///test?options=DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val factory = ConnectionFactories.get("r2dbc:h2:mem:///test?options=DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"); ----- - - -[[r2dbc-ConnectionFactoryUtils]] -==== Using `ConnectionFactoryUtils` - - -The `ConnectionFactoryUtils` class is a convenient and powerful helper class -that provides `static` methods to obtain connections from `ConnectionFactory` -and close connections (if necessary). - -It supports subscriber ``Context``-bound connections with, for example -`R2dbcTransactionManager`. - - -[[r2dbc-SingleConnectionFactory]] -==== Using `SingleConnectionFactory` - -The `SingleConnectionFactory` class is an implementation of `DelegatingConnectionFactory` -interface that wraps a single `Connection` that is not closed after each use. - -If any client code calls `close` on the assumption of a pooled connection (as when using -persistence tools), you should set the `suppressClose` property to `true`. This setting -returns a close-suppressing proxy that wraps the physical connection. Note that you can -no longer cast this to a native `Connection` or a similar object. - -`SingleConnectionFactory` is primarily a test class and may be used for specific requirements -such as pipelining if your R2DBC driver permits for such use. -In contrast to a pooled `ConnectionFactory`, it reuses the same connection all the time, avoiding -excessive creation of physical connections. - - -[[r2dbc-TransactionAwareConnectionFactoryProxy]] -==== Using `TransactionAwareConnectionFactoryProxy` - -`TransactionAwareConnectionFactoryProxy` is a proxy for a target `ConnectionFactory`. -The proxy wraps that target `ConnectionFactory` to add awareness of Spring-managed transactions. - -NOTE: Using this class is required if you use a R2DBC client that is not integrated otherwise -with Spring's R2DBC support. In this case, you can still use this client and, at -the same time, have this client participating in Spring managed transactions. It is generally -preferable to integrate a R2DBC client with proper access to `ConnectionFactoryUtils` -for resource management. - -See the {api-spring-framework}/r2dbc/connection/TransactionAwareConnectionFactoryProxy.html[`TransactionAwareConnectionFactoryProxy`] -javadoc for more details. - - -[[r2dbc-R2dbcTransactionManager]] -==== Using `R2dbcTransactionManager` - -The `R2dbcTransactionManager` class is a `ReactiveTransactionManager` implementation for -single R2DBC data sources. It binds an R2DBC connection from the specified connection factory -to the subscriber `Context`, potentially allowing for one subscriber connection for each -connection factory. - -Application code is required to retrieve the R2DBC connection through -`ConnectionFactoryUtils.getConnection(ConnectionFactory)`, instead of R2DBC's standard -`ConnectionFactory.create()`. - -All framework classes (such as `DatabaseClient`) use this strategy implicitly. -If not used with this transaction manager, the lookup strategy behaves exactly like the common one. -Thus, it can be used in any case. - -The `R2dbcTransactionManager` class supports custom isolation levels that get applied to the connection. - - - -[[orm]] -== Object Relational Mapping (ORM) Data Access - -This section covers data access when you use Object Relational Mapping (ORM). - - - -[[orm-introduction]] -=== Introduction to ORM with Spring - -The Spring Framework supports integration with the Java Persistence API (JPA) and -supports native Hibernate for resource management, data access object (DAO) implementations, -and transaction strategies. For example, for Hibernate, there is first-class support with -several convenient IoC features that address many typical Hibernate integration issues. -You can configure all of the supported features for OR (object relational) mapping -tools through Dependency Injection. They can participate in Spring's resource and -transaction management, and they comply with Spring's generic transaction and DAO -exception hierarchies. The recommended integration style is to code DAOs against plain -Hibernate or JPA APIs. - -Spring adds significant enhancements to the ORM layer of your choice when you create -data access applications. You can leverage as much of the integration support as you -wish, and you should compare this integration effort with the cost and risk of building -a similar infrastructure in-house. You can use much of the ORM support as you would a -library, regardless of technology, because everything is designed as a set of reusable -JavaBeans. ORM in a Spring IoC container facilitates configuration and deployment. Thus, -most examples in this section show configuration inside a Spring container. - -The benefits of using the Spring Framework to create your ORM DAOs include: - -* *Easier testing.* Spring's IoC approach makes it easy to swap the implementations - and configuration locations of Hibernate `SessionFactory` instances, JDBC `DataSource` - instances, transaction managers, and mapped object implementations (if needed). This - in turn makes it much easier to test each piece of persistence-related code in - isolation. -* *Common data access exceptions.* Spring can wrap exceptions from your ORM tool, - converting them from proprietary (potentially checked) exceptions to a common runtime - `DataAccessException` hierarchy. This feature lets you handle most persistence - exceptions, which are non-recoverable, only in the appropriate layers, without - annoying boilerplate catches, throws, and exception declarations. You can still trap - and handle exceptions as necessary. Remember that JDBC exceptions (including - DB-specific dialects) are also converted to the same hierarchy, meaning that you can - perform some operations with JDBC within a consistent programming model. -* *General resource management.* Spring application contexts can handle the location - and configuration of Hibernate `SessionFactory` instances, JPA `EntityManagerFactory` - instances, JDBC `DataSource` instances, and other related resources. This makes these - values easy to manage and change. Spring offers efficient, easy, and safe handling of - persistence resources. For example, related code that uses Hibernate generally needs to - use the same Hibernate `Session` to ensure efficiency and proper transaction handling. - Spring makes it easy to create and bind a `Session` to the current thread transparently, - by exposing a current `Session` through the Hibernate `SessionFactory`. Thus, Spring - solves many chronic problems of typical Hibernate usage, for any local or JTA - transaction environment. -* *Integrated transaction management.* You can wrap your ORM code with a declarative, - aspect-oriented programming (AOP) style method interceptor either through the - `@Transactional` annotation or by explicitly configuring the transaction AOP advice in - an XML configuration file. In both cases, transaction semantics and exception handling - (rollback and so on) are handled for you. As discussed in <<orm-resource-mngmnt>>, - you can also swap various transaction managers, without affecting your ORM-related code. - For example, you can swap between local transactions and JTA, with the same full services - (such as declarative transactions) available in both scenarios. Additionally, - JDBC-related code can fully integrate transactionally with the code you use to do ORM. - This is useful for data access that is not suitable for ORM (such as batch processing and - BLOB streaming) but that still needs to share common transactions with ORM operations. - -TIP: For more comprehensive ORM support, including support for alternative database -technologies such as MongoDB, you might want to check out the -https://projects.spring.io/spring-data/[Spring Data] suite of projects. If you are -a JPA user, the https://spring.io/guides/gs/accessing-data-jpa/[Getting Started Accessing -Data with JPA] guide from https://spring.io provides a great introduction. - - - -[[orm-general]] -=== General ORM Integration Considerations - -This section highlights considerations that apply to all ORM technologies. -The <<orm-hibernate>> section provides more details and also show these features and -configurations in a concrete context. - -The major goal of Spring's ORM integration is clear application layering (with any data -access and transaction technology) and for loose coupling of application objects -- no -more business service dependencies on the data access or transaction strategy, no more -hard-coded resource lookups, no more hard-to-replace singletons, no more custom service -registries. The goal is to have one simple and consistent approach to wiring up application objects, keeping -them as reusable and free from container dependencies as possible. All the individual -data access features are usable on their own but integrate nicely with Spring's -application context concept, providing XML-based configuration and cross-referencing of -plain JavaBean instances that need not be Spring-aware. In a typical Spring application, -many important objects are JavaBeans: data access templates, data access objects, -transaction managers, business services that use the data access objects and transaction -managers, web view resolvers, web controllers that use the business services, and so on. - - -[[orm-resource-mngmnt]] -==== Resource and Transaction Management - -Typical business applications are cluttered with repetitive resource management code. -Many projects try to invent their own solutions, sometimes sacrificing proper handling -of failures for programming convenience. Spring advocates simple solutions for proper -resource handling, namely IoC through templating in the case of JDBC and applying AOP -interceptors for the ORM technologies. - -The infrastructure provides proper resource handling and appropriate conversion of -specific API exceptions to an unchecked infrastructure exception hierarchy. Spring -introduces a DAO exception hierarchy, applicable to any data access strategy. For direct -JDBC, the `JdbcTemplate` class mentioned in a <<jdbc-JdbcTemplate, previous section>> -provides connection handling and proper conversion of `SQLException` to the -`DataAccessException` hierarchy, including translation of database-specific SQL error -codes to meaningful exception classes. For ORM technologies, see the -<<orm-exception-translation, next section>> for how to get the same exception -translation benefits. - -When it comes to transaction management, the `JdbcTemplate` class hooks in to the Spring -transaction support and supports both JTA and JDBC transactions, through respective -Spring transaction managers. For the supported ORM technologies, Spring offers Hibernate -and JPA support through the Hibernate and JPA transaction managers as well as JTA support. -For details on transaction support, see the <<transaction>> chapter. - - -[[orm-exception-translation]] -==== Exception Translation - -When you use Hibernate or JPA in a DAO, you must decide how to handle the persistence -technology's native exception classes. The DAO throws a subclass of a `HibernateException` -or `PersistenceException`, depending on the technology. These exceptions are all runtime -exceptions and do not have to be declared or caught. You may also have to deal with -`IllegalArgumentException` and `IllegalStateException`. This means that callers can only -treat exceptions as being generally fatal, unless they want to depend on the persistence -technology's own exception structure. Catching specific causes (such as an optimistic -locking failure) is not possible without tying the caller to the implementation strategy. -This trade-off might be acceptable to applications that are strongly ORM-based or -do not need any special exception treatment (or both). However, Spring lets exception -translation be applied transparently through the `@Repository` annotation. The following -examples (one for Java configuration and one for XML configuration) show how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Repository - public class ProductDaoImpl implements ProductDao { - - // class body here... - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Repository - class ProductDaoImpl : ProductDao { - - // class body here... - - } ----- - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <!-- Exception translation bean post processor --> - <bean class="org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor"/> - - <bean id="myProductDao" class="product.ProductDaoImpl"/> - - </beans> ----- - -The postprocessor automatically looks for all exception translators (implementations of -the `PersistenceExceptionTranslator` interface) and advises all beans marked with the -`@Repository` annotation so that the discovered translators can intercept and apply the -appropriate translation on the thrown exceptions. - -In summary, you can implement DAOs based on the plain persistence technology's API and -annotations while still benefiting from Spring-managed transactions, dependency -injection, and transparent exception conversion (if desired) to Spring's custom -exception hierarchies. - - - -[[orm-hibernate]] -=== Hibernate - -We start with a coverage of https://hibernate.org/[Hibernate 5] in a Spring environment, -using it to demonstrate the approach that Spring takes towards integrating OR mappers. -This section covers many issues in detail and shows different variations of DAO -implementations and transaction demarcation. Most of these patterns can be directly -translated to all other supported ORM tools. The later sections in this chapter then -cover the other ORM technologies and show brief examples. - -NOTE: As of Spring Framework 5.3, Spring requires Hibernate ORM 5.2+ for Spring's -`HibernateJpaVendorAdapter` as well as for a native Hibernate `SessionFactory` setup. -It is strongly recommended to go with Hibernate ORM 5.4 for a newly started application. -For use with `HibernateJpaVendorAdapter`, Hibernate Search needs to be upgraded to 5.11.6. - - -[[orm-session-factory-setup]] -==== `SessionFactory` Setup in a Spring Container - -To avoid tying application objects to hard-coded resource lookups, you can define -resources (such as a JDBC `DataSource` or a Hibernate `SessionFactory`) as beans in the -Spring container. Application objects that need to access resources receive references -to such predefined instances through bean references, as illustrated in the DAO -definition in the <<orm-hibernate-straight, next section>>. - -The following excerpt from an XML application context definition shows how to set up a -JDBC `DataSource` and a Hibernate `SessionFactory` on top of it: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="myDataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close"> - <property name="driverClassName" value="org.hsqldb.jdbcDriver"/> - <property name="url" value="jdbc:hsqldb:hsql://localhost:9001"/> - <property name="username" value="sa"/> - <property name="password" value=""/> - </bean> - - <bean id="mySessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactoryBean"> - <property name="dataSource" ref="myDataSource"/> - <property name="mappingResources"> - <list> - <value>product.hbm.xml</value> - </list> - </property> - <property name="hibernateProperties"> - <value> - hibernate.dialect=org.hibernate.dialect.HSQLDialect - </value> - </property> - </bean> - - </beans> ----- - -Switching from a local Jakarta Commons DBCP `BasicDataSource` to a JNDI-located -`DataSource` (usually managed by an application server) is only a matter of -configuration, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <jee:jndi-lookup id="myDataSource" jndi-name="java:comp/env/jdbc/myds"/> - </beans> ----- - -You can also access a JNDI-located `SessionFactory`, using Spring's -`JndiObjectFactoryBean` / `<jee:jndi-lookup>` to retrieve and expose it. -However, that is typically not common outside of an EJB context. - -[NOTE] -==== -Spring also provides a `LocalSessionFactoryBuilder` variant, seamlessly integrating -with `@Bean` style configuration and programmatic setup (no `FactoryBean` involved). - -Both `LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background -bootstrapping, with Hibernate initialization running in parallel to the application -bootstrap thread on a given bootstrap executor (such as a `SimpleAsyncTaskExecutor`). -On `LocalSessionFactoryBean`, this is available through the `bootstrapExecutor` -property. On the programmatic `LocalSessionFactoryBuilder`, there is an overloaded -`buildSessionFactory` method that takes a bootstrap executor argument. - -As of Spring Framework 5.1, such a native Hibernate setup can also expose a JPA -`EntityManagerFactory` for standard JPA interaction next to native Hibernate access. -See <<orm-jpa-hibernate, Native Hibernate Setup for JPA>> for details. -==== - - -[[orm-hibernate-straight]] -==== Implementing DAOs Based on the Plain Hibernate API - -Hibernate has a feature called contextual sessions, wherein Hibernate itself manages -one current `Session` per transaction. This is roughly equivalent to Spring's -synchronization of one Hibernate `Session` per transaction. A corresponding DAO -implementation resembles the following example, based on the plain Hibernate API: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ProductDaoImpl implements ProductDao { - - private SessionFactory sessionFactory; - - public void setSessionFactory(SessionFactory sessionFactory) { - this.sessionFactory = sessionFactory; - } - - public Collection loadProductsByCategory(String category) { - return this.sessionFactory.getCurrentSession() - .createQuery("from test.Product product where product.category=?") - .setParameter(0, category) - .list(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ProductDaoImpl(private val sessionFactory: SessionFactory) : ProductDao { - - fun loadProductsByCategory(category: String): Collection<*> { - return sessionFactory.currentSession - .createQuery("from test.Product product where product.category=?") - .setParameter(0, category) - .list() - } - } ----- - -This style is similar to that of the Hibernate reference documentation and examples, -except for holding the `SessionFactory` in an instance variable. We strongly recommend -such an instance-based setup over the old-school `static` `HibernateUtil` class from -Hibernate's CaveatEmptor sample application. (In general, do not keep any resources in -`static` variables unless absolutely necessary.) - -The preceding DAO example follows the dependency injection pattern. It fits nicely into a Spring IoC -container, as it would if coded against Spring's `HibernateTemplate`. -You can also set up such a DAO in plain Java (for example, in unit tests). To do so, -instantiate it and call `setSessionFactory(..)` with the desired factory reference. As a -Spring bean definition, the DAO would resemble the following: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="myProductDao" class="product.ProductDaoImpl"> - <property name="sessionFactory" ref="mySessionFactory"/> - </bean> - - </beans> ----- - -The main advantage of this DAO style is that it depends on Hibernate API only. No import -of any Spring class is required. This is appealing from a non-invasiveness -perspective and may feel more natural to Hibernate developers. - -However, the DAO throws plain `HibernateException` (which is unchecked, so it does not have -to be declared or caught), which means that callers can treat exceptions only as being -generally fatal -- unless they want to depend on Hibernate's own exception hierarchy. -Catching specific causes (such as an optimistic locking failure) is not possible without -tying the caller to the implementation strategy. This trade off might be acceptable to -applications that are strongly Hibernate-based, do not need any special exception -treatment, or both. - -Fortunately, Spring's `LocalSessionFactoryBean` supports Hibernate's -`SessionFactory.getCurrentSession()` method for any Spring transaction strategy, -returning the current Spring-managed transactional `Session`, even with -`HibernateTransactionManager`. The standard behavior of that method remains -to return the current `Session` associated with the ongoing JTA transaction, if any. -This behavior applies regardless of whether you use Spring's -`JtaTransactionManager`, EJB container managed transactions (CMTs), or JTA. - -In summary, you can implement DAOs based on the plain Hibernate API, while still being -able to participate in Spring-managed transactions. - - -[[orm-hibernate-tx-declarative]] -==== Declarative Transaction Demarcation - -We recommend that you use Spring's declarative transaction support, which lets you -replace explicit transaction demarcation API calls in your Java code with an AOP -transaction interceptor. You can configure this transaction interceptor in a Spring -container by using either Java annotations or XML. This declarative transaction capability -lets you keep business services free of repetitive transaction demarcation code and -focus on adding business logic, which is the real value of your application. - -NOTE: Before you continue, we are strongly encourage you to read <<transaction-declarative>> -if you have not already done so. - -You can annotate the service layer with `@Transactional` annotations and instruct the -Spring container to find these annotations and provide transactional semantics for -these annotated methods. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ProductServiceImpl implements ProductService { - - private ProductDao productDao; - - public void setProductDao(ProductDao productDao) { - this.productDao = productDao; - } - - @Transactional - public void increasePriceOfAllProductsInCategory(final String category) { - List productsToChange = this.productDao.loadProductsByCategory(category); - // ... - } - - @Transactional(readOnly = true) - public List<Product> findAllProducts() { - return this.productDao.findAllProducts(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ProductServiceImpl(private val productDao: ProductDao) : ProductService { - - @Transactional - fun increasePriceOfAllProductsInCategory(category: String) { - val productsToChange = productDao.loadProductsByCategory(category) - // ... - } - - @Transactional(readOnly = true) - fun findAllProducts() = productDao.findAllProducts() - } ----- - -In the container, you need to set up the `PlatformTransactionManager` implementation -(as a bean) and a `<tx:annotation-driven/>` entry, opting into `@Transactional` -processing at runtime. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <?xml version="1.0" encoding="UTF-8"?> - <beans xmlns="http://www.springframework.org/schema/beans" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xmlns:aop="http://www.springframework.org/schema/aop" - xmlns:tx="http://www.springframework.org/schema/tx" - xsi:schemaLocation=" - http://www.springframework.org/schema/beans - https://www.springframework.org/schema/beans/spring-beans.xsd - http://www.springframework.org/schema/tx - https://www.springframework.org/schema/tx/spring-tx.xsd - http://www.springframework.org/schema/aop - https://www.springframework.org/schema/aop/spring-aop.xsd"> - - <!-- SessionFactory, DataSource, etc. omitted --> - - <bean id="transactionManager" - class="org.springframework.orm.hibernate5.HibernateTransactionManager"> - <property name="sessionFactory" ref="sessionFactory"/> - </bean> - - <tx:annotation-driven/> - - <bean id="myProductService" class="product.SimpleProductService"> - <property name="productDao" ref="myProductDao"/> - </bean> - - </beans> ----- - - -[[orm-hibernate-tx-programmatic]] -==== Programmatic Transaction Demarcation - -You can demarcate transactions in a higher level of the application, on top of -lower-level data access services that span any number of operations. Nor do restrictions -exist on the implementation of the surrounding business service. It needs only a Spring -`PlatformTransactionManager`. Again, the latter can come from anywhere, but preferably -as a bean reference through a `setTransactionManager(..)` method. Also, the -`productDAO` should be set by a `setProductDao(..)` method. The following pair of snippets show -a transaction manager and a business service definition in a Spring application context -and an example for a business method implementation: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="myTxManager" class="org.springframework.orm.hibernate5.HibernateTransactionManager"> - <property name="sessionFactory" ref="mySessionFactory"/> - </bean> - - <bean id="myProductService" class="product.ProductServiceImpl"> - <property name="transactionManager" ref="myTxManager"/> - <property name="productDao" ref="myProductDao"/> - </bean> - - </beans> ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ProductServiceImpl implements ProductService { - - private TransactionTemplate transactionTemplate; - private ProductDao productDao; - - public void setTransactionManager(PlatformTransactionManager transactionManager) { - this.transactionTemplate = new TransactionTemplate(transactionManager); - } - - public void setProductDao(ProductDao productDao) { - this.productDao = productDao; - } - - public void increasePriceOfAllProductsInCategory(final String category) { - this.transactionTemplate.execute(new TransactionCallbackWithoutResult() { - public void doInTransactionWithoutResult(TransactionStatus status) { - List productsToChange = this.productDao.loadProductsByCategory(category); - // do the price increase... - } - }); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ProductServiceImpl(transactionManager: PlatformTransactionManager, - private val productDao: ProductDao) : ProductService { - - private val transactionTemplate = TransactionTemplate(transactionManager) - - fun increasePriceOfAllProductsInCategory(category: String) { - transactionTemplate.execute { - val productsToChange = productDao.loadProductsByCategory(category) - // do the price increase... - } - } - } ----- - -Spring's `TransactionInterceptor` lets any checked application exception be thrown -with the callback code, while `TransactionTemplate` is restricted to unchecked -exceptions within the callback. `TransactionTemplate` triggers a rollback in case of -an unchecked application exception or if the transaction is marked rollback-only by -the application (by setting `TransactionStatus`). By default, `TransactionInterceptor` -behaves the same way but allows configurable rollback policies per method. - - -[[orm-hibernate-tx-strategies]] -==== Transaction Management Strategies - -Both `TransactionTemplate` and `TransactionInterceptor` delegate the actual transaction -handling to a `PlatformTransactionManager` instance (which can be a -`HibernateTransactionManager` (for a single Hibernate `SessionFactory`) by using a -`ThreadLocal` `Session` under the hood) or a `JtaTransactionManager` (delegating to the -JTA subsystem of the container) for Hibernate applications. You can even use a custom -`PlatformTransactionManager` implementation. Switching from native Hibernate transaction -management to JTA (such as when facing distributed transaction requirements for certain -deployments of your application) is only a matter of configuration. You can replace -the Hibernate transaction manager with Spring's JTA transaction implementation. Both -transaction demarcation and data access code work without changes, because they -use the generic transaction management APIs. - -For distributed transactions across multiple Hibernate session factories, you can combine -`JtaTransactionManager` as a transaction strategy with multiple -`LocalSessionFactoryBean` definitions. Each DAO then gets one specific `SessionFactory` -reference passed into its corresponding bean property. If all underlying JDBC data -sources are transactional container ones, a business service can demarcate transactions -across any number of DAOs and any number of session factories without special regard, as -long as it uses `JtaTransactionManager` as the strategy. - -Both `HibernateTransactionManager` and `JtaTransactionManager` allow for proper -JVM-level cache handling with Hibernate, without container-specific transaction manager -lookup or a JCA connector (if you do not use EJB to initiate transactions). - -`HibernateTransactionManager` can export the Hibernate JDBC `Connection` to plain JDBC -access code for a specific `DataSource`. This ability allows for high-level -transaction demarcation with mixed Hibernate and JDBC data access completely without -JTA, provided you access only one database. `HibernateTransactionManager` automatically -exposes the Hibernate transaction as a JDBC transaction if you have set up the passed-in -`SessionFactory` with a `DataSource` through the `dataSource` property of the -`LocalSessionFactoryBean` class. Alternatively, you can specify explicitly the -`DataSource` for which the transactions are supposed to be exposed through the -`dataSource` property of the `HibernateTransactionManager` class. - - -[[orm-hibernate-resources]] -==== Comparing Container-managed and Locally Defined Resources - -You can switch between a container-managed JNDI `SessionFactory` and a locally defined -one without having to change a single line of application code. Whether to keep -resource definitions in the container or locally within the application is mainly a -matter of the transaction strategy that you use. Compared to a Spring-defined local -`SessionFactory`, a manually registered JNDI `SessionFactory` does not provide any -benefits. Deploying a `SessionFactory` through Hibernate's JCA connector provides the -added value of participating in the Jakarta EE server's management infrastructure, but does -not add actual value beyond that. - -Spring's transaction support is not bound to a container. When configured with any strategy -other than JTA, transaction support also works in a stand-alone or test environment. -Especially in the typical case of single-database transactions, Spring's single-resource -local transaction support is a lightweight and powerful alternative to JTA. When you use -local EJB stateless session beans to drive transactions, you depend both on an EJB -container and on JTA, even if you access only a single database and use only stateless -session beans to provide declarative transactions through container-managed -transactions. Direct use of JTA programmatically also requires a Jakarta EE environment. - -Spring-driven transactions can work as well with a locally defined Hibernate -`SessionFactory` as they do with a local JDBC `DataSource`, provided they access a -single database. Thus, you need only use Spring's JTA transaction strategy when you -have distributed transaction requirements. A JCA connector requires container-specific -deployment steps, and (obviously) JCA support in the first place. This configuration -requires more work than deploying a simple web application with local resource -definitions and Spring-driven transactions. - -All things considered, if you do not use EJBs, stick with local `SessionFactory` setup -and Spring's `HibernateTransactionManager` or `JtaTransactionManager`. You get all of -the benefits, including proper transactional JVM-level caching and distributed -transactions, without the inconvenience of container deployment. JNDI registration of a -Hibernate `SessionFactory` through the JCA connector adds value only when used in -conjunction with EJBs. - - -[[orm-hibernate-invalid-jdbc-access-error]] -==== Spurious Application Server Warnings with Hibernate - -In some JTA environments with very strict `XADataSource` implementations (currently -some WebLogic Server and WebSphere versions), when Hibernate is configured without -regard to the JTA transaction manager for that environment, spurious warnings or -exceptions can show up in the application server log. These warnings or exceptions -indicate that the connection being accessed is no longer valid or JDBC access is no -longer valid, possibly because the transaction is no longer active. As an example, -here is an actual exception from WebLogic: - -[literal] -[subs="verbatim,quotes"] ----- -java.sql.SQLException: The transaction is no longer active - status: 'Committed'. No -further JDBC access is allowed within this transaction. ----- - -Another common problem is a connection leak after JTA transactions, with Hibernate -sessions (and potentially underlying JDBC connections) not getting closed properly. - -You can resolve such issues by making Hibernate aware of the JTA transaction manager, -to which it synchronizes (along with Spring). You have two options for doing this: - -* Pass your Spring `JtaTransactionManager` bean to your Hibernate setup. The easiest - way is a bean reference into the `jtaTransactionManager` property for your - `LocalSessionFactoryBean` bean (see <<transaction-strategies-hibernate>>). - Spring then makes the corresponding JTA strategies available to Hibernate. -* You may also configure Hibernate's JTA-related properties explicitly, in particular - "hibernate.transaction.coordinator_class", "hibernate.connection.handling_mode" - and potentially "hibernate.transaction.jta.platform" in your "hibernateProperties" - on `LocalSessionFactoryBean` (see Hibernate's manual for details on those properties). - -The remainder of this section describes the sequence of events that occur with and -without Hibernate's awareness of the JTA `PlatformTransactionManager`. - -When Hibernate is not configured with any awareness of the JTA transaction manager, -the following events occur when a JTA transaction commits: - -* The JTA transaction commits. -* Spring's `JtaTransactionManager` is synchronized to the JTA transaction, so it is - called back through an `afterCompletion` callback by the JTA transaction manager. -* Among other activities, this synchronization can trigger a callback by Spring to - Hibernate, through Hibernate's `afterTransactionCompletion` callback (used to clear - the Hibernate cache), followed by an explicit `close()` call on the Hibernate session, - which causes Hibernate to attempt to `close()` the JDBC Connection. -* In some environments, this `Connection.close()` call then triggers the warning or - error, as the application server no longer considers the `Connection` to be usable, - because the transaction has already been committed. - -When Hibernate is configured with awareness of the JTA transaction manager, -the following events occur when a JTA transaction commits: - -* The JTA transaction is ready to commit. -* Spring's `JtaTransactionManager` is synchronized to the JTA transaction, so the - transaction is called back through a `beforeCompletion` callback by the JTA - transaction manager. -* Spring is aware that Hibernate itself is synchronized to the JTA transaction and - behaves differently than in the previous scenario. In particular, it aligns with - Hibernate's transactional resource management. -* The JTA transaction commits. -* Hibernate is synchronized to the JTA transaction, so the transaction is called back - through an `afterCompletion` callback by the JTA transaction manager and can - properly clear its cache. - - - -[[orm-jpa]] -=== JPA - -The Spring JPA, available under the `org.springframework.orm.jpa` package, offers -comprehensive support for the -https://www.oracle.com/technetwork/articles/javaee/jpa-137156.html[Java Persistence -API] in a manner similar to the integration with Hibernate while being aware of -the underlying implementation in order to provide additional features. - - -[[orm-jpa-setup]] -==== Three Options for JPA Setup in a Spring Environment - -The Spring JPA support offers three ways of setting up the JPA `EntityManagerFactory` -that is used by the application to obtain an entity manager. - -* <<orm-jpa-setup-lemfb>> -* <<orm-jpa-setup-jndi>> -* <<orm-jpa-setup-lcemfb>> - -[[orm-jpa-setup-lemfb]] -===== Using `LocalEntityManagerFactoryBean` - -You can use this option only in simple deployment environments such as stand-alone -applications and integration tests. - -The `LocalEntityManagerFactoryBean` creates an `EntityManagerFactory` suitable for -simple deployment environments where the application uses only JPA for data access. -The factory bean uses the JPA `PersistenceProvider` auto-detection mechanism (according -to JPA's Java SE bootstrapping) and, in most cases, requires you to specify only the -persistence unit name. The following XML example configures such a bean: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <bean id="myEmf" class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean"> - <property name="persistenceUnitName" value="myPersistenceUnit"/> - </bean> - </beans> ----- - -This form of JPA deployment is the simplest and the most limited. You cannot refer to an -existing JDBC `DataSource` bean definition, and no support for global transactions -exists. Furthermore, weaving (byte-code transformation) of persistent classes is -provider-specific, often requiring a specific JVM agent to be specified on startup. This -option is sufficient only for stand-alone applications and test environments, for which -the JPA specification is designed. - -[[orm-jpa-setup-jndi]] -===== Obtaining an EntityManagerFactory from JNDI - -You can use this option when deploying to a Jakarta EE server. Check your server's documentation -on how to deploy a custom JPA provider into your server, allowing for a different -provider than the server's default. - -Obtaining an `EntityManagerFactory` from JNDI (for example in a Jakarta EE environment), -is a matter of changing the XML configuration, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <jee:jndi-lookup id="myEmf" jndi-name="persistence/myPersistenceUnit"/> - </beans> ----- - -This action assumes standard Jakarta EE bootstrapping. The Jakarta EE server auto-detects -persistence units (in effect, `META-INF/persistence.xml` files in application jars) and -`persistence-unit-ref` entries in the Jakarta EE deployment descriptor (for example, -`web.xml`) and defines environment naming context locations for those persistence units. - -In such a scenario, the entire persistence unit deployment, including the weaving -(byte-code transformation) of persistent classes, is up to the Jakarta EE server. The JDBC -`DataSource` is defined through a JNDI location in the `META-INF/persistence.xml` file. -`EntityManager` transactions are integrated with the server's JTA subsystem. Spring merely -uses the obtained `EntityManagerFactory`, passing it on to application objects through -dependency injection and managing transactions for the persistence unit (typically -through `JtaTransactionManager`). - -If you use multiple persistence units in the same application, the bean names of such -JNDI-retrieved persistence units should match the persistence unit names that the -application uses to refer to them (for example, in `@PersistenceUnit` and -`@PersistenceContext` annotations). - -[[orm-jpa-setup-lcemfb]] -===== Using `LocalContainerEntityManagerFactoryBean` - -You can use this option for full JPA capabilities in a Spring-based application environment. -This includes web containers such as Tomcat, stand-alone applications, and -integration tests with sophisticated persistence requirements. - -NOTE: If you want to specifically configure a Hibernate setup, an immediate alternative -is to set up a native Hibernate `LocalSessionFactoryBean` instead of a plain JPA -`LocalContainerEntityManagerFactoryBean`, letting it interact with JPA access code -as well as native Hibernate access code. -See <<orm-jpa-hibernate, Native Hibernate setup for JPA interaction>> for details. - -The `LocalContainerEntityManagerFactoryBean` gives full control over -`EntityManagerFactory` configuration and is appropriate for environments where -fine-grained customization is required. The `LocalContainerEntityManagerFactoryBean` -creates a `PersistenceUnitInfo` instance based on the `persistence.xml` file, the -supplied `dataSourceLookup` strategy, and the specified `loadTimeWeaver`. It is, thus, -possible to work with custom data sources outside of JNDI and to control the weaving -process. The following example shows a typical bean definition for a -`LocalContainerEntityManagerFactoryBean`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <bean id="myEmf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> - <property name="dataSource" ref="someDataSource"/> - <property name="loadTimeWeaver"> - <bean class="org.springframework.instrument.classloading.InstrumentationLoadTimeWeaver"/> - </property> - </bean> - </beans> ----- - -The following example shows a typical `persistence.xml` file: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0"> - <persistence-unit name="myUnit" transaction-type="RESOURCE_LOCAL"> - <mapping-file>META-INF/orm.xml</mapping-file> - <exclude-unlisted-classes/> - </persistence-unit> - </persistence> ----- - -NOTE: The `<exclude-unlisted-classes/>` shortcut indicates that no scanning for -annotated entity classes is supposed to occur. An explicit 'true' value -(`<exclude-unlisted-classes>true</exclude-unlisted-classes/>`) also means no scan. -`<exclude-unlisted-classes>false</exclude-unlisted-classes/>` does trigger a scan. -However, we recommend omitting the `exclude-unlisted-classes` element -if you want entity class scanning to occur. - -Using the `LocalContainerEntityManagerFactoryBean` is the most powerful JPA setup -option, allowing for flexible local configuration within the application. It supports -links to an existing JDBC `DataSource`, supports both local and global transactions, and -so on. However, it also imposes requirements on the runtime environment, such as the -availability of a weaving-capable class loader if the persistence provider demands -byte-code transformation. - -This option may conflict with the built-in JPA capabilities of a Jakarta EE server. In a -full Jakarta EE environment, consider obtaining your `EntityManagerFactory` from JNDI. -Alternatively, specify a custom `persistenceXmlLocation` on your -`LocalContainerEntityManagerFactoryBean` definition (for example, -META-INF/my-persistence.xml) and include only a descriptor with that name in your -application jar files. Because the Jakarta EE server looks only for default -`META-INF/persistence.xml` files, it ignores such custom persistence units and, hence, -avoids conflicts with a Spring-driven JPA setup upfront. (This applies to Resin 3.1, for -example.) - -.When is load-time weaving required? -**** -Not all JPA providers require a JVM agent. Hibernate is an example of one that does not. -If your provider does not require an agent or you have other alternatives, such as -applying enhancements at build time through a custom compiler or an Ant task, you should not use the -load-time weaver. -**** - -The `LoadTimeWeaver` interface is a Spring-provided class that lets JPA -`ClassTransformer` instances be plugged in a specific manner, depending on whether the -environment is a web container or application server. Hooking `ClassTransformers` -through an -https://docs.oracle.com/javase/6/docs/api/java/lang/instrument/package-summary.html[agent] -is typically not efficient. The agents work against the entire virtual machine and -inspect every class that is loaded, which is usually undesirable in a production -server environment. - -Spring provides a number of `LoadTimeWeaver` implementations for various environments, -letting `ClassTransformer` instances be applied only for each class loader and not -for each VM. - -See the <<core.adoc#aop-aj-ltw-spring, Spring configuration>> in the AOP chapter for -more insight regarding the `LoadTimeWeaver` implementations and their setup, either -generic or customized to various platforms (such as Tomcat, JBoss and WebSphere). - -As described in <<core.adoc#aop-aj-ltw-spring, Spring configuration>>, you can configure -a context-wide `LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation or the -`context:load-time-weaver` XML element. Such a global weaver is automatically picked up -by all JPA `LocalContainerEntityManagerFactoryBean` instances. The following example -shows the preferred way of setting up a load-time weaver, delivering auto-detection -of the platform (e.g. Tomcat's weaving-capable class loader or Spring's JVM agent) -and automatic propagation of the weaver to all weaver-aware beans: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <context:load-time-weaver/> - <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> - ... - </bean> ----- - -However, you can, if needed, manually specify a dedicated weaver through the -`loadTimeWeaver` property, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> - <property name="loadTimeWeaver"> - <bean class="org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver"/> - </property> - </bean> ----- - -No matter how the LTW is configured, by using this technique, JPA applications relying on -instrumentation can run in the target platform (for example, Tomcat) without needing an agent. -This is especially important when the hosting applications rely on different JPA -implementations, because the JPA transformers are applied only at the class-loader level and -are, thus, isolated from each other. - -[[orm-jpa-setup-multiple]] -===== Dealing with Multiple Persistence Units - -For applications that rely on multiple persistence units locations (stored in various -JARS in the classpath, for example), Spring offers the `PersistenceUnitManager` to act as -a central repository and to avoid the persistence units discovery process, which can be -expensive. The default implementation lets multiple locations be specified. These locations are -parsed and later retrieved through the persistence unit name. (By default, the classpath -is searched for `META-INF/persistence.xml` files.) The following example configures -multiple locations: - -[source,xml,indent=0,subs="verbatim"] ----- - <bean id="pum" class="org.springframework.orm.jpa.persistenceunit.DefaultPersistenceUnitManager"> - <property name="persistenceXmlLocations"> - <list> - <value>org/springframework/orm/jpa/domain/persistence-multi.xml</value> - <value>classpath:/my/package/**/custom-persistence.xml</value> - <value>classpath*:META-INF/persistence.xml</value> - </list> - </property> - <property name="dataSources"> - <map> - <entry key="localDataSource" value-ref="local-db"/> - <entry key="remoteDataSource" value-ref="remote-db"/> - </map> - </property> - <!-- if no datasource is specified, use this one --> - <property name="defaultDataSource" ref="remoteDataSource"/> - </bean> - - <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> - <property name="persistenceUnitManager" ref="pum"/> - <property name="persistenceUnitName" value="myCustomUnit"/> - </bean> ----- - -The default implementation allows customization of the `PersistenceUnitInfo` instances -(before they are fed to the JPA provider) either declaratively (through its properties, which -affect all hosted units) or programmatically (through the -`PersistenceUnitPostProcessor`, which allows persistence unit selection). If no -`PersistenceUnitManager` is specified, one is created and used internally by -`LocalContainerEntityManagerFactoryBean`. - -[[orm-jpa-setup-background]] -===== Background Bootstrapping - -`LocalContainerEntityManagerFactoryBean` supports background bootstrapping through -the `bootstrapExecutor` property, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> - <property name="bootstrapExecutor"> - <bean class="org.springframework.core.task.SimpleAsyncTaskExecutor"/> - </property> - </bean> ----- - -The actual JPA provider bootstrapping is handed off to the specified executor and then, -running in parallel, to the application bootstrap thread. The exposed `EntityManagerFactory` -proxy can be injected into other application components and is even able to respond to -`EntityManagerFactoryInfo` configuration inspection. However, once the actual JPA provider -is being accessed by other components (for example, calling `createEntityManager`), those calls -block until the background bootstrapping has completed. In particular, when you use -Spring Data JPA, make sure to set up deferred bootstrapping for its repositories as well. - - -[[orm-jpa-dao]] -==== Implementing DAOs Based on JPA: `EntityManagerFactory` and `EntityManager` - -NOTE: Although `EntityManagerFactory` instances are thread-safe, `EntityManager` instances are -not. The injected JPA `EntityManager` behaves like an `EntityManager` fetched from an -application server's JNDI environment, as defined by the JPA specification. It delegates -all calls to the current transactional `EntityManager`, if any. Otherwise, it falls back -to a newly created `EntityManager` per operation, in effect making its usage thread-safe. - -It is possible to write code against the plain JPA without any Spring dependencies, by -using an injected `EntityManagerFactory` or `EntityManager`. Spring can understand the -`@PersistenceUnit` and `@PersistenceContext` annotations both at the field and the method level -if a `PersistenceAnnotationBeanPostProcessor` is enabled. The following example shows a plain JPA DAO implementation -that uses the `@PersistenceUnit` annotation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ProductDaoImpl implements ProductDao { - - private EntityManagerFactory emf; - - @PersistenceUnit - public void setEntityManagerFactory(EntityManagerFactory emf) { - this.emf = emf; - } - - public Collection loadProductsByCategory(String category) { - EntityManager em = this.emf.createEntityManager(); - try { - Query query = em.createQuery("from Product as p where p.category = ?1"); - query.setParameter(1, category); - return query.getResultList(); - } - finally { - if (em != null) { - em.close(); - } - } - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ProductDaoImpl : ProductDao { - - private lateinit var emf: EntityManagerFactory - - @PersistenceUnit - fun setEntityManagerFactory(emf: EntityManagerFactory) { - this.emf = emf - } - - fun loadProductsByCategory(category: String): Collection<*> { - val em = this.emf.createEntityManager() - val query = em.createQuery("from Product as p where p.category = ?1"); - query.setParameter(1, category); - return query.resultList; - } - } ----- - -The preceding DAO has no dependency on Spring and still fits nicely into a Spring -application context. Moreover, the DAO takes advantage of annotations to require the -injection of the default `EntityManagerFactory`, as the following example bean definition shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <!-- bean post-processor for JPA annotations --> - <bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/> - - <bean id="myProductDao" class="product.ProductDaoImpl"/> - - </beans> ----- - -As an alternative to explicitly defining a `PersistenceAnnotationBeanPostProcessor`, -consider using the Spring `context:annotation-config` XML element in your application -context configuration. Doing so automatically registers all Spring standard -post-processors for annotation-based configuration, including -`CommonAnnotationBeanPostProcessor` and so on. - -Consider the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <!-- post-processors for all standard config annotations --> - <context:annotation-config/> - - <bean id="myProductDao" class="product.ProductDaoImpl"/> - - </beans> ----- - -The main problem with such a DAO is that it always creates a new `EntityManager` through -the factory. You can avoid this by requesting a transactional `EntityManager` (also -called a "`shared EntityManager`" because it is a shared, thread-safe proxy for the actual -transactional EntityManager) to be injected instead of the factory. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class ProductDaoImpl implements ProductDao { - - @PersistenceContext - private EntityManager em; - - public Collection loadProductsByCategory(String category) { - Query query = em.createQuery("from Product as p where p.category = :category"); - query.setParameter("category", category); - return query.getResultList(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class ProductDaoImpl : ProductDao { - - @PersistenceContext - private lateinit var em: EntityManager - - fun loadProductsByCategory(category: String): Collection<*> { - val query = em.createQuery("from Product as p where p.category = :category") - query.setParameter("category", category) - return query.resultList - } - } ----- - -The `@PersistenceContext` annotation has an optional attribute called `type`, which defaults to -`PersistenceContextType.TRANSACTION`. You can use this default to receive a shared -`EntityManager` proxy. The alternative, `PersistenceContextType.EXTENDED`, is a completely -different affair. This results in a so-called extended `EntityManager`, which is not -thread-safe and, hence, must not be used in a concurrently accessed component, such as a -Spring-managed singleton bean. Extended `EntityManager` instances are only supposed to be used in -stateful components that, for example, reside in a session, with the lifecycle of the -`EntityManager` not tied to a current transaction but rather being completely up to the -application. - -.Method- and field-level Injection -**** -You can apply annotations that indicate dependency injections (such as `@PersistenceUnit` and -`@PersistenceContext`) on field or methods inside a class -- hence the -expressions "`method-level injection`" and "`field-level injection`". Field-level -annotations are concise and easier to use while method-level annotations allow for further -processing of the injected dependency. In both cases, the member visibility (public, -protected, or private) does not matter. - -What about class-level annotations? - -On the Jakarta EE platform, they are used for dependency declaration and not for resource -injection. -**** - -The injected `EntityManager` is Spring-managed (aware of the ongoing transaction). -Even though the new DAO implementation uses method-level -injection of an `EntityManager` instead of an `EntityManagerFactory`, no change is -required in the application context XML, due to annotation usage. - -The main advantage of this DAO style is that it depends only on the Java Persistence API. -No import of any Spring class is required. Moreover, as the JPA annotations are understood, -the injections are applied automatically by the Spring container. This is appealing from -a non-invasiveness perspective and can feel more natural to JPA developers. - - -[[orm-jpa-tx]] -==== Spring-driven JPA transactions - -NOTE: We strongly encourage you to read <<transaction-declarative>>, if you have not -already done so, to get more detailed coverage of Spring's declarative transaction support. - -The recommended strategy for JPA is local transactions through JPA's native transaction -support. Spring's `JpaTransactionManager` provides many capabilities known from local -JDBC transactions (such as transaction-specific isolation levels and resource-level -read-only optimizations) against any regular JDBC connection pool (no XA requirement). - -Spring JPA also lets a configured `JpaTransactionManager` expose a JPA transaction -to JDBC access code that accesses the same `DataSource`, provided that the registered -`JpaDialect` supports retrieval of the underlying JDBC `Connection`. -Spring provides dialects for the EclipseLink and Hibernate JPA implementations. -See the <<orm-jpa-dialect, next section>> for details on the `JpaDialect` mechanism. - -NOTE: As an immediate alternative, Spring's native `HibernateTransactionManager` is capable -of interacting with JPA access code, adapting to several Hibernate specifics and providing -JDBC interaction. This makes particular sense in combination with `LocalSessionFactoryBean` -setup. See <<orm-jpa-hibernate, Native Hibernate Setup for JPA Interaction>> for details. - - -[[orm-jpa-dialect]] -==== Understanding `JpaDialect` and `JpaVendorAdapter` - -As an advanced feature, `JpaTransactionManager` and subclasses of -`AbstractEntityManagerFactoryBean` allow a custom `JpaDialect` to be passed into the -`jpaDialect` bean property. A `JpaDialect` implementation can enable the following advanced -features supported by Spring, usually in a vendor-specific manner: - -* Applying specific transaction semantics (such as custom isolation level or transaction - timeout) -* Retrieving the transactional JDBC `Connection` (for exposure to JDBC-based DAOs) -* Advanced translation of `PersistenceExceptions` to Spring `DataAccessExceptions` - -This is particularly valuable for special transaction semantics and for advanced -translation of exception. The default implementation (`DefaultJpaDialect`) does -not provide any special abilities and, if the features listed earlier are required, you have -to specify the appropriate dialect. - -TIP: As an even broader provider adaptation facility primarily for Spring's full-featured -`LocalContainerEntityManagerFactoryBean` setup, `JpaVendorAdapter` combines the -capabilities of `JpaDialect` with other provider-specific defaults. Specifying a -`HibernateJpaVendorAdapter` or `EclipseLinkJpaVendorAdapter` is the most convenient -way of auto-configuring an `EntityManagerFactory` setup for Hibernate or EclipseLink, -respectively. Note that those provider adapters are primarily designed for use with -Spring-driven transaction management (that is, for use with `JpaTransactionManager`). - -See the {api-spring-framework}/orm/jpa/JpaDialect.html[`JpaDialect`] and -{api-spring-framework}/orm/jpa/JpaVendorAdapter.html[`JpaVendorAdapter`] javadoc for -more details of its operations and how they are used within Spring's JPA support. - - -[[orm-jpa-jta]] -==== Setting up JPA with JTA Transaction Management - -As an alternative to `JpaTransactionManager`, Spring also allows for multi-resource -transaction coordination through JTA, either in a Jakarta EE environment or with a -stand-alone transaction coordinator, such as Atomikos. Aside from choosing Spring's -`JtaTransactionManager` instead of `JpaTransactionManager`, you need to take few further -steps: - -* The underlying JDBC connection pools need to be XA-capable and be integrated with -your transaction coordinator. This is usually straightforward in a Jakarta EE environment, -exposing a different kind of `DataSource` through JNDI. See your application server -documentation for details. Analogously, a standalone transaction coordinator usually -comes with special XA-integrated `DataSource` variants. Again, check its documentation. - -* The JPA `EntityManagerFactory` setup needs to be configured for JTA. This is -provider-specific, typically through special properties to be specified as `jpaProperties` -on `LocalContainerEntityManagerFactoryBean`. In the case of Hibernate, these properties -are even version-specific. See your Hibernate documentation for details. - -* Spring's `HibernateJpaVendorAdapter` enforces certain Spring-oriented defaults, such -as the connection release mode, `on-close`, which matches Hibernate's own default in -Hibernate 5.0 but not any more in Hibernate 5.1+. For a JTA setup, make sure to declare -your persistence unit transaction type as "JTA". Alternatively, set Hibernate 5.2's -`hibernate.connection.handling_mode` property to -`DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT` to restore Hibernate's own default. -See <<orm-hibernate-invalid-jdbc-access-error>> for related notes. - -* Alternatively, consider obtaining the `EntityManagerFactory` from your application -server itself (that is, through a JNDI lookup instead of a locally declared -`LocalContainerEntityManagerFactoryBean`). A server-provided `EntityManagerFactory` -might require special definitions in your server configuration (making the deployment -less portable) but is set up for the server's JTA environment. - - -[[orm-jpa-hibernate]] -==== Native Hibernate Setup and Native Hibernate Transactions for JPA Interaction - -A native `LocalSessionFactoryBean` setup in combination with `HibernateTransactionManager` -allows for interaction with `@PersistenceContext` and other JPA access code. A Hibernate -`SessionFactory` natively implements JPA's `EntityManagerFactory` interface now -and a Hibernate `Session` handle natively is a JPA `EntityManager`. -Spring's JPA support facilities automatically detect native Hibernate sessions. - -Such native Hibernate setup can, therefore, serve as a replacement for a standard JPA -`LocalContainerEntityManagerFactoryBean` and `JpaTransactionManager` combination -in many scenarios, allowing for interaction with `SessionFactory.getCurrentSession()` -(and also `HibernateTemplate`) next to `@PersistenceContext EntityManager` within -the same local transaction. Such a setup also provides stronger Hibernate integration -and more configuration flexibility, because it is not constrained by JPA bootstrap contracts. - -You do not need `HibernateJpaVendorAdapter` configuration in such a scenario, -since Spring's native Hibernate setup provides even more features -(for example, custom Hibernate Integrator setup, Hibernate 5.3 bean container integration, -and stronger optimizations for read-only transactions). Last but not least, you can also -express native Hibernate setup through `LocalSessionFactoryBuilder`, -seamlessly integrating with `@Bean` style configuration (no `FactoryBean` involved). - -[NOTE] -==== -`LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background -bootstrapping, just as the JPA `LocalContainerEntityManagerFactoryBean` does. -See <<orm-jpa-setup-background, Background Bootstrapping>> for an introduction. - -On `LocalSessionFactoryBean`, this is available through the `bootstrapExecutor` -property. On the programmatic `LocalSessionFactoryBuilder`, an overloaded -`buildSessionFactory` method takes a bootstrap executor argument. -==== - - - - -[[oxm]] -== Marshalling XML by Using Object-XML Mappers - - - -[[oxm-introduction]] -=== Introduction - -This chapter, describes Spring's Object-XML Mapping support. Object-XML -Mapping (O-X mapping for short) is the act of converting an XML document to and from -an object. This conversion process is also known as XML Marshalling, or XML -Serialization. This chapter uses these terms interchangeably. - -Within the field of O-X mapping, a marshaller is responsible for serializing an -object (graph) to XML. In similar fashion, an unmarshaller deserializes the XML to -an object graph. This XML can take the form of a DOM document, an input or output -stream, or a SAX handler. - -Some of the benefits of using Spring for your O/X mapping needs are: - -* <<oxm-ease-of-configuration>> -* <<oxm-consistent-interfaces>> -* <<oxm-consistent-exception-hierarchy>> - - -[[oxm-ease-of-configuration]] -==== Ease of configuration - -Spring's bean factory makes it easy to configure marshallers, without needing to -construct JAXB context, JiBX binding factories, and so on. You can configure the marshallers -as you would any other bean in your application context. Additionally, XML namespace-based -configuration is available for a number of marshallers, making the configuration even -simpler. - - -[[oxm-consistent-interfaces]] -==== Consistent Interfaces - -Spring's O-X mapping operates through two global interfaces: {api-spring-framework}/oxm/Marshaller.html[`Marshaller`] and -{api-spring-framework}/oxm/Unmarshaller.html[`Unmarshaller`]. These abstractions let you switch O-X mapping frameworks -with relative ease, with little or no change required on the classes that do the -marshalling. This approach has the additional benefit of making it possible to do XML -marshalling with a mix-and-match approach (for example, some marshalling performed using JAXB -and some by XStream) in a non-intrusive fashion, letting you use the strength of each -technology. - - -[[oxm-consistent-exception-hierarchy]] -==== Consistent Exception Hierarchy - -Spring provides a conversion from exceptions from the underlying O-X mapping tool to its -own exception hierarchy with the `XmlMappingException` as the root exception. -These runtime exceptions wrap the original exception so that no information is lost. - - - -[[oxm-marshaller-unmarshaller]] -=== `Marshaller` and `Unmarshaller` - -As stated in the <<oxm-introduction, introduction>>, a marshaller serializes an object -to XML, and an unmarshaller deserializes XML stream to an object. This section describes -the two Spring interfaces used for this purpose. - - -[[oxm-marshaller]] -==== Understanding `Marshaller` - -Spring abstracts all marshalling operations behind the -`org.springframework.oxm.Marshaller` interface, the main method of which follows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface Marshaller { - - /** - * Marshal the object graph with the given root into the provided Result. - */ - void marshal(Object graph, Result result) throws XmlMappingException, IOException; - } ----- - -The `Marshaller` interface has one main method, which marshals the given object to a -given `javax.xml.transform.Result`. The result is a tagging interface that basically -represents an XML output abstraction. Concrete implementations wrap various XML -representations, as the following table indicates: - -[[oxm-marshaller-tbl]] -|=== -| Result implementation| Wraps XML representation - -| `DOMResult` -| `org.w3c.dom.Node` - -| `SAXResult` -| `org.xml.sax.ContentHandler` - -| `StreamResult` -| `java.io.File`, `java.io.OutputStream`, or `java.io.Writer` -|=== - -NOTE: Although the `marshal()` method accepts a plain object as its first parameter, most -`Marshaller` implementations cannot handle arbitrary objects. Instead, an object class -must be mapped in a mapping file, be marked with an annotation, be registered with the -marshaller, or have a common base class. Refer to the later sections in this chapter -to determine how your O-X technology manages this. - - -[[oxm-unmarshaller]] -==== Understanding `Unmarshaller` - -Similar to the `Marshaller`, we have the `org.springframework.oxm.Unmarshaller` -interface, which the following listing shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface Unmarshaller { - - /** - * Unmarshal the given provided Source into an object graph. - */ - Object unmarshal(Source source) throws XmlMappingException, IOException; - } ----- - -This interface also has one method, which reads from the given -`javax.xml.transform.Source` (an XML input abstraction) and returns the object read. As -with `Result`, `Source` is a tagging interface that has three concrete implementations. Each -wraps a different XML representation, as the following table indicates: - -[[oxm-unmarshaller-tbl]] -|=== -| Source implementation| Wraps XML representation - -| `DOMSource` -| `org.w3c.dom.Node` - -| `SAXSource` -| `org.xml.sax.InputSource`, and `org.xml.sax.XMLReader` - -| `StreamSource` -| `java.io.File`, `java.io.InputStream`, or `java.io.Reader` -|=== - -Even though there are two separate marshalling interfaces (`Marshaller` and -`Unmarshaller`), all implementations in Spring-WS implement both in one class. -This means that you can wire up one marshaller class and refer to it both as a -marshaller and as an unmarshaller in your `applicationContext.xml`. - - -[[oxm-xmlmappingexception]] -==== Understanding `XmlMappingException` - -Spring converts exceptions from the underlying O-X mapping tool to its own exception -hierarchy with the `XmlMappingException` as the root exception. -These runtime exceptions wrap the original exception so that no information will be lost. - -Additionally, the `MarshallingFailureException` and `UnmarshallingFailureException` -provide a distinction between marshalling and unmarshalling operations, even though the -underlying O-X mapping tool does not do so. - -The O-X Mapping exception hierarchy is shown in the following figure: - -image::oxm-exceptions.png[] - - - -[[oxm-usage]] -=== Using `Marshaller` and `Unmarshaller` - -You can use Spring's OXM for a wide variety of situations. In the following example, we -use it to marshal the settings of a Spring-managed application as an XML file. In the following example, we -use a simple JavaBean to represent the settings: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class Settings { - - private boolean fooEnabled; - - public boolean isFooEnabled() { - return fooEnabled; - } - - public void setFooEnabled(boolean fooEnabled) { - this.fooEnabled = fooEnabled; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class Settings { - var isFooEnabled: Boolean = false - } ----- - -The application class uses this bean to store its settings. Besides a main method, the -class has two methods: `saveSettings()` saves the settings bean to a file named -`settings.xml`, and `loadSettings()` loads these settings again. The following `main()` method -constructs a Spring application context and calls these two methods: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import java.io.FileInputStream; - import java.io.FileOutputStream; - import java.io.IOException; - import javax.xml.transform.stream.StreamResult; - import javax.xml.transform.stream.StreamSource; - import org.springframework.context.ApplicationContext; - import org.springframework.context.support.ClassPathXmlApplicationContext; - import org.springframework.oxm.Marshaller; - import org.springframework.oxm.Unmarshaller; - - public class Application { - - private static final String FILE_NAME = "settings.xml"; - private Settings settings = new Settings(); - private Marshaller marshaller; - private Unmarshaller unmarshaller; - - public void setMarshaller(Marshaller marshaller) { - this.marshaller = marshaller; - } - - public void setUnmarshaller(Unmarshaller unmarshaller) { - this.unmarshaller = unmarshaller; - } - - public void saveSettings() throws IOException { - try (FileOutputStream os = new FileOutputStream(FILE_NAME)) { - this.marshaller.marshal(settings, new StreamResult(os)); - } - } - - public void loadSettings() throws IOException { - try (FileInputStream is = new FileInputStream(FILE_NAME)) { - this.settings = (Settings) this.unmarshaller.unmarshal(new StreamSource(is)); - } - } - - public static void main(String[] args) throws IOException { - ApplicationContext appContext = - new ClassPathXmlApplicationContext("applicationContext.xml"); - Application application = (Application) appContext.getBean("application"); - application.saveSettings(); - application.loadSettings(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class Application { - - lateinit var marshaller: Marshaller - - lateinit var unmarshaller: Unmarshaller - - fun saveSettings() { - FileOutputStream(FILE_NAME).use { outputStream -> marshaller.marshal(settings, StreamResult(outputStream)) } - } - - fun loadSettings() { - FileInputStream(FILE_NAME).use { inputStream -> settings = unmarshaller.unmarshal(StreamSource(inputStream)) as Settings } - } - } - - private const val FILE_NAME = "settings.xml" - - fun main(args: Array<String>) { - val appContext = ClassPathXmlApplicationContext("applicationContext.xml") - val application = appContext.getBean("application") as Application - application.saveSettings() - application.loadSettings() - } ----- - -The `Application` requires both a `marshaller` and an `unmarshaller` property to be set. We -can do so by using the following `applicationContext.xml`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <bean id="application" class="Application"> - <property name="marshaller" ref="xstreamMarshaller" /> - <property name="unmarshaller" ref="xstreamMarshaller" /> - </bean> - <bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller"/> - </beans> ----- - -This application context uses XStream, but we could have used any of the other marshaller -instances described later in this chapter. Note that, by default, XStream does not require -any further configuration, so the bean definition is rather simple. Also note that the -`XStreamMarshaller` implements both `Marshaller` and `Unmarshaller`, so we can refer to the -`xstreamMarshaller` bean in both the `marshaller` and `unmarshaller` property of the -application. - -This sample application produces the following `settings.xml` file: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <?xml version="1.0" encoding="UTF-8"?> - <settings foo-enabled="false"/> ----- - - - -[[oxm-schema-based-config]] -=== XML Configuration Namespace - -You can configure marshallers more concisely by using tags from the OXM namespace. -To make these tags available, you must first reference the appropriate schema in the -preamble of the XML configuration file. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <?xml version="1.0" encoding="UTF-8"?> - <beans xmlns="http://www.springframework.org/schema/beans" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xmlns:oxm="http://www.springframework.org/schema/oxm" <1> - xsi:schemaLocation="http://www.springframework.org/schema/beans - https://www.springframework.org/schema/beans/spring-beans.xsd - http://www.springframework.org/schema/oxm - https://www.springframework.org/schema/oxm/spring-oxm.xsd"> <2> ----- -<1> Reference the `oxm` schema. -<2> Specify the `oxm` schema location. - - -The schema makes the following elements available: - -* <<oxm-jaxb2-xsd, `jaxb2-marshaller`>> -* <<oxm-jibx-xsd, `jibx-marshaller`>> - -Each tag is explained in its respective marshaller's section. As an example, though, -the configuration of a JAXB2 marshaller might resemble the following: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <oxm:jaxb2-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/> ----- - - - -[[oxm-jaxb]] -=== JAXB - -The JAXB binding compiler translates a W3C XML Schema into one or more Java classes, a -`jaxb.properties` file, and possibly some resource files. JAXB also offers a way to -generate a schema from annotated Java classes. - -Spring supports the JAXB 2.0 API as XML marshalling strategies, following the -`Marshaller` and `Unmarshaller` interfaces described in <<oxm-marshaller-unmarshaller>>. -The corresponding integration classes reside in the `org.springframework.oxm.jaxb` -package. - - -[[oxm-jaxb2]] -==== Using `Jaxb2Marshaller` - -The `Jaxb2Marshaller` class implements both of Spring's `Marshaller` and `Unmarshaller` -interfaces. It requires a context path to operate. You can set the context path by setting the -`contextPath` property. The context path is a list of colon-separated Java package -names that contain schema derived classes. It also offers a `classesToBeBound` property, -which allows you to set an array of classes to be supported by the marshaller. Schema -validation is performed by specifying one or more schema resources to the bean, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <bean id="jaxb2Marshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller"> - <property name="classesToBeBound"> - <list> - <value>org.springframework.oxm.jaxb.Flight</value> - <value>org.springframework.oxm.jaxb.Flights</value> - </list> - </property> - <property name="schema" value="classpath:org/springframework/oxm/schema.xsd"/> - </bean> - - ... - - </beans> ----- - -[[oxm-jaxb2-xsd]] -===== XML Configuration Namespace - -The `jaxb2-marshaller` element configures a `org.springframework.oxm.jaxb.Jaxb2Marshaller`, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <oxm:jaxb2-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/> ----- - -Alternatively, you can provide the list of classes to bind to the marshaller by using the -`class-to-be-bound` child element: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <oxm:jaxb2-marshaller id="marshaller"> - <oxm:class-to-be-bound name="org.springframework.ws.samples.airline.schema.Airport"/> - <oxm:class-to-be-bound name="org.springframework.ws.samples.airline.schema.Flight"/> - ... - </oxm:jaxb2-marshaller> ----- - -The following table describes the available attributes: - -|=== -| Attribute| Description| Required - -| `id` -| The ID of the marshaller -| No - -| `contextPath` -| The JAXB Context path -| No -|=== - - - -[[oxm-jibx]] -=== JiBX - -The JiBX framework offers a solution similar to that which Hibernate provides for ORM: A -binding definition defines the rules for how your Java objects are converted to or from -XML. After preparing the binding and compiling the classes, a JiBX binding compiler -enhances the class files and adds code to handle converting instances of the classes -from or to XML. - -For more information on JiBX, see the http://jibx.sourceforge.net/[JiBX web -site]. The Spring integration classes reside in the `org.springframework.oxm.jibx` -package. - - -[[oxm-jibx-marshaller]] -==== Using `JibxMarshaller` - -The `JibxMarshaller` class implements both the `Marshaller` and `Unmarshaller` -interface. To operate, it requires the name of the class to marshal in, which you can -set using the `targetClass` property. Optionally, you can set the binding name by setting the -`bindingName` property. In the following example, we bind the `Flights` class: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <bean id="jibxFlightsMarshaller" class="org.springframework.oxm.jibx.JibxMarshaller"> - <property name="targetClass">org.springframework.oxm.jibx.Flights</property> - </bean> - ... - </beans> ----- - -A `JibxMarshaller` is configured for a single class. If you want to marshal multiple -classes, you have to configure multiple `JibxMarshaller` instances with different `targetClass` -property values. - -[[oxm-jibx-xsd]] -===== XML Configuration Namespace - -The `jibx-marshaller` tag configures a `org.springframework.oxm.jibx.JibxMarshaller`, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <oxm:jibx-marshaller id="marshaller" target-class="org.springframework.ws.samples.airline.schema.Flight"/> ----- - -The following table describes the available attributes: - -|=== -| Attribute| Description| Required - -| `id` -| The ID of the marshaller -| No - -| `target-class` -| The target class for this marshaller -| Yes - -| `bindingName` -| The binding name used by this marshaller -| No -|=== - - - -[[oxm-xstream]] -=== XStream - -XStream is a simple library to serialize objects to XML and back again. It does not -require any mapping and generates clean XML. - -For more information on XStream, see the https://x-stream.github.io/[XStream -web site]. The Spring integration classes reside in the -`org.springframework.oxm.xstream` package. - - -[[oxm-xstream-marshaller]] -==== Using `XStreamMarshaller` - -The `XStreamMarshaller` does not require any configuration and can be configured in an -application context directly. To further customize the XML, you can set an alias map, -which consists of string aliases mapped to classes, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller"> - <property name="aliases"> - <props> - <prop key="Flight">org.springframework.oxm.xstream.Flight</prop> - </props> - </property> - </bean> - ... - </beans> ----- - -[WARNING] -===== -By default, XStream lets arbitrary classes be unmarshalled, which can lead to -unsafe Java serialization effects. As such, we do not recommend using the -`XStreamMarshaller` to unmarshal XML from external sources (that is, the Web), as this can -result in security vulnerabilities. - -If you choose to use the `XStreamMarshaller` to unmarshal XML from an external source, -set the `supportedClasses` property on the `XStreamMarshaller`, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller"> - <property name="supportedClasses" value="org.springframework.oxm.xstream.Flight"/> - ... - </bean> ----- - -Doing so ensures that only the registered classes are eligible for unmarshalling. - -Additionally, you can register -{api-spring-framework}/oxm/xstream/XStreamMarshaller.html#setConverters(com.thoughtworks.xstream.converters.ConverterMatcher...)[custom -converters] to make sure that only your supported classes can be unmarshalled. You might -want to add a `CatchAllConverter` as the last converter in the list, in addition to -converters that explicitly support the domain classes that should be supported. As a -result, default XStream converters with lower priorities and possible security -vulnerabilities do not get invoked. -===== - -NOTE: Note that XStream is an XML serialization library, not a data binding library. -Therefore, it has limited namespace support. As a result, it is rather unsuitable for usage -within Web Services. - - - - -include::data-access/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/data-access/dao.adoc b/framework-docs/modules/ROOT/pages/data-access/dao.adoc new file mode 100644 index 000000000000..6745abbb0bf3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/dao.adoc @@ -0,0 +1,176 @@ +[[dao]] += DAO Support + +The Data Access Object (DAO) support in Spring is aimed at making it easy to work with +data access technologies (such as JDBC, Hibernate, or JPA) in a consistent way. This +lets you switch between the aforementioned persistence technologies fairly easily, +and it also lets you code without worrying about catching exceptions that are +specific to each technology. + + + +[[dao-exceptions]] +== Consistent Exception Hierarchy + +Spring provides a convenient translation from technology-specific exceptions, such as +`SQLException` to its own exception class hierarchy, which has `DataAccessException` as +the root exception. These exceptions wrap the original exception so that there is never +any risk that you might lose any information about what might have gone wrong. + +In addition to JDBC exceptions, Spring can also wrap JPA- and Hibernate-specific exceptions, +converting them to a set of focused runtime exceptions. This lets you handle most +non-recoverable persistence exceptions in only the appropriate layers, without having +annoying boilerplate catch-and-throw blocks and exception declarations in your DAOs. +(You can still trap and handle exceptions anywhere you need to though.) As mentioned above, +JDBC exceptions (including database-specific dialects) are also converted to the same +hierarchy, meaning that you can perform some operations with JDBC within a consistent +programming model. + +The preceding discussion holds true for the various template classes in Spring's support +for various ORM frameworks. If you use the interceptor-based classes, the application must +care about handling `HibernateExceptions` and `PersistenceExceptions` itself, preferably by +delegating to the `convertHibernateAccessException(..)` or `convertJpaAccessException(..)` +methods, respectively, of `SessionFactoryUtils`. These methods convert the exceptions +to exceptions that are compatible with the exceptions in the `org.springframework.dao` +exception hierarchy. As `PersistenceExceptions` are unchecked, they can get thrown, too +(sacrificing generic DAO abstraction in terms of exceptions, though). + +The following image shows the exception hierarchy that Spring provides. +(Note that the class hierarchy detailed in the image shows only a subset of the entire +`DataAccessException` hierarchy.) + +image::DataAccessException.png[] + + + +[[dao-annotations]] +== Annotations Used to Configure DAO or Repository Classes + +The best way to guarantee that your Data Access Objects (DAOs) or repositories provide +exception translation is to use the `@Repository` annotation. This annotation also +lets the component scanning support find and configure your DAOs and repositories +without having to provide XML configuration entries for them. The following example shows +how to use the `@Repository` annotation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Repository // <1> + public class SomeMovieFinder implements MovieFinder { + // ... + } +---- +<1> The `@Repository` annotation. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Repository // <1> + class SomeMovieFinder : MovieFinder { + // ... + } +---- +<1> The `@Repository` annotation. + + +Any DAO or repository implementation needs access to a persistence resource, +depending on the persistence technology used. For example, a JDBC-based repository +needs access to a JDBC `DataSource`, and a JPA-based repository needs access to an +`EntityManager`. The easiest way to accomplish this is to have this resource dependency +injected by using one of the `@Autowired`, `@Inject`, `@Resource` or `@PersistenceContext` +annotations. The following example works for a JPA repository: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Repository + public class JpaMovieFinder implements MovieFinder { + + @PersistenceContext + private EntityManager entityManager; + + // ... + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Repository + class JpaMovieFinder : MovieFinder { + + @PersistenceContext + private lateinit var entityManager: EntityManager + + // ... + } +---- + + +If you use the classic Hibernate APIs, you can inject `SessionFactory`, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Repository + public class HibernateMovieFinder implements MovieFinder { + + private SessionFactory sessionFactory; + + @Autowired + public void setSessionFactory(SessionFactory sessionFactory) { + this.sessionFactory = sessionFactory; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Repository + class HibernateMovieFinder(private val sessionFactory: SessionFactory) : MovieFinder { + // ... + } +---- + +The last example we show here is for typical JDBC support. You could have the +`DataSource` injected into an initialization method or a constructor, where you would create a +`JdbcTemplate` and other data access support classes (such as `SimpleJdbcCall` and others) by using +this `DataSource`. The following example autowires a `DataSource`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Repository + public class JdbcMovieFinder implements MovieFinder { + + private JdbcTemplate jdbcTemplate; + + @Autowired + public void init(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Repository + class JdbcMovieFinder(dataSource: DataSource) : MovieFinder { + + private val jdbcTemplate = JdbcTemplate(dataSource) + + // ... + } +---- + +NOTE: See the specific coverage of each persistence technology for details on how to +configure the application context to take advantage of these annotations. + + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc.adoc new file mode 100644 index 000000000000..0f82cea1b648 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc.adoc @@ -0,0 +1,58 @@ +[[jdbc]] += Data Access with JDBC + +The value provided by the Spring Framework JDBC abstraction is perhaps best shown by +the sequence of actions outlined in the following table below. The table shows which actions Spring +takes care of and which actions are your responsibility. + +[[jdbc-who-does-what]] +.Spring JDBC - who does what? +|=== +| Action| Spring| You + +| Define connection parameters. +| +| X + +| Open the connection. +| X +| + +| Specify the SQL statement. +| +| X + +| Declare parameters and provide parameter values +| +| X + +| Prepare and run the statement. +| X +| + +| Set up the loop to iterate through the results (if any). +| X +| + +| Do the work for each iteration. +| +| X + +| Process any exception. +| X +| + +| Handle transactions. +| X +| + +| Close the connection, the statement, and the resultset. +| X +| +|=== + +The Spring Framework takes care of all the low-level details that can make JDBC such a +tedious API. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc new file mode 100644 index 000000000000..9c40642d575a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc @@ -0,0 +1,284 @@ +[[jdbc-advanced-jdbc]] += JDBC Batch Operations + +Most JDBC drivers provide improved performance if you batch multiple calls to the same +prepared statement. By grouping updates into batches, you limit the number of round trips +to the database. + + +[[jdbc-batch-classic]] +== Basic Batch Operations with `JdbcTemplate` + +You accomplish `JdbcTemplate` batch processing by implementing two methods of a special +interface, `BatchPreparedStatementSetter`, and passing that implementation in as the second parameter +in your `batchUpdate` method call. You can use the `getBatchSize` method to provide the size of +the current batch. You can use the `setValues` method to set the values for the parameters of +the prepared statement. This method is called the number of times that you +specified in the `getBatchSize` call. The following example updates the `t_actor` table +based on entries in a list, and the entire list is used as the batch: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private JdbcTemplate jdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + public int[] batchUpdate(final List<Actor> actors) { + return this.jdbcTemplate.batchUpdate( + "update t_actor set first_name = ?, last_name = ? where id = ?", + new BatchPreparedStatementSetter() { + public void setValues(PreparedStatement ps, int i) throws SQLException { + Actor actor = actors.get(i); + ps.setString(1, actor.getFirstName()); + ps.setString(2, actor.getLastName()); + ps.setLong(3, actor.getId().longValue()); + } + public int getBatchSize() { + return actors.size(); + } + }); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val jdbcTemplate = JdbcTemplate(dataSource) + + fun batchUpdate(actors: List<Actor>): IntArray { + return jdbcTemplate.batchUpdate( + "update t_actor set first_name = ?, last_name = ? where id = ?", + object: BatchPreparedStatementSetter { + override fun setValues(ps: PreparedStatement, i: Int) { + ps.setString(1, actors[i].firstName) + ps.setString(2, actors[i].lastName) + ps.setLong(3, actors[i].id) + } + + override fun getBatchSize() = actors.size + }) + } + + // ... additional methods + } +---- + +If you process a stream of updates or reading from a file, you might have a +preferred batch size, but the last batch might not have that number of entries. In this +case, you can use the `InterruptibleBatchPreparedStatementSetter` interface, which lets +you interrupt a batch once the input source is exhausted. The `isBatchExhausted` method +lets you signal the end of the batch. + + +[[jdbc-batch-list]] +== Batch Operations with a List of Objects + +Both the `JdbcTemplate` and the `NamedParameterJdbcTemplate` provides an alternate way +of providing the batch update. Instead of implementing a special batch interface, you +provide all parameter values in the call as a list. The framework loops over these +values and uses an internal prepared statement setter. The API varies, depending on +whether you use named parameters. For the named parameters, you provide an array of +`SqlParameterSource`, one entry for each member of the batch. You can use the +`SqlParameterSourceUtils.createBatch` convenience methods to create this array, passing +in an array of bean-style objects (with getter methods corresponding to parameters), +`String`-keyed `Map` instances (containing the corresponding parameters as values), or a mix of both. + +The following example shows a batch update using named parameters: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private NamedParameterTemplate namedParameterJdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.namedParameterJdbcTemplate = new NamedParameterJdbcTemplate(dataSource); + } + + public int[] batchUpdate(List<Actor> actors) { + return this.namedParameterJdbcTemplate.batchUpdate( + "update t_actor set first_name = :firstName, last_name = :lastName where id = :id", + SqlParameterSourceUtils.createBatch(actors)); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) + + fun batchUpdate(actors: List<Actor>): IntArray { + return this.namedParameterJdbcTemplate.batchUpdate( + "update t_actor set first_name = :firstName, last_name = :lastName where id = :id", + SqlParameterSourceUtils.createBatch(actors)); + } + + // ... additional methods + } +---- + +For an SQL statement that uses the classic `?` placeholders, you pass in a list +containing an object array with the update values. This object array must have one entry +for each placeholder in the SQL statement, and they must be in the same order as they are +defined in the SQL statement. + +The following example is the same as the preceding example, except that it uses classic +JDBC `?` placeholders: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private JdbcTemplate jdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + public int[] batchUpdate(final List<Actor> actors) { + List<Object[]> batch = new ArrayList<>(); + for (Actor actor : actors) { + Object[] values = new Object[] { + actor.getFirstName(), actor.getLastName(), actor.getId()}; + batch.add(values); + } + return this.jdbcTemplate.batchUpdate( + "update t_actor set first_name = ?, last_name = ? where id = ?", + batch); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val jdbcTemplate = JdbcTemplate(dataSource) + + fun batchUpdate(actors: List<Actor>): IntArray { + val batch = mutableListOf<Array<Any>>() + for (actor in actors) { + batch.add(arrayOf(actor.firstName, actor.lastName, actor.id)) + } + return jdbcTemplate.batchUpdate( + "update t_actor set first_name = ?, last_name = ? where id = ?", batch) + } + + // ... additional methods + } +---- + +All of the batch update methods that we described earlier return an `int` array +containing the number of affected rows for each batch entry. This count is reported by +the JDBC driver. If the count is not available, the JDBC driver returns a value of `-2`. + +[NOTE] +==== +In such a scenario, with automatic setting of values on an underlying `PreparedStatement`, +the corresponding JDBC type for each value needs to be derived from the given Java type. +While this usually works well, there is a potential for issues (for example, with Map-contained +`null` values). Spring, by default, calls `ParameterMetaData.getParameterType` in such a +case, which can be expensive with your JDBC driver. You should use a recent driver +version and consider setting the `spring.jdbc.getParameterType.ignore` property to `true` +(as a JVM system property or via the +<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism) if you encounter +a performance issue (as reported on Oracle 12c, JBoss, and PostgreSQL). + +Alternatively, you might consider specifying the corresponding JDBC types explicitly, +either through a `BatchPreparedStatementSetter` (as shown earlier), through an explicit type +array given to a `List<Object[]>` based call, through `registerSqlType` calls on a +custom `MapSqlParameterSource` instance, or through a `BeanPropertySqlParameterSource` +that derives the SQL type from the Java-declared property type even for a null value. +==== + + +[[jdbc-batch-multi]] +== Batch Operations with Multiple Batches + +The preceding example of a batch update deals with batches that are so large that you want to +break them up into several smaller batches. You can do this with the methods +mentioned earlier by making multiple calls to the `batchUpdate` method, but there is now a +more convenient method. This method takes, in addition to the SQL statement, a +`Collection` of objects that contain the parameters, the number of updates to make for each +batch, and a `ParameterizedPreparedStatementSetter` to set the values for the parameters +of the prepared statement. The framework loops over the provided values and breaks the +update calls into batches of the size specified. + +The following example shows a batch update that uses a batch size of 100: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private JdbcTemplate jdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + public int[][] batchUpdate(final Collection<Actor> actors) { + int[][] updateCounts = jdbcTemplate.batchUpdate( + "update t_actor set first_name = ?, last_name = ? where id = ?", + actors, + 100, + (PreparedStatement ps, Actor actor) -> { + ps.setString(1, actor.getFirstName()); + ps.setString(2, actor.getLastName()); + ps.setLong(3, actor.getId().longValue()); + }); + return updateCounts; + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val jdbcTemplate = JdbcTemplate(dataSource) + + fun batchUpdate(actors: List<Actor>): Array<IntArray> { + return jdbcTemplate.batchUpdate( + "update t_actor set first_name = ?, last_name = ? where id = ?", + actors, 100) { ps, argument -> + ps.setString(1, argument.firstName) + ps.setString(2, argument.lastName) + ps.setLong(3, argument.id) + } + } + + // ... additional methods + } +---- + +The batch update method for this call returns an array of `int` arrays that contains an +array entry for each batch with an array of the number of affected rows for each update. +The top-level array's length indicates the number of batches run, and the second level +array's length indicates the number of updates in that batch. The number of updates in +each batch should be the batch size provided for all batches (except that the last one +that might be less), depending on the total number of update objects provided. The update +count for each update statement is the one reported by the JDBC driver. If the count is +not available, the JDBC driver returns a value of `-2`. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/choose-style.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/choose-style.adoc new file mode 100644 index 000000000000..ebf3f4be1395 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/choose-style.adoc @@ -0,0 +1,31 @@ +[[jdbc-choose-style]] += Choosing an Approach for JDBC Database Access + +You can choose among several approaches to form the basis for your JDBC database access. +In addition to three flavors of `JdbcTemplate`, a new `SimpleJdbcInsert` and +`SimpleJdbcCall` approach optimizes database metadata, and the RDBMS Object style takes a +more object-oriented approach similar to that of JDO Query design. Once you start using +one of these approaches, you can still mix and match to include a feature from a +different approach. All approaches require a JDBC 2.0-compliant driver, and some +advanced features require a JDBC 3.0 driver. + +* `JdbcTemplate` is the classic and most popular Spring JDBC approach. This + "`lowest-level`" approach and all others use a JdbcTemplate under the covers. +* `NamedParameterJdbcTemplate` wraps a `JdbcTemplate` to provide named parameters + instead of the traditional JDBC `?` placeholders. This approach provides better + documentation and ease of use when you have multiple parameters for an SQL statement. +* `SimpleJdbcInsert` and `SimpleJdbcCall` optimize database metadata to limit the amount + of necessary configuration. This approach simplifies coding so that you need to + provide only the name of the table or procedure and provide a map of parameters matching + the column names. This works only if the database provides adequate metadata. If the + database does not provide this metadata, you have to provide explicit + configuration of the parameters. +* RDBMS objects — including `MappingSqlQuery`, `SqlUpdate`, and `StoredProcedure` — + require you to create reusable and thread-safe objects during initialization of your + data-access layer. This approach is modeled after JDO Query, wherein you define your + query string, declare parameters, and compile the query. Once you do that, + `execute(...)`, `update(...)`, and `findObject(...)` methods can be called multiple + times with various parameter values. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc new file mode 100644 index 000000000000..80fe71b59359 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc @@ -0,0 +1,223 @@ +[[jdbc-connections]] += Controlling Database Connections + +This section covers: + +* <<jdbc-datasource>> +* <<jdbc-DataSourceUtils>> +* <<jdbc-SmartDataSource>> +* <<jdbc-AbstractDataSource>> +* <<jdbc-SingleConnectionDataSource>> +* <<jdbc-DriverManagerDataSource>> +* <<jdbc-TransactionAwareDataSourceProxy>> +* <<jdbc-DataSourceTransactionManager>> + + +[[jdbc-datasource]] +== Using `DataSource` + +Spring obtains a connection to the database through a `DataSource`. A `DataSource` is +part of the JDBC specification and is a generalized connection factory. It lets a +container or a framework hide connection pooling and transaction management issues +from the application code. As a developer, you need not know details about how to +connect to the database. That is the responsibility of the administrator who sets up +the datasource. You most likely fill both roles as you develop and test code, but you +do not necessarily have to know how the production data source is configured. + +When you use Spring's JDBC layer, you can obtain a data source from JNDI, or you can +configure your own with a connection pool implementation provided by a third party. +Traditional choices are Apache Commons DBCP and C3P0 with bean-style `DataSource` classes; +for a modern JDBC connection pool, consider HikariCP with its builder-style API instead. + +NOTE: You should use the `DriverManagerDataSource` and `SimpleDriverDataSource` classes +(as included in the Spring distribution) only for testing purposes! Those variants do not +provide pooling and perform poorly when multiple requests for a connection are made. + +The following section uses Spring's `DriverManagerDataSource` implementation. +Several other `DataSource` variants are covered later. + +To configure a `DriverManagerDataSource`: + +. Obtain a connection with `DriverManagerDataSource` as you typically obtain a JDBC + connection. +. Specify the fully qualified class name of the JDBC driver so that the `DriverManager` + can load the driver class. +. Provide a URL that varies between JDBC drivers. (See the documentation for your driver + for the correct value.) +. Provide a username and a password to connect to the database. + +The following example shows how to configure a `DriverManagerDataSource` in Java: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + DriverManagerDataSource dataSource = new DriverManagerDataSource(); + dataSource.setDriverClassName("org.hsqldb.jdbcDriver"); + dataSource.setUrl("jdbc:hsqldb:hsql://localhost:"); + dataSource.setUsername("sa"); + dataSource.setPassword(""); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val dataSource = DriverManagerDataSource().apply { + setDriverClassName("org.hsqldb.jdbcDriver") + url = "jdbc:hsqldb:hsql://localhost:" + username = "sa" + password = "" + } +---- + +The following example shows the corresponding XML configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource"> + <property name="driverClassName" value="${jdbc.driverClassName}"/> + <property name="url" value="${jdbc.url}"/> + <property name="username" value="${jdbc.username}"/> + <property name="password" value="${jdbc.password}"/> + </bean> + + <context:property-placeholder location="jdbc.properties"/> +---- + +The next two examples show the basic connectivity and configuration for DBCP and C3P0. +To learn about more options that help control the pooling features, see the product +documentation for the respective connection pooling implementations. + +The following example shows DBCP configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close"> + <property name="driverClassName" value="${jdbc.driverClassName}"/> + <property name="url" value="${jdbc.url}"/> + <property name="username" value="${jdbc.username}"/> + <property name="password" value="${jdbc.password}"/> + </bean> + + <context:property-placeholder location="jdbc.properties"/> +---- + +The following example shows C3P0 configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="dataSource" class="com.mchange.v2.c3p0.ComboPooledDataSource" destroy-method="close"> + <property name="driverClass" value="${jdbc.driverClassName}"/> + <property name="jdbcUrl" value="${jdbc.url}"/> + <property name="user" value="${jdbc.username}"/> + <property name="password" value="${jdbc.password}"/> + </bean> + + <context:property-placeholder location="jdbc.properties"/> +---- + + +[[jdbc-DataSourceUtils]] +== Using `DataSourceUtils` + +The `DataSourceUtils` class is a convenient and powerful helper class that provides +`static` methods to obtain connections from JNDI and close connections if necessary. It +supports thread-bound connections with, for example, `DataSourceTransactionManager`. + + +[[jdbc-SmartDataSource]] +== Implementing `SmartDataSource` + +The `SmartDataSource` interface should be implemented by classes that can provide a +connection to a relational database. It extends the `DataSource` interface to let +classes that use it query whether the connection should be closed after a given +operation. This usage is efficient when you know that you need to reuse a connection. + + +[[jdbc-AbstractDataSource]] +== Extending `AbstractDataSource` + +`AbstractDataSource` is an `abstract` base class for Spring's `DataSource` +implementations. It implements code that is common to all `DataSource` implementations. +You should extend the `AbstractDataSource` class if you write your own `DataSource` +implementation. + + +[[jdbc-SingleConnectionDataSource]] +== Using `SingleConnectionDataSource` + +The `SingleConnectionDataSource` class is an implementation of the `SmartDataSource` +interface that wraps a single `Connection` that is not closed after each use. +This is not multi-threading capable. + +If any client code calls `close` on the assumption of a pooled connection (as when using +persistence tools), you should set the `suppressClose` property to `true`. This setting +returns a close-suppressing proxy that wraps the physical connection. Note that you can +no longer cast this to a native Oracle `Connection` or a similar object. + +`SingleConnectionDataSource` is primarily a test class. It typically enables easy testing +of code outside an application server, in conjunction with a simple JNDI environment. +In contrast to `DriverManagerDataSource`, it reuses the same connection all the time, +avoiding excessive creation of physical connections. + + + +[[jdbc-DriverManagerDataSource]] +== Using `DriverManagerDataSource` + +The `DriverManagerDataSource` class is an implementation of the standard `DataSource` +interface that configures a plain JDBC driver through bean properties and returns a new +`Connection` every time. + +This implementation is useful for test and stand-alone environments outside of a Jakarta EE +container, either as a `DataSource` bean in a Spring IoC container or in conjunction +with a simple JNDI environment. Pool-assuming `Connection.close()` calls +close the connection, so any `DataSource`-aware persistence code should work. However, +using JavaBean-style connection pools (such as `commons-dbcp`) is so easy, even in a test +environment, that it is almost always preferable to use such a connection pool over +`DriverManagerDataSource`. + + +[[jdbc-TransactionAwareDataSourceProxy]] +== Using `TransactionAwareDataSourceProxy` + +`TransactionAwareDataSourceProxy` is a proxy for a target `DataSource`. The proxy wraps that +target `DataSource` to add awareness of Spring-managed transactions. In this respect, it +is similar to a transactional JNDI `DataSource`, as provided by a Jakarta EE server. + +NOTE: It is rarely desirable to use this class, except when already existing code must be +called and passed a standard JDBC `DataSource` interface implementation. In this case, +you can still have this code be usable and, at the same time, have this code +participating in Spring managed transactions. It is generally preferable to write your +own new code by using the higher level abstractions for resource management, such as +`JdbcTemplate` or `DataSourceUtils`. + +See the {api-spring-framework}/jdbc/datasource/TransactionAwareDataSourceProxy.html[`TransactionAwareDataSourceProxy`] +javadoc for more details. + + +[[jdbc-DataSourceTransactionManager]] +== Using `DataSourceTransactionManager` + +The `DataSourceTransactionManager` class is a `PlatformTransactionManager` +implementation for single JDBC data sources. It binds a JDBC connection from the +specified data source to the currently executing thread, potentially allowing for one +thread connection per data source. + +Application code is required to retrieve the JDBC connection through +`DataSourceUtils.getConnection(DataSource)` instead of Jakarta EE's standard +`DataSource.getConnection`. It throws unchecked `org.springframework.dao` exceptions +instead of checked `SQLExceptions`. All framework classes (such as `JdbcTemplate`) use this +strategy implicitly. If not used with this transaction manager, the lookup strategy +behaves exactly like the common one. Thus, it can be used in any case. + +The `DataSourceTransactionManager` class supports custom isolation levels and timeouts +that get applied as appropriate JDBC statement query timeouts. To support the latter, +application code must either use `JdbcTemplate` or call the +`DataSourceUtils.applyTransactionTimeout(..)` method for each created statement. + +You can use this implementation instead of `JtaTransactionManager` in the single-resource +case, as it does not require the container to support JTA. Switching between +both is just a matter of configuration, provided you stick to the required connection lookup +pattern. JTA does not support custom isolation levels. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc new file mode 100644 index 000000000000..a2488bfa2106 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc @@ -0,0 +1,955 @@ +[[jdbc-core]] += Using the JDBC Core Classes to Control Basic JDBC Processing and Error Handling + +This section covers how to use the JDBC core classes to control basic JDBC processing, +including error handling. It includes the following topics: + +* <<jdbc-JdbcTemplate>> +* <<jdbc-NamedParameterJdbcTemplate>> +* <<jdbc-SQLExceptionTranslator>> +* <<jdbc-statements-executing>> +* <<jdbc-statements-querying>> +* <<jdbc-updates>> +* <<jdbc-auto-generated-keys>> + + +[[jdbc-JdbcTemplate]] +== Using `JdbcTemplate` + +`JdbcTemplate` is the central class in the JDBC core package. It handles the +creation and release of resources, which helps you avoid common errors, such as +forgetting to close the connection. It performs the basic tasks of the core JDBC +workflow (such as statement creation and execution), leaving application code to provide +SQL and extract results. The `JdbcTemplate` class: + +* Runs SQL queries +* Updates statements and stored procedure calls +* Performs iteration over `ResultSet` instances and extraction of returned parameter values. +* Catches JDBC exceptions and translates them to the generic, more informative, exception +hierarchy defined in the `org.springframework.dao` package. (See <<dao-exceptions>>.) + +When you use the `JdbcTemplate` for your code, you need only to implement callback +interfaces, giving them a clearly defined contract. Given a `Connection` provided by the +`JdbcTemplate` class, the `PreparedStatementCreator` callback interface creates a prepared +statement, providing SQL and any necessary parameters. The same is true for the +`CallableStatementCreator` interface, which creates callable statements. The +`RowCallbackHandler` interface extracts values from each row of a `ResultSet`. + +You can use `JdbcTemplate` within a DAO implementation through direct instantiation +with a `DataSource` reference, or you can configure it in a Spring IoC container and give it to +DAOs as a bean reference. + +NOTE: The `DataSource` should always be configured as a bean in the Spring IoC container. In +the first case the bean is given to the service directly; in the second case it is given +to the prepared template. + +All SQL issued by this class is logged at the `DEBUG` level under the category +corresponding to the fully qualified class name of the template instance (typically +`JdbcTemplate`, but it may be different if you use a custom subclass of the +`JdbcTemplate` class). + +The following sections provide some examples of `JdbcTemplate` usage. These examples +are not an exhaustive list of all of the functionality exposed by the `JdbcTemplate`. +See the attendant {api-spring-framework}/jdbc/core/JdbcTemplate.html[javadoc] for that. + +[[jdbc-JdbcTemplate-examples-query]] +=== Querying (`SELECT`) + +The following query gets the number of rows in a relation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + int rowCount = this.jdbcTemplate.queryForObject("select count(*) from t_actor", Integer.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val rowCount = jdbcTemplate.queryForObject<Int>("select count(*) from t_actor")!! +---- + +The following query uses a bind variable: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + int countOfActorsNamedJoe = this.jdbcTemplate.queryForObject( + "select count(*) from t_actor where first_name = ?", Integer.class, "Joe"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val countOfActorsNamedJoe = jdbcTemplate.queryForObject<Int>( + "select count(*) from t_actor where first_name = ?", arrayOf("Joe"))!! +---- + + +The following query looks for a `String`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + String lastName = this.jdbcTemplate.queryForObject( + "select last_name from t_actor where id = ?", + String.class, 1212L); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val lastName = this.jdbcTemplate.queryForObject<String>( + "select last_name from t_actor where id = ?", + arrayOf(1212L))!! +---- + +The following query finds and populates a single domain object: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Actor actor = jdbcTemplate.queryForObject( + "select first_name, last_name from t_actor where id = ?", + (resultSet, rowNum) -> { + Actor newActor = new Actor(); + newActor.setFirstName(resultSet.getString("first_name")); + newActor.setLastName(resultSet.getString("last_name")); + return newActor; + }, + 1212L); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val actor = jdbcTemplate.queryForObject( + "select first_name, last_name from t_actor where id = ?", + arrayOf(1212L)) { rs, _ -> + Actor(rs.getString("first_name"), rs.getString("last_name")) + } +---- + +The following query finds and populates a list of domain objects: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + List<Actor> actors = this.jdbcTemplate.query( + "select first_name, last_name from t_actor", + (resultSet, rowNum) -> { + Actor actor = new Actor(); + actor.setFirstName(resultSet.getString("first_name")); + actor.setLastName(resultSet.getString("last_name")); + return actor; + }); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val actors = jdbcTemplate.query("select first_name, last_name from t_actor") { rs, _ -> + Actor(rs.getString("first_name"), rs.getString("last_name")) +---- + +If the last two snippets of code actually existed in the same application, it would make +sense to remove the duplication present in the two `RowMapper` lambda expressions and +extract them out into a single field that could then be referenced by DAO methods as needed. +For example, it may be better to write the preceding code snippet as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + private final RowMapper<Actor> actorRowMapper = (resultSet, rowNum) -> { + Actor actor = new Actor(); + actor.setFirstName(resultSet.getString("first_name")); + actor.setLastName(resultSet.getString("last_name")); + return actor; + }; + + public List<Actor> findAllActors() { + return this.jdbcTemplate.query("select first_name, last_name from t_actor", actorRowMapper); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val actorMapper = RowMapper<Actor> { rs: ResultSet, rowNum: Int -> + Actor(rs.getString("first_name"), rs.getString("last_name")) + } + + fun findAllActors(): List<Actor> { + return jdbcTemplate.query("select first_name, last_name from t_actor", actorMapper) + } +---- + +[[jdbc-JdbcTemplate-examples-update]] +=== Updating (`INSERT`, `UPDATE`, and `DELETE`) with `JdbcTemplate` + +You can use the `update(..)` method to perform insert, update, and delete operations. +Parameter values are usually provided as variable arguments or, alternatively, as an object array. + +The following example inserts a new entry: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + this.jdbcTemplate.update( + "insert into t_actor (first_name, last_name) values (?, ?)", + "Leonor", "Watling"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + jdbcTemplate.update( + "insert into t_actor (first_name, last_name) values (?, ?)", + "Leonor", "Watling") +---- + +The following example updates an existing entry: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + this.jdbcTemplate.update( + "update t_actor set last_name = ? where id = ?", + "Banjo", 5276L); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + jdbcTemplate.update( + "update t_actor set last_name = ? where id = ?", + "Banjo", 5276L) +---- + +The following example deletes an entry: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + this.jdbcTemplate.update( + "delete from t_actor where id = ?", + Long.valueOf(actorId)); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + jdbcTemplate.update("delete from t_actor where id = ?", actorId.toLong()) +---- + +[[jdbc-JdbcTemplate-examples-other]] +=== Other `JdbcTemplate` Operations + +You can use the `execute(..)` method to run any arbitrary SQL. Consequently, the +method is often used for DDL statements. It is heavily overloaded with variants that take +callback interfaces, binding variable arrays, and so on. The following example creates a +table: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + this.jdbcTemplate.execute("create table mytable (id integer, name varchar(100))"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + jdbcTemplate.execute("create table mytable (id integer, name varchar(100))") +---- + +The following example invokes a stored procedure: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + this.jdbcTemplate.update( + "call SUPPORT.REFRESH_ACTORS_SUMMARY(?)", + Long.valueOf(unionId)); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + jdbcTemplate.update( + "call SUPPORT.REFRESH_ACTORS_SUMMARY(?)", + unionId.toLong()) +---- + + +More sophisticated stored procedure support is <<jdbc-StoredProcedure, covered later>>. + +[[jdbc-JdbcTemplate-idioms]] +=== `JdbcTemplate` Best Practices + +Instances of the `JdbcTemplate` class are thread-safe, once configured. This is +important because it means that you can configure a single instance of a `JdbcTemplate` +and then safely inject this shared reference into multiple DAOs (or repositories). +The `JdbcTemplate` is stateful, in that it maintains a reference to a `DataSource`, but +this state is not conversational state. + +A common practice when using the `JdbcTemplate` class (and the associated +<<jdbc-NamedParameterJdbcTemplate, `NamedParameterJdbcTemplate`>> class) is to +configure a `DataSource` in your Spring configuration file and then dependency-inject +that shared `DataSource` bean into your DAO classes. The `JdbcTemplate` is created in +the setter for the `DataSource`. This leads to DAOs that resemble the following: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcCorporateEventDao implements CorporateEventDao { + + private JdbcTemplate jdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + // JDBC-backed implementations of the methods on the CorporateEventDao follow... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcCorporateEventDao(dataSource: DataSource) : CorporateEventDao { + + private val jdbcTemplate = JdbcTemplate(dataSource) + + // JDBC-backed implementations of the methods on the CorporateEventDao follow... + } +---- +-- + +The following example shows the corresponding XML configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:context="http://www.springframework.org/schema/context" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/context + https://www.springframework.org/schema/context/spring-context.xsd"> + + <bean id="corporateEventDao" class="com.example.JdbcCorporateEventDao"> + <property name="dataSource" ref="dataSource"/> + </bean> + + <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close"> + <property name="driverClassName" value="${jdbc.driverClassName}"/> + <property name="url" value="${jdbc.url}"/> + <property name="username" value="${jdbc.username}"/> + <property name="password" value="${jdbc.password}"/> + </bean> + + <context:property-placeholder location="jdbc.properties"/> + + </beans> +---- + +An alternative to explicit configuration is to use component-scanning and annotation +support for dependency injection. In this case, you can annotate the class with `@Repository` +(which makes it a candidate for component-scanning) and annotate the `DataSource` setter +method with `@Autowired`. The following example shows how to do so: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Repository // <1> + public class JdbcCorporateEventDao implements CorporateEventDao { + + private JdbcTemplate jdbcTemplate; + + @Autowired // <2> + public void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); // <3> + } + + // JDBC-backed implementations of the methods on the CorporateEventDao follow... + } +---- +<1> Annotate the class with `@Repository`. +<2> Annotate the `DataSource` setter method with `@Autowired`. +<3> Create a new `JdbcTemplate` with the `DataSource`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Repository // <1> + class JdbcCorporateEventDao(dataSource: DataSource) : CorporateEventDao { // <2> + + private val jdbcTemplate = JdbcTemplate(dataSource) // <3> + + // JDBC-backed implementations of the methods on the CorporateEventDao follow... + } +---- +<1> Annotate the class with `@Repository`. +<2> Constructor injection of the `DataSource`. +<3> Create a new `JdbcTemplate` with the `DataSource`. +-- + + +The following example shows the corresponding XML configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:context="http://www.springframework.org/schema/context" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/context + https://www.springframework.org/schema/context/spring-context.xsd"> + + <!-- Scans within the base package of the application for @Component classes to configure as beans --> + <context:component-scan base-package="org.springframework.docs.test" /> + + <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close"> + <property name="driverClassName" value="${jdbc.driverClassName}"/> + <property name="url" value="${jdbc.url}"/> + <property name="username" value="${jdbc.username}"/> + <property name="password" value="${jdbc.password}"/> + </bean> + + <context:property-placeholder location="jdbc.properties"/> + + </beans> +---- + +If you use Spring's `JdbcDaoSupport` class and your various JDBC-backed DAO classes +extend from it, your sub-class inherits a `setDataSource(..)` method from the +`JdbcDaoSupport` class. You can choose whether to inherit from this class. The +`JdbcDaoSupport` class is provided as a convenience only. + +Regardless of which of the above template initialization styles you choose to use (or +not), it is seldom necessary to create a new instance of a `JdbcTemplate` class each +time you want to run SQL. Once configured, a `JdbcTemplate` instance is thread-safe. +If your application accesses multiple +databases, you may want multiple `JdbcTemplate` instances, which requires multiple `DataSources` and, subsequently, multiple differently +configured `JdbcTemplate` instances. + + +[[jdbc-NamedParameterJdbcTemplate]] +== Using `NamedParameterJdbcTemplate` + +The `NamedParameterJdbcTemplate` class adds support for programming JDBC statements +by using named parameters, as opposed to programming JDBC statements using only classic +placeholder ( `'?'`) arguments. The `NamedParameterJdbcTemplate` class wraps a +`JdbcTemplate` and delegates to the wrapped `JdbcTemplate` to do much of its work. This +section describes only those areas of the `NamedParameterJdbcTemplate` class that differ +from the `JdbcTemplate` itself -- namely, programming JDBC statements by using named +parameters. The following example shows how to use `NamedParameterJdbcTemplate`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // some JDBC-backed DAO class... + private NamedParameterJdbcTemplate namedParameterJdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.namedParameterJdbcTemplate = new NamedParameterJdbcTemplate(dataSource); + } + + public int countOfActorsByFirstName(String firstName) { + + String sql = "select count(*) from T_ACTOR where first_name = :first_name"; + + SqlParameterSource namedParameters = new MapSqlParameterSource("first_name", firstName); + + return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) + + fun countOfActorsByFirstName(firstName: String): Int { + val sql = "select count(*) from T_ACTOR where first_name = :first_name" + val namedParameters = MapSqlParameterSource("first_name", firstName) + return namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Int::class.java)!! + } +---- + +Notice the use of the named parameter notation in the value assigned to the `sql` +variable and the corresponding value that is plugged into the `namedParameters` +variable (of type `MapSqlParameterSource`). + +Alternatively, you can pass along named parameters and their corresponding values to a +`NamedParameterJdbcTemplate` instance by using the `Map`-based style. The remaining +methods exposed by the `NamedParameterJdbcOperations` and implemented by the +`NamedParameterJdbcTemplate` class follow a similar pattern and are not covered here. + +The following example shows the use of the `Map`-based style: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // some JDBC-backed DAO class... + private NamedParameterJdbcTemplate namedParameterJdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.namedParameterJdbcTemplate = new NamedParameterJdbcTemplate(dataSource); + } + + public int countOfActorsByFirstName(String firstName) { + + String sql = "select count(*) from T_ACTOR where first_name = :first_name"; + + Map<String, String> namedParameters = Collections.singletonMap("first_name", firstName); + + return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // some JDBC-backed DAO class... + private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) + + fun countOfActorsByFirstName(firstName: String): Int { + val sql = "select count(*) from T_ACTOR where first_name = :first_name" + val namedParameters = mapOf("first_name" to firstName) + return namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Int::class.java)!! + } +---- + +One nice feature related to the `NamedParameterJdbcTemplate` (and existing in the same +Java package) is the `SqlParameterSource` interface. You have already seen an example of +an implementation of this interface in one of the previous code snippets (the +`MapSqlParameterSource` class). An `SqlParameterSource` is a source of named parameter +values to a `NamedParameterJdbcTemplate`. The `MapSqlParameterSource` class is a +simple implementation that is an adapter around a `java.util.Map`, where the keys +are the parameter names and the values are the parameter values. + +Another `SqlParameterSource` implementation is the `BeanPropertySqlParameterSource` +class. This class wraps an arbitrary JavaBean (that is, an instance of a class that +adheres to https://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html[the +JavaBean conventions]) and uses the properties of the wrapped JavaBean as the source +of named parameter values. + +The following example shows a typical JavaBean: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class Actor { + + private Long id; + private String firstName; + private String lastName; + + public String getFirstName() { + return this.firstName; + } + + public String getLastName() { + return this.lastName; + } + + public Long getId() { + return this.id; + } + + // setters omitted... + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + data class Actor(val id: Long, val firstName: String, val lastName: String) +---- + +The following example uses a `NamedParameterJdbcTemplate` to return the count of the +members of the class shown in the preceding example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // some JDBC-backed DAO class... + private NamedParameterJdbcTemplate namedParameterJdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.namedParameterJdbcTemplate = new NamedParameterJdbcTemplate(dataSource); + } + + public int countOfActors(Actor exampleActor) { + + // notice how the named parameters match the properties of the above 'Actor' class + String sql = "select count(*) from T_ACTOR where first_name = :firstName and last_name = :lastName"; + + SqlParameterSource namedParameters = new BeanPropertySqlParameterSource(exampleActor); + + return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // some JDBC-backed DAO class... + private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) + + private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) + + fun countOfActors(exampleActor: Actor): Int { + // notice how the named parameters match the properties of the above 'Actor' class + val sql = "select count(*) from T_ACTOR where first_name = :firstName and last_name = :lastName" + val namedParameters = BeanPropertySqlParameterSource(exampleActor) + return namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Int::class.java)!! + } +---- + +Remember that the `NamedParameterJdbcTemplate` class wraps a classic `JdbcTemplate` +template. If you need access to the wrapped `JdbcTemplate` instance to access +functionality that is present only in the `JdbcTemplate` class, you can use the +`getJdbcOperations()` method to access the wrapped `JdbcTemplate` through the +`JdbcOperations` interface. + +See also <<jdbc-JdbcTemplate-idioms>> for guidelines on using the +`NamedParameterJdbcTemplate` class in the context of an application. + + +[[jdbc-SQLExceptionTranslator]] +== Using `SQLExceptionTranslator` + +`SQLExceptionTranslator` is an interface to be implemented by classes that can translate +between ``SQLException``s and Spring's own `org.springframework.dao.DataAccessException`, +which is agnostic in regard to data access strategy. Implementations can be generic (for +example, using SQLState codes for JDBC) or proprietary (for example, using Oracle error +codes) for greater precision. + +`SQLErrorCodeSQLExceptionTranslator` is the implementation of `SQLExceptionTranslator` +that is used by default. This implementation uses specific vendor codes. It is more +precise than the `SQLState` implementation. The error code translations are based on +codes held in a JavaBean type class called `SQLErrorCodes`. This class is created and +populated by an `SQLErrorCodesFactory`, which (as the name suggests) is a factory for +creating `SQLErrorCodes` based on the contents of a configuration file named +`sql-error-codes.xml`. This file is populated with vendor codes and based on the +`DatabaseProductName` taken from `DatabaseMetaData`. The codes for the actual +database you are using are used. + +The `SQLErrorCodeSQLExceptionTranslator` applies matching rules in the following sequence: + +. Any custom translation implemented by a subclass. Normally, the provided concrete + `SQLErrorCodeSQLExceptionTranslator` is used, so this rule does not apply. It + applies only if you have actually provided a subclass implementation. +. Any custom implementation of the `SQLExceptionTranslator` interface that is provided + as the `customSqlExceptionTranslator` property of the `SQLErrorCodes` class. +. The list of instances of the `CustomSQLErrorCodesTranslation` class (provided for the + `customTranslations` property of the `SQLErrorCodes` class) are searched for a match. +. Error code matching is applied. +. Use the fallback translator. `SQLExceptionSubclassTranslator` is the default fallback + translator. If this translation is not available, the next fallback translator is + the `SQLStateSQLExceptionTranslator`. + +NOTE: The `SQLErrorCodesFactory` is used by default to define `Error` codes and custom exception +translations. They are looked up in a file named `sql-error-codes.xml` from the +classpath, and the matching `SQLErrorCodes` instance is located based on the database +name from the database metadata of the database in use. + +You can extend `SQLErrorCodeSQLExceptionTranslator`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class CustomSQLErrorCodesTranslator extends SQLErrorCodeSQLExceptionTranslator { + + protected DataAccessException customTranslate(String task, String sql, SQLException sqlEx) { + if (sqlEx.getErrorCode() == -12345) { + return new DeadlockLoserDataAccessException(task, sqlEx); + } + return null; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class CustomSQLErrorCodesTranslator : SQLErrorCodeSQLExceptionTranslator() { + + override fun customTranslate(task: String, sql: String?, sqlEx: SQLException): DataAccessException? { + if (sqlEx.errorCode == -12345) { + return DeadlockLoserDataAccessException(task, sqlEx) + } + return null + } + } +---- + +In the preceding example, the specific error code (`-12345`) is translated, while other errors are +left to be translated by the default translator implementation. To use this custom +translator, you must pass it to the `JdbcTemplate` through the method +`setExceptionTranslator`, and you must use this `JdbcTemplate` for all of the data access +processing where this translator is needed. The following example shows how you can use this custom +translator: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + private JdbcTemplate jdbcTemplate; + + public void setDataSource(DataSource dataSource) { + + // create a JdbcTemplate and set data source + this.jdbcTemplate = new JdbcTemplate(); + this.jdbcTemplate.setDataSource(dataSource); + + // create a custom translator and set the DataSource for the default translation lookup + CustomSQLErrorCodesTranslator tr = new CustomSQLErrorCodesTranslator(); + tr.setDataSource(dataSource); + this.jdbcTemplate.setExceptionTranslator(tr); + + } + + public void updateShippingCharge(long orderId, long pct) { + // use the prepared JdbcTemplate for this update + this.jdbcTemplate.update("update orders" + + " set shipping_charge = shipping_charge * ? / 100" + + " where id = ?", pct, orderId); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // create a JdbcTemplate and set data source + private val jdbcTemplate = JdbcTemplate(dataSource).apply { + // create a custom translator and set the DataSource for the default translation lookup + exceptionTranslator = CustomSQLErrorCodesTranslator().apply { + this.dataSource = dataSource + } + } + + fun updateShippingCharge(orderId: Long, pct: Long) { + // use the prepared JdbcTemplate for this update + this.jdbcTemplate!!.update("update orders" + + " set shipping_charge = shipping_charge * ? / 100" + + " where id = ?", pct, orderId) + } +---- + +The custom translator is passed a data source in order to look up the error codes in +`sql-error-codes.xml`. + + +[[jdbc-statements-executing]] +== Running Statements + +Running an SQL statement requires very little code. You need a `DataSource` and a +`JdbcTemplate`, including the convenience methods that are provided with the +`JdbcTemplate`. The following example shows what you need to include for a minimal but +fully functional class that creates a new table: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import javax.sql.DataSource; + import org.springframework.jdbc.core.JdbcTemplate; + + public class ExecuteAStatement { + + private JdbcTemplate jdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + public void doExecute() { + this.jdbcTemplate.execute("create table mytable (id integer, name varchar(100))"); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import javax.sql.DataSource + import org.springframework.jdbc.core.JdbcTemplate + + class ExecuteAStatement(dataSource: DataSource) { + + private val jdbcTemplate = JdbcTemplate(dataSource) + + fun doExecute() { + jdbcTemplate.execute("create table mytable (id integer, name varchar(100))") + } + } +---- + + +[[jdbc-statements-querying]] +== Running Queries + +Some query methods return a single value. To retrieve a count or a specific value from +one row, use `queryForObject(..)`. The latter converts the returned JDBC `Type` to the +Java class that is passed in as an argument. If the type conversion is invalid, an +`InvalidDataAccessApiUsageException` is thrown. The following example contains two +query methods, one for an `int` and one that queries for a `String`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import javax.sql.DataSource; + import org.springframework.jdbc.core.JdbcTemplate; + + public class RunAQuery { + + private JdbcTemplate jdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + public int getCount() { + return this.jdbcTemplate.queryForObject("select count(*) from mytable", Integer.class); + } + + public String getName() { + return this.jdbcTemplate.queryForObject("select name from mytable", String.class); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +import javax.sql.DataSource +import org.springframework.jdbc.core.JdbcTemplate + +class RunAQuery(dataSource: DataSource) { + + private val jdbcTemplate = JdbcTemplate(dataSource) + + val count: Int + get() = jdbcTemplate.queryForObject("select count(*) from mytable")!! + + val name: String? + get() = jdbcTemplate.queryForObject("select name from mytable") +} +---- + +In addition to the single result query methods, several methods return a list with an +entry for each row that the query returned. The most generic method is `queryForList(..)`, +which returns a `List` where each element is a `Map` containing one entry for each column, +using the column name as the key. If you add a method to the preceding example to retrieve a +list of all the rows, it might be as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + private JdbcTemplate jdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + public List<Map<String, Object>> getList() { + return this.jdbcTemplate.queryForList("select * from mytable"); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + private val jdbcTemplate = JdbcTemplate(dataSource) + + fun getList(): List<Map<String, Any>> { + return jdbcTemplate.queryForList("select * from mytable") + } +---- + +The returned list would resemble the following: + +[literal,subs="verbatim,quotes"] +---- +[{name=Bob, id=1}, {name=Mary, id=2}] +---- + + +[[jdbc-updates]] +== Updating the Database + +The following example updates a column for a certain primary key: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import javax.sql.DataSource; + import org.springframework.jdbc.core.JdbcTemplate; + + public class ExecuteAnUpdate { + + private JdbcTemplate jdbcTemplate; + + public void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + public void setName(int id, String name) { + this.jdbcTemplate.update("update mytable set name = ? where id = ?", name, id); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import javax.sql.DataSource + import org.springframework.jdbc.core.JdbcTemplate + + class ExecuteAnUpdate(dataSource: DataSource) { + + private val jdbcTemplate = JdbcTemplate(dataSource) + + fun setName(id: Int, name: String) { + jdbcTemplate.update("update mytable set name = ? where id = ?", name, id) + } + } +---- + +In the preceding example, +an SQL statement has placeholders for row parameters. You can pass the parameter values +in as varargs or, alternatively, as an array of objects. Thus, you should explicitly wrap primitives +in the primitive wrapper classes, or you should use auto-boxing. + + +[[jdbc-auto-generated-keys]] +== Retrieving Auto-generated Keys + +An `update()` convenience method supports the retrieval of primary keys generated by the +database. This support is part of the JDBC 3.0 standard. See Chapter 13.6 of the +specification for details. The method takes a `PreparedStatementCreator` as its first +argument, and this is the way the required insert statement is specified. The other +argument is a `KeyHolder`, which contains the generated key on successful return from the +update. There is no standard single way to create an appropriate `PreparedStatement` +(which explains why the method signature is the way it is). The following example works +on Oracle but may not work on other platforms: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + final String INSERT_SQL = "insert into my_test (name) values(?)"; + final String name = "Rob"; + + KeyHolder keyHolder = new GeneratedKeyHolder(); + jdbcTemplate.update(connection -> { + PreparedStatement ps = connection.prepareStatement(INSERT_SQL, new String[] { "id" }); + ps.setString(1, name); + return ps; + }, keyHolder); + + // keyHolder.getKey() now contains the generated key +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val INSERT_SQL = "insert into my_test (name) values(?)" + val name = "Rob" + + val keyHolder = GeneratedKeyHolder() + jdbcTemplate.update({ + it.prepareStatement (INSERT_SQL, arrayOf("id")).apply { setString(1, name) } + }, keyHolder) + + // keyHolder.getKey() now contains the generated key +---- + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc new file mode 100644 index 000000000000..53b4a855aed8 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc @@ -0,0 +1,276 @@ +[[jdbc-embedded-database-support]] += Embedded Database Support + +The `org.springframework.jdbc.datasource.embedded` package provides support for embedded +Java database engines. Support for https://www.hsqldb.org[HSQL], +https://www.h2database.com[H2], and https://db.apache.org/derby[Derby] is provided +natively. You can also use an extensible API to plug in new embedded database types and +`DataSource` implementations. + + +[[jdbc-why-embedded-database]] +== Why Use an Embedded Database? + +An embedded database can be useful during the development phase of a project because of its +lightweight nature. Benefits include ease of configuration, quick startup time, +testability, and the ability to rapidly evolve your SQL during development. + + +[[jdbc-embedded-database-xml]] +== Creating an Embedded Database by Using Spring XML + +If you want to expose an embedded database instance as a bean in a Spring +`ApplicationContext`, you can use the `embedded-database` tag in the `spring-jdbc` namespace: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <jdbc:embedded-database id="dataSource" generate-name="true"> + <jdbc:script location="classpath:schema.sql"/> + <jdbc:script location="classpath:test-data.sql"/> + </jdbc:embedded-database> +---- + +The preceding configuration creates an embedded HSQL database that is populated with SQL from +the `schema.sql` and `test-data.sql` resources in the root of the classpath. In addition, as +a best practice, the embedded database is assigned a uniquely generated name. The +embedded database is made available to the Spring container as a bean of type +`javax.sql.DataSource` that can then be injected into data access objects as needed. + + +[[jdbc-embedded-database-java]] +== Creating an Embedded Database Programmatically + +The `EmbeddedDatabaseBuilder` class provides a fluent API for constructing an embedded +database programmatically. You can use this when you need to create an embedded database in a +stand-alone environment or in a stand-alone integration test, as in the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + EmbeddedDatabase db = new EmbeddedDatabaseBuilder() + .generateUniqueName(true) + .setType(H2) + .setScriptEncoding("UTF-8") + .ignoreFailedDrops(true) + .addScript("schema.sql") + .addScripts("user_data.sql", "country_data.sql") + .build(); + + // perform actions against the db (EmbeddedDatabase extends javax.sql.DataSource) + + db.shutdown() +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val db = EmbeddedDatabaseBuilder() + .generateUniqueName(true) + .setType(H2) + .setScriptEncoding("UTF-8") + .ignoreFailedDrops(true) + .addScript("schema.sql") + .addScripts("user_data.sql", "country_data.sql") + .build() + + // perform actions against the db (EmbeddedDatabase extends javax.sql.DataSource) + + db.shutdown() +---- + +See the {api-spring-framework}/jdbc/datasource/embedded/EmbeddedDatabaseBuilder.html[javadoc for `EmbeddedDatabaseBuilder`] +for further details on all supported options. + +You can also use the `EmbeddedDatabaseBuilder` to create an embedded database by using Java +configuration, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class DataSourceConfig { + + @Bean + public DataSource dataSource() { + return new EmbeddedDatabaseBuilder() + .generateUniqueName(true) + .setType(H2) + .setScriptEncoding("UTF-8") + .ignoreFailedDrops(true) + .addScript("schema.sql") + .addScripts("user_data.sql", "country_data.sql") + .build(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class DataSourceConfig { + + @Bean + fun dataSource(): DataSource { + return EmbeddedDatabaseBuilder() + .generateUniqueName(true) + .setType(H2) + .setScriptEncoding("UTF-8") + .ignoreFailedDrops(true) + .addScript("schema.sql") + .addScripts("user_data.sql", "country_data.sql") + .build() + } + } +---- + + +[[jdbc-embedded-database-types]] +== Selecting the Embedded Database Type + +This section covers how to select one of the three embedded databases that Spring +supports. It includes the following topics: + +* <<jdbc-embedded-database-using-HSQL>> +* <<jdbc-embedded-database-using-H2>> +* <<jdbc-embedded-database-using-Derby>> + +[[jdbc-embedded-database-using-HSQL]] +=== Using HSQL + +Spring supports HSQL 1.8.0 and above. HSQL is the default embedded database if no type is +explicitly specified. To specify HSQL explicitly, set the `type` attribute of the +`embedded-database` tag to `HSQL`. If you use the builder API, call the +`setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.HSQL`. + +[[jdbc-embedded-database-using-H2]] +=== Using H2 + +Spring supports the H2 database. To enable H2, set the `type` attribute of the +`embedded-database` tag to `H2`. If you use the builder API, call the +`setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.H2`. + +[[jdbc-embedded-database-using-Derby]] +=== Using Derby + +Spring supports Apache Derby 10.5 and above. To enable Derby, set the `type` +attribute of the `embedded-database` tag to `DERBY`. If you use the builder API, +call the `setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.DERBY`. + + +[[jdbc-embedded-database-dao-testing]] +== Testing Data Access Logic with an Embedded Database + +Embedded databases provide a lightweight way to test data access code. The next example is a +data access integration test template that uses an embedded database. Using such a template +can be useful for one-offs when the embedded database does not need to be reused across test +classes. However, if you wish to create an embedded database that is shared within a test suite, +consider using the <<testing.adoc#testcontext-framework, Spring TestContext Framework>> and +configuring the embedded database as a bean in the Spring `ApplicationContext` as described +in <<jdbc-embedded-database-xml>> and <<jdbc-embedded-database-java>>. The following listing +shows the test template: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class DataAccessIntegrationTestTemplate { + + private EmbeddedDatabase db; + + @BeforeEach + public void setUp() { + // creates an HSQL in-memory database populated from default scripts + // classpath:schema.sql and classpath:data.sql + db = new EmbeddedDatabaseBuilder() + .generateUniqueName(true) + .addDefaultScripts() + .build(); + } + + @Test + public void testDataAccess() { + JdbcTemplate template = new JdbcTemplate(db); + template.query( /* ... */ ); + } + + @AfterEach + public void tearDown() { + db.shutdown(); + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class DataAccessIntegrationTestTemplate { + + private lateinit var db: EmbeddedDatabase + + @BeforeEach + fun setUp() { + // creates an HSQL in-memory database populated from default scripts + // classpath:schema.sql and classpath:data.sql + db = EmbeddedDatabaseBuilder() + .generateUniqueName(true) + .addDefaultScripts() + .build() + } + + @Test + fun testDataAccess() { + val template = JdbcTemplate(db) + template.query( /* ... */) + } + + @AfterEach + fun tearDown() { + db.shutdown() + } + } +---- + + +[[jdbc-embedded-database-unique-names]] +== Generating Unique Names for Embedded Databases + +Development teams often encounter errors with embedded databases if their test suite +inadvertently attempts to recreate additional instances of the same database. This can +happen quite easily if an XML configuration file or `@Configuration` class is responsible +for creating an embedded database and the corresponding configuration is then reused +across multiple testing scenarios within the same test suite (that is, within the same JVM +process) -- for example, integration tests against embedded databases whose +`ApplicationContext` configuration differs only with regard to which bean definition +profiles are active. + +The root cause of such errors is the fact that Spring's `EmbeddedDatabaseFactory` (used +internally by both the `<jdbc:embedded-database>` XML namespace element and the +`EmbeddedDatabaseBuilder` for Java configuration) sets the name of the embedded database to +`testdb` if not otherwise specified. For the case of `<jdbc:embedded-database>`, the +embedded database is typically assigned a name equal to the bean's `id` (often, +something like `dataSource`). Thus, subsequent attempts to create an embedded database +do not result in a new database. Instead, the same JDBC connection URL is reused, +and attempts to create a new embedded database actually point to an existing +embedded database created from the same configuration. + +To address this common issue, Spring Framework 4.2 provides support for generating +unique names for embedded databases. To enable the use of generated names, use one of +the following options. + +* `EmbeddedDatabaseFactory.setGenerateUniqueDatabaseName()` +* `EmbeddedDatabaseBuilder.generateUniqueName()` +* `<jdbc:embedded-database generate-name="true" ... >` + + +[[jdbc-embedded-database-extension]] +== Extending the Embedded Database Support + +You can extend Spring JDBC embedded database support in two ways: + +* Implement `EmbeddedDatabaseConfigurer` to support a new embedded database type. +* Implement `DataSourceFactory` to support a new `DataSource` implementation, such as a + connection pool to manage embedded database connections. + +We encourage you to contribute extensions to the Spring community at +https://github.com/spring-projects/spring-framework/issues[GitHub Issues]. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/initializing-datasource.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/initializing-datasource.adoc new file mode 100644 index 000000000000..c17999835667 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/initializing-datasource.adoc @@ -0,0 +1,146 @@ +[[jdbc-initializing-datasource]] += Initializing a `DataSource` + +The `org.springframework.jdbc.datasource.init` package provides support for initializing +an existing `DataSource`. The embedded database support provides one option for creating +and initializing a `DataSource` for an application. However, you may sometimes need to initialize +an instance that runs on a server somewhere. + + +[[jdbc-initializing-datasource-xml]] +== Initializing a Database by Using Spring XML + +If you want to initialize a database and you can provide a reference to a `DataSource` +bean, you can use the `initialize-database` tag in the `spring-jdbc` namespace: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <jdbc:initialize-database data-source="dataSource"> + <jdbc:script location="classpath:com/foo/sql/db-schema.sql"/> + <jdbc:script location="classpath:com/foo/sql/db-test-data.sql"/> + </jdbc:initialize-database> +---- + +The preceding example runs the two specified scripts against the database. The first +script creates a schema, and the second populates tables with a test data set. The script +locations can also be patterns with wildcards in the usual Ant style used for resources +in Spring (for example, +`classpath{asterisk}:/com/foo/{asterisk}{asterisk}/sql/{asterisk}-data.sql`). If you use a +pattern, the scripts are run in the lexical order of their URL or filename. + +The default behavior of the database initializer is to unconditionally run the provided +scripts. This may not always be what you want -- for instance, if you run +the scripts against a database that already has test data in it. The likelihood +of accidentally deleting data is reduced by following the common pattern (shown earlier) +of creating the tables first and then inserting the data. The first step fails if +the tables already exist. + +However, to gain more control over the creation and deletion of existing data, the XML +namespace provides a few additional options. The first is a flag to switch the +initialization on and off. You can set this according to the environment (such as pulling a +boolean value from system properties or from an environment bean). The following example gets a value from a system property: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <jdbc:initialize-database data-source="dataSource" + enabled="#{systemProperties.INITIALIZE_DATABASE}"> <1> + <jdbc:script location="..."/> + </jdbc:initialize-database> +---- +<1> Get the value for `enabled` from a system property called `INITIALIZE_DATABASE`. + + +The second option to control what happens with existing data is to be more tolerant of +failures. To this end, you can control the ability of the initializer to ignore certain +errors in the SQL it runs from the scripts, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <jdbc:initialize-database data-source="dataSource" ignore-failures="DROPS"> + <jdbc:script location="..."/> + </jdbc:initialize-database> +---- + +In the preceding example, we are saying that we expect that, sometimes, the scripts are run +against an empty database, and there are some `DROP` statements in the scripts that +would, therefore, fail. So failed SQL `DROP` statements will be ignored, but other failures +will cause an exception. This is useful if your SQL dialect doesn't support `DROP ... IF +EXISTS` (or similar) but you want to unconditionally remove all test data before +re-creating it. In that case the first script is usually a set of `DROP` statements, +followed by a set of `CREATE` statements. + +The `ignore-failures` option can be set to `NONE` (the default), `DROPS` (ignore failed +drops), or `ALL` (ignore all failures). + +Each statement should be separated by `;` or a new line if the `;` character is not +present at all in the script. You can control that globally or script by script, as the +following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <jdbc:initialize-database data-source="dataSource" separator="@@"> <1> + <jdbc:script location="classpath:com/myapp/sql/db-schema.sql" separator=";"/> <2> + <jdbc:script location="classpath:com/myapp/sql/db-test-data-1.sql"/> + <jdbc:script location="classpath:com/myapp/sql/db-test-data-2.sql"/> + </jdbc:initialize-database> +---- +<1> Set the separator scripts to `@@`. +<2> Set the separator for `db-schema.sql` to `;`. + +In this example, the two `test-data` scripts use `@@` as statement separator and only +the `db-schema.sql` uses `;`. This configuration specifies that the default separator +is `@@` and overrides that default for the `db-schema` script. + +If you need more control than you get from the XML namespace, you can use the +`DataSourceInitializer` directly and define it as a component in your application. + +[[jdbc-client-component-initialization]] +=== Initialization of Other Components that Depend on the Database + +A large class of applications (those that do not use the database until after the Spring context has +started) can use the database initializer with no further +complications. If your application is not one of those, you might need to read the rest +of this section. + +The database initializer depends on a `DataSource` instance and runs the scripts +provided in its initialization callback (analogous to an `init-method` in an XML bean +definition, a `@PostConstruct` method in a component, or the `afterPropertiesSet()` +method in a component that implements `InitializingBean`). If other beans depend on the +same data source and use the data source in an initialization callback, there +might be a problem because the data has not yet been initialized. A common example of +this is a cache that initializes eagerly and loads data from the database on application +startup. + +To get around this issue, you have two options: change your cache initialization strategy +to a later phase or ensure that the database initializer is initialized first. + +Changing your cache initialization strategy might be easy if the application is in your control and not otherwise. +Some suggestions for how to implement this include: + +* Make the cache initialize lazily on first usage, which improves application startup + time. +* Have your cache or a separate component that initializes the cache implement + `Lifecycle` or `SmartLifecycle`. When the application context starts, you can + automatically start a `SmartLifecycle` by setting its `autoStartup` flag, and you can + manually start a `Lifecycle` by calling `ConfigurableApplicationContext.start()` + on the enclosing context. +* Use a Spring `ApplicationEvent` or similar custom observer mechanism to trigger the + cache initialization. `ContextRefreshedEvent` is always published by the context when + it is ready for use (after all beans have been initialized), so that is often a useful + hook (this is how the `SmartLifecycle` works by default). + +Ensuring that the database initializer is initialized first can also be easy. Some suggestions on how to implement this include: + +* Rely on the default behavior of the Spring `BeanFactory`, which is that beans are + initialized in registration order. You can easily arrange that by adopting the common + practice of a set of `<import/>` elements in XML configuration that order your + application modules and ensuring that the database and database initialization are + listed first. +* Separate the `DataSource` and the business components that use it and control their + startup order by putting them in separate `ApplicationContext` instances (for example, the + parent context contains the `DataSource`, and the child context contains the business + components). This structure is common in Spring web applications but can be more + generally applied. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc new file mode 100644 index 000000000000..f3489b5082cc --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc @@ -0,0 +1,544 @@ +[[jdbc-object]] += Modeling JDBC Operations as Java Objects + +The `org.springframework.jdbc.object` package contains classes that let you access +the database in a more object-oriented manner. As an example, you can run queries +and get the results back as a list that contains business objects with the relational +column data mapped to the properties of the business object. You can also run stored +procedures and run update, delete, and insert statements. + +[NOTE] +==== +Many Spring developers believe that the various RDBMS operation classes described below +(with the exception of the <<jdbc-StoredProcedure, `StoredProcedure`>> class) can often +be replaced with straight `JdbcTemplate` calls. Often, it is simpler to write a DAO +method that calls a method on a `JdbcTemplate` directly (as opposed to +encapsulating a query as a full-blown class). + +However, if you are getting measurable value from using the RDBMS operation classes, +you should continue to use these classes. +==== + + +[[jdbc-SqlQuery]] +== Understanding `SqlQuery` + +`SqlQuery` is a reusable, thread-safe class that encapsulates an SQL query. Subclasses +must implement the `newRowMapper(..)` method to provide a `RowMapper` instance that can +create one object per row obtained from iterating over the `ResultSet` that is created +during the execution of the query. The `SqlQuery` class is rarely used directly, because +the `MappingSqlQuery` subclass provides a much more convenient implementation for +mapping rows to Java classes. Other implementations that extend `SqlQuery` are +`MappingSqlQueryWithParameters` and `UpdatableSqlQuery`. + + +[[jdbc-MappingSqlQuery]] +== Using `MappingSqlQuery` + +`MappingSqlQuery` is a reusable query in which concrete subclasses must implement the +abstract `mapRow(..)` method to convert each row of the supplied `ResultSet` into an +object of the type specified. The following example shows a custom query that maps the +data from the `t_actor` relation to an instance of the `Actor` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ActorMappingQuery extends MappingSqlQuery<Actor> { + + public ActorMappingQuery(DataSource ds) { + super(ds, "select id, first_name, last_name from t_actor where id = ?"); + declareParameter(new SqlParameter("id", Types.INTEGER)); + compile(); + } + + @Override + protected Actor mapRow(ResultSet rs, int rowNumber) throws SQLException { + Actor actor = new Actor(); + actor.setId(rs.getLong("id")); + actor.setFirstName(rs.getString("first_name")); + actor.setLastName(rs.getString("last_name")); + return actor; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ActorMappingQuery(ds: DataSource) : MappingSqlQuery<Actor>(ds, "select id, first_name, last_name from t_actor where id = ?") { + + init { + declareParameter(SqlParameter("id", Types.INTEGER)) + compile() + } + + override fun mapRow(rs: ResultSet, rowNumber: Int) = Actor( + rs.getLong("id"), + rs.getString("first_name"), + rs.getString("last_name") + ) + } + +---- + +The class extends `MappingSqlQuery` parameterized with the `Actor` type. The constructor +for this customer query takes a `DataSource` as the only parameter. In this +constructor, you can call the constructor on the superclass with the `DataSource` and the SQL +that should be run to retrieve the rows for this query. This SQL is used to +create a `PreparedStatement`, so it may contain placeholders for any parameters to be +passed in during execution. You must declare each parameter by using the `declareParameter` +method passing in an `SqlParameter`. The `SqlParameter` takes a name, and the JDBC type +as defined in `java.sql.Types`. After you define all parameters, you can call the +`compile()` method so that the statement can be prepared and later run. This class is +thread-safe after it is compiled, so, as long as these instances are created when the DAO +is initialized, they can be kept as instance variables and be reused. The following +example shows how to define such a class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + private ActorMappingQuery actorMappingQuery; + + @Autowired + public void setDataSource(DataSource dataSource) { + this.actorMappingQuery = new ActorMappingQuery(dataSource); + } + + public Customer getCustomer(Long id) { + return actorMappingQuery.findObject(id); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + private val actorMappingQuery = ActorMappingQuery(dataSource) + + fun getCustomer(id: Long) = actorMappingQuery.findObject(id) +---- + +The method in the preceding example retrieves the customer with the `id` that is passed in as the +only parameter. Since we want only one object to be returned, we call the `findObject` convenience +method with the `id` as the parameter. If we had instead a query that returned a +list of objects and took additional parameters, we would use one of the `execute` +methods that takes an array of parameter values passed in as varargs. The following +example shows such a method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public List<Actor> searchForActors(int age, String namePattern) { + return actorSearchMappingQuery.execute(age, namePattern); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun searchForActors(age: Int, namePattern: String) = + actorSearchMappingQuery.execute(age, namePattern) +---- + + +[[jdbc-SqlUpdate]] +== Using `SqlUpdate` + +The `SqlUpdate` class encapsulates an SQL update. As with a query, an update object is +reusable, and, as with all `RdbmsOperation` classes, an update can have parameters and is +defined in SQL. This class provides a number of `update(..)` methods analogous to the +`execute(..)` methods of query objects. The `SqlUpdate` class is concrete. It can be +subclassed -- for example, to add a custom update method. +However, you do not have to subclass the `SqlUpdate` +class, since it can easily be parameterized by setting SQL and declaring parameters. +The following example creates a custom update method named `execute`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import java.sql.Types; + import javax.sql.DataSource; + import org.springframework.jdbc.core.SqlParameter; + import org.springframework.jdbc.object.SqlUpdate; + + public class UpdateCreditRating extends SqlUpdate { + + public UpdateCreditRating(DataSource ds) { + setDataSource(ds); + setSql("update customer set credit_rating = ? where id = ?"); + declareParameter(new SqlParameter("creditRating", Types.NUMERIC)); + declareParameter(new SqlParameter("id", Types.NUMERIC)); + compile(); + } + + /** + * @param id for the Customer to be updated + * @param rating the new value for credit rating + * @return number of rows updated + */ + public int execute(int id, int rating) { + return update(rating, id); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import java.sql.Types + import javax.sql.DataSource + import org.springframework.jdbc.core.SqlParameter + import org.springframework.jdbc.`object`.SqlUpdate + + class UpdateCreditRating(ds: DataSource) : SqlUpdate() { + + init { + setDataSource(ds) + sql = "update customer set credit_rating = ? where id = ?" + declareParameter(SqlParameter("creditRating", Types.NUMERIC)) + declareParameter(SqlParameter("id", Types.NUMERIC)) + compile() + } + + /** + * @param id for the Customer to be updated + * @param rating the new value for credit rating + * @return number of rows updated + */ + fun execute(id: Int, rating: Int): Int { + return update(rating, id) + } + } +---- + + +[[jdbc-StoredProcedure]] +== Using `StoredProcedure` + +The `StoredProcedure` class is an `abstract` superclass for object abstractions of RDBMS +stored procedures. + +The inherited `sql` property is the name of the stored procedure in the RDBMS. + +To define a parameter for the `StoredProcedure` class, you can use an `SqlParameter` or one +of its subclasses. You must specify the parameter name and SQL type in the constructor, +as the following code snippet shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + new SqlParameter("in_id", Types.NUMERIC), + new SqlOutParameter("out_first_name", Types.VARCHAR), +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + SqlParameter("in_id", Types.NUMERIC), + SqlOutParameter("out_first_name", Types.VARCHAR), +---- + +The SQL type is specified using the `java.sql.Types` constants. + +The first line (with the `SqlParameter`) declares an IN parameter. You can use IN parameters +both for stored procedure calls and for queries using the `SqlQuery` and its +subclasses (covered in <<jdbc-SqlQuery>>). + +The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in the +stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters +(parameters that provide an `in` value to the procedure and that also return a value). + +For `in` parameters, in addition to the name and the SQL type, you can specify a +scale for numeric data or a type name for custom database types. For `out` parameters, +you can provide a `RowMapper` to handle mapping of rows returned from a `REF` cursor. +Another option is to specify an `SqlReturnType` that lets you define customized +handling of the return values. + +The next example of a simple DAO uses a `StoredProcedure` to call a function +(`sysdate()`), which comes with any Oracle database. To use the stored procedure +functionality, you have to create a class that extends `StoredProcedure`. In this +example, the `StoredProcedure` class is an inner class. However, if you need to reuse the +`StoredProcedure`, you can declare it as a top-level class. This example has no input +parameters, but an output parameter is declared as a date type by using the +`SqlOutParameter` class. The `execute()` method runs the procedure and extracts the +returned date from the results `Map`. The results `Map` has an entry for each declared +output parameter (in this case, only one) by using the parameter name as the key. +The following listing shows our custom StoredProcedure class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import java.sql.Types; + import java.util.Date; + import java.util.HashMap; + import java.util.Map; + import javax.sql.DataSource; + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.jdbc.core.SqlOutParameter; + import org.springframework.jdbc.object.StoredProcedure; + + public class StoredProcedureDao { + + private GetSysdateProcedure getSysdate; + + @Autowired + public void init(DataSource dataSource) { + this.getSysdate = new GetSysdateProcedure(dataSource); + } + + public Date getSysdate() { + return getSysdate.execute(); + } + + private class GetSysdateProcedure extends StoredProcedure { + + private static final String SQL = "sysdate"; + + public GetSysdateProcedure(DataSource dataSource) { + setDataSource(dataSource); + setFunction(true); + setSql(SQL); + declareParameter(new SqlOutParameter("date", Types.DATE)); + compile(); + } + + public Date execute() { + // the 'sysdate' sproc has no input parameters, so an empty Map is supplied... + Map<String, Object> results = execute(new HashMap<String, Object>()); + Date sysdate = (Date) results.get("date"); + return sysdate; + } + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import java.sql.Types + import java.util.Date + import java.util.Map + import javax.sql.DataSource + import org.springframework.jdbc.core.SqlOutParameter + import org.springframework.jdbc.object.StoredProcedure + + class StoredProcedureDao(dataSource: DataSource) { + + private val SQL = "sysdate" + + private val getSysdate = GetSysdateProcedure(dataSource) + + val sysdate: Date + get() = getSysdate.execute() + + private inner class GetSysdateProcedure(dataSource: DataSource) : StoredProcedure() { + + init { + setDataSource(dataSource) + isFunction = true + sql = SQL + declareParameter(SqlOutParameter("date", Types.DATE)) + compile() + } + + fun execute(): Date { + // the 'sysdate' sproc has no input parameters, so an empty Map is supplied... + val results = execute(mutableMapOf<String, Any>()) + return results["date"] as Date + } + } + } +---- + +The following example of a `StoredProcedure` has two output parameters (in this case, +Oracle REF cursors): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import java.util.HashMap; + import java.util.Map; + import javax.sql.DataSource; + import oracle.jdbc.OracleTypes; + import org.springframework.jdbc.core.SqlOutParameter; + import org.springframework.jdbc.object.StoredProcedure; + + public class TitlesAndGenresStoredProcedure extends StoredProcedure { + + private static final String SPROC_NAME = "AllTitlesAndGenres"; + + public TitlesAndGenresStoredProcedure(DataSource dataSource) { + super(dataSource, SPROC_NAME); + declareParameter(new SqlOutParameter("titles", OracleTypes.CURSOR, new TitleMapper())); + declareParameter(new SqlOutParameter("genres", OracleTypes.CURSOR, new GenreMapper())); + compile(); + } + + public Map<String, Object> execute() { + // again, this sproc has no input parameters, so an empty Map is supplied + return super.execute(new HashMap<String, Object>()); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import java.util.HashMap + import javax.sql.DataSource + import oracle.jdbc.OracleTypes + import org.springframework.jdbc.core.SqlOutParameter + import org.springframework.jdbc.`object`.StoredProcedure + + class TitlesAndGenresStoredProcedure(dataSource: DataSource) : StoredProcedure(dataSource, SPROC_NAME) { + + companion object { + private const val SPROC_NAME = "AllTitlesAndGenres" + } + + init { + declareParameter(SqlOutParameter("titles", OracleTypes.CURSOR, TitleMapper())) + declareParameter(SqlOutParameter("genres", OracleTypes.CURSOR, GenreMapper())) + compile() + } + + fun execute(): Map<String, Any> { + // again, this sproc has no input parameters, so an empty Map is supplied + return super.execute(HashMap<String, Any>()) + } + } +---- + +Notice how the overloaded variants of the `declareParameter(..)` method that have been +used in the `TitlesAndGenresStoredProcedure` constructor are passed `RowMapper` +implementation instances. This is a very convenient and powerful way to reuse existing +functionality. The next two examples provide code for the two `RowMapper` implementations. + +The `TitleMapper` class maps a `ResultSet` to a `Title` domain object for each row in +the supplied `ResultSet`, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import java.sql.ResultSet; + import java.sql.SQLException; + import com.foo.domain.Title; + import org.springframework.jdbc.core.RowMapper; + + public final class TitleMapper implements RowMapper<Title> { + + public Title mapRow(ResultSet rs, int rowNum) throws SQLException { + Title title = new Title(); + title.setId(rs.getLong("id")); + title.setName(rs.getString("name")); + return title; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import java.sql.ResultSet + import com.foo.domain.Title + import org.springframework.jdbc.core.RowMapper + + class TitleMapper : RowMapper<Title> { + + override fun mapRow(rs: ResultSet, rowNum: Int) = + Title(rs.getLong("id"), rs.getString("name")) + } +---- + +The `GenreMapper` class maps a `ResultSet` to a `Genre` domain object for each row in +the supplied `ResultSet`, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import java.sql.ResultSet; + import java.sql.SQLException; + import com.foo.domain.Genre; + import org.springframework.jdbc.core.RowMapper; + + public final class GenreMapper implements RowMapper<Genre> { + + public Genre mapRow(ResultSet rs, int rowNum) throws SQLException { + return new Genre(rs.getString("name")); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import java.sql.ResultSet + import com.foo.domain.Genre + import org.springframework.jdbc.core.RowMapper + + class GenreMapper : RowMapper<Genre> { + + override fun mapRow(rs: ResultSet, rowNum: Int): Genre { + return Genre(rs.getString("name")) + } + } +---- + +To pass parameters to a stored procedure that has one or more input parameters in its +definition in the RDBMS, you can code a strongly typed `execute(..)` method that would +delegate to the untyped `execute(Map)` method in the superclass, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import java.sql.Types; + import java.util.Date; + import java.util.HashMap; + import java.util.Map; + import javax.sql.DataSource; + import oracle.jdbc.OracleTypes; + import org.springframework.jdbc.core.SqlOutParameter; + import org.springframework.jdbc.core.SqlParameter; + import org.springframework.jdbc.object.StoredProcedure; + + public class TitlesAfterDateStoredProcedure extends StoredProcedure { + + private static final String SPROC_NAME = "TitlesAfterDate"; + private static final String CUTOFF_DATE_PARAM = "cutoffDate"; + + public TitlesAfterDateStoredProcedure(DataSource dataSource) { + super(dataSource, SPROC_NAME); + declareParameter(new SqlParameter(CUTOFF_DATE_PARAM, Types.DATE); + declareParameter(new SqlOutParameter("titles", OracleTypes.CURSOR, new TitleMapper())); + compile(); + } + + public Map<String, Object> execute(Date cutoffDate) { + Map<String, Object> inputs = new HashMap<String, Object>(); + inputs.put(CUTOFF_DATE_PARAM, cutoffDate); + return super.execute(inputs); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import java.sql.Types + import java.util.Date + import javax.sql.DataSource + import oracle.jdbc.OracleTypes + import org.springframework.jdbc.core.SqlOutParameter + import org.springframework.jdbc.core.SqlParameter + import org.springframework.jdbc.`object`.StoredProcedure + + class TitlesAfterDateStoredProcedure(dataSource: DataSource) : StoredProcedure(dataSource, SPROC_NAME) { + + companion object { + private const val SPROC_NAME = "TitlesAfterDate" + private const val CUTOFF_DATE_PARAM = "cutoffDate" + } + + init { + declareParameter(SqlParameter(CUTOFF_DATE_PARAM, Types.DATE)) + declareParameter(SqlOutParameter("titles", OracleTypes.CURSOR, TitleMapper())) + compile() + } + + fun execute(cutoffDate: Date) = super.execute( + mapOf<String, Any>(CUTOFF_DATE_PARAM to cutoffDate)) + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc new file mode 100644 index 000000000000..5d4a56cbb531 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc @@ -0,0 +1,36 @@ +[[jdbc-packages]] += Package Hierarchy + +The Spring Framework's JDBC abstraction framework consists of four different packages: + +* `core`: The `org.springframework.jdbc.core` package contains the `JdbcTemplate` class and its +various callback interfaces, plus a variety of related classes. A subpackage named +`org.springframework.jdbc.core.simple` contains the `SimpleJdbcInsert` and +`SimpleJdbcCall` classes. Another subpackage named +`org.springframework.jdbc.core.namedparam` contains the `NamedParameterJdbcTemplate` +class and the related support classes. See <<jdbc-core>>, <<jdbc-advanced-jdbc>>, and +<<jdbc-simple-jdbc>>. + +* `datasource`: The `org.springframework.jdbc.datasource` package contains a utility class for easy +`DataSource` access and various simple `DataSource` implementations that you can use for +testing and running unmodified JDBC code outside of a Jakarta EE container. A subpackage +named `org.springfamework.jdbc.datasource.embedded` provides support for creating +embedded databases by using Java database engines, such as HSQL, H2, and Derby. See +<<jdbc-connections>> and <<jdbc-embedded-database-support>>. + +* `object`: The `org.springframework.jdbc.object` package contains classes that represent RDBMS +queries, updates, and stored procedures as thread-safe, reusable objects. See +<<jdbc-object>>. This approach is modeled by JDO, although objects returned by queries +are naturally disconnected from the database. This higher-level of JDBC abstraction +depends on the lower-level abstraction in the `org.springframework.jdbc.core` package. + +* `support`: The `org.springframework.jdbc.support` package provides `SQLException` translation +functionality and some utility classes. Exceptions thrown during JDBC processing are +translated to exceptions defined in the `org.springframework.dao` package. This means +that code using the Spring JDBC abstraction layer does not need to implement JDBC or +RDBMS-specific error handling. All translated exceptions are unchecked, which gives you +the option of catching the exceptions from which you can recover while letting other +exceptions be propagated to the caller. See <<jdbc-SQLExceptionTranslator>>. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/parameter-handling.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/parameter-handling.adoc new file mode 100644 index 000000000000..09210858805f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/parameter-handling.adoc @@ -0,0 +1,322 @@ +[[jdbc-parameter-handling]] += Common Problems with Parameter and Data Value Handling + +Common problems with parameters and data values exist in the different approaches +provided by Spring Framework's JDBC support. This section covers how to address them. + + +[[jdbc-type-information]] +== Providing SQL Type Information for Parameters + +Usually, Spring determines the SQL type of the parameters based on the type of parameter +passed in. It is possible to explicitly provide the SQL type to be used when setting +parameter values. This is sometimes necessary to correctly set `NULL` values. + +You can provide SQL type information in several ways: + +* Many update and query methods of the `JdbcTemplate` take an additional parameter in + the form of an `int` array. This array is used to indicate the SQL type of the + corresponding parameter by using constant values from the `java.sql.Types` class. Provide + one entry for each parameter. +* You can use the `SqlParameterValue` class to wrap the parameter value that needs this + additional information. To do so, create a new instance for each value and pass in the SQL type + and the parameter value in the constructor. You can also provide an optional scale + parameter for numeric values. +* For methods that work with named parameters, you can use the `SqlParameterSource` classes, + `BeanPropertySqlParameterSource` or `MapSqlParameterSource`. They both have methods + for registering the SQL type for any of the named parameter values. + + +[[jdbc-lob]] +== Handling BLOB and CLOB objects + +You can store images, other binary data, and large chunks of text in the database. These +large objects are called BLOBs (Binary Large OBject) for binary data and CLOBs (Character +Large OBject) for character data. In Spring, you can handle these large objects by using +the `JdbcTemplate` directly and also when using the higher abstractions provided by RDBMS +Objects and the `SimpleJdbc` classes. All of these approaches use an implementation of +the `LobHandler` interface for the actual management of the LOB (Large OBject) data. +`LobHandler` provides access to a `LobCreator` class, through the `getLobCreator` method, +that is used for creating new LOB objects to be inserted. + +`LobCreator` and `LobHandler` provide the following support for LOB input and output: + +* BLOB +** `byte[]`: `getBlobAsBytes` and `setBlobAsBytes` +** `InputStream`: `getBlobAsBinaryStream` and `setBlobAsBinaryStream` +* CLOB +** `String`: `getClobAsString` and `setClobAsString` +** `InputStream`: `getClobAsAsciiStream` and `setClobAsAsciiStream` +** `Reader`: `getClobAsCharacterStream` and `setClobAsCharacterStream` + +The next example shows how to create and insert a BLOB. Later we show how to read +it back from the database. + +This example uses a `JdbcTemplate` and an implementation of the +`AbstractLobCreatingPreparedStatementCallback`. It implements one method, +`setValues`. This method provides a `LobCreator` that we use to set the values for the +LOB columns in your SQL insert statement. + +For this example, we assume that there is a variable, `lobHandler`, that is already +set to an instance of a `DefaultLobHandler`. You typically set this value through +dependency injection. + +The following example shows how to create and insert a BLOB: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + final File blobIn = new File("spring2004.jpg"); + final InputStream blobIs = new FileInputStream(blobIn); + final File clobIn = new File("large.txt"); + final InputStream clobIs = new FileInputStream(clobIn); + final InputStreamReader clobReader = new InputStreamReader(clobIs); + + jdbcTemplate.execute( + "INSERT INTO lob_table (id, a_clob, a_blob) VALUES (?, ?, ?)", + new AbstractLobCreatingPreparedStatementCallback(lobHandler) { // <1> + protected void setValues(PreparedStatement ps, LobCreator lobCreator) throws SQLException { + ps.setLong(1, 1L); + lobCreator.setClobAsCharacterStream(ps, 2, clobReader, (int)clobIn.length()); // <2> + lobCreator.setBlobAsBinaryStream(ps, 3, blobIs, (int)blobIn.length()); // <3> + } + } + ); + + blobIs.close(); + clobReader.close(); +---- +<1> Pass in the `lobHandler` that (in this example) is a plain `DefaultLobHandler`. +<2> Using the method `setClobAsCharacterStream` to pass in the contents of the CLOB. +<3> Using the method `setBlobAsBinaryStream` to pass in the contents of the BLOB. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val blobIn = File("spring2004.jpg") + val blobIs = FileInputStream(blobIn) + val clobIn = File("large.txt") + val clobIs = FileInputStream(clobIn) + val clobReader = InputStreamReader(clobIs) + + jdbcTemplate.execute( + "INSERT INTO lob_table (id, a_clob, a_blob) VALUES (?, ?, ?)", + object: AbstractLobCreatingPreparedStatementCallback(lobHandler) { // <1> + override fun setValues(ps: PreparedStatement, lobCreator: LobCreator) { + ps.setLong(1, 1L) + lobCreator.setClobAsCharacterStream(ps, 2, clobReader, clobIn.length().toInt()) // <2> + lobCreator.setBlobAsBinaryStream(ps, 3, blobIs, blobIn.length().toInt()) // <3> + } + } + ) + blobIs.close() + clobReader.close() +---- +<1> Pass in the `lobHandler` that (in this example) is a plain `DefaultLobHandler`. +<2> Using the method `setClobAsCharacterStream` to pass in the contents of the CLOB. +<3> Using the method `setBlobAsBinaryStream` to pass in the contents of the BLOB. + + +[NOTE] +==== +If you invoke the `setBlobAsBinaryStream`, `setClobAsAsciiStream`, or +`setClobAsCharacterStream` method on the `LobCreator` returned from +`DefaultLobHandler.getLobCreator()`, you can optionally specify a negative value for the +`contentLength` argument. If the specified content length is negative, the +`DefaultLobHandler` uses the JDBC 4.0 variants of the set-stream methods without a +length parameter. Otherwise, it passes the specified length on to the driver. + +See the documentation for the JDBC driver you use to verify that it supports streaming a +LOB without providing the content length. +==== + +Now it is time to read the LOB data from the database. Again, you use a `JdbcTemplate` +with the same instance variable `lobHandler` and a reference to a `DefaultLobHandler`. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + List<Map<String, Object>> l = jdbcTemplate.query("select id, a_clob, a_blob from lob_table", + new RowMapper<Map<String, Object>>() { + public Map<String, Object> mapRow(ResultSet rs, int i) throws SQLException { + Map<String, Object> results = new HashMap<String, Object>(); + String clobText = lobHandler.getClobAsString(rs, "a_clob"); // <1> + results.put("CLOB", clobText); + byte[] blobBytes = lobHandler.getBlobAsBytes(rs, "a_blob"); // <2> + results.put("BLOB", blobBytes); + return results; + } + }); +---- +<1> Using the method `getClobAsString` to retrieve the contents of the CLOB. +<2> Using the method `getBlobAsBytes` to retrieve the contents of the BLOB. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val l = jdbcTemplate.query("select id, a_clob, a_blob from lob_table") { rs, _ -> + val clobText = lobHandler.getClobAsString(rs, "a_clob") // <1> + val blobBytes = lobHandler.getBlobAsBytes(rs, "a_blob") // <2> + mapOf("CLOB" to clobText, "BLOB" to blobBytes) + } +---- +<1> Using the method `getClobAsString` to retrieve the contents of the CLOB. +<2> Using the method `getBlobAsBytes` to retrieve the contents of the BLOB. + + +[[jdbc-in-clause]] +== Passing in Lists of Values for IN Clause + +The SQL standard allows for selecting rows based on an expression that includes a +variable list of values. A typical example would be `select * from T_ACTOR where id in +(1, 2, 3)`. This variable list is not directly supported for prepared statements by the +JDBC standard. You cannot declare a variable number of placeholders. You need a number +of variations with the desired number of placeholders prepared, or you need to generate +the SQL string dynamically once you know how many placeholders are required. The named +parameter support provided in the `NamedParameterJdbcTemplate` and `JdbcTemplate` takes +the latter approach. You can pass in the values as a `java.util.List` of primitive objects. This +list is used to insert the required placeholders and pass in the values during +statement execution. + +NOTE: Be careful when passing in many values. The JDBC standard does not guarantee that you +can use more than 100 values for an `in` expression list. Various databases exceed this +number, but they usually have a hard limit for how many values are allowed. For example, Oracle's +limit is 1000. + +In addition to the primitive values in the value list, you can create a `java.util.List` +of object arrays. This list can support multiple expressions being defined for the `in` +clause, such as `+++select * from T_ACTOR where (id, last_name) in ((1, 'Johnson'), (2, +'Harrop'))+++`. This, of course, requires that your database supports this syntax. + + +[[jdbc-complex-types]] +== Handling Complex Types for Stored Procedure Calls + +When you call stored procedures, you can sometimes use complex types specific to the +database. To accommodate these types, Spring provides a `SqlReturnType` for handling +them when they are returned from the stored procedure call and `SqlTypeValue` when they +are passed in as a parameter to the stored procedure. + +The `SqlReturnType` interface has a single method (named `getTypeValue`) that must be +implemented. This interface is used as part of the declaration of an `SqlOutParameter`. +The following example shows returning the value of an Oracle `STRUCT` object of the user +declared type `ITEM_TYPE`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class TestItemStoredProcedure extends StoredProcedure { + + public TestItemStoredProcedure(DataSource dataSource) { + // ... + declareParameter(new SqlOutParameter("item", OracleTypes.STRUCT, "ITEM_TYPE", + (CallableStatement cs, int colIndx, int sqlType, String typeName) -> { + STRUCT struct = (STRUCT) cs.getObject(colIndx); + Object[] attr = struct.getAttributes(); + TestItem item = new TestItem(); + item.setId(((Number) attr[0]).longValue()); + item.setDescription((String) attr[1]); + item.setExpirationDate((java.util.Date) attr[2]); + return item; + })); + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class TestItemStoredProcedure(dataSource: DataSource) : StoredProcedure() { + + init { + // ... + declareParameter(SqlOutParameter("item", OracleTypes.STRUCT, "ITEM_TYPE") { cs, colIndx, sqlType, typeName -> + val struct = cs.getObject(colIndx) as STRUCT + val attr = struct.getAttributes() + TestItem((attr[0] as Long, attr[1] as String, attr[2] as Date) + }) + // ... + } + } +---- + +You can use `SqlTypeValue` to pass the value of a Java object (such as `TestItem`) to a +stored procedure. The `SqlTypeValue` interface has a single method (named +`createTypeValue`) that you must implement. The active connection is passed in, and you +can use it to create database-specific objects, such as `StructDescriptor` instances +or `ArrayDescriptor` instances. The following example creates a `StructDescriptor` instance: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + final TestItem testItem = new TestItem(123L, "A test item", + new SimpleDateFormat("yyyy-M-d").parse("2010-12-31")); + + SqlTypeValue value = new AbstractSqlTypeValue() { + protected Object createTypeValue(Connection conn, int sqlType, String typeName) throws SQLException { + StructDescriptor itemDescriptor = new StructDescriptor(typeName, conn); + Struct item = new STRUCT(itemDescriptor, conn, + new Object[] { + testItem.getId(), + testItem.getDescription(), + new java.sql.Date(testItem.getExpirationDate().getTime()) + }); + return item; + } + }; +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val (id, description, expirationDate) = TestItem(123L, "A test item", + SimpleDateFormat("yyyy-M-d").parse("2010-12-31")) + + val value = object : AbstractSqlTypeValue() { + override fun createTypeValue(conn: Connection, sqlType: Int, typeName: String?): Any { + val itemDescriptor = StructDescriptor(typeName, conn) + return STRUCT(itemDescriptor, conn, + arrayOf(id, description, java.sql.Date(expirationDate.time))) + } + } +---- + +You can now add this `SqlTypeValue` to the `Map` that contains the input parameters for the +`execute` call of the stored procedure. + +Another use for the `SqlTypeValue` is passing in an array of values to an Oracle stored +procedure. Oracle has its own internal `ARRAY` class that must be used in this case, and +you can use the `SqlTypeValue` to create an instance of the Oracle `ARRAY` and populate +it with values from the Java `ARRAY`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + final Long[] ids = new Long[] {1L, 2L}; + + SqlTypeValue value = new AbstractSqlTypeValue() { + protected Object createTypeValue(Connection conn, int sqlType, String typeName) throws SQLException { + ArrayDescriptor arrayDescriptor = new ArrayDescriptor(typeName, conn); + ARRAY idArray = new ARRAY(arrayDescriptor, conn, ids); + return idArray; + } + }; +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class TestItemStoredProcedure(dataSource: DataSource) : StoredProcedure() { + + init { + val ids = arrayOf(1L, 2L) + val value = object : AbstractSqlTypeValue() { + override fun createTypeValue(conn: Connection, sqlType: Int, typeName: String?): Any { + val arrayDescriptor = ArrayDescriptor(typeName, conn) + return ARRAY(arrayDescriptor, conn, ids) + } + } + } + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc new file mode 100644 index 000000000000..ef434dce1c4c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc @@ -0,0 +1,707 @@ +[[jdbc-simple-jdbc]] += Simplifying JDBC Operations with the `SimpleJdbc` Classes + +The `SimpleJdbcInsert` and `SimpleJdbcCall` classes provide a simplified configuration +by taking advantage of database metadata that can be retrieved through the JDBC driver. +This means that you have less to configure up front, although you can override or turn off +the metadata processing if you prefer to provide all the details in your code. + + +[[jdbc-simple-jdbc-insert-1]] +== Inserting Data by Using `SimpleJdbcInsert` + +We start by looking at the `SimpleJdbcInsert` class with the minimal amount of +configuration options. You should instantiate the `SimpleJdbcInsert` in the data access +layer's initialization method. For this example, the initializing method is the +`setDataSource` method. You do not need to subclass the `SimpleJdbcInsert` class. Instead, +you can create a new instance and set the table name by using the `withTableName` method. +Configuration methods for this class follow the `fluid` style that returns the instance +of the `SimpleJdbcInsert`, which lets you chain all configuration methods. The following +example uses only one configuration method (we show examples of multiple methods later): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcInsert insertActor; + + public void setDataSource(DataSource dataSource) { + this.insertActor = new SimpleJdbcInsert(dataSource).withTableName("t_actor"); + } + + public void add(Actor actor) { + Map<String, Object> parameters = new HashMap<>(3); + parameters.put("id", actor.getId()); + parameters.put("first_name", actor.getFirstName()); + parameters.put("last_name", actor.getLastName()); + insertActor.execute(parameters); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val insertActor = SimpleJdbcInsert(dataSource).withTableName("t_actor") + + fun add(actor: Actor) { + val parameters = mutableMapOf<String, Any>() + parameters["id"] = actor.id + parameters["first_name"] = actor.firstName + parameters["last_name"] = actor.lastName + insertActor.execute(parameters) + } + + // ... additional methods + } +---- + +The `execute` method used here takes a plain `java.util.Map` as its only parameter. The +important thing to note here is that the keys used for the `Map` must match the column +names of the table, as defined in the database. This is because we read the metadata +to construct the actual insert statement. + + +[[jdbc-simple-jdbc-insert-2]] +== Retrieving Auto-generated Keys by Using `SimpleJdbcInsert` + +The next example uses the same insert as the preceding example, but, instead of passing in the `id`, it +retrieves the auto-generated key and sets it on the new `Actor` object. When it creates +the `SimpleJdbcInsert`, in addition to specifying the table name, it specifies the name +of the generated key column with the `usingGeneratedKeyColumns` method. The following +listing shows how it works: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcInsert insertActor; + + public void setDataSource(DataSource dataSource) { + this.insertActor = new SimpleJdbcInsert(dataSource) + .withTableName("t_actor") + .usingGeneratedKeyColumns("id"); + } + + public void add(Actor actor) { + Map<String, Object> parameters = new HashMap<>(2); + parameters.put("first_name", actor.getFirstName()); + parameters.put("last_name", actor.getLastName()); + Number newId = insertActor.executeAndReturnKey(parameters); + actor.setId(newId.longValue()); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val insertActor = SimpleJdbcInsert(dataSource) + .withTableName("t_actor").usingGeneratedKeyColumns("id") + + fun add(actor: Actor): Actor { + val parameters = mapOf( + "first_name" to actor.firstName, + "last_name" to actor.lastName) + val newId = insertActor.executeAndReturnKey(parameters); + return actor.copy(id = newId.toLong()) + } + + // ... additional methods + } +---- + +The main difference when you run the insert by using this second approach is that you do not +add the `id` to the `Map`, and you call the `executeAndReturnKey` method. This returns a +`java.lang.Number` object with which you can create an instance of the numerical type that +is used in your domain class. You cannot rely on all databases to return a specific Java +class here. `java.lang.Number` is the base class that you can rely on. If you have +multiple auto-generated columns or the generated values are non-numeric, you can +use a `KeyHolder` that is returned from the `executeAndReturnKeyHolder` method. + + +[[jdbc-simple-jdbc-insert-3]] +== Specifying Columns for a `SimpleJdbcInsert` + +You can limit the columns for an insert by specifying a list of column names with the +`usingColumns` method, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcInsert insertActor; + + public void setDataSource(DataSource dataSource) { + this.insertActor = new SimpleJdbcInsert(dataSource) + .withTableName("t_actor") + .usingColumns("first_name", "last_name") + .usingGeneratedKeyColumns("id"); + } + + public void add(Actor actor) { + Map<String, Object> parameters = new HashMap<>(2); + parameters.put("first_name", actor.getFirstName()); + parameters.put("last_name", actor.getLastName()); + Number newId = insertActor.executeAndReturnKey(parameters); + actor.setId(newId.longValue()); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val insertActor = SimpleJdbcInsert(dataSource) + .withTableName("t_actor") + .usingColumns("first_name", "last_name") + .usingGeneratedKeyColumns("id") + + fun add(actor: Actor): Actor { + val parameters = mapOf( + "first_name" to actor.firstName, + "last_name" to actor.lastName) + val newId = insertActor.executeAndReturnKey(parameters); + return actor.copy(id = newId.toLong()) + } + + // ... additional methods + } +---- + +The execution of the insert is the same as if you had relied on the metadata to determine +which columns to use. + + +[[jdbc-simple-jdbc-parameters]] +== Using `SqlParameterSource` to Provide Parameter Values + +Using a `Map` to provide parameter values works fine, but it is not the most convenient +class to use. Spring provides a couple of implementations of the `SqlParameterSource` +interface that you can use instead. The first one is `BeanPropertySqlParameterSource`, +which is a very convenient class if you have a JavaBean-compliant class that contains +your values. It uses the corresponding getter method to extract the parameter +values. The following example shows how to use `BeanPropertySqlParameterSource`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcInsert insertActor; + + public void setDataSource(DataSource dataSource) { + this.insertActor = new SimpleJdbcInsert(dataSource) + .withTableName("t_actor") + .usingGeneratedKeyColumns("id"); + } + + public void add(Actor actor) { + SqlParameterSource parameters = new BeanPropertySqlParameterSource(actor); + Number newId = insertActor.executeAndReturnKey(parameters); + actor.setId(newId.longValue()); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val insertActor = SimpleJdbcInsert(dataSource) + .withTableName("t_actor") + .usingGeneratedKeyColumns("id") + + fun add(actor: Actor): Actor { + val parameters = BeanPropertySqlParameterSource(actor) + val newId = insertActor.executeAndReturnKey(parameters) + return actor.copy(id = newId.toLong()) + } + + // ... additional methods + } +---- + +Another option is the `MapSqlParameterSource` that resembles a `Map` but provides a more +convenient `addValue` method that can be chained. The following example shows how to use it: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcInsert insertActor; + + public void setDataSource(DataSource dataSource) { + this.insertActor = new SimpleJdbcInsert(dataSource) + .withTableName("t_actor") + .usingGeneratedKeyColumns("id"); + } + + public void add(Actor actor) { + SqlParameterSource parameters = new MapSqlParameterSource() + .addValue("first_name", actor.getFirstName()) + .addValue("last_name", actor.getLastName()); + Number newId = insertActor.executeAndReturnKey(parameters); + actor.setId(newId.longValue()); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val insertActor = SimpleJdbcInsert(dataSource) + .withTableName("t_actor") + .usingGeneratedKeyColumns("id") + + fun add(actor: Actor): Actor { + val parameters = MapSqlParameterSource() + .addValue("first_name", actor.firstName) + .addValue("last_name", actor.lastName) + val newId = insertActor.executeAndReturnKey(parameters) + return actor.copy(id = newId.toLong()) + } + + // ... additional methods + } +---- + +As you can see, the configuration is the same. Only the executing code has to change to +use these alternative input classes. + + +[[jdbc-simple-jdbc-call-1]] +== Calling a Stored Procedure with `SimpleJdbcCall` + +The `SimpleJdbcCall` class uses metadata in the database to look up names of `in` +and `out` parameters so that you do not have to explicitly declare them. You can +declare parameters if you prefer to do that or if you have parameters (such as `ARRAY` +or `STRUCT`) that do not have an automatic mapping to a Java class. The first example +shows a simple procedure that returns only scalar values in `VARCHAR` and `DATE` format +from a MySQL database. The example procedure reads a specified actor entry and returns +`first_name`, `last_name`, and `birth_date` columns in the form of `out` parameters. +The following listing shows the first example: + +[source,sql,indent=0,subs="verbatim,quotes"] +---- + CREATE PROCEDURE read_actor ( + IN in_id INTEGER, + OUT out_first_name VARCHAR(100), + OUT out_last_name VARCHAR(100), + OUT out_birth_date DATE) + BEGIN + SELECT first_name, last_name, birth_date + INTO out_first_name, out_last_name, out_birth_date + FROM t_actor where id = in_id; + END; +---- + +The `in_id` parameter contains the `id` of the actor that you are looking up. The `out` +parameters return the data read from the table. + +You can declare `SimpleJdbcCall` in a manner similar to declaring `SimpleJdbcInsert`. You +should instantiate and configure the class in the initialization method of your data-access +layer. Compared to the `StoredProcedure` class, you need not create a subclass +and you need not to declare parameters that can be looked up in the database metadata. +The following example of a `SimpleJdbcCall` configuration uses the preceding stored +procedure (the only configuration option, in addition to the `DataSource`, is the name +of the stored procedure): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcCall procReadActor; + + public void setDataSource(DataSource dataSource) { + this.procReadActor = new SimpleJdbcCall(dataSource) + .withProcedureName("read_actor"); + } + + public Actor readActor(Long id) { + SqlParameterSource in = new MapSqlParameterSource() + .addValue("in_id", id); + Map out = procReadActor.execute(in); + Actor actor = new Actor(); + actor.setId(id); + actor.setFirstName((String) out.get("out_first_name")); + actor.setLastName((String) out.get("out_last_name")); + actor.setBirthDate((Date) out.get("out_birth_date")); + return actor; + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val procReadActor = SimpleJdbcCall(dataSource) + .withProcedureName("read_actor") + + + fun readActor(id: Long): Actor { + val source = MapSqlParameterSource().addValue("in_id", id) + val output = procReadActor.execute(source) + return Actor( + id, + output["out_first_name"] as String, + output["out_last_name"] as String, + output["out_birth_date"] as Date) + } + + // ... additional methods + } +---- + +The code you write for the execution of the call involves creating an `SqlParameterSource` +containing the IN parameter. You must match the name provided for the input value +with that of the parameter name declared in the stored procedure. The case does not have +to match because you use metadata to determine how database objects should be referred to +in a stored procedure. What is specified in the source for the stored procedure is not +necessarily the way it is stored in the database. Some databases transform names to all +upper case, while others use lower case or use the case as specified. + +The `execute` method takes the IN parameters and returns a `Map` that contains any `out` +parameters keyed by the name, as specified in the stored procedure. In this case, they are +`out_first_name`, `out_last_name`, and `out_birth_date`. + +The last part of the `execute` method creates an `Actor` instance to use to return the +data retrieved. Again, it is important to use the names of the `out` parameters as they +are declared in the stored procedure. Also, the case in the names of the `out` +parameters stored in the results map matches that of the `out` parameter names in the +database, which could vary between databases. To make your code more portable, you should +do a case-insensitive lookup or instruct Spring to use a `LinkedCaseInsensitiveMap`. +To do the latter, you can create your own `JdbcTemplate` and set the `setResultsMapCaseInsensitive` +property to `true`. Then you can pass this customized `JdbcTemplate` instance into +the constructor of your `SimpleJdbcCall`. The following example shows this configuration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcCall procReadActor; + + public void setDataSource(DataSource dataSource) { + JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); + jdbcTemplate.setResultsMapCaseInsensitive(true); + this.procReadActor = new SimpleJdbcCall(jdbcTemplate) + .withProcedureName("read_actor"); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private var procReadActor = SimpleJdbcCall(JdbcTemplate(dataSource).apply { + isResultsMapCaseInsensitive = true + }).withProcedureName("read_actor") + + // ... additional methods + } +---- + +By taking this action, you avoid conflicts in the case used for the names of your +returned `out` parameters. + + +[[jdbc-simple-jdbc-call-2]] +== Explicitly Declaring Parameters to Use for a `SimpleJdbcCall` + +Earlier in this chapter, we described how parameters are deduced from metadata, but you can declare them +explicitly if you wish. You can do so by creating and configuring `SimpleJdbcCall` with +the `declareParameters` method, which takes a variable number of `SqlParameter` objects +as input. See the <<jdbc-params, next section>> for details on how to define an `SqlParameter`. + +NOTE: Explicit declarations are necessary if the database you use is not a Spring-supported +database. Currently, Spring supports metadata lookup of stored procedure calls for the +following databases: Apache Derby, DB2, MySQL, Microsoft SQL Server, Oracle, and Sybase. +We also support metadata lookup of stored functions for MySQL, Microsoft SQL Server, +and Oracle. + +You can opt to explicitly declare one, some, or all of the parameters. The parameter +metadata is still used where you do not explicitly declare parameters. To bypass all +processing of metadata lookups for potential parameters and use only the declared +parameters, you can call the method `withoutProcedureColumnMetaDataAccess` as part of the +declaration. Suppose that you have two or more different call signatures declared for a +database function. In this case, you call `useInParameterNames` to specify the list +of IN parameter names to include for a given signature. + +The following example shows a fully declared procedure call and uses the information from +the preceding example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcCall procReadActor; + + public void setDataSource(DataSource dataSource) { + JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); + jdbcTemplate.setResultsMapCaseInsensitive(true); + this.procReadActor = new SimpleJdbcCall(jdbcTemplate) + .withProcedureName("read_actor") + .withoutProcedureColumnMetaDataAccess() + .useInParameterNames("in_id") + .declareParameters( + new SqlParameter("in_id", Types.NUMERIC), + new SqlOutParameter("out_first_name", Types.VARCHAR), + new SqlOutParameter("out_last_name", Types.VARCHAR), + new SqlOutParameter("out_birth_date", Types.DATE) + ); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val procReadActor = SimpleJdbcCall(JdbcTemplate(dataSource).apply { + isResultsMapCaseInsensitive = true + }).withProcedureName("read_actor") + .withoutProcedureColumnMetaDataAccess() + .useInParameterNames("in_id") + .declareParameters( + SqlParameter("in_id", Types.NUMERIC), + SqlOutParameter("out_first_name", Types.VARCHAR), + SqlOutParameter("out_last_name", Types.VARCHAR), + SqlOutParameter("out_birth_date", Types.DATE) + ) + + // ... additional methods + } +---- + +The execution and end results of the two examples are the same. The second example specifies all +details explicitly rather than relying on metadata. + + +[[jdbc-params]] +== How to Define `SqlParameters` + +To define a parameter for the `SimpleJdbc` classes and also for the RDBMS operations +classes (covered in <<jdbc-object>>) you can use `SqlParameter` or one of its subclasses. +To do so, you typically specify the parameter name and SQL type in the constructor. The SQL type +is specified by using the `java.sql.Types` constants. Earlier in this chapter, we saw declarations +similar to the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + new SqlParameter("in_id", Types.NUMERIC), + new SqlOutParameter("out_first_name", Types.VARCHAR), +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + SqlParameter("in_id", Types.NUMERIC), + SqlOutParameter("out_first_name", Types.VARCHAR), +---- + +The first line with the `SqlParameter` declares an IN parameter. You can use IN parameters +for both stored procedure calls and for queries by using the `SqlQuery` and its +subclasses (covered in <<jdbc-SqlQuery>>). + +The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in a +stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters +(parameters that provide an IN value to the procedure and that also return a value). + +NOTE: Only parameters declared as `SqlParameter` and `SqlInOutParameter` are used to +provide input values. This is different from the `StoredProcedure` class, which (for +backwards compatibility reasons) lets input values be provided for parameters +declared as `SqlOutParameter`. + +For IN parameters, in addition to the name and the SQL type, you can specify a scale for +numeric data or a type name for custom database types. For `out` parameters, you can +provide a `RowMapper` to handle mapping of rows returned from a `REF` cursor. Another +option is to specify an `SqlReturnType` that provides an opportunity to define +customized handling of the return values. + + +[[jdbc-simple-jdbc-call-3]] +== Calling a Stored Function by Using `SimpleJdbcCall` + +You can call a stored function in almost the same way as you call a stored procedure, except +that you provide a function name rather than a procedure name. You use the +`withFunctionName` method as part of the configuration to indicate that you want to make +a call to a function, and the corresponding string for a function call is generated. A +specialized call (`executeFunction`) is used to run the function, and it +returns the function return value as an object of a specified type, which means you do +not have to retrieve the return value from the results map. A similar convenience method +(named `executeObject`) is also available for stored procedures that have only one `out` +parameter. The following example (for MySQL) is based on a stored function named `get_actor_name` +that returns an actor's full name: + +[source,sql,indent=0,subs="verbatim,quotes"] +---- + CREATE FUNCTION get_actor_name (in_id INTEGER) + RETURNS VARCHAR(200) READS SQL DATA + BEGIN + DECLARE out_name VARCHAR(200); + SELECT concat(first_name, ' ', last_name) + INTO out_name + FROM t_actor where id = in_id; + RETURN out_name; + END; +---- + +To call this function, we again create a `SimpleJdbcCall` in the initialization method, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcCall funcGetActorName; + + public void setDataSource(DataSource dataSource) { + JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); + jdbcTemplate.setResultsMapCaseInsensitive(true); + this.funcGetActorName = new SimpleJdbcCall(jdbcTemplate) + .withFunctionName("get_actor_name"); + } + + public String getActorName(Long id) { + SqlParameterSource in = new MapSqlParameterSource() + .addValue("in_id", id); + String name = funcGetActorName.executeFunction(String.class, in); + return name; + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val jdbcTemplate = JdbcTemplate(dataSource).apply { + isResultsMapCaseInsensitive = true + } + private val funcGetActorName = SimpleJdbcCall(jdbcTemplate) + .withFunctionName("get_actor_name") + + fun getActorName(id: Long): String { + val source = MapSqlParameterSource().addValue("in_id", id) + return funcGetActorName.executeFunction(String::class.java, source) + } + + // ... additional methods + } +---- + +The `executeFunction` method used returns a `String` that contains the return value from the +function call. + + +[[jdbc-simple-jdbc-call-4]] +== Returning a `ResultSet` or REF Cursor from a `SimpleJdbcCall` + +Calling a stored procedure or function that returns a result set is a bit tricky. Some +databases return result sets during the JDBC results processing, while others require an +explicitly registered `out` parameter of a specific type. Both approaches need +additional processing to loop over the result set and process the returned rows. With +the `SimpleJdbcCall`, you can use the `returningResultSet` method and declare a `RowMapper` +implementation to be used for a specific parameter. If the result set is +returned during the results processing, there are no names defined, so the returned +results must match the order in which you declare the `RowMapper` +implementations. The name specified is still used to store the processed list of results +in the results map that is returned from the `execute` statement. + +The next example (for MySQL) uses a stored procedure that takes no IN parameters and returns +all rows from the `t_actor` table: + +[source,sql,indent=0,subs="verbatim,quotes"] +---- + CREATE PROCEDURE read_all_actors() + BEGIN + SELECT a.id, a.first_name, a.last_name, a.birth_date FROM t_actor a; + END; +---- + +To call this procedure, you can declare the `RowMapper`. Because the class to which you want +to map follows the JavaBean rules, you can use a `BeanPropertyRowMapper` that is created by +passing in the required class to map to in the `newInstance` method. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class JdbcActorDao implements ActorDao { + + private SimpleJdbcCall procReadAllActors; + + public void setDataSource(DataSource dataSource) { + JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); + jdbcTemplate.setResultsMapCaseInsensitive(true); + this.procReadAllActors = new SimpleJdbcCall(jdbcTemplate) + .withProcedureName("read_all_actors") + .returningResultSet("actors", + BeanPropertyRowMapper.newInstance(Actor.class)); + } + + public List getActorsList() { + Map m = procReadAllActors.execute(new HashMap<String, Object>(0)); + return (List) m.get("actors"); + } + + // ... additional methods + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class JdbcActorDao(dataSource: DataSource) : ActorDao { + + private val procReadAllActors = SimpleJdbcCall(JdbcTemplate(dataSource).apply { + isResultsMapCaseInsensitive = true + }).withProcedureName("read_all_actors") + .returningResultSet("actors", + BeanPropertyRowMapper.newInstance(Actor::class.java)) + + fun getActorsList(): List<Actor> { + val m = procReadAllActors.execute(mapOf<String, Any>()) + return m["actors"] as List<Actor> + } + + // ... additional methods + } +---- + +The `execute` call passes in an empty `Map`, because this call does not take any parameters. +The list of actors is then retrieved from the results map and returned to the caller. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/orm.adoc b/framework-docs/modules/ROOT/pages/data-access/orm.adoc new file mode 100644 index 000000000000..5bf7a8ea176f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/orm.adoc @@ -0,0 +1,7 @@ +[[orm]] += Object Relational Mapping (ORM) Data Access + +This section covers data access when you use Object Relational Mapping (ORM). + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc new file mode 100644 index 000000000000..846760f93d81 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc @@ -0,0 +1,108 @@ +[[orm-general]] += General ORM Integration Considerations + +This section highlights considerations that apply to all ORM technologies. +The <<orm-hibernate>> section provides more details and also show these features and +configurations in a concrete context. + +The major goal of Spring's ORM integration is clear application layering (with any data +access and transaction technology) and for loose coupling of application objects -- no +more business service dependencies on the data access or transaction strategy, no more +hard-coded resource lookups, no more hard-to-replace singletons, no more custom service +registries. The goal is to have one simple and consistent approach to wiring up application objects, keeping +them as reusable and free from container dependencies as possible. All the individual +data access features are usable on their own but integrate nicely with Spring's +application context concept, providing XML-based configuration and cross-referencing of +plain JavaBean instances that need not be Spring-aware. In a typical Spring application, +many important objects are JavaBeans: data access templates, data access objects, +transaction managers, business services that use the data access objects and transaction +managers, web view resolvers, web controllers that use the business services, and so on. + + +[[orm-resource-mngmnt]] +== Resource and Transaction Management + +Typical business applications are cluttered with repetitive resource management code. +Many projects try to invent their own solutions, sometimes sacrificing proper handling +of failures for programming convenience. Spring advocates simple solutions for proper +resource handling, namely IoC through templating in the case of JDBC and applying AOP +interceptors for the ORM technologies. + +The infrastructure provides proper resource handling and appropriate conversion of +specific API exceptions to an unchecked infrastructure exception hierarchy. Spring +introduces a DAO exception hierarchy, applicable to any data access strategy. For direct +JDBC, the `JdbcTemplate` class mentioned in a <<jdbc-JdbcTemplate, previous section>> +provides connection handling and proper conversion of `SQLException` to the +`DataAccessException` hierarchy, including translation of database-specific SQL error +codes to meaningful exception classes. For ORM technologies, see the +<<orm-exception-translation, next section>> for how to get the same exception +translation benefits. + +When it comes to transaction management, the `JdbcTemplate` class hooks in to the Spring +transaction support and supports both JTA and JDBC transactions, through respective +Spring transaction managers. For the supported ORM technologies, Spring offers Hibernate +and JPA support through the Hibernate and JPA transaction managers as well as JTA support. +For details on transaction support, see the <<transaction>> chapter. + + +[[orm-exception-translation]] +== Exception Translation + +When you use Hibernate or JPA in a DAO, you must decide how to handle the persistence +technology's native exception classes. The DAO throws a subclass of a `HibernateException` +or `PersistenceException`, depending on the technology. These exceptions are all runtime +exceptions and do not have to be declared or caught. You may also have to deal with +`IllegalArgumentException` and `IllegalStateException`. This means that callers can only +treat exceptions as being generally fatal, unless they want to depend on the persistence +technology's own exception structure. Catching specific causes (such as an optimistic +locking failure) is not possible without tying the caller to the implementation strategy. +This trade-off might be acceptable to applications that are strongly ORM-based or +do not need any special exception treatment (or both). However, Spring lets exception +translation be applied transparently through the `@Repository` annotation. The following +examples (one for Java configuration and one for XML configuration) show how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Repository + public class ProductDaoImpl implements ProductDao { + + // class body here... + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Repository + class ProductDaoImpl : ProductDao { + + // class body here... + + } +---- + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <!-- Exception translation bean post processor --> + <bean class="org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor"/> + + <bean id="myProductDao" class="product.ProductDaoImpl"/> + + </beans> +---- + +The postprocessor automatically looks for all exception translators (implementations of +the `PersistenceExceptionTranslator` interface) and advises all beans marked with the +`@Repository` annotation so that the discovered translators can intercept and apply the +appropriate translation on the thrown exceptions. + +In summary, you can implement DAOs based on the plain persistence technology's API and +annotations while still benefiting from Spring-managed transactions, dependency +injection, and transparent exception conversion (if desired) to Spring's custom +exception hierarchies. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc new file mode 100644 index 000000000000..fb32064e91f0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc @@ -0,0 +1,490 @@ +[[orm-hibernate]] += Hibernate + +We start with a coverage of https://hibernate.org/[Hibernate 5] in a Spring environment, +using it to demonstrate the approach that Spring takes towards integrating OR mappers. +This section covers many issues in detail and shows different variations of DAO +implementations and transaction demarcation. Most of these patterns can be directly +translated to all other supported ORM tools. The later sections in this chapter then +cover the other ORM technologies and show brief examples. + +NOTE: As of Spring Framework 5.3, Spring requires Hibernate ORM 5.2+ for Spring's +`HibernateJpaVendorAdapter` as well as for a native Hibernate `SessionFactory` setup. +It is strongly recommended to go with Hibernate ORM 5.4 for a newly started application. +For use with `HibernateJpaVendorAdapter`, Hibernate Search needs to be upgraded to 5.11.6. + + +[[orm-session-factory-setup]] +== `SessionFactory` Setup in a Spring Container + +To avoid tying application objects to hard-coded resource lookups, you can define +resources (such as a JDBC `DataSource` or a Hibernate `SessionFactory`) as beans in the +Spring container. Application objects that need to access resources receive references +to such predefined instances through bean references, as illustrated in the DAO +definition in the <<orm-hibernate-straight, next section>>. + +The following excerpt from an XML application context definition shows how to set up a +JDBC `DataSource` and a Hibernate `SessionFactory` on top of it: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="myDataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close"> + <property name="driverClassName" value="org.hsqldb.jdbcDriver"/> + <property name="url" value="jdbc:hsqldb:hsql://localhost:9001"/> + <property name="username" value="sa"/> + <property name="password" value=""/> + </bean> + + <bean id="mySessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactoryBean"> + <property name="dataSource" ref="myDataSource"/> + <property name="mappingResources"> + <list> + <value>product.hbm.xml</value> + </list> + </property> + <property name="hibernateProperties"> + <value> + hibernate.dialect=org.hibernate.dialect.HSQLDialect + </value> + </property> + </bean> + + </beans> +---- + +Switching from a local Jakarta Commons DBCP `BasicDataSource` to a JNDI-located +`DataSource` (usually managed by an application server) is only a matter of +configuration, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <jee:jndi-lookup id="myDataSource" jndi-name="java:comp/env/jdbc/myds"/> + </beans> +---- + +You can also access a JNDI-located `SessionFactory`, using Spring's +`JndiObjectFactoryBean` / `<jee:jndi-lookup>` to retrieve and expose it. +However, that is typically not common outside of an EJB context. + +[NOTE] +==== +Spring also provides a `LocalSessionFactoryBuilder` variant, seamlessly integrating +with `@Bean` style configuration and programmatic setup (no `FactoryBean` involved). + +Both `LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background +bootstrapping, with Hibernate initialization running in parallel to the application +bootstrap thread on a given bootstrap executor (such as a `SimpleAsyncTaskExecutor`). +On `LocalSessionFactoryBean`, this is available through the `bootstrapExecutor` +property. On the programmatic `LocalSessionFactoryBuilder`, there is an overloaded +`buildSessionFactory` method that takes a bootstrap executor argument. + +As of Spring Framework 5.1, such a native Hibernate setup can also expose a JPA +`EntityManagerFactory` for standard JPA interaction next to native Hibernate access. +See <<orm-jpa-hibernate, Native Hibernate Setup for JPA>> for details. +==== + + +[[orm-hibernate-straight]] +== Implementing DAOs Based on the Plain Hibernate API + +Hibernate has a feature called contextual sessions, wherein Hibernate itself manages +one current `Session` per transaction. This is roughly equivalent to Spring's +synchronization of one Hibernate `Session` per transaction. A corresponding DAO +implementation resembles the following example, based on the plain Hibernate API: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ProductDaoImpl implements ProductDao { + + private SessionFactory sessionFactory; + + public void setSessionFactory(SessionFactory sessionFactory) { + this.sessionFactory = sessionFactory; + } + + public Collection loadProductsByCategory(String category) { + return this.sessionFactory.getCurrentSession() + .createQuery("from test.Product product where product.category=?") + .setParameter(0, category) + .list(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ProductDaoImpl(private val sessionFactory: SessionFactory) : ProductDao { + + fun loadProductsByCategory(category: String): Collection<*> { + return sessionFactory.currentSession + .createQuery("from test.Product product where product.category=?") + .setParameter(0, category) + .list() + } + } +---- + +This style is similar to that of the Hibernate reference documentation and examples, +except for holding the `SessionFactory` in an instance variable. We strongly recommend +such an instance-based setup over the old-school `static` `HibernateUtil` class from +Hibernate's CaveatEmptor sample application. (In general, do not keep any resources in +`static` variables unless absolutely necessary.) + +The preceding DAO example follows the dependency injection pattern. It fits nicely into a Spring IoC +container, as it would if coded against Spring's `HibernateTemplate`. +You can also set up such a DAO in plain Java (for example, in unit tests). To do so, +instantiate it and call `setSessionFactory(..)` with the desired factory reference. As a +Spring bean definition, the DAO would resemble the following: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="myProductDao" class="product.ProductDaoImpl"> + <property name="sessionFactory" ref="mySessionFactory"/> + </bean> + + </beans> +---- + +The main advantage of this DAO style is that it depends on Hibernate API only. No import +of any Spring class is required. This is appealing from a non-invasiveness +perspective and may feel more natural to Hibernate developers. + +However, the DAO throws plain `HibernateException` (which is unchecked, so it does not have +to be declared or caught), which means that callers can treat exceptions only as being +generally fatal -- unless they want to depend on Hibernate's own exception hierarchy. +Catching specific causes (such as an optimistic locking failure) is not possible without +tying the caller to the implementation strategy. This trade off might be acceptable to +applications that are strongly Hibernate-based, do not need any special exception +treatment, or both. + +Fortunately, Spring's `LocalSessionFactoryBean` supports Hibernate's +`SessionFactory.getCurrentSession()` method for any Spring transaction strategy, +returning the current Spring-managed transactional `Session`, even with +`HibernateTransactionManager`. The standard behavior of that method remains +to return the current `Session` associated with the ongoing JTA transaction, if any. +This behavior applies regardless of whether you use Spring's +`JtaTransactionManager`, EJB container managed transactions (CMTs), or JTA. + +In summary, you can implement DAOs based on the plain Hibernate API, while still being +able to participate in Spring-managed transactions. + + +[[orm-hibernate-tx-declarative]] +== Declarative Transaction Demarcation + +We recommend that you use Spring's declarative transaction support, which lets you +replace explicit transaction demarcation API calls in your Java code with an AOP +transaction interceptor. You can configure this transaction interceptor in a Spring +container by using either Java annotations or XML. This declarative transaction capability +lets you keep business services free of repetitive transaction demarcation code and +focus on adding business logic, which is the real value of your application. + +NOTE: Before you continue, we are strongly encourage you to read <<transaction-declarative>> +if you have not already done so. + +You can annotate the service layer with `@Transactional` annotations and instruct the +Spring container to find these annotations and provide transactional semantics for +these annotated methods. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ProductServiceImpl implements ProductService { + + private ProductDao productDao; + + public void setProductDao(ProductDao productDao) { + this.productDao = productDao; + } + + @Transactional + public void increasePriceOfAllProductsInCategory(final String category) { + List productsToChange = this.productDao.loadProductsByCategory(category); + // ... + } + + @Transactional(readOnly = true) + public List<Product> findAllProducts() { + return this.productDao.findAllProducts(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ProductServiceImpl(private val productDao: ProductDao) : ProductService { + + @Transactional + fun increasePriceOfAllProductsInCategory(category: String) { + val productsToChange = productDao.loadProductsByCategory(category) + // ... + } + + @Transactional(readOnly = true) + fun findAllProducts() = productDao.findAllProducts() + } +---- + +In the container, you need to set up the `PlatformTransactionManager` implementation +(as a bean) and a `<tx:annotation-driven/>` entry, opting into `@Transactional` +processing at runtime. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:aop="http://www.springframework.org/schema/aop" + xmlns:tx="http://www.springframework.org/schema/tx" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx + https://www.springframework.org/schema/tx/spring-tx.xsd + http://www.springframework.org/schema/aop + https://www.springframework.org/schema/aop/spring-aop.xsd"> + + <!-- SessionFactory, DataSource, etc. omitted --> + + <bean id="transactionManager" + class="org.springframework.orm.hibernate5.HibernateTransactionManager"> + <property name="sessionFactory" ref="sessionFactory"/> + </bean> + + <tx:annotation-driven/> + + <bean id="myProductService" class="product.SimpleProductService"> + <property name="productDao" ref="myProductDao"/> + </bean> + + </beans> +---- + + +[[orm-hibernate-tx-programmatic]] +== Programmatic Transaction Demarcation + +You can demarcate transactions in a higher level of the application, on top of +lower-level data access services that span any number of operations. Nor do restrictions +exist on the implementation of the surrounding business service. It needs only a Spring +`PlatformTransactionManager`. Again, the latter can come from anywhere, but preferably +as a bean reference through a `setTransactionManager(..)` method. Also, the +`productDAO` should be set by a `setProductDao(..)` method. The following pair of snippets show +a transaction manager and a business service definition in a Spring application context +and an example for a business method implementation: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="myTxManager" class="org.springframework.orm.hibernate5.HibernateTransactionManager"> + <property name="sessionFactory" ref="mySessionFactory"/> + </bean> + + <bean id="myProductService" class="product.ProductServiceImpl"> + <property name="transactionManager" ref="myTxManager"/> + <property name="productDao" ref="myProductDao"/> + </bean> + + </beans> +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ProductServiceImpl implements ProductService { + + private TransactionTemplate transactionTemplate; + private ProductDao productDao; + + public void setTransactionManager(PlatformTransactionManager transactionManager) { + this.transactionTemplate = new TransactionTemplate(transactionManager); + } + + public void setProductDao(ProductDao productDao) { + this.productDao = productDao; + } + + public void increasePriceOfAllProductsInCategory(final String category) { + this.transactionTemplate.execute(new TransactionCallbackWithoutResult() { + public void doInTransactionWithoutResult(TransactionStatus status) { + List productsToChange = this.productDao.loadProductsByCategory(category); + // do the price increase... + } + }); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ProductServiceImpl(transactionManager: PlatformTransactionManager, + private val productDao: ProductDao) : ProductService { + + private val transactionTemplate = TransactionTemplate(transactionManager) + + fun increasePriceOfAllProductsInCategory(category: String) { + transactionTemplate.execute { + val productsToChange = productDao.loadProductsByCategory(category) + // do the price increase... + } + } + } +---- + +Spring's `TransactionInterceptor` lets any checked application exception be thrown +with the callback code, while `TransactionTemplate` is restricted to unchecked +exceptions within the callback. `TransactionTemplate` triggers a rollback in case of +an unchecked application exception or if the transaction is marked rollback-only by +the application (by setting `TransactionStatus`). By default, `TransactionInterceptor` +behaves the same way but allows configurable rollback policies per method. + + +[[orm-hibernate-tx-strategies]] +== Transaction Management Strategies + +Both `TransactionTemplate` and `TransactionInterceptor` delegate the actual transaction +handling to a `PlatformTransactionManager` instance (which can be a +`HibernateTransactionManager` (for a single Hibernate `SessionFactory`) by using a +`ThreadLocal` `Session` under the hood) or a `JtaTransactionManager` (delegating to the +JTA subsystem of the container) for Hibernate applications. You can even use a custom +`PlatformTransactionManager` implementation. Switching from native Hibernate transaction +management to JTA (such as when facing distributed transaction requirements for certain +deployments of your application) is only a matter of configuration. You can replace +the Hibernate transaction manager with Spring's JTA transaction implementation. Both +transaction demarcation and data access code work without changes, because they +use the generic transaction management APIs. + +For distributed transactions across multiple Hibernate session factories, you can combine +`JtaTransactionManager` as a transaction strategy with multiple +`LocalSessionFactoryBean` definitions. Each DAO then gets one specific `SessionFactory` +reference passed into its corresponding bean property. If all underlying JDBC data +sources are transactional container ones, a business service can demarcate transactions +across any number of DAOs and any number of session factories without special regard, as +long as it uses `JtaTransactionManager` as the strategy. + +Both `HibernateTransactionManager` and `JtaTransactionManager` allow for proper +JVM-level cache handling with Hibernate, without container-specific transaction manager +lookup or a JCA connector (if you do not use EJB to initiate transactions). + +`HibernateTransactionManager` can export the Hibernate JDBC `Connection` to plain JDBC +access code for a specific `DataSource`. This ability allows for high-level +transaction demarcation with mixed Hibernate and JDBC data access completely without +JTA, provided you access only one database. `HibernateTransactionManager` automatically +exposes the Hibernate transaction as a JDBC transaction if you have set up the passed-in +`SessionFactory` with a `DataSource` through the `dataSource` property of the +`LocalSessionFactoryBean` class. Alternatively, you can specify explicitly the +`DataSource` for which the transactions are supposed to be exposed through the +`dataSource` property of the `HibernateTransactionManager` class. + + +[[orm-hibernate-resources]] +== Comparing Container-managed and Locally Defined Resources + +You can switch between a container-managed JNDI `SessionFactory` and a locally defined +one without having to change a single line of application code. Whether to keep +resource definitions in the container or locally within the application is mainly a +matter of the transaction strategy that you use. Compared to a Spring-defined local +`SessionFactory`, a manually registered JNDI `SessionFactory` does not provide any +benefits. Deploying a `SessionFactory` through Hibernate's JCA connector provides the +added value of participating in the Jakarta EE server's management infrastructure, but does +not add actual value beyond that. + +Spring's transaction support is not bound to a container. When configured with any strategy +other than JTA, transaction support also works in a stand-alone or test environment. +Especially in the typical case of single-database transactions, Spring's single-resource +local transaction support is a lightweight and powerful alternative to JTA. When you use +local EJB stateless session beans to drive transactions, you depend both on an EJB +container and on JTA, even if you access only a single database and use only stateless +session beans to provide declarative transactions through container-managed +transactions. Direct use of JTA programmatically also requires a Jakarta EE environment. + +Spring-driven transactions can work as well with a locally defined Hibernate +`SessionFactory` as they do with a local JDBC `DataSource`, provided they access a +single database. Thus, you need only use Spring's JTA transaction strategy when you +have distributed transaction requirements. A JCA connector requires container-specific +deployment steps, and (obviously) JCA support in the first place. This configuration +requires more work than deploying a simple web application with local resource +definitions and Spring-driven transactions. + +All things considered, if you do not use EJBs, stick with local `SessionFactory` setup +and Spring's `HibernateTransactionManager` or `JtaTransactionManager`. You get all of +the benefits, including proper transactional JVM-level caching and distributed +transactions, without the inconvenience of container deployment. JNDI registration of a +Hibernate `SessionFactory` through the JCA connector adds value only when used in +conjunction with EJBs. + + +[[orm-hibernate-invalid-jdbc-access-error]] +== Spurious Application Server Warnings with Hibernate + +In some JTA environments with very strict `XADataSource` implementations (currently +some WebLogic Server and WebSphere versions), when Hibernate is configured without +regard to the JTA transaction manager for that environment, spurious warnings or +exceptions can show up in the application server log. These warnings or exceptions +indicate that the connection being accessed is no longer valid or JDBC access is no +longer valid, possibly because the transaction is no longer active. As an example, +here is an actual exception from WebLogic: + +[literal] +[subs="verbatim,quotes"] +---- +java.sql.SQLException: The transaction is no longer active - status: 'Committed'. No +further JDBC access is allowed within this transaction. +---- + +Another common problem is a connection leak after JTA transactions, with Hibernate +sessions (and potentially underlying JDBC connections) not getting closed properly. + +You can resolve such issues by making Hibernate aware of the JTA transaction manager, +to which it synchronizes (along with Spring). You have two options for doing this: + +* Pass your Spring `JtaTransactionManager` bean to your Hibernate setup. The easiest + way is a bean reference into the `jtaTransactionManager` property for your + `LocalSessionFactoryBean` bean (see <<transaction-strategies-hibernate>>). + Spring then makes the corresponding JTA strategies available to Hibernate. +* You may also configure Hibernate's JTA-related properties explicitly, in particular + "hibernate.transaction.coordinator_class", "hibernate.connection.handling_mode" + and potentially "hibernate.transaction.jta.platform" in your "hibernateProperties" + on `LocalSessionFactoryBean` (see Hibernate's manual for details on those properties). + +The remainder of this section describes the sequence of events that occur with and +without Hibernate's awareness of the JTA `PlatformTransactionManager`. + +When Hibernate is not configured with any awareness of the JTA transaction manager, +the following events occur when a JTA transaction commits: + +* The JTA transaction commits. +* Spring's `JtaTransactionManager` is synchronized to the JTA transaction, so it is + called back through an `afterCompletion` callback by the JTA transaction manager. +* Among other activities, this synchronization can trigger a callback by Spring to + Hibernate, through Hibernate's `afterTransactionCompletion` callback (used to clear + the Hibernate cache), followed by an explicit `close()` call on the Hibernate session, + which causes Hibernate to attempt to `close()` the JDBC Connection. +* In some environments, this `Connection.close()` call then triggers the warning or + error, as the application server no longer considers the `Connection` to be usable, + because the transaction has already been committed. + +When Hibernate is configured with awareness of the JTA transaction manager, +the following events occur when a JTA transaction commits: + +* The JTA transaction is ready to commit. +* Spring's `JtaTransactionManager` is synchronized to the JTA transaction, so the + transaction is called back through a `beforeCompletion` callback by the JTA + transaction manager. +* Spring is aware that Hibernate itself is synchronized to the JTA transaction and + behaves differently than in the previous scenario. In particular, it aligns with + Hibernate's transactional resource management. +* The JTA transaction commits. +* Hibernate is synchronized to the JTA transaction, so the transaction is called back + through an `afterCompletion` callback by the JTA transaction manager and can + properly clear its cache. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc new file mode 100644 index 000000000000..58b4b8aadeb1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc @@ -0,0 +1,66 @@ +[[orm-introduction]] += Introduction to ORM with Spring + +The Spring Framework supports integration with the Java Persistence API (JPA) and +supports native Hibernate for resource management, data access object (DAO) implementations, +and transaction strategies. For example, for Hibernate, there is first-class support with +several convenient IoC features that address many typical Hibernate integration issues. +You can configure all of the supported features for OR (object relational) mapping +tools through Dependency Injection. They can participate in Spring's resource and +transaction management, and they comply with Spring's generic transaction and DAO +exception hierarchies. The recommended integration style is to code DAOs against plain +Hibernate or JPA APIs. + +Spring adds significant enhancements to the ORM layer of your choice when you create +data access applications. You can leverage as much of the integration support as you +wish, and you should compare this integration effort with the cost and risk of building +a similar infrastructure in-house. You can use much of the ORM support as you would a +library, regardless of technology, because everything is designed as a set of reusable +JavaBeans. ORM in a Spring IoC container facilitates configuration and deployment. Thus, +most examples in this section show configuration inside a Spring container. + +The benefits of using the Spring Framework to create your ORM DAOs include: + +* *Easier testing.* Spring's IoC approach makes it easy to swap the implementations + and configuration locations of Hibernate `SessionFactory` instances, JDBC `DataSource` + instances, transaction managers, and mapped object implementations (if needed). This + in turn makes it much easier to test each piece of persistence-related code in + isolation. +* *Common data access exceptions.* Spring can wrap exceptions from your ORM tool, + converting them from proprietary (potentially checked) exceptions to a common runtime + `DataAccessException` hierarchy. This feature lets you handle most persistence + exceptions, which are non-recoverable, only in the appropriate layers, without + annoying boilerplate catches, throws, and exception declarations. You can still trap + and handle exceptions as necessary. Remember that JDBC exceptions (including + DB-specific dialects) are also converted to the same hierarchy, meaning that you can + perform some operations with JDBC within a consistent programming model. +* *General resource management.* Spring application contexts can handle the location + and configuration of Hibernate `SessionFactory` instances, JPA `EntityManagerFactory` + instances, JDBC `DataSource` instances, and other related resources. This makes these + values easy to manage and change. Spring offers efficient, easy, and safe handling of + persistence resources. For example, related code that uses Hibernate generally needs to + use the same Hibernate `Session` to ensure efficiency and proper transaction handling. + Spring makes it easy to create and bind a `Session` to the current thread transparently, + by exposing a current `Session` through the Hibernate `SessionFactory`. Thus, Spring + solves many chronic problems of typical Hibernate usage, for any local or JTA + transaction environment. +* *Integrated transaction management.* You can wrap your ORM code with a declarative, + aspect-oriented programming (AOP) style method interceptor either through the + `@Transactional` annotation or by explicitly configuring the transaction AOP advice in + an XML configuration file. In both cases, transaction semantics and exception handling + (rollback and so on) are handled for you. As discussed in <<orm-resource-mngmnt>>, + you can also swap various transaction managers, without affecting your ORM-related code. + For example, you can swap between local transactions and JTA, with the same full services + (such as declarative transactions) available in both scenarios. Additionally, + JDBC-related code can fully integrate transactionally with the code you use to do ORM. + This is useful for data access that is not suitable for ORM (such as batch processing and + BLOB streaming) but that still needs to share common transactions with ORM operations. + +TIP: For more comprehensive ORM support, including support for alternative database +technologies such as MongoDB, you might want to check out the +https://projects.spring.io/spring-data/[Spring Data] suite of projects. If you are +a JPA user, the https://spring.io/guides/gs/accessing-data-jpa/[Getting Started Accessing +Data with JPA] guide from https://spring.io provides a great introduction. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc new file mode 100644 index 000000000000..76fc82209824 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc @@ -0,0 +1,577 @@ +[[orm-jpa]] += JPA + +The Spring JPA, available under the `org.springframework.orm.jpa` package, offers +comprehensive support for the +https://www.oracle.com/technetwork/articles/javaee/jpa-137156.html[Java Persistence +API] in a manner similar to the integration with Hibernate while being aware of +the underlying implementation in order to provide additional features. + + +[[orm-jpa-setup]] +== Three Options for JPA Setup in a Spring Environment + +The Spring JPA support offers three ways of setting up the JPA `EntityManagerFactory` +that is used by the application to obtain an entity manager. + +* <<orm-jpa-setup-lemfb>> +* <<orm-jpa-setup-jndi>> +* <<orm-jpa-setup-lcemfb>> + +[[orm-jpa-setup-lemfb]] +=== Using `LocalEntityManagerFactoryBean` + +You can use this option only in simple deployment environments such as stand-alone +applications and integration tests. + +The `LocalEntityManagerFactoryBean` creates an `EntityManagerFactory` suitable for +simple deployment environments where the application uses only JPA for data access. +The factory bean uses the JPA `PersistenceProvider` auto-detection mechanism (according +to JPA's Java SE bootstrapping) and, in most cases, requires you to specify only the +persistence unit name. The following XML example configures such a bean: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <bean id="myEmf" class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean"> + <property name="persistenceUnitName" value="myPersistenceUnit"/> + </bean> + </beans> +---- + +This form of JPA deployment is the simplest and the most limited. You cannot refer to an +existing JDBC `DataSource` bean definition, and no support for global transactions +exists. Furthermore, weaving (byte-code transformation) of persistent classes is +provider-specific, often requiring a specific JVM agent to be specified on startup. This +option is sufficient only for stand-alone applications and test environments, for which +the JPA specification is designed. + +[[orm-jpa-setup-jndi]] +=== Obtaining an EntityManagerFactory from JNDI + +You can use this option when deploying to a Jakarta EE server. Check your server's documentation +on how to deploy a custom JPA provider into your server, allowing for a different +provider than the server's default. + +Obtaining an `EntityManagerFactory` from JNDI (for example in a Jakarta EE environment), +is a matter of changing the XML configuration, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <jee:jndi-lookup id="myEmf" jndi-name="persistence/myPersistenceUnit"/> + </beans> +---- + +This action assumes standard Jakarta EE bootstrapping. The Jakarta EE server auto-detects +persistence units (in effect, `META-INF/persistence.xml` files in application jars) and +`persistence-unit-ref` entries in the Jakarta EE deployment descriptor (for example, +`web.xml`) and defines environment naming context locations for those persistence units. + +In such a scenario, the entire persistence unit deployment, including the weaving +(byte-code transformation) of persistent classes, is up to the Jakarta EE server. The JDBC +`DataSource` is defined through a JNDI location in the `META-INF/persistence.xml` file. +`EntityManager` transactions are integrated with the server's JTA subsystem. Spring merely +uses the obtained `EntityManagerFactory`, passing it on to application objects through +dependency injection and managing transactions for the persistence unit (typically +through `JtaTransactionManager`). + +If you use multiple persistence units in the same application, the bean names of such +JNDI-retrieved persistence units should match the persistence unit names that the +application uses to refer to them (for example, in `@PersistenceUnit` and +`@PersistenceContext` annotations). + +[[orm-jpa-setup-lcemfb]] +=== Using `LocalContainerEntityManagerFactoryBean` + +You can use this option for full JPA capabilities in a Spring-based application environment. +This includes web containers such as Tomcat, stand-alone applications, and +integration tests with sophisticated persistence requirements. + +NOTE: If you want to specifically configure a Hibernate setup, an immediate alternative +is to set up a native Hibernate `LocalSessionFactoryBean` instead of a plain JPA +`LocalContainerEntityManagerFactoryBean`, letting it interact with JPA access code +as well as native Hibernate access code. +See <<orm-jpa-hibernate, Native Hibernate setup for JPA interaction>> for details. + +The `LocalContainerEntityManagerFactoryBean` gives full control over +`EntityManagerFactory` configuration and is appropriate for environments where +fine-grained customization is required. The `LocalContainerEntityManagerFactoryBean` +creates a `PersistenceUnitInfo` instance based on the `persistence.xml` file, the +supplied `dataSourceLookup` strategy, and the specified `loadTimeWeaver`. It is, thus, +possible to work with custom data sources outside of JNDI and to control the weaving +process. The following example shows a typical bean definition for a +`LocalContainerEntityManagerFactoryBean`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <bean id="myEmf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> + <property name="dataSource" ref="someDataSource"/> + <property name="loadTimeWeaver"> + <bean class="org.springframework.instrument.classloading.InstrumentationLoadTimeWeaver"/> + </property> + </bean> + </beans> +---- + +The following example shows a typical `persistence.xml` file: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0"> + <persistence-unit name="myUnit" transaction-type="RESOURCE_LOCAL"> + <mapping-file>META-INF/orm.xml</mapping-file> + <exclude-unlisted-classes/> + </persistence-unit> + </persistence> +---- + +NOTE: The `<exclude-unlisted-classes/>` shortcut indicates that no scanning for +annotated entity classes is supposed to occur. An explicit 'true' value +(`<exclude-unlisted-classes>true</exclude-unlisted-classes/>`) also means no scan. +`<exclude-unlisted-classes>false</exclude-unlisted-classes/>` does trigger a scan. +However, we recommend omitting the `exclude-unlisted-classes` element +if you want entity class scanning to occur. + +Using the `LocalContainerEntityManagerFactoryBean` is the most powerful JPA setup +option, allowing for flexible local configuration within the application. It supports +links to an existing JDBC `DataSource`, supports both local and global transactions, and +so on. However, it also imposes requirements on the runtime environment, such as the +availability of a weaving-capable class loader if the persistence provider demands +byte-code transformation. + +This option may conflict with the built-in JPA capabilities of a Jakarta EE server. In a +full Jakarta EE environment, consider obtaining your `EntityManagerFactory` from JNDI. +Alternatively, specify a custom `persistenceXmlLocation` on your +`LocalContainerEntityManagerFactoryBean` definition (for example, +META-INF/my-persistence.xml) and include only a descriptor with that name in your +application jar files. Because the Jakarta EE server looks only for default +`META-INF/persistence.xml` files, it ignores such custom persistence units and, hence, +avoids conflicts with a Spring-driven JPA setup upfront. (This applies to Resin 3.1, for +example.) + +.When is load-time weaving required? +**** +Not all JPA providers require a JVM agent. Hibernate is an example of one that does not. +If your provider does not require an agent or you have other alternatives, such as +applying enhancements at build time through a custom compiler or an Ant task, you should not use the +load-time weaver. +**** + +The `LoadTimeWeaver` interface is a Spring-provided class that lets JPA +`ClassTransformer` instances be plugged in a specific manner, depending on whether the +environment is a web container or application server. Hooking `ClassTransformers` +through an +https://docs.oracle.com/javase/6/docs/api/java/lang/instrument/package-summary.html[agent] +is typically not efficient. The agents work against the entire virtual machine and +inspect every class that is loaded, which is usually undesirable in a production +server environment. + +Spring provides a number of `LoadTimeWeaver` implementations for various environments, +letting `ClassTransformer` instances be applied only for each class loader and not +for each VM. + +See the <<core.adoc#aop-aj-ltw-spring, Spring configuration>> in the AOP chapter for +more insight regarding the `LoadTimeWeaver` implementations and their setup, either +generic or customized to various platforms (such as Tomcat, JBoss and WebSphere). + +As described in <<core.adoc#aop-aj-ltw-spring, Spring configuration>>, you can configure +a context-wide `LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation or the +`context:load-time-weaver` XML element. Such a global weaver is automatically picked up +by all JPA `LocalContainerEntityManagerFactoryBean` instances. The following example +shows the preferred way of setting up a load-time weaver, delivering auto-detection +of the platform (e.g. Tomcat's weaving-capable class loader or Spring's JVM agent) +and automatic propagation of the weaver to all weaver-aware beans: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <context:load-time-weaver/> + <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> + ... + </bean> +---- + +However, you can, if needed, manually specify a dedicated weaver through the +`loadTimeWeaver` property, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> + <property name="loadTimeWeaver"> + <bean class="org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver"/> + </property> + </bean> +---- + +No matter how the LTW is configured, by using this technique, JPA applications relying on +instrumentation can run in the target platform (for example, Tomcat) without needing an agent. +This is especially important when the hosting applications rely on different JPA +implementations, because the JPA transformers are applied only at the class-loader level and +are, thus, isolated from each other. + +[[orm-jpa-setup-multiple]] +=== Dealing with Multiple Persistence Units + +For applications that rely on multiple persistence units locations (stored in various +JARS in the classpath, for example), Spring offers the `PersistenceUnitManager` to act as +a central repository and to avoid the persistence units discovery process, which can be +expensive. The default implementation lets multiple locations be specified. These locations are +parsed and later retrieved through the persistence unit name. (By default, the classpath +is searched for `META-INF/persistence.xml` files.) The following example configures +multiple locations: + +[source,xml,indent=0,subs="verbatim"] +---- + <bean id="pum" class="org.springframework.orm.jpa.persistenceunit.DefaultPersistenceUnitManager"> + <property name="persistenceXmlLocations"> + <list> + <value>org/springframework/orm/jpa/domain/persistence-multi.xml</value> + <value>classpath:/my/package/**/custom-persistence.xml</value> + <value>classpath*:META-INF/persistence.xml</value> + </list> + </property> + <property name="dataSources"> + <map> + <entry key="localDataSource" value-ref="local-db"/> + <entry key="remoteDataSource" value-ref="remote-db"/> + </map> + </property> + <!-- if no datasource is specified, use this one --> + <property name="defaultDataSource" ref="remoteDataSource"/> + </bean> + + <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> + <property name="persistenceUnitManager" ref="pum"/> + <property name="persistenceUnitName" value="myCustomUnit"/> + </bean> +---- + +The default implementation allows customization of the `PersistenceUnitInfo` instances +(before they are fed to the JPA provider) either declaratively (through its properties, which +affect all hosted units) or programmatically (through the +`PersistenceUnitPostProcessor`, which allows persistence unit selection). If no +`PersistenceUnitManager` is specified, one is created and used internally by +`LocalContainerEntityManagerFactoryBean`. + +[[orm-jpa-setup-background]] +=== Background Bootstrapping + +`LocalContainerEntityManagerFactoryBean` supports background bootstrapping through +the `bootstrapExecutor` property, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> + <property name="bootstrapExecutor"> + <bean class="org.springframework.core.task.SimpleAsyncTaskExecutor"/> + </property> + </bean> +---- + +The actual JPA provider bootstrapping is handed off to the specified executor and then, +running in parallel, to the application bootstrap thread. The exposed `EntityManagerFactory` +proxy can be injected into other application components and is even able to respond to +`EntityManagerFactoryInfo` configuration inspection. However, once the actual JPA provider +is being accessed by other components (for example, calling `createEntityManager`), those calls +block until the background bootstrapping has completed. In particular, when you use +Spring Data JPA, make sure to set up deferred bootstrapping for its repositories as well. + + +[[orm-jpa-dao]] +== Implementing DAOs Based on JPA: `EntityManagerFactory` and `EntityManager` + +NOTE: Although `EntityManagerFactory` instances are thread-safe, `EntityManager` instances are +not. The injected JPA `EntityManager` behaves like an `EntityManager` fetched from an +application server's JNDI environment, as defined by the JPA specification. It delegates +all calls to the current transactional `EntityManager`, if any. Otherwise, it falls back +to a newly created `EntityManager` per operation, in effect making its usage thread-safe. + +It is possible to write code against the plain JPA without any Spring dependencies, by +using an injected `EntityManagerFactory` or `EntityManager`. Spring can understand the +`@PersistenceUnit` and `@PersistenceContext` annotations both at the field and the method level +if a `PersistenceAnnotationBeanPostProcessor` is enabled. The following example shows a plain JPA DAO implementation +that uses the `@PersistenceUnit` annotation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ProductDaoImpl implements ProductDao { + + private EntityManagerFactory emf; + + @PersistenceUnit + public void setEntityManagerFactory(EntityManagerFactory emf) { + this.emf = emf; + } + + public Collection loadProductsByCategory(String category) { + EntityManager em = this.emf.createEntityManager(); + try { + Query query = em.createQuery("from Product as p where p.category = ?1"); + query.setParameter(1, category); + return query.getResultList(); + } + finally { + if (em != null) { + em.close(); + } + } + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ProductDaoImpl : ProductDao { + + private lateinit var emf: EntityManagerFactory + + @PersistenceUnit + fun setEntityManagerFactory(emf: EntityManagerFactory) { + this.emf = emf + } + + fun loadProductsByCategory(category: String): Collection<*> { + val em = this.emf.createEntityManager() + val query = em.createQuery("from Product as p where p.category = ?1"); + query.setParameter(1, category); + return query.resultList; + } + } +---- + +The preceding DAO has no dependency on Spring and still fits nicely into a Spring +application context. Moreover, the DAO takes advantage of annotations to require the +injection of the default `EntityManagerFactory`, as the following example bean definition shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <!-- bean post-processor for JPA annotations --> + <bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/> + + <bean id="myProductDao" class="product.ProductDaoImpl"/> + + </beans> +---- + +As an alternative to explicitly defining a `PersistenceAnnotationBeanPostProcessor`, +consider using the Spring `context:annotation-config` XML element in your application +context configuration. Doing so automatically registers all Spring standard +post-processors for annotation-based configuration, including +`CommonAnnotationBeanPostProcessor` and so on. + +Consider the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <!-- post-processors for all standard config annotations --> + <context:annotation-config/> + + <bean id="myProductDao" class="product.ProductDaoImpl"/> + + </beans> +---- + +The main problem with such a DAO is that it always creates a new `EntityManager` through +the factory. You can avoid this by requesting a transactional `EntityManager` (also +called a "`shared EntityManager`" because it is a shared, thread-safe proxy for the actual +transactional EntityManager) to be injected instead of the factory. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class ProductDaoImpl implements ProductDao { + + @PersistenceContext + private EntityManager em; + + public Collection loadProductsByCategory(String category) { + Query query = em.createQuery("from Product as p where p.category = :category"); + query.setParameter("category", category); + return query.getResultList(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class ProductDaoImpl : ProductDao { + + @PersistenceContext + private lateinit var em: EntityManager + + fun loadProductsByCategory(category: String): Collection<*> { + val query = em.createQuery("from Product as p where p.category = :category") + query.setParameter("category", category) + return query.resultList + } + } +---- + +The `@PersistenceContext` annotation has an optional attribute called `type`, which defaults to +`PersistenceContextType.TRANSACTION`. You can use this default to receive a shared +`EntityManager` proxy. The alternative, `PersistenceContextType.EXTENDED`, is a completely +different affair. This results in a so-called extended `EntityManager`, which is not +thread-safe and, hence, must not be used in a concurrently accessed component, such as a +Spring-managed singleton bean. Extended `EntityManager` instances are only supposed to be used in +stateful components that, for example, reside in a session, with the lifecycle of the +`EntityManager` not tied to a current transaction but rather being completely up to the +application. + +.Method- and field-level Injection +**** +You can apply annotations that indicate dependency injections (such as `@PersistenceUnit` and +`@PersistenceContext`) on field or methods inside a class -- hence the +expressions "`method-level injection`" and "`field-level injection`". Field-level +annotations are concise and easier to use while method-level annotations allow for further +processing of the injected dependency. In both cases, the member visibility (public, +protected, or private) does not matter. + +What about class-level annotations? + +On the Jakarta EE platform, they are used for dependency declaration and not for resource +injection. +**** + +The injected `EntityManager` is Spring-managed (aware of the ongoing transaction). +Even though the new DAO implementation uses method-level +injection of an `EntityManager` instead of an `EntityManagerFactory`, no change is +required in the application context XML, due to annotation usage. + +The main advantage of this DAO style is that it depends only on the Java Persistence API. +No import of any Spring class is required. Moreover, as the JPA annotations are understood, +the injections are applied automatically by the Spring container. This is appealing from +a non-invasiveness perspective and can feel more natural to JPA developers. + + +[[orm-jpa-tx]] +== Spring-driven JPA transactions + +NOTE: We strongly encourage you to read <<transaction-declarative>>, if you have not +already done so, to get more detailed coverage of Spring's declarative transaction support. + +The recommended strategy for JPA is local transactions through JPA's native transaction +support. Spring's `JpaTransactionManager` provides many capabilities known from local +JDBC transactions (such as transaction-specific isolation levels and resource-level +read-only optimizations) against any regular JDBC connection pool (no XA requirement). + +Spring JPA also lets a configured `JpaTransactionManager` expose a JPA transaction +to JDBC access code that accesses the same `DataSource`, provided that the registered +`JpaDialect` supports retrieval of the underlying JDBC `Connection`. +Spring provides dialects for the EclipseLink and Hibernate JPA implementations. +See the <<orm-jpa-dialect, next section>> for details on the `JpaDialect` mechanism. + +NOTE: As an immediate alternative, Spring's native `HibernateTransactionManager` is capable +of interacting with JPA access code, adapting to several Hibernate specifics and providing +JDBC interaction. This makes particular sense in combination with `LocalSessionFactoryBean` +setup. See <<orm-jpa-hibernate, Native Hibernate Setup for JPA Interaction>> for details. + + +[[orm-jpa-dialect]] +== Understanding `JpaDialect` and `JpaVendorAdapter` + +As an advanced feature, `JpaTransactionManager` and subclasses of +`AbstractEntityManagerFactoryBean` allow a custom `JpaDialect` to be passed into the +`jpaDialect` bean property. A `JpaDialect` implementation can enable the following advanced +features supported by Spring, usually in a vendor-specific manner: + +* Applying specific transaction semantics (such as custom isolation level or transaction + timeout) +* Retrieving the transactional JDBC `Connection` (for exposure to JDBC-based DAOs) +* Advanced translation of `PersistenceExceptions` to Spring `DataAccessExceptions` + +This is particularly valuable for special transaction semantics and for advanced +translation of exception. The default implementation (`DefaultJpaDialect`) does +not provide any special abilities and, if the features listed earlier are required, you have +to specify the appropriate dialect. + +TIP: As an even broader provider adaptation facility primarily for Spring's full-featured +`LocalContainerEntityManagerFactoryBean` setup, `JpaVendorAdapter` combines the +capabilities of `JpaDialect` with other provider-specific defaults. Specifying a +`HibernateJpaVendorAdapter` or `EclipseLinkJpaVendorAdapter` is the most convenient +way of auto-configuring an `EntityManagerFactory` setup for Hibernate or EclipseLink, +respectively. Note that those provider adapters are primarily designed for use with +Spring-driven transaction management (that is, for use with `JpaTransactionManager`). + +See the {api-spring-framework}/orm/jpa/JpaDialect.html[`JpaDialect`] and +{api-spring-framework}/orm/jpa/JpaVendorAdapter.html[`JpaVendorAdapter`] javadoc for +more details of its operations and how they are used within Spring's JPA support. + + +[[orm-jpa-jta]] +== Setting up JPA with JTA Transaction Management + +As an alternative to `JpaTransactionManager`, Spring also allows for multi-resource +transaction coordination through JTA, either in a Jakarta EE environment or with a +stand-alone transaction coordinator, such as Atomikos. Aside from choosing Spring's +`JtaTransactionManager` instead of `JpaTransactionManager`, you need to take few further +steps: + +* The underlying JDBC connection pools need to be XA-capable and be integrated with +your transaction coordinator. This is usually straightforward in a Jakarta EE environment, +exposing a different kind of `DataSource` through JNDI. See your application server +documentation for details. Analogously, a standalone transaction coordinator usually +comes with special XA-integrated `DataSource` variants. Again, check its documentation. + +* The JPA `EntityManagerFactory` setup needs to be configured for JTA. This is +provider-specific, typically through special properties to be specified as `jpaProperties` +on `LocalContainerEntityManagerFactoryBean`. In the case of Hibernate, these properties +are even version-specific. See your Hibernate documentation for details. + +* Spring's `HibernateJpaVendorAdapter` enforces certain Spring-oriented defaults, such +as the connection release mode, `on-close`, which matches Hibernate's own default in +Hibernate 5.0 but not any more in Hibernate 5.1+. For a JTA setup, make sure to declare +your persistence unit transaction type as "JTA". Alternatively, set Hibernate 5.2's +`hibernate.connection.handling_mode` property to +`DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT` to restore Hibernate's own default. +See <<orm-hibernate-invalid-jdbc-access-error>> for related notes. + +* Alternatively, consider obtaining the `EntityManagerFactory` from your application +server itself (that is, through a JNDI lookup instead of a locally declared +`LocalContainerEntityManagerFactoryBean`). A server-provided `EntityManagerFactory` +might require special definitions in your server configuration (making the deployment +less portable) but is set up for the server's JTA environment. + + +[[orm-jpa-hibernate]] +== Native Hibernate Setup and Native Hibernate Transactions for JPA Interaction + +A native `LocalSessionFactoryBean` setup in combination with `HibernateTransactionManager` +allows for interaction with `@PersistenceContext` and other JPA access code. A Hibernate +`SessionFactory` natively implements JPA's `EntityManagerFactory` interface now +and a Hibernate `Session` handle natively is a JPA `EntityManager`. +Spring's JPA support facilities automatically detect native Hibernate sessions. + +Such native Hibernate setup can, therefore, serve as a replacement for a standard JPA +`LocalContainerEntityManagerFactoryBean` and `JpaTransactionManager` combination +in many scenarios, allowing for interaction with `SessionFactory.getCurrentSession()` +(and also `HibernateTemplate`) next to `@PersistenceContext EntityManager` within +the same local transaction. Such a setup also provides stronger Hibernate integration +and more configuration flexibility, because it is not constrained by JPA bootstrap contracts. + +You do not need `HibernateJpaVendorAdapter` configuration in such a scenario, +since Spring's native Hibernate setup provides even more features +(for example, custom Hibernate Integrator setup, Hibernate 5.3 bean container integration, +and stronger optimizations for read-only transactions). Last but not least, you can also +express native Hibernate setup through `LocalSessionFactoryBuilder`, +seamlessly integrating with `@Bean` style configuration (no `FactoryBean` involved). + +[NOTE] +==== +`LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background +bootstrapping, just as the JPA `LocalContainerEntityManagerFactoryBean` does. +See <<orm-jpa-setup-background, Background Bootstrapping>> for an introduction. + +On `LocalSessionFactoryBean`, this is available through the `bootstrapExecutor` +property. On the programmatic `LocalSessionFactoryBuilder`, an overloaded +`buildSessionFactory` method takes a bootstrap executor argument. +==== + + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/oxm.adoc b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc new file mode 100644 index 000000000000..1ead502a7ffd --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc @@ -0,0 +1,563 @@ +[[oxm]] += Marshalling XML by Using Object-XML Mappers + + + +[[oxm-introduction]] +== Introduction + +This chapter, describes Spring's Object-XML Mapping support. Object-XML +Mapping (O-X mapping for short) is the act of converting an XML document to and from +an object. This conversion process is also known as XML Marshalling, or XML +Serialization. This chapter uses these terms interchangeably. + +Within the field of O-X mapping, a marshaller is responsible for serializing an +object (graph) to XML. In similar fashion, an unmarshaller deserializes the XML to +an object graph. This XML can take the form of a DOM document, an input or output +stream, or a SAX handler. + +Some of the benefits of using Spring for your O/X mapping needs are: + +* <<oxm-ease-of-configuration>> +* <<oxm-consistent-interfaces>> +* <<oxm-consistent-exception-hierarchy>> + + +[[oxm-ease-of-configuration]] +=== Ease of configuration + +Spring's bean factory makes it easy to configure marshallers, without needing to +construct JAXB context, JiBX binding factories, and so on. You can configure the marshallers +as you would any other bean in your application context. Additionally, XML namespace-based +configuration is available for a number of marshallers, making the configuration even +simpler. + + +[[oxm-consistent-interfaces]] +=== Consistent Interfaces + +Spring's O-X mapping operates through two global interfaces: {api-spring-framework}/oxm/Marshaller.html[`Marshaller`] and +{api-spring-framework}/oxm/Unmarshaller.html[`Unmarshaller`]. These abstractions let you switch O-X mapping frameworks +with relative ease, with little or no change required on the classes that do the +marshalling. This approach has the additional benefit of making it possible to do XML +marshalling with a mix-and-match approach (for example, some marshalling performed using JAXB +and some by XStream) in a non-intrusive fashion, letting you use the strength of each +technology. + + +[[oxm-consistent-exception-hierarchy]] +=== Consistent Exception Hierarchy + +Spring provides a conversion from exceptions from the underlying O-X mapping tool to its +own exception hierarchy with the `XmlMappingException` as the root exception. +These runtime exceptions wrap the original exception so that no information is lost. + + + +[[oxm-marshaller-unmarshaller]] +== `Marshaller` and `Unmarshaller` + +As stated in the <<oxm-introduction, introduction>>, a marshaller serializes an object +to XML, and an unmarshaller deserializes XML stream to an object. This section describes +the two Spring interfaces used for this purpose. + + +[[oxm-marshaller]] +=== Understanding `Marshaller` + +Spring abstracts all marshalling operations behind the +`org.springframework.oxm.Marshaller` interface, the main method of which follows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface Marshaller { + + /** + * Marshal the object graph with the given root into the provided Result. + */ + void marshal(Object graph, Result result) throws XmlMappingException, IOException; + } +---- + +The `Marshaller` interface has one main method, which marshals the given object to a +given `javax.xml.transform.Result`. The result is a tagging interface that basically +represents an XML output abstraction. Concrete implementations wrap various XML +representations, as the following table indicates: + +[[oxm-marshaller-tbl]] +|=== +| Result implementation| Wraps XML representation + +| `DOMResult` +| `org.w3c.dom.Node` + +| `SAXResult` +| `org.xml.sax.ContentHandler` + +| `StreamResult` +| `java.io.File`, `java.io.OutputStream`, or `java.io.Writer` +|=== + +NOTE: Although the `marshal()` method accepts a plain object as its first parameter, most +`Marshaller` implementations cannot handle arbitrary objects. Instead, an object class +must be mapped in a mapping file, be marked with an annotation, be registered with the +marshaller, or have a common base class. Refer to the later sections in this chapter +to determine how your O-X technology manages this. + + +[[oxm-unmarshaller]] +=== Understanding `Unmarshaller` + +Similar to the `Marshaller`, we have the `org.springframework.oxm.Unmarshaller` +interface, which the following listing shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface Unmarshaller { + + /** + * Unmarshal the given provided Source into an object graph. + */ + Object unmarshal(Source source) throws XmlMappingException, IOException; + } +---- + +This interface also has one method, which reads from the given +`javax.xml.transform.Source` (an XML input abstraction) and returns the object read. As +with `Result`, `Source` is a tagging interface that has three concrete implementations. Each +wraps a different XML representation, as the following table indicates: + +[[oxm-unmarshaller-tbl]] +|=== +| Source implementation| Wraps XML representation + +| `DOMSource` +| `org.w3c.dom.Node` + +| `SAXSource` +| `org.xml.sax.InputSource`, and `org.xml.sax.XMLReader` + +| `StreamSource` +| `java.io.File`, `java.io.InputStream`, or `java.io.Reader` +|=== + +Even though there are two separate marshalling interfaces (`Marshaller` and +`Unmarshaller`), all implementations in Spring-WS implement both in one class. +This means that you can wire up one marshaller class and refer to it both as a +marshaller and as an unmarshaller in your `applicationContext.xml`. + + +[[oxm-xmlmappingexception]] +=== Understanding `XmlMappingException` + +Spring converts exceptions from the underlying O-X mapping tool to its own exception +hierarchy with the `XmlMappingException` as the root exception. +These runtime exceptions wrap the original exception so that no information will be lost. + +Additionally, the `MarshallingFailureException` and `UnmarshallingFailureException` +provide a distinction between marshalling and unmarshalling operations, even though the +underlying O-X mapping tool does not do so. + +The O-X Mapping exception hierarchy is shown in the following figure: + +image::oxm-exceptions.png[] + + + +[[oxm-usage]] +== Using `Marshaller` and `Unmarshaller` + +You can use Spring's OXM for a wide variety of situations. In the following example, we +use it to marshal the settings of a Spring-managed application as an XML file. In the following example, we +use a simple JavaBean to represent the settings: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class Settings { + + private boolean fooEnabled; + + public boolean isFooEnabled() { + return fooEnabled; + } + + public void setFooEnabled(boolean fooEnabled) { + this.fooEnabled = fooEnabled; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class Settings { + var isFooEnabled: Boolean = false + } +---- + +The application class uses this bean to store its settings. Besides a main method, the +class has two methods: `saveSettings()` saves the settings bean to a file named +`settings.xml`, and `loadSettings()` loads these settings again. The following `main()` method +constructs a Spring application context and calls these two methods: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import java.io.FileInputStream; + import java.io.FileOutputStream; + import java.io.IOException; + import javax.xml.transform.stream.StreamResult; + import javax.xml.transform.stream.StreamSource; + import org.springframework.context.ApplicationContext; + import org.springframework.context.support.ClassPathXmlApplicationContext; + import org.springframework.oxm.Marshaller; + import org.springframework.oxm.Unmarshaller; + + public class Application { + + private static final String FILE_NAME = "settings.xml"; + private Settings settings = new Settings(); + private Marshaller marshaller; + private Unmarshaller unmarshaller; + + public void setMarshaller(Marshaller marshaller) { + this.marshaller = marshaller; + } + + public void setUnmarshaller(Unmarshaller unmarshaller) { + this.unmarshaller = unmarshaller; + } + + public void saveSettings() throws IOException { + try (FileOutputStream os = new FileOutputStream(FILE_NAME)) { + this.marshaller.marshal(settings, new StreamResult(os)); + } + } + + public void loadSettings() throws IOException { + try (FileInputStream is = new FileInputStream(FILE_NAME)) { + this.settings = (Settings) this.unmarshaller.unmarshal(new StreamSource(is)); + } + } + + public static void main(String[] args) throws IOException { + ApplicationContext appContext = + new ClassPathXmlApplicationContext("applicationContext.xml"); + Application application = (Application) appContext.getBean("application"); + application.saveSettings(); + application.loadSettings(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class Application { + + lateinit var marshaller: Marshaller + + lateinit var unmarshaller: Unmarshaller + + fun saveSettings() { + FileOutputStream(FILE_NAME).use { outputStream -> marshaller.marshal(settings, StreamResult(outputStream)) } + } + + fun loadSettings() { + FileInputStream(FILE_NAME).use { inputStream -> settings = unmarshaller.unmarshal(StreamSource(inputStream)) as Settings } + } + } + + private const val FILE_NAME = "settings.xml" + + fun main(args: Array<String>) { + val appContext = ClassPathXmlApplicationContext("applicationContext.xml") + val application = appContext.getBean("application") as Application + application.saveSettings() + application.loadSettings() + } +---- + +The `Application` requires both a `marshaller` and an `unmarshaller` property to be set. We +can do so by using the following `applicationContext.xml`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <bean id="application" class="Application"> + <property name="marshaller" ref="xstreamMarshaller" /> + <property name="unmarshaller" ref="xstreamMarshaller" /> + </bean> + <bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller"/> + </beans> +---- + +This application context uses XStream, but we could have used any of the other marshaller +instances described later in this chapter. Note that, by default, XStream does not require +any further configuration, so the bean definition is rather simple. Also note that the +`XStreamMarshaller` implements both `Marshaller` and `Unmarshaller`, so we can refer to the +`xstreamMarshaller` bean in both the `marshaller` and `unmarshaller` property of the +application. + +This sample application produces the following `settings.xml` file: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <settings foo-enabled="false"/> +---- + + + +[[oxm-schema-based-config]] +== XML Configuration Namespace + +You can configure marshallers more concisely by using tags from the OXM namespace. +To make these tags available, you must first reference the appropriate schema in the +preamble of the XML configuration file. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:oxm="http://www.springframework.org/schema/oxm" <1> + xsi:schemaLocation="http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/oxm + https://www.springframework.org/schema/oxm/spring-oxm.xsd"> <2> +---- +<1> Reference the `oxm` schema. +<2> Specify the `oxm` schema location. + + +The schema makes the following elements available: + +* <<oxm-jaxb2-xsd, `jaxb2-marshaller`>> +* <<oxm-jibx-xsd, `jibx-marshaller`>> + +Each tag is explained in its respective marshaller's section. As an example, though, +the configuration of a JAXB2 marshaller might resemble the following: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <oxm:jaxb2-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/> +---- + + + +[[oxm-jaxb]] +== JAXB + +The JAXB binding compiler translates a W3C XML Schema into one or more Java classes, a +`jaxb.properties` file, and possibly some resource files. JAXB also offers a way to +generate a schema from annotated Java classes. + +Spring supports the JAXB 2.0 API as XML marshalling strategies, following the +`Marshaller` and `Unmarshaller` interfaces described in <<oxm-marshaller-unmarshaller>>. +The corresponding integration classes reside in the `org.springframework.oxm.jaxb` +package. + + +[[oxm-jaxb2]] +=== Using `Jaxb2Marshaller` + +The `Jaxb2Marshaller` class implements both of Spring's `Marshaller` and `Unmarshaller` +interfaces. It requires a context path to operate. You can set the context path by setting the +`contextPath` property. The context path is a list of colon-separated Java package +names that contain schema derived classes. It also offers a `classesToBeBound` property, +which allows you to set an array of classes to be supported by the marshaller. Schema +validation is performed by specifying one or more schema resources to the bean, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <bean id="jaxb2Marshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller"> + <property name="classesToBeBound"> + <list> + <value>org.springframework.oxm.jaxb.Flight</value> + <value>org.springframework.oxm.jaxb.Flights</value> + </list> + </property> + <property name="schema" value="classpath:org/springframework/oxm/schema.xsd"/> + </bean> + + ... + + </beans> +---- + +[[oxm-jaxb2-xsd]] +==== XML Configuration Namespace + +The `jaxb2-marshaller` element configures a `org.springframework.oxm.jaxb.Jaxb2Marshaller`, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <oxm:jaxb2-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/> +---- + +Alternatively, you can provide the list of classes to bind to the marshaller by using the +`class-to-be-bound` child element: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <oxm:jaxb2-marshaller id="marshaller"> + <oxm:class-to-be-bound name="org.springframework.ws.samples.airline.schema.Airport"/> + <oxm:class-to-be-bound name="org.springframework.ws.samples.airline.schema.Flight"/> + ... + </oxm:jaxb2-marshaller> +---- + +The following table describes the available attributes: + +|=== +| Attribute| Description| Required + +| `id` +| The ID of the marshaller +| No + +| `contextPath` +| The JAXB Context path +| No +|=== + + + +[[oxm-jibx]] +== JiBX + +The JiBX framework offers a solution similar to that which Hibernate provides for ORM: A +binding definition defines the rules for how your Java objects are converted to or from +XML. After preparing the binding and compiling the classes, a JiBX binding compiler +enhances the class files and adds code to handle converting instances of the classes +from or to XML. + +For more information on JiBX, see the http://jibx.sourceforge.net/[JiBX web +site]. The Spring integration classes reside in the `org.springframework.oxm.jibx` +package. + + +[[oxm-jibx-marshaller]] +=== Using `JibxMarshaller` + +The `JibxMarshaller` class implements both the `Marshaller` and `Unmarshaller` +interface. To operate, it requires the name of the class to marshal in, which you can +set using the `targetClass` property. Optionally, you can set the binding name by setting the +`bindingName` property. In the following example, we bind the `Flights` class: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <bean id="jibxFlightsMarshaller" class="org.springframework.oxm.jibx.JibxMarshaller"> + <property name="targetClass">org.springframework.oxm.jibx.Flights</property> + </bean> + ... + </beans> +---- + +A `JibxMarshaller` is configured for a single class. If you want to marshal multiple +classes, you have to configure multiple `JibxMarshaller` instances with different `targetClass` +property values. + +[[oxm-jibx-xsd]] +==== XML Configuration Namespace + +The `jibx-marshaller` tag configures a `org.springframework.oxm.jibx.JibxMarshaller`, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <oxm:jibx-marshaller id="marshaller" target-class="org.springframework.ws.samples.airline.schema.Flight"/> +---- + +The following table describes the available attributes: + +|=== +| Attribute| Description| Required + +| `id` +| The ID of the marshaller +| No + +| `target-class` +| The target class for this marshaller +| Yes + +| `bindingName` +| The binding name used by this marshaller +| No +|=== + + + +[[oxm-xstream]] +== XStream + +XStream is a simple library to serialize objects to XML and back again. It does not +require any mapping and generates clean XML. + +For more information on XStream, see the https://x-stream.github.io/[XStream +web site]. The Spring integration classes reside in the +`org.springframework.oxm.xstream` package. + + +[[oxm-xstream-marshaller]] +=== Using `XStreamMarshaller` + +The `XStreamMarshaller` does not require any configuration and can be configured in an +application context directly. To further customize the XML, you can set an alias map, +which consists of string aliases mapped to classes, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller"> + <property name="aliases"> + <props> + <prop key="Flight">org.springframework.oxm.xstream.Flight</prop> + </props> + </property> + </bean> + ... + </beans> +---- + +[WARNING] +===== +By default, XStream lets arbitrary classes be unmarshalled, which can lead to +unsafe Java serialization effects. As such, we do not recommend using the +`XStreamMarshaller` to unmarshal XML from external sources (that is, the Web), as this can +result in security vulnerabilities. + +If you choose to use the `XStreamMarshaller` to unmarshal XML from an external source, +set the `supportedClasses` property on the `XStreamMarshaller`, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller"> + <property name="supportedClasses" value="org.springframework.oxm.xstream.Flight"/> + ... + </bean> +---- + +Doing so ensures that only the registered classes are eligible for unmarshalling. + +Additionally, you can register +{api-spring-framework}/oxm/xstream/XStreamMarshaller.html#setConverters(com.thoughtworks.xstream.converters.ConverterMatcher...)[custom +converters] to make sure that only your supported classes can be unmarshalled. You might +want to add a `CatchAllConverter` as the last converter in the list, in addition to +converters that explicitly support the domain classes that should be supported. As a +result, default XStream converters with lower priorities and possible security +vulnerabilities do not get invoked. +===== + +NOTE: Note that XStream is an XML serialization library, not a data binding library. +Therefore, it has limited namespace support. As a result, it is rather unsuitable for usage +within Web Services. + + + + +include:../:data-access/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc b/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc new file mode 100644 index 000000000000..178387529f02 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc @@ -0,0 +1,654 @@ +[[r2dbc]] += Data Access with R2DBC + +https://r2dbc.io[R2DBC] ("Reactive Relational Database Connectivity") is a community-driven +specification effort to standardize access to SQL databases using reactive patterns. + + +[[r2dbc-packages]] +== Package Hierarchy + +The Spring Framework's R2DBC abstraction framework consists of two different packages: + +* `core`: The `org.springframework.r2dbc.core` package contains the `DatabaseClient` +class plus a variety of related classes. See <<r2dbc-core>>. + +* `connection`: The `org.springframework.r2dbc.connection` package contains a utility class +for easy `ConnectionFactory` access and various simple `ConnectionFactory` implementations +that you can use for testing and running unmodified R2DBC. See <<r2dbc-connections>>. + + +[[r2dbc-core]] +== Using the R2DBC Core Classes to Control Basic R2DBC Processing and Error Handling + +This section covers how to use the R2DBC core classes to control basic R2DBC processing, +including error handling. It includes the following topics: + +* <<r2dbc-DatabaseClient>> +* <<r2dbc-DatabaseClient-examples-statement>> +* <<r2dbc-DatabaseClient-examples-query>> +* <<r2dbc-DatabaseClient-examples-update>> +* <<r2dbc-DatabaseClient-filter>> +* <<r2dbc-auto-generated-keys>> + +[[r2dbc-DatabaseClient]] +=== Using `DatabaseClient` + +`DatabaseClient` is the central class in the R2DBC core package. It handles the +creation and release of resources, which helps to avoid common errors, such as +forgetting to close the connection. It performs the basic tasks of the core R2DBC +workflow (such as statement creation and execution), leaving application code to provide +SQL and extract results. The `DatabaseClient` class: + +* Runs SQL queries +* Update statements and stored procedure calls +* Performs iteration over `Result` instances +* Catches R2DBC exceptions and translates them to the generic, more informative, exception +hierarchy defined in the `org.springframework.dao` package. (See <<dao-exceptions>>.) + +The client has a functional, fluent API using reactive types for declarative composition. + +When you use the `DatabaseClient` for your code, you need only to implement +`java.util.function` interfaces, giving them a clearly defined contract. +Given a `Connection` provided by the `DatabaseClient` class, a `Function` +callback creates a `Publisher`. The same is true for mapping functions that +extract a `Row` result. + +You can use `DatabaseClient` within a DAO implementation through direct instantiation +with a `ConnectionFactory` reference, or you can configure it in a Spring IoC container +and give it to DAOs as a bean reference. + +The simplest way to create a `DatabaseClient` object is through a static factory method, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + DatabaseClient client = DatabaseClient.create(connectionFactory); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val client = DatabaseClient.create(connectionFactory) +---- + +NOTE: The `ConnectionFactory` should always be configured as a bean in the Spring IoC +container. + +The preceding method creates a `DatabaseClient` with default settings. + +You can also obtain a `Builder` instance from `DatabaseClient.builder()`. +You can customize the client by calling the following methods: + +* `….bindMarkers(…)`: Supply a specific `BindMarkersFactory` to configure named +parameter to database bind marker translation. +* `….executeFunction(…)`: Set the `ExecuteFunction` how `Statement` objects get + run. +* `….namedParameters(false)`: Disable named parameter expansion. Enabled by default. + +TIP: Dialects are resolved by {api-spring-framework}/r2dbc/core/binding/BindMarkersFactoryResolver.html[`BindMarkersFactoryResolver`] + from a `ConnectionFactory`, typically by inspecting `ConnectionFactoryMetadata`. + + +You can let Spring auto-discover your `BindMarkersFactory` by registering a +class that implements `org.springframework.r2dbc.core.binding.BindMarkersFactoryResolver$BindMarkerFactoryProvider` +through `META-INF/spring.factories`. +`BindMarkersFactoryResolver` discovers bind marker provider implementations from +the class path using Spring's `SpringFactoriesLoader`. + + + +Currently supported databases are: + +* H2 +* MariaDB +* Microsoft SQL Server +* MySQL +* Postgres + +All SQL issued by this class is logged at the `DEBUG` level under the category +corresponding to the fully qualified class name of the client instance (typically +`DefaultDatabaseClient`). Additionally, each execution registers a checkpoint in +the reactive sequence to aid debugging. + +The following sections provide some examples of `DatabaseClient` usage. These examples +are not an exhaustive list of all of the functionality exposed by the `DatabaseClient`. +See the attendant {api-spring-framework}/r2dbc/core/DatabaseClient.html[javadoc] for that. + +[[r2dbc-DatabaseClient-examples-statement]] +==== Executing Statements + +`DatabaseClient` provides the basic functionality of running a statement. +The following example shows what you need to include for minimal but fully functional +code that creates a new table: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<Void> completion = client.sql("CREATE TABLE person (id VARCHAR(255) PRIMARY KEY, name VARCHAR(255), age INTEGER);") + .then(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + client.sql("CREATE TABLE person (id VARCHAR(255) PRIMARY KEY, name VARCHAR(255), age INTEGER);") + .await() +---- + +`DatabaseClient` is designed for convenient, fluent usage. +It exposes intermediate, continuation, and terminal methods at each stage of the +execution specification. The preceding example above uses `then()` to return a completion +`Publisher` that completes as soon as the query (or queries, if the SQL query contains +multiple statements) completes. + +NOTE: `execute(…)` accepts either the SQL query string or a query `Supplier<String>` +to defer the actual query creation until execution. + +[[r2dbc-DatabaseClient-examples-query]] +==== Querying (`SELECT`) + +SQL queries can return values through `Row` objects or the number of affected rows. +`DatabaseClient` can return the number of updated rows or the rows themselves, +depending on the issued query. + +The following query gets the `id` and `name` columns from a table: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<Map<String, Object>> first = client.sql("SELECT id, name FROM person") + .fetch().first(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val first = client.sql("SELECT id, name FROM person") + .fetch().awaitSingle() +---- + +The following query uses a bind variable: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<Map<String, Object>> first = client.sql("SELECT id, name FROM person WHERE first_name = :fn") + .bind("fn", "Joe") + .fetch().first(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val first = client.sql("SELECT id, name FROM person WHERE first_name = :fn") + .bind("fn", "Joe") + .fetch().awaitSingle() +---- + +You might have noticed the use of `fetch()` in the example above. `fetch()` is a +continuation operator that lets you specify how much data you want to consume. + +Calling `first()` returns the first row from the result and discards remaining rows. +You can consume data with the following operators: + +* `first()` return the first row of the entire result. Its Kotlin Coroutine variant +is named `awaitSingle()` for non-nullable return values and `awaitSingleOrNull()` +if the value is optional. +* `one()` returns exactly one result and fails if the result contains more rows. +Using Kotlin Coroutines, `awaitOne()` for exactly one value or `awaitOneOrNull()` +if the value may be `null`. +* `all()` returns all rows of the result. When using Kotlin Coroutines, use `flow()`. +* `rowsUpdated()` returns the number of affected rows (`INSERT`/`UPDATE`/`DELETE` +count). Its Kotlin Coroutine variant is named `awaitRowsUpdated()`. + +Without specifying further mapping details, queries return tabular results +as `Map` whose keys are case-insensitive column names that map to their column value. + +You can take control over result mapping by supplying a `Function<Row, T>` that gets +called for each `Row` so it can return arbitrary values (singular values, +collections and maps, and objects). + +The following example extracts the `name` column and emits its value: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Flux<String> names = client.sql("SELECT name FROM person") + .map(row -> row.get("name", String.class)) + .all(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val names = client.sql("SELECT name FROM person") + .map{ row: Row -> row.get("name", String.class) } + .flow() +---- + + +[[r2dbc-DatabaseClient-mapping-null]] +.What about `null`? +**** +Relational database results can contain `null` values. +The Reactive Streams specification forbids the emission of `null` values. +That requirement mandates proper `null` handling in the extractor function. +While you can obtain `null` values from a `Row`, you must not emit a `null` +value. You must wrap any `null` values in an object (for example, `Optional` +for singular values) to make sure a `null` value is never returned directly +by your extractor function. +**** + +[[r2dbc-DatabaseClient-examples-update]] +==== Updating (`INSERT`, `UPDATE`, and `DELETE`) with `DatabaseClient` + +The only difference of modifying statements is that these statements typically +do not return tabular data so you use `rowsUpdated()` to consume results. + +The following example shows an `UPDATE` statement that returns the number +of updated rows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<Integer> affectedRows = client.sql("UPDATE person SET first_name = :fn") + .bind("fn", "Joe") + .fetch().rowsUpdated(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val affectedRows = client.sql("UPDATE person SET first_name = :fn") + .bind("fn", "Joe") + .fetch().awaitRowsUpdated() +---- + +[[r2dbc-DatabaseClient-named-parameters]] +==== Binding Values to Queries + +A typical application requires parameterized SQL statements to select or +update rows according to some input. These are typically `SELECT` statements +constrained by a `WHERE` clause or `INSERT` and `UPDATE` statements that accept +input parameters. Parameterized statements bear the risk of SQL injection if +parameters are not escaped properly. `DatabaseClient` leverages R2DBC's +`bind` API to eliminate the risk of SQL injection for query parameters. +You can provide a parameterized SQL statement with the `execute(…)` operator +and bind parameters to the actual `Statement`. Your R2DBC driver then runs +the statement by using prepared statements and parameter substitution. + +Parameter binding supports two binding strategies: + +* By Index, using zero-based parameter indexes. +* By Name, using the placeholder name. + +The following example shows parameter binding for a query: + +==== +[source,java] +---- +db.sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)") + .bind("id", "joe") + .bind("name", "Joe") + .bind("age", 34); +---- +==== + +.R2DBC Native Bind Markers +**** +R2DBC uses database-native bind markers that depend on the actual database vendor. +As an example, Postgres uses indexed markers, such as `$1`, `$2`, `$n`. +Another example is SQL Server, which uses named bind markers prefixed with `@`. + +This is different from JDBC, which requires `?` as bind markers. +In JDBC, the actual drivers translate `?` bind markers to database-native +markers as part of their statement execution. + +Spring Framework's R2DBC support lets you use native bind markers or named bind +markers with the `:name` syntax. + +Named parameter support leverages a `BindMarkersFactory` instance to expand named +parameters to native bind markers at the time of query execution, which gives you +a certain degree of query portability across various database vendors. +**** + +The query-preprocessor unrolls named `Collection` parameters into a series of bind +markers to remove the need of dynamic query creation based on the number of arguments. +Nested object arrays are expanded to allow usage of (for example) select lists. + +Consider the following query: + +[source,sql] +---- +SELECT id, name, state FROM table WHERE (name, age) IN (('John', 35), ('Ann', 50)) +---- + +The preceding query can be parameterized and run as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + List<Object[]> tuples = new ArrayList<>(); + tuples.add(new Object[] {"John", 35}); + tuples.add(new Object[] {"Ann", 50}); + + client.sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)") + .bind("tuples", tuples); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val tuples: MutableList<Array<Any>> = ArrayList() + tuples.add(arrayOf("John", 35)) + tuples.add(arrayOf("Ann", 50)) + + client.sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)") + .bind("tuples", tuples) +---- + +NOTE: Usage of select lists is vendor-dependent. + +The following example shows a simpler variant using `IN` predicates: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + client.sql("SELECT id, name, state FROM table WHERE age IN (:ages)") + .bind("ages", Arrays.asList(35, 50)); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val tuples: MutableList<Array<Any>> = ArrayList() + tuples.add(arrayOf("John", 35)) + tuples.add(arrayOf("Ann", 50)) + + client.sql("SELECT id, name, state FROM table WHERE age IN (:ages)") + .bind("tuples", arrayOf(35, 50)) +---- + +NOTE: R2DBC itself does not support Collection-like values. Nevertheless, +expanding a given `List` in the example above works for named parameters +in Spring's R2DBC support, e.g. for use in `IN` clauses as shown above. +However, inserting or updating array-typed columns (e.g. in Postgres) +requires an array type that is supported by the underlying R2DBC driver: +typically a Java array, e.g. `String[]` to update a `text[]` column. +Do not pass `Collection<String>` or the like as an array parameter. + +[[r2dbc-DatabaseClient-filter]] +==== Statement Filters + +Sometimes it you need to fine-tune options on the actual `Statement` +before it gets run. Register a `Statement` filter +(`StatementFilterFunction`) through `DatabaseClient` to intercept and +modify statements in their execution, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") + .filter((s, next) -> next.execute(s.returnGeneratedValues("id"))) + .bind("name", …) + .bind("state", …); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") + .filter { s: Statement, next: ExecuteFunction -> next.execute(s.returnGeneratedValues("id")) } + .bind("name", …) + .bind("state", …) +---- + +`DatabaseClient` exposes also simplified `filter(…)` overload accepting `Function<Statement, Statement>`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") + .filter(statement -> s.returnGeneratedValues("id")); + + client.sql("SELECT id, name, state FROM table") + .filter(statement -> s.fetchSize(25)); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") + .filter { statement -> s.returnGeneratedValues("id") } + + client.sql("SELECT id, name, state FROM table") + .filter { statement -> s.fetchSize(25) } +---- + +`StatementFilterFunction` implementations allow filtering of the +`Statement` and filtering of `Result` objects. + +[[r2dbc-DatabaseClient-idioms]] +==== `DatabaseClient` Best Practices + +Instances of the `DatabaseClient` class are thread-safe, once configured. This is +important because it means that you can configure a single instance of a `DatabaseClient` +and then safely inject this shared reference into multiple DAOs (or repositories). +The `DatabaseClient` is stateful, in that it maintains a reference to a `ConnectionFactory`, +but this state is not conversational state. + +A common practice when using the `DatabaseClient` class is to configure a `ConnectionFactory` +in your Spring configuration file and then dependency-inject +that shared `ConnectionFactory` bean into your DAO classes. The `DatabaseClient` is created in +the setter for the `ConnectionFactory`. This leads to DAOs that resemble the following: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class R2dbcCorporateEventDao implements CorporateEventDao { + + private DatabaseClient databaseClient; + + public void setConnectionFactory(ConnectionFactory connectionFactory) { + this.databaseClient = DatabaseClient.create(connectionFactory); + } + + // R2DBC-backed implementations of the methods on the CorporateEventDao follow... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class R2dbcCorporateEventDao(connectionFactory: ConnectionFactory) : CorporateEventDao { + + private val databaseClient = DatabaseClient.create(connectionFactory) + + // R2DBC-backed implementations of the methods on the CorporateEventDao follow... + } +---- +-- + +An alternative to explicit configuration is to use component-scanning and annotation +support for dependency injection. In this case, you can annotate the class with `@Component` +(which makes it a candidate for component-scanning) and annotate the `ConnectionFactory` setter +method with `@Autowired`. The following example shows how to do so: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component // <1> + public class R2dbcCorporateEventDao implements CorporateEventDao { + + private DatabaseClient databaseClient; + + @Autowired // <2> + public void setConnectionFactory(ConnectionFactory connectionFactory) { + this.databaseClient = DatabaseClient.create(connectionFactory); // <3> + } + + // R2DBC-backed implementations of the methods on the CorporateEventDao follow... + } +---- +<1> Annotate the class with `@Component`. +<2> Annotate the `ConnectionFactory` setter method with `@Autowired`. +<3> Create a new `DatabaseClient` with the `ConnectionFactory`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component // <1> + class R2dbcCorporateEventDao(connectionFactory: ConnectionFactory) : CorporateEventDao { // <2> + + private val databaseClient = DatabaseClient(connectionFactory) // <3> + + // R2DBC-backed implementations of the methods on the CorporateEventDao follow... + } +---- +<1> Annotate the class with `@Component`. +<2> Constructor injection of the `ConnectionFactory`. +<3> Create a new `DatabaseClient` with the `ConnectionFactory`. +-- + +Regardless of which of the above template initialization styles you choose to use (or +not), it is seldom necessary to create a new instance of a `DatabaseClient` class each +time you want to run SQL. Once configured, a `DatabaseClient` instance is thread-safe. +If your application accesses multiple +databases, you may want multiple `DatabaseClient` instances, which requires multiple +`ConnectionFactory` and, subsequently, multiple differently configured `DatabaseClient` +instances. + +[[r2dbc-auto-generated-keys]] +== Retrieving Auto-generated Keys + +`INSERT` statements may generate keys when inserting rows into a table +that defines an auto-increment or identity column. To get full control over +the column name to generate, simply register a `StatementFilterFunction` that +requests the generated key for the desired column. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<Integer> generatedId = client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") + .filter(statement -> s.returnGeneratedValues("id")) + .map(row -> row.get("id", Integer.class)) + .first(); + + // generatedId emits the generated key once the INSERT statement has finished +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val generatedId = client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") + .filter { statement -> s.returnGeneratedValues("id") } + .map { row -> row.get("id", Integer.class) } + .awaitOne() + + // generatedId emits the generated key once the INSERT statement has finished +---- + + +[[r2dbc-connections]] +== Controlling Database Connections + +This section covers: + +* <<r2dbc-ConnectionFactory>> +* <<r2dbc-ConnectionFactoryUtils>> +* <<r2dbc-SingleConnectionFactory>> +* <<r2dbc-TransactionAwareConnectionFactoryProxy>> +* <<r2dbc-R2dbcTransactionManager>> + + +[[r2dbc-ConnectionFactory]] +=== Using `ConnectionFactory` + +Spring obtains an R2DBC connection to the database through a `ConnectionFactory`. +A `ConnectionFactory` is part of the R2DBC specification and is a common entry-point +for drivers. It lets a container or a framework hide connection pooling +and transaction management issues from the application code. As a developer, +you need not know details about how to connect to the database. That is the +responsibility of the administrator who sets up the `ConnectionFactory`. You +most likely fill both roles as you develop and test code, but you do not +necessarily have to know how the production data source is configured. + +When you use Spring's R2DBC layer, you can configure your own with a +connection pool implementation provided by a third party. A popular +implementation is R2DBC Pool (`r2dbc-pool`). Implementations in the Spring +distribution are meant only for testing purposes and do not provide pooling. + +To configure a `ConnectionFactory`: + +. Obtain a connection with `ConnectionFactory` as you typically obtain an R2DBC `ConnectionFactory`. +. Provide an R2DBC URL +(See the documentation for your driver for the correct value). + +The following example shows how to configure a `ConnectionFactory`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ConnectionFactory factory = ConnectionFactories.get("r2dbc:h2:mem:///test?options=DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val factory = ConnectionFactories.get("r2dbc:h2:mem:///test?options=DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"); +---- + + +[[r2dbc-ConnectionFactoryUtils]] +=== Using `ConnectionFactoryUtils` + + +The `ConnectionFactoryUtils` class is a convenient and powerful helper class +that provides `static` methods to obtain connections from `ConnectionFactory` +and close connections (if necessary). + +It supports subscriber ``Context``-bound connections with, for example +`R2dbcTransactionManager`. + + +[[r2dbc-SingleConnectionFactory]] +=== Using `SingleConnectionFactory` + +The `SingleConnectionFactory` class is an implementation of `DelegatingConnectionFactory` +interface that wraps a single `Connection` that is not closed after each use. + +If any client code calls `close` on the assumption of a pooled connection (as when using +persistence tools), you should set the `suppressClose` property to `true`. This setting +returns a close-suppressing proxy that wraps the physical connection. Note that you can +no longer cast this to a native `Connection` or a similar object. + +`SingleConnectionFactory` is primarily a test class and may be used for specific requirements +such as pipelining if your R2DBC driver permits for such use. +In contrast to a pooled `ConnectionFactory`, it reuses the same connection all the time, avoiding +excessive creation of physical connections. + + +[[r2dbc-TransactionAwareConnectionFactoryProxy]] +=== Using `TransactionAwareConnectionFactoryProxy` + +`TransactionAwareConnectionFactoryProxy` is a proxy for a target `ConnectionFactory`. +The proxy wraps that target `ConnectionFactory` to add awareness of Spring-managed transactions. + +NOTE: Using this class is required if you use a R2DBC client that is not integrated otherwise +with Spring's R2DBC support. In this case, you can still use this client and, at +the same time, have this client participating in Spring managed transactions. It is generally +preferable to integrate a R2DBC client with proper access to `ConnectionFactoryUtils` +for resource management. + +See the {api-spring-framework}/r2dbc/connection/TransactionAwareConnectionFactoryProxy.html[`TransactionAwareConnectionFactoryProxy`] +javadoc for more details. + + +[[r2dbc-R2dbcTransactionManager]] +=== Using `R2dbcTransactionManager` + +The `R2dbcTransactionManager` class is a `ReactiveTransactionManager` implementation for +single R2DBC data sources. It binds an R2DBC connection from the specified connection factory +to the subscriber `Context`, potentially allowing for one subscriber connection for each +connection factory. + +Application code is required to retrieve the R2DBC connection through +`ConnectionFactoryUtils.getConnection(ConnectionFactory)`, instead of R2DBC's standard +`ConnectionFactory.create()`. + +All framework classes (such as `DatabaseClient`) use this strategy implicitly. +If not used with this transaction manager, the lookup strategy behaves exactly like the common one. +Thus, it can be used in any case. + +The `R2dbcTransactionManager` class supports custom isolation levels that get applied to the connection. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction.adoc new file mode 100644 index 000000000000..758ef2eddb97 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction.adoc @@ -0,0 +1,40 @@ +[[transaction]] += Transaction Management + +Comprehensive transaction support is among the most compelling reasons to use the Spring +Framework. The Spring Framework provides a consistent abstraction for transaction +management that delivers the following benefits: + +* A consistent programming model across different transaction APIs, such as Java + Transaction API (JTA), JDBC, Hibernate, and the Java Persistence API (JPA). +* Support for <<transaction-declarative, declarative transaction management>>. +* A simpler API for <<transaction-programmatic, programmatic>> transaction management + than complex transaction APIs, such as JTA. +* Excellent integration with Spring's data access abstractions. + +The following sections describe the Spring Framework's transaction features and +technologies: + +* <<transaction-motivation, Advantages of the Spring Framework's transaction support + model>> describes why you would use the Spring Framework's transaction abstraction + instead of EJB Container-Managed Transactions (CMT) or choosing to drive local + transactions through a proprietary API, such as Hibernate. +* <<transaction-strategies, Understanding the Spring Framework transaction abstraction>> + outlines the core classes and describes how to configure and obtain `DataSource` + instances from a variety of sources. +* <<tx-resource-synchronization, Synchronizing resources with transactions>> describes + how the application code ensures that resources are created, reused, and cleaned up + properly. +* <<transaction-declarative, Declarative transaction management>> describes support for + declarative transaction management. +* <<transaction-programmatic, Programmatic transaction management>> covers support for + programmatic (that is, explicitly coded) transaction management. +* <<transaction-event, Transaction bound event>> describes how you could use application + events within a transaction. + +The chapter also includes discussions of best practices, +<<transaction-application-server-integration, application server integration>>, +and <<transaction-solutions-to-common-problems, solutions to common problems>>. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/application-server-integration.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/application-server-integration.adoc new file mode 100644 index 000000000000..abd9418b23a3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/application-server-integration.adoc @@ -0,0 +1,51 @@ +[[transaction-application-server-integration]] += Application server-specific integration + +Spring's transaction abstraction is generally application server-agnostic. Additionally, +Spring's `JtaTransactionManager` class (which can optionally perform a JNDI lookup for +the JTA `UserTransaction` and `TransactionManager` objects) autodetects the location for +the latter object, which varies by application server. Having access to the JTA +`TransactionManager` allows for enhanced transaction semantics -- in particular, +supporting transaction suspension. See the +{api-spring-framework}/transaction/jta/JtaTransactionManager.html[`JtaTransactionManager`] +javadoc for details. + +Spring's `JtaTransactionManager` is the standard choice to run on Jakarta EE application +servers and is known to work on all common servers. Advanced functionality, such as +transaction suspension, works on many servers as well (including GlassFish, JBoss and +Geronimo) without any special configuration required. However, for fully supported +transaction suspension and further advanced integration, Spring includes special adapters +for WebLogic Server and WebSphere. These adapters are discussed in the following +sections. + +For standard scenarios, including WebLogic Server and WebSphere, consider using the +convenient `<tx:jta-transaction-manager/>` configuration element. When configured, +this element automatically detects the underlying server and chooses the best +transaction manager available for the platform. This means that you need not explicitly +configure server-specific adapter classes (as discussed in the following sections). +Rather, they are chosen automatically, with the standard +`JtaTransactionManager` as the default fallback. + + +[[transaction-application-server-integration-websphere]] +== IBM WebSphere + +On WebSphere 6.1.0.9 and above, the recommended Spring JTA transaction manager to use is +`WebSphereUowTransactionManager`. This special adapter uses IBM's `UOWManager` API, +which is available in WebSphere Application Server 6.1.0.9 and later. With this adapter, +Spring-driven transaction suspension (suspend and resume as initiated by +`PROPAGATION_REQUIRES_NEW`) is officially supported by IBM. + + +[[transaction-application-server-integration-weblogic]] +== Oracle WebLogic Server + +On WebLogic Server 9.0 or above, you would typically use the +`WebLogicJtaTransactionManager` instead of the stock `JtaTransactionManager` class. This +special WebLogic-specific subclass of the normal `JtaTransactionManager` supports the +full power of Spring's transaction definitions in a WebLogic-managed transaction +environment, beyond standard JTA semantics. Features include transaction names, +per-transaction isolation levels, and proper resuming of transactions in all cases. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc new file mode 100644 index 000000000000..949f8285df60 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc @@ -0,0 +1,53 @@ +[[transaction-declarative]] += Declarative Transaction Management + +NOTE: Most Spring Framework users choose declarative transaction management. This option has +the least impact on application code and, hence, is most consistent with the ideals of a +non-invasive lightweight container. + +The Spring Framework's declarative transaction management is made possible with Spring +aspect-oriented programming (AOP). However, as the transactional aspects code comes +with the Spring Framework distribution and may be used in a boilerplate fashion, AOP +concepts do not generally have to be understood to make effective use of this code. + +The Spring Framework's declarative transaction management is similar to EJB CMT, in that +you can specify transaction behavior (or lack of it) down to the individual method level. +You can make a `setRollbackOnly()` call within a transaction context, if +necessary. The differences between the two types of transaction management are: + +* Unlike EJB CMT, which is tied to JTA, the Spring Framework's declarative transaction + management works in any environment. It can work with JTA transactions or local + transactions by using JDBC, JPA, or Hibernate by adjusting the configuration + files. +* You can apply the Spring Framework declarative transaction management to any class, + not merely special classes such as EJBs. +* The Spring Framework offers declarative + <<transaction-declarative-rolling-back, rollback rules>>, a feature with no EJB + equivalent. Both programmatic and declarative support for rollback rules is provided. +* The Spring Framework lets you customize transactional behavior by using AOP. + For example, you can insert custom behavior in the case of transaction rollback. You + can also add arbitrary advice, along with transactional advice. With EJB CMT, you + cannot influence the container's transaction management, except with + `setRollbackOnly()`. +* The Spring Framework does not support propagation of transaction contexts across + remote calls, as high-end application servers do. If you need this feature, we + recommend that you use EJB. However, consider carefully before using such a feature, + because, normally, one does not want transactions to span remote calls. + +The concept of rollback rules is important. They let you specify which exceptions +(and throwables) should cause automatic rollback. You can specify this declaratively, in +configuration, not in Java code. So, although you can still call `setRollbackOnly()` on +the `TransactionStatus` object to roll back the current transaction back, most often you +can specify a rule that `MyApplicationException` must always result in rollback. The +significant advantage to this option is that business objects do not depend on the +transaction infrastructure. For example, they typically do not need to import Spring +transaction APIs or other Spring APIs. + +Although EJB container default behavior automatically rolls back the transaction on a +system exception (usually a runtime exception), EJB CMT does not roll back the +transaction automatically on an application exception (that is, a checked exception +other than `java.rmi.RemoteException`). While the Spring default behavior for +declarative transaction management follows EJB convention (roll back is automatic only +on unchecked exceptions), it is often useful to customize this behavior. + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc new file mode 100644 index 000000000000..536df97c369a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc @@ -0,0 +1,598 @@ +[[transaction-declarative-annotations]] += Using `@Transactional` + +In addition to the XML-based declarative approach to transaction configuration, you can +use an annotation-based approach. Declaring transaction semantics directly in the Java +source code puts the declarations much closer to the affected code. There is not much +danger of undue coupling, because code that is meant to be used transactionally is +almost always deployed that way anyway. + +NOTE: The standard `jakarta.transaction.Transactional` annotation is also supported as +a drop-in replacement to Spring's own annotation. Please refer to the JTA documentation +for more details. + +The ease-of-use afforded by the use of the `@Transactional` annotation is best +illustrated with an example, which is explained in the text that follows. +Consider the following class definition: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // the service class that we want to make transactional + @Transactional + public class DefaultFooService implements FooService { + + @Override + public Foo getFoo(String fooName) { + // ... + } + + @Override + public Foo getFoo(String fooName, String barName) { + // ... + } + + @Override + public void insertFoo(Foo foo) { + // ... + } + + @Override + public void updateFoo(Foo foo) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // the service class that we want to make transactional + @Transactional + class DefaultFooService : FooService { + + override fun getFoo(fooName: String): Foo { + // ... + } + + override fun getFoo(fooName: String, barName: String): Foo { + // ... + } + + override fun insertFoo(foo: Foo) { + // ... + } + + override fun updateFoo(foo: Foo) { + // ... + } + } +---- + +Used at the class level as above, the annotation indicates a default for all methods of +the declaring class (as well as its subclasses). Alternatively, each method can be +annotated individually. See <<transaction-declarative-annotations-method-visibility>> for +further details on which methods Spring considers transactional. Note that a class-level +annotation does not apply to ancestor classes up the class hierarchy; in such a scenario, +inherited methods need to be locally redeclared in order to participate in a +subclass-level annotation. + +When a POJO class such as the one above is defined as a bean in a Spring context, +you can make the bean instance transactional through an `@EnableTransactionManagement` +annotation in a `@Configuration` class. See the +{api-spring-framework}/transaction/annotation/EnableTransactionManagement.html[javadoc] +for full details. + +In XML configuration, the `<tx:annotation-driven/>` tag provides similar convenience: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <!-- from the file 'context.xml' --> + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:aop="http://www.springframework.org/schema/aop" + xmlns:tx="http://www.springframework.org/schema/tx" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx + https://www.springframework.org/schema/tx/spring-tx.xsd + http://www.springframework.org/schema/aop + https://www.springframework.org/schema/aop/spring-aop.xsd"> + + <!-- this is the service object that we want to make transactional --> + <bean id="fooService" class="x.y.service.DefaultFooService"/> + + <!-- enable the configuration of transactional behavior based on annotations --> + <!-- a TransactionManager is still required --> + <tx:annotation-driven transaction-manager="txManager"/> <1> + + <bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager"> + <!-- (this dependency is defined somewhere else) --> + <property name="dataSource" ref="dataSource"/> + </bean> + + <!-- other <bean/> definitions here --> + + </beans> +---- +<1> The line that makes the bean instance transactional. + + +TIP: You can omit the `transaction-manager` attribute in the `<tx:annotation-driven/>` +tag if the bean name of the `TransactionManager` that you want to wire in has the name +`transactionManager`. If the `TransactionManager` bean that you want to dependency-inject +has any other name, you have to use the `transaction-manager` attribute, as in the +preceding example. + +Reactive transactional methods use reactive return types in contrast to imperative +programming arrangements as the following listing shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // the reactive service class that we want to make transactional + @Transactional + public class DefaultFooService implements FooService { + + @Override + public Publisher<Foo> getFoo(String fooName) { + // ... + } + + @Override + public Mono<Foo> getFoo(String fooName, String barName) { + // ... + } + + @Override + public Mono<Void> insertFoo(Foo foo) { + // ... + } + + @Override + public Mono<Void> updateFoo(Foo foo) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // the reactive service class that we want to make transactional + @Transactional + class DefaultFooService : FooService { + + override fun getFoo(fooName: String): Flow<Foo> { + // ... + } + + override fun getFoo(fooName: String, barName: String): Mono<Foo> { + // ... + } + + override fun insertFoo(foo: Foo): Mono<Void> { + // ... + } + + override fun updateFoo(foo: Foo): Mono<Void> { + // ... + } + } +---- + +Note that there are special considerations for the returned `Publisher` with regards to +Reactive Streams cancellation signals. See the <<tx-prog-operator-cancel>> section under +"Using the TransactionalOperator" for more details. + + +[[transaction-declarative-annotations-method-visibility]] +.Method visibility and `@Transactional` +[NOTE] +==== +When you use transactional proxies with Spring's standard configuration, you should apply +the `@Transactional` annotation only to methods with `public` visibility. If you do +annotate `protected`, `private`, or package-visible methods with the `@Transactional` +annotation, no error is raised, but the annotated method does not exhibit the configured +transactional settings. If you need to annotate non-public methods, consider the tip in +the following paragraph for class-based proxies or consider using AspectJ compile-time or +load-time weaving (described later). + +When using `@EnableTransactionManagement` in a `@Configuration` class, `protected` or +package-visible methods can also be made transactional for class-based proxies by +registering a custom `transactionAttributeSource` bean like in the following example. +Note, however, that transactional methods in interface-based proxies must always be +`public` and defined in the proxied interface. + +[source,java,indent=0,subs="verbatim,quotes"] +---- + /** + * Register a custom AnnotationTransactionAttributeSource with the + * publicMethodsOnly flag set to false to enable support for + * protected and package-private @Transactional methods in + * class-based proxies. + * + * @see ProxyTransactionManagementConfiguration#transactionAttributeSource() + */ + @Bean + TransactionAttributeSource transactionAttributeSource() { + return new AnnotationTransactionAttributeSource(false); + } +---- + +The _Spring TestContext Framework_ supports non-private `@Transactional` test methods by +default. See <<testing.adoc#testcontext-tx,Transaction Management>> in the testing +chapter for examples. +==== + +You can apply the `@Transactional` annotation to an interface definition, a method +on an interface, a class definition, or a method on a class. However, the +mere presence of the `@Transactional` annotation is not enough to activate the +transactional behavior. The `@Transactional` annotation is merely metadata that can +be consumed by some runtime infrastructure that is `@Transactional`-aware and that +can use the metadata to configure the appropriate beans with transactional behavior. +In the preceding example, the `<tx:annotation-driven/>` element switches on the +transactional behavior. + +TIP: The Spring team recommends that you annotate only concrete classes (and methods of +concrete classes) with the `@Transactional` annotation, as opposed to annotating interfaces. +You certainly can place the `@Transactional` annotation on an interface (or an interface +method), but this works only as you would expect it to if you use interface-based +proxies. The fact that Java annotations are not inherited from interfaces means that, +if you use class-based proxies (`proxy-target-class="true"`) or the weaving-based +aspect (`mode="aspectj"`), the transaction settings are not recognized by the proxying +and weaving infrastructure, and the object is not wrapped in a transactional proxy. + +NOTE: In proxy mode (which is the default), only external method calls coming in through +the proxy are intercepted. This means that self-invocation (in effect, a method within +the target object calling another method of the target object) does not lead to an actual +transaction at runtime even if the invoked method is marked with `@Transactional`. Also, +the proxy must be fully initialized to provide the expected behavior, so you should not +rely on this feature in your initialization code -- for example, in a `@PostConstruct` +method. + +Consider using AspectJ mode (see the `mode` attribute in the following table) if you +expect self-invocations to be wrapped with transactions as well. In this case, there is +no proxy in the first place. Instead, the target class is woven (that is, its byte code +is modified) to support `@Transactional` runtime behavior on any kind of method. + +[[tx-annotation-driven-settings]] +.Annotation driven transaction settings +|=== +| XML Attribute| Annotation Attribute| Default| Description + +| `transaction-manager` +| N/A (see {api-spring-framework}/transaction/annotation/TransactionManagementConfigurer.html[`TransactionManagementConfigurer`] javadoc) +| `transactionManager` +| Name of the transaction manager to use. Required only if the name of the transaction + manager is not `transactionManager`, as in the preceding example. + +| `mode` +| `mode` +| `proxy` +| The default mode (`proxy`) processes annotated beans to be proxied by using Spring's AOP + framework (following proxy semantics, as discussed earlier, applying to method calls + coming in through the proxy only). The alternative mode (`aspectj`) instead weaves the + affected classes with Spring's AspectJ transaction aspect, modifying the target class + byte code to apply to any kind of method call. AspectJ weaving requires + `spring-aspects.jar` in the classpath as well as having load-time weaving (or compile-time + weaving) enabled. (See <<core.adoc#aop-aj-ltw-spring, Spring configuration>> + for details on how to set up load-time weaving.) + +| `proxy-target-class` +| `proxyTargetClass` +| `false` +| Applies to `proxy` mode only. Controls what type of transactional proxies are created + for classes annotated with the `@Transactional` annotation. If the + `proxy-target-class` attribute is set to `true`, class-based proxies are created. + If `proxy-target-class` is `false` or if the attribute is omitted, then standard JDK + interface-based proxies are created. (See <<core.adoc#aop-proxying, Proxying Mechanisms>> + for a detailed examination of the different proxy types.) + +| `order` +| `order` +| `Ordered.LOWEST_PRECEDENCE` +| Defines the order of the transaction advice that is applied to beans annotated with + `@Transactional`. (For more information about the rules related to ordering of AOP + advice, see <<core.adoc#aop-ataspectj-advice-ordering, Advice Ordering>>.) + No specified ordering means that the AOP subsystem determines the order of the advice. +|=== + +NOTE: The default advice mode for processing `@Transactional` annotations is `proxy`, +which allows for interception of calls through the proxy only. Local calls within the +same class cannot get intercepted that way. For a more advanced mode of interception, +consider switching to `aspectj` mode in combination with compile-time or load-time weaving. + +NOTE: The `proxy-target-class` attribute controls what type of transactional proxies are +created for classes annotated with the `@Transactional` annotation. If +`proxy-target-class` is set to `true`, class-based proxies are created. If +`proxy-target-class` is `false` or if the attribute is omitted, standard JDK +interface-based proxies are created. (See <<core.adoc#aop-proxying, Proxying Mechanisms>> +for a discussion of the different proxy types.) + +NOTE: `@EnableTransactionManagement` and `<tx:annotation-driven/>` look for +`@Transactional` only on beans in the same application context in which they are defined. +This means that, if you put annotation-driven configuration in a `WebApplicationContext` +for a `DispatcherServlet`, it checks for `@Transactional` beans only in your controllers +and not in your services. See <<web.adoc#mvc-servlet, MVC>> for more information. + +The most derived location takes precedence when evaluating the transactional settings +for a method. In the case of the following example, the `DefaultFooService` class is +annotated at the class level with the settings for a read-only transaction, but the +`@Transactional` annotation on the `updateFoo(Foo)` method in the same class takes +precedence over the transactional settings defined at the class level. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Transactional(readOnly = true) + public class DefaultFooService implements FooService { + + public Foo getFoo(String fooName) { + // ... + } + + // these settings have precedence for this method + @Transactional(readOnly = false, propagation = Propagation.REQUIRES_NEW) + public void updateFoo(Foo foo) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Transactional(readOnly = true) + class DefaultFooService : FooService { + + override fun getFoo(fooName: String): Foo { + // ... + } + + // these settings have precedence for this method + @Transactional(readOnly = false, propagation = Propagation.REQUIRES_NEW) + override fun updateFoo(foo: Foo) { + // ... + } + } +---- + + +[[transaction-declarative-attransactional-settings]] +== `@Transactional` Settings + +The `@Transactional` annotation is metadata that specifies that an interface, class, +or method must have transactional semantics (for example, "start a brand new read-only +transaction when this method is invoked, suspending any existing transaction"). +The default `@Transactional` settings are as follows: + +* The propagation setting is `PROPAGATION_REQUIRED.` +* The isolation level is `ISOLATION_DEFAULT.` +* The transaction is read-write. +* The transaction timeout defaults to the default timeout of the underlying transaction + system, or to none if timeouts are not supported. +* Any `RuntimeException` or `Error` triggers rollback, and any checked `Exception` does + not. + +You can change these default settings. The following table summarizes the various +properties of the `@Transactional` annotation: + +[[tx-attransactional-properties]] +.@Transactional Settings +|=== +| Property| Type| Description + +| <<tx-multiple-tx-mgrs-with-attransactional,value>> +| `String` +| Optional qualifier that specifies the transaction manager to be used. + +| `transactionManager` +| `String` +| Alias for `value`. + +| `label` +| Array of `String` labels to add an expressive description to the transaction. +| Labels may be evaluated by transaction managers to associate implementation-specific behavior with the actual transaction. + +| <<tx-propagation,propagation>> +| `enum`: `Propagation` +| Optional propagation setting. + +| `isolation` +| `enum`: `Isolation` +| Optional isolation level. Applies only to propagation values of `REQUIRED` or `REQUIRES_NEW`. + +| `timeout` +| `int` (in seconds of granularity) +| Optional transaction timeout. Applies only to propagation values of `REQUIRED` or `REQUIRES_NEW`. + +| `timeoutString` +| `String` (in seconds of granularity) +| Alternative for specifying the `timeout` in seconds as a `String` value -- for example, as a placeholder. + +| `readOnly` +| `boolean` +| Read-write versus read-only transaction. Only applicable to values of `REQUIRED` or `REQUIRES_NEW`. + +| `rollbackFor` +| Array of `Class` objects, which must be derived from `Throwable.` +| Optional array of exception types that must cause rollback. + +| `rollbackForClassName` +| Array of exception name patterns. +| Optional array of exception name patterns that must cause rollback. + +| `noRollbackFor` +| Array of `Class` objects, which must be derived from `Throwable.` +| Optional array of exception types that must not cause rollback. + +| `noRollbackForClassName` +| Array of exception name patterns. +| Optional array of exception name patterns that must not cause rollback. +|=== + +TIP: See <<transaction-declarative-rollback-rules, Rollback rules>> for further details +on rollback rule semantics, patterns, and warnings regarding possible unintentional +matches for pattern-based rollback rules. + +Currently, you cannot have explicit control over the name of a transaction, where 'name' +means the transaction name that appears in a transaction monitor, if applicable +(for example, WebLogic's transaction monitor), and in logging output. For declarative +transactions, the transaction name is always the fully-qualified class name + `.` ++ the method name of the transactionally advised class. For example, if the +`handlePayment(..)` method of the `BusinessService` class started a transaction, the +name of the transaction would be: `com.example.BusinessService.handlePayment`. + +[[tx-multiple-tx-mgrs-with-attransactional]] +== Multiple Transaction Managers with `@Transactional` + +Most Spring applications need only a single transaction manager, but there may be +situations where you want multiple independent transaction managers in a single +application. You can use the `value` or `transactionManager` attribute of the +`@Transactional` annotation to optionally specify the identity of the +`TransactionManager` to be used. This can either be the bean name or the qualifier value +of the transaction manager bean. For example, using the qualifier notation, you can +combine the following Java code with the following transaction manager bean declarations +in the application context: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class TransactionalService { + + @Transactional("order") + public void setSomething(String name) { ... } + + @Transactional("account") + public void doSomething() { ... } + + @Transactional("reactive-account") + public Mono<Void> doSomethingReactive() { ... } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + class TransactionalService { + + @Transactional("order") + fun setSomething(name: String) { + // ... + } + + @Transactional("account") + fun doSomething() { + // ... + } + + @Transactional("reactive-account") + fun doSomethingReactive(): Mono<Void> { + // ... + } + } +---- + +The following listing shows the bean declarations: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <tx:annotation-driven/> + + <bean id="transactionManager1" class="org.springframework.jdbc.datasource.DataSourceTransactionManager"> + ... + <qualifier value="order"/> + </bean> + + <bean id="transactionManager2" class="org.springframework.jdbc.datasource.DataSourceTransactionManager"> + ... + <qualifier value="account"/> + </bean> + + <bean id="transactionManager3" class="org.springframework.data.r2dbc.connectionfactory.R2dbcTransactionManager"> + ... + <qualifier value="reactive-account"/> + </bean> +---- + +In this case, the individual methods on `TransactionalService` run under separate +transaction managers, differentiated by the `order`, `account`, and `reactive-account` +qualifiers. The default `<tx:annotation-driven>` target bean name, `transactionManager`, +is still used if no specifically qualified `TransactionManager` bean is found. + +[[tx-custom-attributes]] +== Custom Composed Annotations + +If you find you repeatedly use the same attributes with `@Transactional` on many different +methods, <<core.adoc#beans-meta-annotations, Spring's meta-annotation support>> lets you +define custom composed annotations for your specific use cases. For example, consider the +following annotation definitions: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target({ElementType.METHOD, ElementType.TYPE}) + @Retention(RetentionPolicy.RUNTIME) + @Transactional(transactionManager = "order", label = "causal-consistency") + public @interface OrderTx { + } + + @Target({ElementType.METHOD, ElementType.TYPE}) + @Retention(RetentionPolicy.RUNTIME) + @Transactional(transactionManager = "account", label = "retryable") + public @interface AccountTx { + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.FUNCTION, AnnotationTarget.TYPE) + @Retention(AnnotationRetention.RUNTIME) + @Transactional(transactionManager = "order", label = ["causal-consistency"]) + annotation class OrderTx + + @Target(AnnotationTarget.FUNCTION, AnnotationTarget.TYPE) + @Retention(AnnotationRetention.RUNTIME) + @Transactional(transactionManager = "account", label = ["retryable"]) + annotation class AccountTx +---- + +The preceding annotations let us write the example from the previous section as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class TransactionalService { + + @OrderTx + public void setSomething(String name) { + // ... + } + + @AccountTx + public void doSomething() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + class TransactionalService { + + @OrderTx + fun setSomething(name: String) { + // ... + } + + @AccountTx + fun doSomething() { + // ... + } + } +---- + +In the preceding example, we used the syntax to define the transaction manager qualifier +and transactional labels, but we could also have included propagation behavior, +rollback rules, timeouts, and other features. + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc new file mode 100644 index 000000000000..a9fd8d8b2f8b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc @@ -0,0 +1,216 @@ +[[transaction-declarative-applying-more-than-just-tx-advice]] += Advising Transactional Operations + +Suppose you want to run both transactional operations and some basic profiling advice. +How do you effect this in the context of `<tx:annotation-driven/>`? + +When you invoke the `updateFoo(Foo)` method, you want to see the following actions: + +* The configured profiling aspect starts. +* The transactional advice runs. +* The method on the advised object runs. +* The transaction commits. +* The profiling aspect reports the exact duration of the whole transactional method invocation. + +NOTE: This chapter is not concerned with explaining AOP in any great detail (except as it +applies to transactions). See <<core.adoc#aop,AOP>> for detailed coverage of the AOP +configuration and AOP in general. + +The following code shows the simple profiling aspect discussed earlier: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package x.y; + + import org.aspectj.lang.ProceedingJoinPoint; + import org.springframework.util.StopWatch; + import org.springframework.core.Ordered; + + public class SimpleProfiler implements Ordered { + + private int order; + + // allows us to control the ordering of advice + public int getOrder() { + return this.order; + } + + public void setOrder(int order) { + this.order = order; + } + + // this method is the around advice + public Object profile(ProceedingJoinPoint call) throws Throwable { + Object returnValue; + StopWatch clock = new StopWatch(getClass().getName()); + try { + clock.start(call.toShortString()); + returnValue = call.proceed(); + } finally { + clock.stop(); + System.out.println(clock.prettyPrint()); + } + return returnValue; + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] +.Kotlin +---- + package x.y + + import org.aspectj.lang.ProceedingJoinPoint + import org.springframework.util.StopWatch + import org.springframework.core.Ordered + + class SimpleProfiler : Ordered { + + private var order: Int = 0 + + // allows us to control the ordering of advice + override fun getOrder(): Int { + return this.order + } + + fun setOrder(order: Int) { + this.order = order + } + + // this method is the around advice + fun profile(call: ProceedingJoinPoint): Any { + var returnValue: Any + val clock = StopWatch(javaClass.name) + try { + clock.start(call.toShortString()) + returnValue = call.proceed() + } finally { + clock.stop() + println(clock.prettyPrint()) + } + return returnValue + } + } +---- + +The ordering of advice +is controlled through the `Ordered` interface. For full details on advice ordering, see +<<core.adoc#aop-ataspectj-advice-ordering,Advice ordering>>. + +The following configuration creates a `fooService` bean that has profiling and +transactional aspects applied to it in the desired order: + +[source,xml,indent=0,subs="verbatim"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:aop="http://www.springframework.org/schema/aop" + xmlns:tx="http://www.springframework.org/schema/tx" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx + https://www.springframework.org/schema/tx/spring-tx.xsd + http://www.springframework.org/schema/aop + https://www.springframework.org/schema/aop/spring-aop.xsd"> + + <bean id="fooService" class="x.y.service.DefaultFooService"/> + + <!-- this is the aspect --> + <bean id="profiler" class="x.y.SimpleProfiler"> + <!-- run before the transactional advice (hence the lower order number) --> + <property name="order" value="1"/> + </bean> + + <tx:annotation-driven transaction-manager="txManager" order="200"/> + + <aop:config> + <!-- this advice runs around the transactional advice --> + <aop:aspect id="profilingAspect" ref="profiler"> + <aop:pointcut id="serviceMethodWithReturnValue" + expression="execution(!void x.y..*Service.*(..))"/> + <aop:around method="profile" pointcut-ref="serviceMethodWithReturnValue"/> + </aop:aspect> + </aop:config> + + <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close"> + <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/> + <property name="url" value="jdbc:oracle:thin:@rj-t42:1521:elvis"/> + <property name="username" value="scott"/> + <property name="password" value="tiger"/> + </bean> + + <bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager"> + <property name="dataSource" ref="dataSource"/> + </bean> + + </beans> +---- + +You can configure any number +of additional aspects in similar fashion. + +The following example creates the same setup as the previous two examples but uses the purely XML +declarative approach: + +[source,xml,indent=0,subs="verbatim"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:aop="http://www.springframework.org/schema/aop" + xmlns:tx="http://www.springframework.org/schema/tx" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx + https://www.springframework.org/schema/tx/spring-tx.xsd + http://www.springframework.org/schema/aop + https://www.springframework.org/schema/aop/spring-aop.xsd"> + + <bean id="fooService" class="x.y.service.DefaultFooService"/> + + <!-- the profiling advice --> + <bean id="profiler" class="x.y.SimpleProfiler"> + <!-- run before the transactional advice (hence the lower order number) --> + <property name="order" value="1"/> + </bean> + + <aop:config> + <aop:pointcut id="entryPointMethod" expression="execution(* x.y..*Service.*(..))"/> + <!-- runs after the profiling advice (cf. the order attribute) --> + + <aop:advisor advice-ref="txAdvice" pointcut-ref="entryPointMethod" order="2"/> + <!-- order value is higher than the profiling aspect --> + + <aop:aspect id="profilingAspect" ref="profiler"> + <aop:pointcut id="serviceMethodWithReturnValue" + expression="execution(!void x.y..*Service.*(..))"/> + <aop:around method="profile" pointcut-ref="serviceMethodWithReturnValue"/> + </aop:aspect> + + </aop:config> + + <tx:advice id="txAdvice" transaction-manager="txManager"> + <tx:attributes> + <tx:method name="get*" read-only="true"/> + <tx:method name="*"/> + </tx:attributes> + </tx:advice> + + <!-- other <bean/> definitions such as a DataSource and a TransactionManager here --> + + </beans> +---- + +The result of the preceding configuration is a `fooService` bean that has profiling and +transactional aspects applied to it in that order. If you want the profiling advice +to run after the transactional advice on the way in and before the +transactional advice on the way out, you can swap the value of the profiling +aspect bean's `order` property so that it is higher than the transactional advice's +order value. + +You can configure additional aspects in similar fashion. + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc new file mode 100644 index 000000000000..cddd2e292479 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc @@ -0,0 +1,60 @@ +[[transaction-declarative-aspectj]] += Using `@Transactional` with AspectJ + +You can also use the Spring Framework's `@Transactional` support outside of a Spring +container by means of an AspectJ aspect. To do so, first annotate your classes +(and optionally your classes' methods) with the `@Transactional` annotation, +and then link (weave) your application with the +`org.springframework.transaction.aspectj.AnnotationTransactionAspect` defined in the +`spring-aspects.jar` file. You must also configure the aspect with a transaction +manager. You can use the Spring Framework's IoC container to take care of +dependency-injecting the aspect. The simplest way to configure the transaction +management aspect is to use the `<tx:annotation-driven/>` element and specify the `mode` +attribute to `aspectj` as described in <<transaction-declarative-annotations>>. Because +we focus here on applications that run outside of a Spring container, we show +you how to do it programmatically. + +NOTE: Prior to continuing, you may want to read <<transaction-declarative-annotations>> and +<<core.adoc#aop, AOP>> respectively. + +The following example shows how to create a transaction manager and configure the +`AnnotationTransactionAspect` to use it: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // construct an appropriate transaction manager + DataSourceTransactionManager txManager = new DataSourceTransactionManager(getDataSource()); + + // configure the AnnotationTransactionAspect to use it; this must be done before executing any transactional methods + AnnotationTransactionAspect.aspectOf().setTransactionManager(txManager); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // construct an appropriate transaction manager + val txManager = DataSourceTransactionManager(getDataSource()) + + // configure the AnnotationTransactionAspect to use it; this must be done before executing any transactional methods + AnnotationTransactionAspect.aspectOf().transactionManager = txManager +---- + +NOTE: When you use this aspect, you must annotate the implementation class (or the methods +within that class or both), not the interface (if any) that the class implements. AspectJ +follows Java's rule that annotations on interfaces are not inherited. + +The `@Transactional` annotation on a class specifies the default transaction semantics +for the execution of any public method in the class. + +The `@Transactional` annotation on a method within the class overrides the default +transaction semantics given by the class annotation (if present). You can annotate any method, +regardless of visibility. + +To weave your applications with the `AnnotationTransactionAspect`, you must either build +your application with AspectJ (see the +https://www.eclipse.org/aspectj/doc/released/devguide/index.html[AspectJ Development +Guide]) or use load-time weaving. See <<core.adoc#aop-aj-ltw,Load-time weaving with +AspectJ in the Spring Framework>> for a discussion of load-time weaving with AspectJ. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/diff-tx.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/diff-tx.adoc new file mode 100644 index 000000000000..4881f06f5c98 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/diff-tx.adoc @@ -0,0 +1,114 @@ +[[transaction-declarative-diff-tx]] += Configuring Different Transactional Semantics for Different Beans + +Consider the scenario where you have a number of service layer objects, and you want to +apply a totally different transactional configuration to each of them. You can do so +by defining distinct `<aop:advisor/>` elements with differing `pointcut` and +`advice-ref` attribute values. + +As a point of comparison, first assume that all of your service layer classes are +defined in a root `x.y.service` package. To make all beans that are instances of classes +defined in that package (or in subpackages) and that have names ending in `Service` have +the default transactional configuration, you could write the following: + +[source,xml,indent=0,subs="verbatim"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:aop="http://www.springframework.org/schema/aop" + xmlns:tx="http://www.springframework.org/schema/tx" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx + https://www.springframework.org/schema/tx/spring-tx.xsd + http://www.springframework.org/schema/aop + https://www.springframework.org/schema/aop/spring-aop.xsd"> + + <aop:config> + + <aop:pointcut id="serviceOperation" + expression="execution(* x.y.service..*Service.*(..))"/> + + <aop:advisor pointcut-ref="serviceOperation" advice-ref="txAdvice"/> + + </aop:config> + + <!-- these two beans will be transactional... --> + <bean id="fooService" class="x.y.service.DefaultFooService"/> + <bean id="barService" class="x.y.service.extras.SimpleBarService"/> + + <!-- ... and these two beans won't --> + <bean id="anotherService" class="org.xyz.SomeService"/> <!-- (not in the right package) --> + <bean id="barManager" class="x.y.service.SimpleBarManager"/> <!-- (doesn't end in 'Service') --> + + <tx:advice id="txAdvice"> + <tx:attributes> + <tx:method name="get*" read-only="true"/> + <tx:method name="*"/> + </tx:attributes> + </tx:advice> + + <!-- other transaction infrastructure beans such as a TransactionManager omitted... --> + + </beans> +---- + +The following example shows how to configure two distinct beans with totally different +transactional settings: + +[source,xml,indent=0,subs="verbatim"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:aop="http://www.springframework.org/schema/aop" + xmlns:tx="http://www.springframework.org/schema/tx" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx + https://www.springframework.org/schema/tx/spring-tx.xsd + http://www.springframework.org/schema/aop + https://www.springframework.org/schema/aop/spring-aop.xsd"> + + <aop:config> + + <aop:pointcut id="defaultServiceOperation" + expression="execution(* x.y.service.*Service.*(..))"/> + + <aop:pointcut id="noTxServiceOperation" + expression="execution(* x.y.service.ddl.DefaultDdlManager.*(..))"/> + + <aop:advisor pointcut-ref="defaultServiceOperation" advice-ref="defaultTxAdvice"/> + + <aop:advisor pointcut-ref="noTxServiceOperation" advice-ref="noTxAdvice"/> + + </aop:config> + + <!-- this bean will be transactional (see the 'defaultServiceOperation' pointcut) --> + <bean id="fooService" class="x.y.service.DefaultFooService"/> + + <!-- this bean will also be transactional, but with totally different transactional settings --> + <bean id="anotherFooService" class="x.y.service.ddl.DefaultDdlManager"/> + + <tx:advice id="defaultTxAdvice"> + <tx:attributes> + <tx:method name="get*" read-only="true"/> + <tx:method name="*"/> + </tx:attributes> + </tx:advice> + + <tx:advice id="noTxAdvice"> + <tx:attributes> + <tx:method name="*" propagation="NEVER"/> + </tx:attributes> + </tx:advice> + + <!-- other transaction infrastructure beans such as a TransactionManager omitted... --> + + </beans> +---- + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc new file mode 100644 index 000000000000..167e109daf10 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc @@ -0,0 +1,399 @@ +[[transaction-declarative-first-example]] += Example of Declarative Transaction Implementation + +Consider the following interface and its attendant implementation. This example uses +`Foo` and `Bar` classes as placeholders so that you can concentrate on the transaction +usage without focusing on a particular domain model. For the purposes of this example, +the fact that the `DefaultFooService` class throws `UnsupportedOperationException` +instances in the body of each implemented method is good. That behavior lets you see +transactions being created and then rolled back in response to the +`UnsupportedOperationException` instance. The following listing shows the `FooService` +interface: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + // the service interface that we want to make transactional + + package x.y.service; + + public interface FooService { + + Foo getFoo(String fooName); + + Foo getFoo(String fooName, String barName); + + void insertFoo(Foo foo); + + void updateFoo(Foo foo); + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + // the service interface that we want to make transactional + + package x.y.service + + interface FooService { + + fun getFoo(fooName: String): Foo + + fun getFoo(fooName: String, barName: String): Foo + + fun insertFoo(foo: Foo) + + fun updateFoo(foo: Foo) + } +---- + +The following example shows an implementation of the preceding interface: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package x.y.service; + + public class DefaultFooService implements FooService { + + @Override + public Foo getFoo(String fooName) { + // ... + } + + @Override + public Foo getFoo(String fooName, String barName) { + // ... + } + + @Override + public void insertFoo(Foo foo) { + // ... + } + + @Override + public void updateFoo(Foo foo) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package x.y.service + + class DefaultFooService : FooService { + + override fun getFoo(fooName: String): Foo { + // ... + } + + override fun getFoo(fooName: String, barName: String): Foo { + // ... + } + + override fun insertFoo(foo: Foo) { + // ... + } + + override fun updateFoo(foo: Foo) { + // ... + } + } +---- + +Assume that the first two methods of the `FooService` interface, `getFoo(String)` and +`getFoo(String, String)`, must run in the context of a transaction with read-only +semantics and that the other methods, `insertFoo(Foo)` and `updateFoo(Foo)`, must +run in the context of a transaction with read-write semantics. The following +configuration is explained in detail in the next few paragraphs: + +[source,xml,indent=0,subs="verbatim"] +---- + <!-- from the file 'context.xml' --> + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:aop="http://www.springframework.org/schema/aop" + xmlns:tx="http://www.springframework.org/schema/tx" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx + https://www.springframework.org/schema/tx/spring-tx.xsd + http://www.springframework.org/schema/aop + https://www.springframework.org/schema/aop/spring-aop.xsd"> + + <!-- this is the service object that we want to make transactional --> + <bean id="fooService" class="x.y.service.DefaultFooService"/> + + <!-- the transactional advice (what 'happens'; see the <aop:advisor/> bean below) --> + <tx:advice id="txAdvice" transaction-manager="txManager"> + <!-- the transactional semantics... --> + <tx:attributes> + <!-- all methods starting with 'get' are read-only --> + <tx:method name="get*" read-only="true"/> + <!-- other methods use the default transaction settings (see below) --> + <tx:method name="*"/> + </tx:attributes> + </tx:advice> + + <!-- ensure that the above transactional advice runs for any execution + of an operation defined by the FooService interface --> + <aop:config> + <aop:pointcut id="fooServiceOperation" expression="execution(* x.y.service.FooService.*(..))"/> + <aop:advisor advice-ref="txAdvice" pointcut-ref="fooServiceOperation"/> + </aop:config> + + <!-- don't forget the DataSource --> + <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close"> + <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/> + <property name="url" value="jdbc:oracle:thin:@rj-t42:1521:elvis"/> + <property name="username" value="scott"/> + <property name="password" value="tiger"/> + </bean> + + <!-- similarly, don't forget the TransactionManager --> + <bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager"> + <property name="dataSource" ref="dataSource"/> + </bean> + + <!-- other <bean/> definitions here --> + + </beans> +---- + +Examine the preceding configuration. It assumes that you want to make a service object, +the `fooService` bean, transactional. The transaction semantics to apply are encapsulated +in the `<tx:advice/>` definition. The `<tx:advice/>` definition reads as "all methods +starting with `get` are to run in the context of a read-only transaction, and all +other methods are to run with the default transaction semantics". The +`transaction-manager` attribute of the `<tx:advice/>` tag is set to the name of the +`TransactionManager` bean that is going to drive the transactions (in this case, the +`txManager` bean). + +TIP: You can omit the `transaction-manager` attribute in the transactional advice +(`<tx:advice/>`) if the bean name of the `TransactionManager` that you want to +wire in has the name `transactionManager`. If the `TransactionManager` bean that +you want to wire in has any other name, you must use the `transaction-manager` +attribute explicitly, as in the preceding example. + +The `<aop:config/>` definition ensures that the transactional advice defined by the +`txAdvice` bean runs at the appropriate points in the program. First, you define a +pointcut that matches the execution of any operation defined in the `FooService` interface +(`fooServiceOperation`). Then you associate the pointcut with the `txAdvice` by using an +advisor. The result indicates that, at the execution of a `fooServiceOperation`, +the advice defined by `txAdvice` is run. + +The expression defined within the `<aop:pointcut/>` element is an AspectJ pointcut +expression. See <<core.adoc#aop, the AOP section>> for more details on pointcut +expressions in Spring. + +A common requirement is to make an entire service layer transactional. The best way to +do this is to change the pointcut expression to match any operation in your +service layer. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim"] +---- + <aop:config> + <aop:pointcut id="fooServiceMethods" expression="execution(* x.y.service.*.*(..))"/> + <aop:advisor advice-ref="txAdvice" pointcut-ref="fooServiceMethods"/> + </aop:config> +---- + +NOTE: In the preceding example, it is assumed that all your service interfaces are defined +in the `x.y.service` package. See <<core.adoc#aop, the AOP section>> for more details. + +Now that we have analyzed the configuration, you may be asking yourself, +"What does all this configuration actually do?" + +The configuration shown earlier is used to create a transactional proxy around the object +that is created from the `fooService` bean definition. The proxy is configured with +the transactional advice so that, when an appropriate method is invoked on the proxy, +a transaction is started, suspended, marked as read-only, and so on, depending on the +transaction configuration associated with that method. Consider the following program +that test drives the configuration shown earlier: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public final class Boot { + + public static void main(final String[] args) throws Exception { + ApplicationContext ctx = new ClassPathXmlApplicationContext("context.xml"); + FooService fooService = ctx.getBean(FooService.class); + fooService.insertFoo(new Foo()); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.beans.factory.getBean + + fun main() { + val ctx = ClassPathXmlApplicationContext("context.xml") + val fooService = ctx.getBean<FooService>("fooService") + fooService.insertFoo(Foo()) + } +---- + +The output from running the preceding program should resemble the following (the Log4J +output and the stack trace from the `UnsupportedOperationException` thrown by the +`insertFoo(..)` method of the `DefaultFooService` class have been truncated for clarity): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <!-- the Spring container is starting up... --> + [AspectJInvocationContextExposingAdvisorAutoProxyCreator] - Creating implicit proxy for bean 'fooService' with 0 common interceptors and 1 specific interceptors + + <!-- the DefaultFooService is actually proxied --> + [JdkDynamicAopProxy] - Creating JDK dynamic proxy for [x.y.service.DefaultFooService] + + <!-- ... the insertFoo(..) method is now being invoked on the proxy --> + [TransactionInterceptor] - Getting transaction for x.y.service.FooService.insertFoo + + <!-- the transactional advice kicks in here... --> + [DataSourceTransactionManager] - Creating new transaction with name [x.y.service.FooService.insertFoo] + [DataSourceTransactionManager] - Acquired Connection [org.apache.commons.dbcp.PoolableConnection@a53de4] for JDBC transaction + + <!-- the insertFoo(..) method from DefaultFooService throws an exception... --> + [RuleBasedTransactionAttribute] - Applying rules to determine whether transaction should rollback on java.lang.UnsupportedOperationException + [TransactionInterceptor] - Invoking rollback for transaction on x.y.service.FooService.insertFoo due to throwable [java.lang.UnsupportedOperationException] + + <!-- and the transaction is rolled back (by default, RuntimeException instances cause rollback) --> + [DataSourceTransactionManager] - Rolling back JDBC transaction on Connection [org.apache.commons.dbcp.PoolableConnection@a53de4] + [DataSourceTransactionManager] - Releasing JDBC Connection after transaction + [DataSourceUtils] - Returning JDBC Connection to DataSource + + Exception in thread "main" java.lang.UnsupportedOperationException at x.y.service.DefaultFooService.insertFoo(DefaultFooService.java:14) + <!-- AOP infrastructure stack trace elements removed for clarity --> + at $Proxy0.insertFoo(Unknown Source) + at Boot.main(Boot.java:11) +---- + +To use reactive transaction management the code has to use reactive types. + +NOTE: Spring Framework uses the `ReactiveAdapterRegistry` to determine whether a method +return type is reactive. + +The following listing shows a modified version of the previously used `FooService`, but +this time the code uses reactive types: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + // the reactive service interface that we want to make transactional + + package x.y.service; + + public interface FooService { + + Flux<Foo> getFoo(String fooName); + + Publisher<Foo> getFoo(String fooName, String barName); + + Mono<Void> insertFoo(Foo foo); + + Mono<Void> updateFoo(Foo foo); + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + // the reactive service interface that we want to make transactional + + package x.y.service + + interface FooService { + + fun getFoo(fooName: String): Flow<Foo> + + fun getFoo(fooName: String, barName: String): Publisher<Foo> + + fun insertFoo(foo: Foo) : Mono<Void> + + fun updateFoo(foo: Foo) : Mono<Void> + } +---- + +The following example shows an implementation of the preceding interface: + +[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] +.Java +---- + package x.y.service; + + public class DefaultFooService implements FooService { + + @Override + public Flux<Foo> getFoo(String fooName) { + // ... + } + + @Override + public Publisher<Foo> getFoo(String fooName, String barName) { + // ... + } + + @Override + public Mono<Void> insertFoo(Foo foo) { + // ... + } + + @Override + public Mono<Void> updateFoo(Foo foo) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] +.Kotlin +---- + package x.y.service + + class DefaultFooService : FooService { + + override fun getFoo(fooName: String): Flow<Foo> { + // ... + } + + override fun getFoo(fooName: String, barName: String): Publisher<Foo> { + // ... + } + + override fun insertFoo(foo: Foo): Mono<Void> { + // ... + } + + override fun updateFoo(foo: Foo): Mono<Void> { + // ... + } + } +---- + +Imperative and reactive transaction management share the same semantics for transaction +boundary and transaction attribute definitions. The main difference between imperative +and reactive transactions is the deferred nature of the latter. `TransactionInterceptor` +decorates the returned reactive type with a transactional operator to begin and clean up +the transaction. Therefore, calling a transactional reactive method defers the actual +transaction management to a subscription type that activates processing of the reactive +type. + +Another aspect of reactive transaction management relates to data escaping which is a +natural consequence of the programming model. + +Method return values of imperative transactions are returned from transactional methods +upon successful termination of a method so that partially computed results do not escape +the method closure. + +Reactive transaction methods return a reactive wrapper type which represents a +computation sequence along with a promise to begin and complete the computation. + +A `Publisher` can emit data while a transaction is ongoing but not necessarily completed. +Therefore, methods that depend upon successful completion of an entire transaction need +to ensure completion and buffer results in the calling code. + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc new file mode 100644 index 000000000000..4391a8ef4a95 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc @@ -0,0 +1,170 @@ +[[transaction-declarative-rolling-back]] += Rolling Back a Declarative Transaction + +The previous section outlined the basics of how to specify transactional settings for +classes, typically service layer classes, declaratively in your application. This section +describes how you can control the rollback of transactions in a simple, declarative +fashion in XML configuration. For details on controlling rollback semantics declaratively +with the `@Transactional` annotation, see +<<transaction-declarative-attransactional-settings>>. + +The recommended way to indicate to the Spring Framework's transaction infrastructure +that a transaction's work is to be rolled back is to throw an `Exception` from code that +is currently executing in the context of a transaction. The Spring Framework's +transaction infrastructure code catches any unhandled `Exception` as it bubbles up +the call stack and makes a determination whether to mark the transaction for rollback. + +In its default configuration, the Spring Framework's transaction infrastructure code +marks a transaction for rollback only in the case of runtime, unchecked exceptions. +That is, when the thrown exception is an instance or subclass of `RuntimeException`. +(`Error` instances also, by default, result in a rollback). + +As of Spring Framework 5.2, the default configuration also provides support for +Vavr's `Try` method to trigger transaction rollbacks when it returns a 'Failure'. +This allows you to handle functional-style errors using Try and have the transaction +automatically rolled back in case of a failure. For more information on Vavr's Try, +refer to the [official Vavr documentation](https://www.vavr.io/vavr-docs/#_try). + +Here's an example of how to use Vavr's Try with a transactional method: +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Transactional + public Try<String> myTransactionalMethod() { + // If myDataAccessOperation throws an exception, it will be caught by the + // Try instance created with Try.of() and wrapped inside the Failure class + // which can be checked using the isFailure() method on the Try instance. + return Try.of(delegate::myDataAccessOperation); + } +---- + +Checked exceptions that are thrown from a transactional method do not result in a rollback +in the default configuration. You can configure exactly which `Exception` types mark a +transaction for rollback, including checked exceptions by specifying _rollback rules_. + +.Rollback rules +[[transaction-declarative-rollback-rules]] +[NOTE] +==== +Rollback rules determine if a transaction should be rolled back when a given exception is +thrown, and the rules are based on exception types or exception patterns. + +Rollback rules may be configured in XML via the `rollback-for` and `no-rollback-for` +attributes, which allow rules to be defined as patterns. When using +<<transaction-declarative-attransactional-settings,`@Transactional`>>, rollback rules may +be configured via the `rollbackFor`/`noRollbackFor` and +`rollbackForClassName`/`noRollbackForClassName` attributes, which allow rules to be +defined based on exception types or patterns, respectively. + +When a rollback rule is defined with an exception type, that type will be used to match +against the type of a thrown exception and its super types, providing type safety and +avoiding any unintentional matches that may occur when using a pattern. For example, a +value of `jakarta.servlet.ServletException.class` will only match thrown exceptions of +type `jakarta.servlet.ServletException` and its subclasses. + +When a rollback rule is defined with an exception pattern, the pattern can be a fully +qualified class name or a substring of a fully qualified class name for an exception type +(which must be a subclass of `Throwable`), with no wildcard support at present. For +example, a value of `"jakarta.servlet.ServletException"` or `"ServletException"` will +match `jakarta.servlet.ServletException` and its subclasses. + +[WARNING] +===== +You must carefully consider how specific a pattern is and whether to include package +information (which isn't mandatory). For example, `"Exception"` will match nearly +anything and will probably hide other rules. `"java.lang.Exception"` would be correct if +`"Exception"` were meant to define a rule for all checked exceptions. With more unique +exception names such as `"BaseBusinessException"` there is likely no need to use the +fully qualified class name for the exception pattern. + +Furthermore, pattern-based rollback rules may result in unintentional matches for +similarly named exceptions and nested classes. This is due to the fact that a thrown +exception is considered to be a match for a given pattern-based rollback rule if the name +of the thrown exception contains the exception pattern configured for the rollback rule. +For example, given a rule configured to match on `"com.example.CustomException"`, that +rule will match against an exception named `com.example.CustomExceptionV2` (an exception +in the same package as `CustomException` but with an additional suffix) or an exception +named `com.example.CustomException$AnotherException` (an exception declared as a nested +class in `CustomException`). +===== +==== + +The following XML snippet demonstrates how to configure rollback for a checked, +application-specific `Exception` type by supplying an _exception pattern_ via the +`rollback-for` attribute: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <tx:advice id="txAdvice" transaction-manager="txManager"> + <tx:attributes> + <tx:method name="get*" read-only="true" rollback-for="NoProductInStockException"/> + <tx:method name="*"/> + </tx:attributes> + </tx:advice> +---- + +If you do not want a transaction rolled back when an exception is thrown, you can also +specify 'no rollback' rules. The following example tells the Spring Framework's +transaction infrastructure to commit the attendant transaction even in the face of an +unhandled `InstrumentNotFoundException`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <tx:advice id="txAdvice"> + <tx:attributes> + <tx:method name="updateStock" no-rollback-for="InstrumentNotFoundException"/> + <tx:method name="*"/> + </tx:attributes> + </tx:advice> +---- + +When the Spring Framework's transaction infrastructure catches an exception and consults +the configured rollback rules to determine whether to mark the transaction for rollback, +the strongest matching rule wins. So, in the case of the following configuration, any +exception other than an `InstrumentNotFoundException` results in a rollback of the +attendant transaction: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <tx:advice id="txAdvice"> + <tx:attributes> + <tx:method name="*" rollback-for="Throwable" no-rollback-for="InstrumentNotFoundException"/> + </tx:attributes> + </tx:advice> +---- + +You can also indicate a required rollback programmatically. Although simple, this process +is quite invasive and tightly couples your code to the Spring Framework's transaction +infrastructure. The following example shows how to programmatically indicate a required +rollback: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public void resolvePosition() { + try { + // some business logic... + } catch (NoProductInStockException ex) { + // trigger rollback programmatically + TransactionAspectSupport.currentTransactionStatus().setRollbackOnly(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun resolvePosition() { + try { + // some business logic... + } catch (ex: NoProductInStockException) { + // trigger rollback programmatically + TransactionAspectSupport.currentTransactionStatus().setRollbackOnly(); + } + } +---- + +You are strongly encouraged to use the declarative approach to rollback, if at all +possible. Programmatic rollback is available should you absolutely need it, but its +usage flies in the face of achieving a clean POJO-based architecture. + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc new file mode 100644 index 000000000000..e3372fc1edc5 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc @@ -0,0 +1,47 @@ +[[tx-decl-explained]] += Understanding the Spring Framework's Declarative Transaction Implementation + +It is not sufficient merely to tell you to annotate your classes with the +`@Transactional` annotation, add `@EnableTransactionManagement` to your configuration, +and expect you to understand how it all works. To provide a deeper understanding, this +section explains the inner workings of the Spring Framework's declarative transaction +infrastructure in the context of transaction-related issues. + +The most important concepts to grasp with regard to the Spring Framework's declarative +transaction support are that this support is enabled +<<core.adoc#aop-understanding-aop-proxies, via AOP proxies>> and that the transactional +advice is driven by metadata (currently XML- or annotation-based). The combination of AOP +with transactional metadata yields an AOP proxy that uses a `TransactionInterceptor` in +conjunction with an appropriate `TransactionManager` implementation to drive transactions +around method invocations. + +NOTE: Spring AOP is covered in <<core.adoc#aop, the AOP section>>. + +Spring Framework's `TransactionInterceptor` provides transaction management for +imperative and reactive programming models. The interceptor detects the desired flavor of +transaction management by inspecting the method return type. Methods returning a reactive +type such as `Publisher` or Kotlin `Flow` (or a subtype of those) qualify for reactive +transaction management. All other return types including `void` use the code path for +imperative transaction management. + +Transaction management flavors impact which transaction manager is required. Imperative +transactions require a `PlatformTransactionManager`, while reactive transactions use +`ReactiveTransactionManager` implementations. + +[NOTE] +==== +`@Transactional` commonly works with thread-bound transactions managed by +`PlatformTransactionManager`, exposing a transaction to all data access operations within +the current execution thread. Note: This does _not_ propagate to newly started threads +within the method. + +A reactive transaction managed by `ReactiveTransactionManager` uses the Reactor context +instead of thread-local attributes. As a consequence, all participating data access +operations need to execute within the same Reactor context in the same reactive pipeline. +==== + +The following image shows a conceptual view of calling a method on a transactional proxy: + +image::tx.png[] + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-propagation.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-propagation.adoc new file mode 100644 index 000000000000..2c29cf7a5055 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-propagation.adoc @@ -0,0 +1,72 @@ +[[tx-propagation]] += Transaction Propagation + +This section describes some semantics of transaction propagation in Spring. Note +that this section is not a proper introduction to transaction propagation. Rather, it +details some of the semantics regarding transaction propagation in Spring. + +In Spring-managed transactions, be aware of the difference between physical and +logical transactions, and how the propagation setting applies to this difference. + +[[tx-propagation-required]] +== Understanding `PROPAGATION_REQUIRED` + +image::tx_prop_required.png[] + +`PROPAGATION_REQUIRED` enforces a physical transaction, either locally for the current +scope if no transaction exists yet or participating in an existing 'outer' transaction +defined for a larger scope. This is a fine default in common call stack arrangements +within the same thread (for example, a service facade that delegates to several repository methods +where all the underlying resources have to participate in the service-level transaction). + +NOTE: By default, a participating transaction joins the characteristics of the outer scope, +silently ignoring the local isolation level, timeout value, or read-only flag (if any). +Consider switching the `validateExistingTransactions` flag to `true` on your transaction +manager if you want isolation level declarations to be rejected when participating in +an existing transaction with a different isolation level. This non-lenient mode also +rejects read-only mismatches (that is, an inner read-write transaction that tries to participate +in a read-only outer scope). + +When the propagation setting is `PROPAGATION_REQUIRED`, a logical transaction scope +is created for each method upon which the setting is applied. Each such logical +transaction scope can determine rollback-only status individually, with an outer +transaction scope being logically independent from the inner transaction scope. +In the case of standard `PROPAGATION_REQUIRED` behavior, all these scopes are +mapped to the same physical transaction. So a rollback-only marker set in the inner +transaction scope does affect the outer transaction's chance to actually commit. + +However, in the case where an inner transaction scope sets the rollback-only marker, the +outer transaction has not decided on the rollback itself, so the rollback (silently +triggered by the inner transaction scope) is unexpected. A corresponding +`UnexpectedRollbackException` is thrown at that point. This is expected behavior so +that the caller of a transaction can never be misled to assume that a commit was +performed when it really was not. So, if an inner transaction (of which the outer caller +is not aware) silently marks a transaction as rollback-only, the outer caller still +calls commit. The outer caller needs to receive an `UnexpectedRollbackException` to +indicate clearly that a rollback was performed instead. + +[[tx-propagation-requires_new]] +== Understanding `PROPAGATION_REQUIRES_NEW` + +image::tx_prop_requires_new.png[] + +`PROPAGATION_REQUIRES_NEW`, in contrast to `PROPAGATION_REQUIRED`, always uses an +independent physical transaction for each affected transaction scope, never +participating in an existing transaction for an outer scope. In such an arrangement, +the underlying resource transactions are different and, hence, can commit or roll back +independently, with an outer transaction not affected by an inner transaction's rollback +status and with an inner transaction's locks released immediately after its completion. +Such an independent inner transaction can also declare its own isolation level, timeout, +and read-only settings and not inherit an outer transaction's characteristics. + +[[tx-propagation-nested]] +== Understanding `PROPAGATION_NESTED` + +`PROPAGATION_NESTED` uses a single physical transaction with multiple savepoints +that it can roll back to. Such partial rollbacks let an inner transaction scope +trigger a rollback for its scope, with the outer transaction being able to continue +the physical transaction despite some operations having been rolled back. This setting +is typically mapped onto JDBC savepoints, so it works only with JDBC resource +transactions. See Spring's {api-spring-framework}/jdbc/datasource/DataSourceTransactionManager.html[`DataSourceTransactionManager`]. + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc new file mode 100644 index 000000000000..cac80d805b42 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc @@ -0,0 +1,63 @@ +[[transaction-declarative-txadvice-settings]] += <tx:advice/> Settings + +This section summarizes the various transactional settings that you can specify by using +the `<tx:advice/>` tag. The default `<tx:advice/>` settings are: + +* The <<tx-propagation, propagation setting>> is `REQUIRED.` +* The isolation level is `DEFAULT.` +* The transaction is read-write. +* The transaction timeout defaults to the default timeout of the underlying transaction + system or none if timeouts are not supported. +* Any `RuntimeException` triggers rollback, and any checked `Exception` does not. + +You can change these default settings. The following table summarizes the various attributes of the `<tx:method/>` tags +that are nested within `<tx:advice/>` and `<tx:attributes/>` tags: + +[[tx-method-settings]] +.<tx:method/> settings +|=== +| Attribute| Required?| Default| Description + +| `name` +| Yes +| +| Method names with which the transaction attributes are to be associated. The + wildcard ({asterisk}) character can be used to associate the same transaction attribute + settings with a number of methods (for example, `get*`, `handle*`, `on*Event`, and so + forth). + +| `propagation` +| No +| `REQUIRED` +| Transaction propagation behavior. + +| `isolation` +| No +| `DEFAULT` +| Transaction isolation level. Only applicable to propagation settings of `REQUIRED` or `REQUIRES_NEW`. + +| `timeout` +| No +| -1 +| Transaction timeout (seconds). Only applicable to propagation `REQUIRED` or `REQUIRES_NEW`. + +| `read-only` +| No +| false +| Read-write versus read-only transaction. Applies only to `REQUIRED` or `REQUIRES_NEW`. + +| `rollback-for` +| No +| +| Comma-delimited list of `Exception` instances that trigger rollback. For example, + `com.foo.MyBusinessException,ServletException`. + +| `no-rollback-for` +| No +| +| Comma-delimited list of `Exception` instances that do not trigger rollback. For example, + `com.foo.MyBusinessException,ServletException`. +|=== + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/event.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/event.adoc new file mode 100644 index 000000000000..7bdbad98b330 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/event.adoc @@ -0,0 +1,61 @@ +[[transaction-event]] += Transaction-bound Events + +As of Spring 4.2, the listener of an event can be bound to a phase of the transaction. +The typical example is to handle the event when the transaction has completed successfully. +Doing so lets events be used with more flexibility when the outcome of the current +transaction actually matters to the listener. + +You can register a regular event listener by using the `@EventListener` annotation. +If you need to bind it to the transaction, use `@TransactionalEventListener`. +When you do so, the listener is bound to the commit phase of the transaction by default. + +The next example shows this concept. Assume that a component publishes an order-created +event and that we want to define a listener that should only handle that event once the +transaction in which it has been published has committed successfully. The following +example sets up such an event listener: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + public class MyComponent { + + @TransactionalEventListener + public void handleOrderCreatedEvent(CreationEvent<Order> creationEvent) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + class MyComponent { + + @TransactionalEventListener + fun handleOrderCreatedEvent(creationEvent: CreationEvent<Order>) { + // ... + } + } +---- + +The `@TransactionalEventListener` annotation exposes a `phase` attribute that lets you +customize the phase of the transaction to which the listener should be bound. +The valid phases are `BEFORE_COMMIT`, `AFTER_COMMIT` (default), `AFTER_ROLLBACK`, as well as +`AFTER_COMPLETION` which aggregates the transaction completion (be it a commit or a rollback). + +If no transaction is running, the listener is not invoked at all, since we cannot honor the +required semantics. You can, however, override that behavior by setting the `fallbackExecution` +attribute of the annotation to `true`. + +[NOTE] +==== +`@TransactionalEventListener` only works with thread-bound transactions managed by +`PlatformTransactionManager`. A reactive transaction managed by `ReactiveTransactionManager` +uses the Reactor context instead of thread-local attributes, so from the perspective of +an event listener, there is no compatible active transaction that it can participate in. +==== + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/motivation.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/motivation.adoc new file mode 100644 index 000000000000..60bf567d9c41 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/motivation.adoc @@ -0,0 +1,90 @@ +[[transaction-motivation]] += Advantages of the Spring Framework's Transaction Support Model + +Traditionally, EE application developers have had two choices for transaction management: +global or local transactions, both of which have profound limitations. Global +and local transaction management is reviewed in the next two sections, followed by a +discussion of how the Spring Framework's transaction management support addresses the +limitations of the global and local transaction models. + + +[[transaction-global]] +== Global Transactions + +Global transactions let you work with multiple transactional resources, typically +relational databases and message queues. The application server manages global +transactions through the JTA, which is a cumbersome API (partly due to its +exception model). Furthermore, a JTA `UserTransaction` normally needs to be sourced from +JNDI, meaning that you also need to use JNDI in order to use JTA. The use +of global transactions limits any potential reuse of application code, as JTA is +normally only available in an application server environment. + +Previously, the preferred way to use global transactions was through EJB CMT +(Container Managed Transaction). CMT is a form of declarative transaction +management (as distinguished from programmatic transaction management). EJB CMT +removes the need for transaction-related JNDI lookups, although the use of EJB +itself necessitates the use of JNDI. It removes most but not all of the need to write +Java code to control transactions. The significant downside is that CMT is tied to JTA +and an application server environment. Also, it is only available if one chooses to +implement business logic in EJBs (or at least behind a transactional EJB facade). The +negatives of EJB in general are so great that this is not an attractive proposition, +especially in the face of compelling alternatives for declarative transaction management. + + +[[transaction-local]] +== Local Transactions + +Local transactions are resource-specific, such as a transaction associated with a JDBC +connection. Local transactions may be easier to use but have a significant disadvantage: +They cannot work across multiple transactional resources. For example, code that manages +transactions by using a JDBC connection cannot run within a global JTA transaction. Because +the application server is not involved in transaction management, it cannot help ensure +correctness across multiple resources. (It is worth noting that most applications use a +single transaction resource.) Another downside is that local transactions are invasive +to the programming model. + + +[[transaction-programming-model]] +== Spring Framework's Consistent Programming Model + +Spring resolves the disadvantages of global and local transactions. It lets +application developers use a consistent programming model in any environment. +You write your code once, and it can benefit from different transaction management +strategies in different environments. The Spring Framework provides both declarative and +programmatic transaction management. Most users prefer declarative transaction +management, which we recommend in most cases. + +With programmatic transaction management, developers work with the Spring Framework +transaction abstraction, which can run over any underlying transaction infrastructure. +With the preferred declarative model, developers typically write little or no code +related to transaction management and, hence, do not depend on the Spring Framework +transaction API or any other transaction API. + +.Do you need an application server for transaction management? +**** +The Spring Framework's transaction management support changes traditional rules as to +when an enterprise Java application requires an application server. + +In particular, you do not need an application server purely for declarative transactions +through EJBs. In fact, even if your application server has powerful JTA capabilities, +you may decide that the Spring Framework's declarative transactions offer more power and +a more productive programming model than EJB CMT. + +Typically, you need an application server's JTA capability only if your application needs +to handle transactions across multiple resources, which is not a requirement for many +applications. Many high-end applications use a single, highly scalable database (such as +Oracle RAC) instead. Stand-alone transaction managers (such as +https://www.atomikos.com/[Atomikos Transactions]) +are other options. Of course, you may need other application server capabilities, such as +Java Message Service (JMS) and Jakarta EE Connector Architecture (JCA). + +The Spring Framework gives you the choice of when to scale your application to a fully +loaded application server. Gone are the days when the only alternative to using EJB +CMT or JTA was to write code with local transactions (such as those on JDBC connections) +and face a hefty rework if you need that code to run within global, container-managed +transactions. With the Spring Framework, only some of the bean definitions in your +configuration file need to change (rather than your code). +**** + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc new file mode 100644 index 000000000000..60a51310fabb --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc @@ -0,0 +1,442 @@ +[[transaction-programmatic]] += Programmatic Transaction Management + +The Spring Framework provides two means of programmatic transaction management, by using: + +* The `TransactionTemplate` or `TransactionalOperator`. +* A `TransactionManager` implementation directly. + +The Spring team generally recommends the `TransactionTemplate` for programmatic +transaction management in imperative flows and `TransactionalOperator` for reactive code. +The second approach is similar to using the JTA `UserTransaction` API, although exception +handling is less cumbersome. + + +[[tx-prog-template]] +== Using the `TransactionTemplate` + +The `TransactionTemplate` adopts the same approach as other Spring templates, such as +the `JdbcTemplate`. It uses a callback approach (to free application code from having to +do the boilerplate acquisition and release transactional resources) and results in +code that is intention driven, in that your code focuses solely on what +you want to do. + +NOTE: As the examples that follow show, using the `TransactionTemplate` absolutely +couples you to Spring's transaction infrastructure and APIs. Whether or not programmatic +transaction management is suitable for your development needs is a decision that you +have to make yourself. + +Application code that must run in a transactional context and that explicitly uses the +`TransactionTemplate` resembles the next example. You, as an application +developer, can write a `TransactionCallback` implementation (typically expressed as an +anonymous inner class) that contains the code that you need to run in the context of +a transaction. You can then pass an instance of your custom `TransactionCallback` to the +`execute(..)` method exposed on the `TransactionTemplate`. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleService implements Service { + + // single TransactionTemplate shared amongst all methods in this instance + private final TransactionTemplate transactionTemplate; + + // use constructor-injection to supply the PlatformTransactionManager + public SimpleService(PlatformTransactionManager transactionManager) { + this.transactionTemplate = new TransactionTemplate(transactionManager); + } + + public Object someServiceMethod() { + return transactionTemplate.execute(new TransactionCallback() { + // the code in this method runs in a transactional context + public Object doInTransaction(TransactionStatus status) { + updateOperation1(); + return resultOfUpdateOperation2(); + } + }); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // use constructor-injection to supply the PlatformTransactionManager + class SimpleService(transactionManager: PlatformTransactionManager) : Service { + + // single TransactionTemplate shared amongst all methods in this instance + private val transactionTemplate = TransactionTemplate(transactionManager) + + fun someServiceMethod() = transactionTemplate.execute<Any?> { + updateOperation1() + resultOfUpdateOperation2() + } + } +---- + + +If there is no return value, you can use the convenient `TransactionCallbackWithoutResult` class +with an anonymous class, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + transactionTemplate.execute(new TransactionCallbackWithoutResult() { + protected void doInTransactionWithoutResult(TransactionStatus status) { + updateOperation1(); + updateOperation2(); + } + }); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + transactionTemplate.execute(object : TransactionCallbackWithoutResult() { + override fun doInTransactionWithoutResult(status: TransactionStatus) { + updateOperation1() + updateOperation2() + } + }) +---- + + +Code within the callback can roll the transaction back by calling the +`setRollbackOnly()` method on the supplied `TransactionStatus` object, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + transactionTemplate.execute(new TransactionCallbackWithoutResult() { + + protected void doInTransactionWithoutResult(TransactionStatus status) { + try { + updateOperation1(); + updateOperation2(); + } catch (SomeBusinessException ex) { + status.setRollbackOnly(); + } + } + }); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + transactionTemplate.execute(object : TransactionCallbackWithoutResult() { + + override fun doInTransactionWithoutResult(status: TransactionStatus) { + try { + updateOperation1() + updateOperation2() + } catch (ex: SomeBusinessException) { + status.setRollbackOnly() + } + } + }) +---- + +[[tx-prog-template-settings]] +=== Specifying Transaction Settings + +You can specify transaction settings (such as the propagation mode, the isolation level, +the timeout, and so forth) on the `TransactionTemplate` either programmatically or in +configuration. By default, `TransactionTemplate` instances have the +<<transaction-declarative-txadvice-settings,default transactional settings>>. The +following example shows the programmatic customization of the transactional settings for +a specific `TransactionTemplate:` + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleService implements Service { + + private final TransactionTemplate transactionTemplate; + + public SimpleService(PlatformTransactionManager transactionManager) { + this.transactionTemplate = new TransactionTemplate(transactionManager); + + // the transaction settings can be set here explicitly if so desired + this.transactionTemplate.setIsolationLevel(TransactionDefinition.ISOLATION_READ_UNCOMMITTED); + this.transactionTemplate.setTimeout(30); // 30 seconds + // and so forth... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SimpleService(transactionManager: PlatformTransactionManager) : Service { + + private val transactionTemplate = TransactionTemplate(transactionManager).apply { + // the transaction settings can be set here explicitly if so desired + isolationLevel = TransactionDefinition.ISOLATION_READ_UNCOMMITTED + timeout = 30 // 30 seconds + // and so forth... + } + } +---- + +The following example defines a `TransactionTemplate` with some custom transactional +settings by using Spring XML configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="sharedTransactionTemplate" + class="org.springframework.transaction.support.TransactionTemplate"> + <property name="isolationLevelName" value="ISOLATION_READ_UNCOMMITTED"/> + <property name="timeout" value="30"/> + </bean> +---- + +You can then inject the `sharedTransactionTemplate` +into as many services as are required. + +Finally, instances of the `TransactionTemplate` class are thread-safe, in that instances +do not maintain any conversational state. `TransactionTemplate` instances do, however, +maintain configuration state. So, while a number of classes may share a single instance +of a `TransactionTemplate`, if a class needs to use a `TransactionTemplate` with +different settings (for example, a different isolation level), you need to create +two distinct `TransactionTemplate` instances. + +[[tx-prog-operator]] +== Using the `TransactionalOperator` + +The `TransactionalOperator` follows an operator design that is similar to other reactive +operators. It uses a callback approach (to free application code from having to do the +boilerplate acquisition and release transactional resources) and results in code that is +intention driven, in that your code focuses solely on what you want to do. + +NOTE: As the examples that follow show, using the `TransactionalOperator` absolutely +couples you to Spring's transaction infrastructure and APIs. Whether or not programmatic +transaction management is suitable for your development needs is a decision that you have +to make yourself. + +Application code that must run in a transactional context and that explicitly uses +the `TransactionalOperator` resembles the next example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleService implements Service { + + // single TransactionalOperator shared amongst all methods in this instance + private final TransactionalOperator transactionalOperator; + + // use constructor-injection to supply the ReactiveTransactionManager + public SimpleService(ReactiveTransactionManager transactionManager) { + this.transactionalOperator = TransactionalOperator.create(transactionManager); + } + + public Mono<Object> someServiceMethod() { + + // the code in this method runs in a transactional context + + Mono<Object> update = updateOperation1(); + + return update.then(resultOfUpdateOperation2).as(transactionalOperator::transactional); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // use constructor-injection to supply the ReactiveTransactionManager + class SimpleService(transactionManager: ReactiveTransactionManager) : Service { + + // single TransactionalOperator shared amongst all methods in this instance + private val transactionalOperator = TransactionalOperator.create(transactionManager) + + suspend fun someServiceMethod() = transactionalOperator.executeAndAwait<Any?> { + updateOperation1() + resultOfUpdateOperation2() + } + } +---- + +`TransactionalOperator` can be used in two ways: + +* Operator-style using Project Reactor types (`mono.as(transactionalOperator::transactional)`) +* Callback-style for every other case (`transactionalOperator.execute(TransactionCallback<T>)`) + +Code within the callback can roll the transaction back by calling the `setRollbackOnly()` +method on the supplied `ReactiveTransaction` object, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + transactionalOperator.execute(new TransactionCallback<>() { + + public Mono<Object> doInTransaction(ReactiveTransaction status) { + return updateOperation1().then(updateOperation2) + .doOnError(SomeBusinessException.class, e -> status.setRollbackOnly()); + } + } + }); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + transactionalOperator.execute(object : TransactionCallback() { + + override fun doInTransactionWithoutResult(status: ReactiveTransaction) { + updateOperation1().then(updateOperation2) + .doOnError(SomeBusinessException.class, e -> status.setRollbackOnly()) + } + }) +---- + +[[tx-prog-operator-cancel]] +=== Cancel Signals + +In Reactive Streams, a `Subscriber` can cancel its `Subscription` and stop its +`Publisher`. Operators in Project Reactor, as well as in other libraries, such as `next()`, +`take(long)`, `timeout(Duration)`, and others can issue cancellations. There is no way to +know the reason for the cancellation, whether it is due to an error or a simply lack of +interest to consume further. Since version 5.3 cancel signals lead to a roll back. +As a result it is important to consider the operators used downstream from a transaction +`Publisher`. In particular in the case of a `Flux` or other multi-value `Publisher`, +the full output must be consumed to allow the transaction to complete. + + +[[tx-prog-operator-settings]] +=== Specifying Transaction Settings + +You can specify transaction settings (such as the propagation mode, the isolation level, +the timeout, and so forth) for the `TransactionalOperator`. By default, +`TransactionalOperator` instances have +<<transaction-declarative-txadvice-settings,default transactional settings>>. The +following example shows customization of the transactional settings for a specific +`TransactionalOperator:` + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleService implements Service { + + private final TransactionalOperator transactionalOperator; + + public SimpleService(ReactiveTransactionManager transactionManager) { + DefaultTransactionDefinition definition = new DefaultTransactionDefinition(); + + // the transaction settings can be set here explicitly if so desired + definition.setIsolationLevel(TransactionDefinition.ISOLATION_READ_UNCOMMITTED); + definition.setTimeout(30); // 30 seconds + // and so forth... + + this.transactionalOperator = TransactionalOperator.create(transactionManager, definition); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SimpleService(transactionManager: ReactiveTransactionManager) : Service { + + private val definition = DefaultTransactionDefinition().apply { + // the transaction settings can be set here explicitly if so desired + isolationLevel = TransactionDefinition.ISOLATION_READ_UNCOMMITTED + timeout = 30 // 30 seconds + // and so forth... + } + private val transactionalOperator = TransactionalOperator(transactionManager, definition) + } +---- + +[[transaction-programmatic-tm]] +== Using the `TransactionManager` + +The following sections explain programmatic usage of imperative and reactive transaction +managers. + +[[transaction-programmatic-ptm]] +=== Using the `PlatformTransactionManager` + +For imperative transactions, you can use a +`org.springframework.transaction.PlatformTransactionManager` directly to manage your +transaction. To do so, pass the implementation of the `PlatformTransactionManager` you +use to your bean through a bean reference. Then, by using the `TransactionDefinition` and +`TransactionStatus` objects, you can initiate transactions, roll back, and commit. The +following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + DefaultTransactionDefinition def = new DefaultTransactionDefinition(); + // explicitly setting the transaction name is something that can be done only programmatically + def.setName("SomeTxName"); + def.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRED); + + TransactionStatus status = txManager.getTransaction(def); + try { + // put your business logic here + } catch (MyException ex) { + txManager.rollback(status); + throw ex; + } + txManager.commit(status); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val def = DefaultTransactionDefinition() + // explicitly setting the transaction name is something that can be done only programmatically + def.setName("SomeTxName") + def.propagationBehavior = TransactionDefinition.PROPAGATION_REQUIRED + + val status = txManager.getTransaction(def) + try { + // put your business logic here + } catch (ex: MyException) { + txManager.rollback(status) + throw ex + } + + txManager.commit(status) +---- + + +[[transaction-programmatic-rtm]] +=== Using the `ReactiveTransactionManager` + +When working with reactive transactions, you can use a +`org.springframework.transaction.ReactiveTransactionManager` directly to manage your +transaction. To do so, pass the implementation of the `ReactiveTransactionManager` you +use to your bean through a bean reference. Then, by using the `TransactionDefinition` and +`ReactiveTransaction` objects, you can initiate transactions, roll back, and commit. The +following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + DefaultTransactionDefinition def = new DefaultTransactionDefinition(); + // explicitly setting the transaction name is something that can be done only programmatically + def.setName("SomeTxName"); + def.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRED); + + Mono<ReactiveTransaction> reactiveTx = txManager.getReactiveTransaction(def); + + reactiveTx.flatMap(status -> { + + Mono<Object> tx = ...; // put your business logic here + + return tx.then(txManager.commit(status)) + .onErrorResume(ex -> txManager.rollback(status).then(Mono.error(ex))); + }); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val def = DefaultTransactionDefinition() + // explicitly setting the transaction name is something that can be done only programmatically + def.setName("SomeTxName") + def.propagationBehavior = TransactionDefinition.PROPAGATION_REQUIRED + + val reactiveTx = txManager.getReactiveTransaction(def) + reactiveTx.flatMap { status -> + + val tx = ... // put your business logic here + + tx.then(txManager.commit(status)) + .onErrorResume { ex -> txManager.rollback(status).then(Mono.error(ex)) } + } +---- + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/resources.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/resources.adoc new file mode 100644 index 000000000000..62672974575f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/resources.adoc @@ -0,0 +1,17 @@ +[[transaction-resources]] += Further Resources + +For more information about the Spring Framework's transaction support, see: + +* https://www.infoworld.com/article/2077963/distributed-transactions-in-spring--with-and-without-xa.html[Distributed + transactions in Spring, with and without XA] is a JavaWorld presentation in which + Spring's David Syer guides you through seven patterns for distributed + transactions in Spring applications, three of them with XA and four without. +* https://www.infoq.com/minibooks/JTDS[_Java Transaction Design Strategies_] is a book + available from https://www.infoq.com/[InfoQ] that provides a well-paced introduction + to transactions in Java. It also includes side-by-side examples of how to configure + and use transactions with both the Spring Framework and EJB3. + + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc new file mode 100644 index 000000000000..562a5162441e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc @@ -0,0 +1,22 @@ +[[transaction-solutions-to-common-problems]] += Solutions to Common Problems + +This section describes solutions to some common problems. + + +[[transaction-solutions-to-common-problems-wrong-ptm]] +== Using the Wrong Transaction Manager for a Specific `DataSource` + +Use the correct `PlatformTransactionManager` implementation based on your choice of +transactional technologies and requirements. Used properly, the Spring Framework merely +provides a straightforward and portable abstraction. If you use global +transactions, you must use the +`org.springframework.transaction.jta.JtaTransactionManager` class (or an +<<transaction-application-server-integration,application server-specific subclass>> of +it) for all your transactional operations. Otherwise, the transaction infrastructure +tries to perform local transactions on such resources as container `DataSource` +instances. Such local transactions do not make sense, and a good application server +treats them as errors. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc new file mode 100644 index 000000000000..7b3c8f9368d9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc @@ -0,0 +1,284 @@ +[[transaction-strategies]] += Understanding the Spring Framework Transaction Abstraction + +The key to the Spring transaction abstraction is the notion of a transaction strategy. A +transaction strategy is defined by a `TransactionManager`, specifically the +`org.springframework.transaction.PlatformTransactionManager` interface for imperative +transaction management and the +`org.springframework.transaction.ReactiveTransactionManager` interface for reactive +transaction management. The following listing shows the definition of the +`PlatformTransactionManager` API: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface PlatformTransactionManager extends TransactionManager { + + TransactionStatus getTransaction(TransactionDefinition definition) throws TransactionException; + + void commit(TransactionStatus status) throws TransactionException; + + void rollback(TransactionStatus status) throws TransactionException; + } +---- + +This is primarily a service provider interface (SPI), although you can use it +<<transaction-programmatic-ptm, programmatically>> from your application code. Because +`PlatformTransactionManager` is an interface, it can be easily mocked or stubbed as +necessary. It is not tied to a lookup strategy, such as JNDI. +`PlatformTransactionManager` implementations are defined like any other object (or bean) +in the Spring Framework IoC container. This benefit alone makes Spring Framework +transactions a worthwhile abstraction, even when you work with JTA. You can test +transactional code much more easily than if it used JTA directly. + +Again, in keeping with Spring's philosophy, the `TransactionException` that can be thrown +by any of the `PlatformTransactionManager` interface's methods is unchecked (that +is, it extends the `java.lang.RuntimeException` class). Transaction infrastructure +failures are almost invariably fatal. In rare cases where application code can actually +recover from a transaction failure, the application developer can still choose to catch +and handle `TransactionException`. The salient point is that developers are not +_forced_ to do so. + +The `getTransaction(..)` method returns a `TransactionStatus` object, depending on a +`TransactionDefinition` parameter. The returned `TransactionStatus` might represent a +new transaction or can represent an existing transaction, if a matching transaction +exists in the current call stack. The implication in this latter case is that, as with +Jakarta EE transaction contexts, a `TransactionStatus` is associated with a thread of +execution. + +As of Spring Framework 5.2, Spring also provides a transaction management abstraction for +reactive applications that make use of reactive types or Kotlin Coroutines. The following +listing shows the transaction strategy defined by +`org.springframework.transaction.ReactiveTransactionManager`: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface ReactiveTransactionManager extends TransactionManager { + + Mono<ReactiveTransaction> getReactiveTransaction(TransactionDefinition definition) throws TransactionException; + + Mono<Void> commit(ReactiveTransaction status) throws TransactionException; + + Mono<Void> rollback(ReactiveTransaction status) throws TransactionException; + } +---- + +The reactive transaction manager is primarily a service provider interface (SPI), +although you can use it <<transaction-programmatic-rtm, programmatically>> from your +application code. Because `ReactiveTransactionManager` is an interface, it can be easily +mocked or stubbed as necessary. + +The `TransactionDefinition` interface specifies: + +* Propagation: Typically, all code within a transaction scope runs in + that transaction. However, you can specify the behavior if + a transactional method is run when a transaction context already exists. For + example, code can continue running in the existing transaction (the common case), or + the existing transaction can be suspended and a new transaction created. Spring + offers all of the transaction propagation options familiar from EJB CMT. To read + about the semantics of transaction propagation in Spring, see <<tx-propagation>>. +* Isolation: The degree to which this transaction is isolated from the work of other + transactions. For example, can this transaction see uncommitted writes from other + transactions? +* Timeout: How long this transaction runs before timing out and being automatically rolled back + by the underlying transaction infrastructure. +* Read-only status: You can use a read-only transaction when your code reads but + does not modify data. Read-only transactions can be a useful optimization in some + cases, such as when you use Hibernate. + +These settings reflect standard transactional concepts. If necessary, refer to resources +that discuss transaction isolation levels and other core transaction concepts. +Understanding these concepts is essential to using the Spring Framework or any +transaction management solution. + +The `TransactionStatus` interface provides a simple way for transactional code to +control transaction execution and query transaction status. The concepts should be +familiar, as they are common to all transaction APIs. The following listing shows the +`TransactionStatus` interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface TransactionStatus extends TransactionExecution, SavepointManager, Flushable { + + @Override + boolean isNewTransaction(); + + boolean hasSavepoint(); + + @Override + void setRollbackOnly(); + + @Override + boolean isRollbackOnly(); + + void flush(); + + @Override + boolean isCompleted(); + } +---- + +Regardless of whether you opt for declarative or programmatic transaction management in +Spring, defining the correct `TransactionManager` implementation is absolutely essential. +You typically define this implementation through dependency injection. + +`TransactionManager` implementations normally require knowledge of the environment in +which they work: JDBC, JTA, Hibernate, and so on. The following examples show how you can +define a local `PlatformTransactionManager` implementation (in this case, with plain +JDBC.) + +You can define a JDBC `DataSource` by creating a bean similar to the following: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close"> + <property name="driverClassName" value="${jdbc.driverClassName}" /> + <property name="url" value="${jdbc.url}" /> + <property name="username" value="${jdbc.username}" /> + <property name="password" value="${jdbc.password}" /> + </bean> +---- + +The related `PlatformTransactionManager` bean definition then has a reference to the +`DataSource` definition. It should resemble the following example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager"> + <property name="dataSource" ref="dataSource"/> + </bean> +---- + +If you use JTA in a Jakarta EE container, then you use a container `DataSource`, obtained +through JNDI, in conjunction with Spring's `JtaTransactionManager`. The following example +shows what the JTA and JNDI lookup version would look like: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:jee="http://www.springframework.org/schema/jee" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/jee + https://www.springframework.org/schema/jee/spring-jee.xsd"> + + <jee:jndi-lookup id="dataSource" jndi-name="jdbc/jpetstore"/> + + <bean id="txManager" class="org.springframework.transaction.jta.JtaTransactionManager" /> + + <!-- other <bean/> definitions here --> + + </beans> +---- + +The `JtaTransactionManager` does not need to know about the `DataSource` (or any other +specific resources) because it uses the container's global transaction management +infrastructure. + +NOTE: The preceding definition of the `dataSource` bean uses the `<jndi-lookup/>` tag +from the `jee` namespace. For more information see +<<integration.adoc#integration.appendix.xsd-schemas-jee, The JEE Schema>>. + +NOTE: If you use JTA, your transaction manager definition should look the same, regardless +of what data access technology you use, be it JDBC, Hibernate JPA, or any other supported +technology. This is due to the fact that JTA transactions are global transactions, which +can enlist any transactional resource. + +In all Spring transaction setups, application code does not need to change. You can change +how transactions are managed merely by changing configuration, even if that change means +moving from local to global transactions or vice versa. + + +[[transaction-strategies-hibernate]] +== Hibernate Transaction Setup + +You can also easily use Hibernate local transactions, as shown in the following examples. +In this case, you need to define a Hibernate `LocalSessionFactoryBean`, which your +application code can use to obtain Hibernate `Session` instances. + +The `DataSource` bean definition is similar to the local JDBC example shown previously +and, thus, is not shown in the following example. + +NOTE: If the `DataSource` (used by any non-JTA transaction manager) is looked up through +JNDI and managed by a Jakarta EE container, it should be non-transactional, because the +Spring Framework (rather than the Jakarta EE container) manages the transactions. + +The `txManager` bean in this case is of the `HibernateTransactionManager` type. In the +same way as the `DataSourceTransactionManager` needs a reference to the `DataSource`, the +`HibernateTransactionManager` needs a reference to the `SessionFactory`. The following +example declares `sessionFactory` and `txManager` beans: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="sessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactoryBean"> + <property name="dataSource" ref="dataSource"/> + <property name="mappingResources"> + <list> + <value>org/springframework/samples/petclinic/hibernate/petclinic.hbm.xml</value> + </list> + </property> + <property name="hibernateProperties"> + <value> + hibernate.dialect=${hibernate.dialect} + </value> + </property> + </bean> + + <bean id="txManager" class="org.springframework.orm.hibernate5.HibernateTransactionManager"> + <property name="sessionFactory" ref="sessionFactory"/> + </bean> +---- + +If you use Hibernate and Jakarta EE container-managed JTA transactions, you should use the +same `JtaTransactionManager` as in the previous JTA example for JDBC, as the following +example shows. Also, it is recommended to make Hibernate aware of JTA through its +transaction coordinator and possibly also its connection release mode configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="sessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactoryBean"> + <property name="dataSource" ref="dataSource"/> + <property name="mappingResources"> + <list> + <value>org/springframework/samples/petclinic/hibernate/petclinic.hbm.xml</value> + </list> + </property> + <property name="hibernateProperties"> + <value> + hibernate.dialect=${hibernate.dialect} + hibernate.transaction.coordinator_class=jta + hibernate.connection.handling_mode=DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT + </value> + </property> + </bean> + + <bean id="txManager" class="org.springframework.transaction.jta.JtaTransactionManager"/> +---- + +Or alternatively, you may pass the `JtaTransactionManager` into your `LocalSessionFactoryBean` +for enforcing the same defaults: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="sessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactoryBean"> + <property name="dataSource" ref="dataSource"/> + <property name="mappingResources"> + <list> + <value>org/springframework/samples/petclinic/hibernate/petclinic.hbm.xml</value> + </list> + </property> + <property name="hibernateProperties"> + <value> + hibernate.dialect=${hibernate.dialect} + </value> + </property> + <property name="jtaTransactionManager" ref="txManager"/> + </bean> + + <bean id="txManager" class="org.springframework.transaction.jta.JtaTransactionManager"/> +---- + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/tx-decl-vs-prog.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/tx-decl-vs-prog.adoc new file mode 100644 index 000000000000..b90bd9b0ff17 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/tx-decl-vs-prog.adoc @@ -0,0 +1,19 @@ +[[tx-decl-vs-prog]] += Choosing Between Programmatic and Declarative Transaction Management + +Programmatic transaction management is usually a good idea only if you have a small +number of transactional operations. For example, if you have a web application that +requires transactions only for certain update operations, you may not want to set up +transactional proxies by using Spring or any other technology. In this case, using the +`TransactionTemplate` may be a good approach. Being able to set the transaction name +explicitly is also something that can be done only by using the programmatic approach +to transaction management. + +On the other hand, if your application has numerous transactional operations, +declarative transaction management is usually worthwhile. It keeps transaction +management out of business logic and is not difficult to configure. When using the +Spring Framework, rather than EJB CMT, the configuration cost of declarative transaction +management is greatly reduced. + + + diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/tx-resource-synchronization.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/tx-resource-synchronization.adoc new file mode 100644 index 000000000000..c3eae7a6110a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/tx-resource-synchronization.adoc @@ -0,0 +1,83 @@ +[[tx-resource-synchronization]] += Synchronizing Resources with Transactions + +How to create different transaction managers and how they are linked to related resources +that need to be synchronized to transactions (for example `DataSourceTransactionManager` +to a JDBC `DataSource`, `HibernateTransactionManager` to a Hibernate `SessionFactory`, +and so forth) should now be clear. This section describes how the application code +(directly or indirectly, by using a persistence API such as JDBC, Hibernate, or JPA) +ensures that these resources are created, reused, and cleaned up properly. The section +also discusses how transaction synchronization is (optionally) triggered through the +relevant `TransactionManager`. + + +[[tx-resource-synchronization-high]] +== High-level Synchronization Approach + +The preferred approach is to use Spring's highest-level template-based persistence +integration APIs or to use native ORM APIs with transaction-aware factory beans or +proxies for managing the native resource factories. These transaction-aware solutions +internally handle resource creation and reuse, cleanup, optional transaction +synchronization of the resources, and exception mapping. Thus, user data access code does +not have to address these tasks but can focus purely on non-boilerplate +persistence logic. Generally, you use the native ORM API or take a template approach +for JDBC access by using the `JdbcTemplate`. These solutions are detailed in subsequent +sections of this reference documentation. + + +[[tx-resource-synchronization-low]] +== Low-level Synchronization Approach + +Classes such as `DataSourceUtils` (for JDBC), `EntityManagerFactoryUtils` (for JPA), +`SessionFactoryUtils` (for Hibernate), and so on exist at a lower level. When you want the +application code to deal directly with the resource types of the native persistence APIs, +you use these classes to ensure that proper Spring Framework-managed instances are obtained, +transactions are (optionally) synchronized, and exceptions that occur in the process are +properly mapped to a consistent API. + +For example, in the case of JDBC, instead of the traditional JDBC approach of calling +the `getConnection()` method on the `DataSource`, you can instead use Spring's +`org.springframework.jdbc.datasource.DataSourceUtils` class, as follows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + Connection conn = DataSourceUtils.getConnection(dataSource); +---- + +If an existing transaction already has a connection synchronized (linked) to it, that +instance is returned. Otherwise, the method call triggers the creation of a new +connection, which is (optionally) synchronized to any existing transaction and made +available for subsequent reuse in that same transaction. As mentioned earlier, any +`SQLException` is wrapped in a Spring Framework `CannotGetJdbcConnectionException`, one +of the Spring Framework's hierarchy of unchecked `DataAccessException` types. This approach +gives you more information than can be obtained easily from the `SQLException` and +ensures portability across databases and even across different persistence technologies. + +This approach also works without Spring transaction management (transaction +synchronization is optional), so you can use it whether or not you use Spring for +transaction management. + +Of course, once you have used Spring's JDBC support, JPA support, or Hibernate support, +you generally prefer not to use `DataSourceUtils` or the other helper classes, +because you are much happier working through the Spring abstraction than directly +with the relevant APIs. For example, if you use the Spring `JdbcTemplate` or +`jdbc.object` package to simplify your use of JDBC, correct connection retrieval occurs +behind the scenes and you need not write any special code. + + +[[tx-resource-synchronization-tadsp]] +== `TransactionAwareDataSourceProxy` + +At the very lowest level exists the `TransactionAwareDataSourceProxy` class. This is a +proxy for a target `DataSource`, which wraps the target `DataSource` to add awareness of +Spring-managed transactions. In this respect, it is similar to a transactional JNDI +`DataSource`, as provided by a Jakarta EE server. + +You should almost never need or want to use this class, except when existing +code must be called and passed a standard JDBC `DataSource` interface implementation. In +that case, it is possible that this code is usable but is participating in Spring-managed +transactions. You can write your new code by using the higher-level +abstractions mentioned earlier. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/cache.adoc b/framework-docs/modules/ROOT/pages/integration/cache.adoc index 2b20a09b7740..9042bfdc8b2c 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache.adoc @@ -11,1061 +11,3 @@ for <<cache-jsr-107,JSR-107 annotations>> and more customization options. -[[cache-strategies]] -== Understanding the Cache Abstraction - -.Cache vs Buffer -**** - -The terms, "`buffer`" and "`cache,`" tend to be used interchangeably. Note, however, -that they represent different things. Traditionally, a buffer is used as an intermediate -temporary store for data between a fast and a slow entity. As one party would have to wait -for the other (which affects performance), the buffer alleviates this by allowing entire -blocks of data to move at once rather than in small chunks. The data is written and read -only once from the buffer. Furthermore, the buffers are visible to at least one party -that is aware of it. - -A cache, on the other hand, is, by definition, hidden, and neither party is aware that -caching occurs. It also improves performance but does so by letting the same data be -read multiple times in a fast fashion. - -You can find a further explanation of the differences between a buffer and a cache -https://en.wikipedia.org/wiki/Cache_(computing)#The_difference_between_buffer_and_cache[here]. -**** - -At its core, the cache abstraction applies caching to Java methods, thus reducing the -number of executions based on the information available in the cache. That is, each time -a targeted method is invoked, the abstraction applies a caching behavior that checks -whether the method has been already invoked for the given arguments. If it has been -invoked, the cached result is returned without having to invoke the actual method. -If the method has not been invoked, then it is invoked, and the result is cached and -returned to the user so that, the next time the method is invoked, the cached result is -returned. This way, expensive methods (whether CPU- or IO-bound) can be invoked only -once for a given set of parameters and the result reused without having to actually -invoke the method again. The caching logic is applied transparently without any -interference to the invoker. - -IMPORTANT: This approach works only for methods that are guaranteed to return the same -output (result) for a given input (or arguments) no matter how many times they are invoked. - -The caching abstraction provides other cache-related operations, such as the ability -to update the content of the cache or to remove one or all entries. These are useful if -the cache deals with data that can change during the course of the application. - -As with other services in the Spring Framework, the caching service is an abstraction -(not a cache implementation) and requires the use of actual storage to store the cache data -- -that is, the abstraction frees you from having to write the caching logic but does not -provide the actual data store. This abstraction is materialized by the -`org.springframework.cache.Cache` and `org.springframework.cache.CacheManager` interfaces. - -Spring provides <<cache-store-configuration, a few implementations>> of that abstraction: -JDK `java.util.concurrent.ConcurrentMap` based caches, Gemfire cache, -https://github.com/ben-manes/caffeine/wiki[Caffeine], and JSR-107 compliant caches (such -as Ehcache 3.x). See <<cache-plug>> for more information on plugging in other cache -stores and providers. - -IMPORTANT: The caching abstraction has no special handling for multi-threaded and -multi-process environments, as such features are handled by the cache implementation. - -If you have a multi-process environment (that is, an application deployed on several nodes), -you need to configure your cache provider accordingly. Depending on your use cases, a copy -of the same data on several nodes can be enough. However, if you change the data during -the course of the application, you may need to enable other propagation mechanisms. - -Caching a particular item is a direct equivalent of the typical -get-if-not-found-then-proceed-and-put-eventually code blocks -found with programmatic cache interaction. -No locks are applied, and several threads may try to load the same item concurrently. -The same applies to eviction. If several threads are trying to update or evict data -concurrently, you may use stale data. Certain cache providers offer advanced features -in that area. See the documentation of your cache provider for more details. - -To use the cache abstraction, you need to take care of two aspects: - -* Caching declaration: Identify the methods that need to be cached and their policies. -* Cache configuration: The backing cache where the data is stored and from which it is read. - - - -[[cache-annotations]] -== Declarative Annotation-based Caching - -For caching declaration, Spring's caching abstraction provides a set of Java annotations: - -* `@Cacheable`: Triggers cache population. -* `@CacheEvict`: Triggers cache eviction. -* `@CachePut`: Updates the cache without interfering with the method execution. -* `@Caching`: Regroups multiple cache operations to be applied on a method. -* `@CacheConfig`: Shares some common cache-related settings at class-level. - - -[[cache-annotations-cacheable]] -=== The `@Cacheable` Annotation - -As the name implies, you can use `@Cacheable` to demarcate methods that are cacheable -- -that is, methods for which the result is stored in the cache so that, on subsequent -invocations (with the same arguments), the value in the cache is returned without -having to actually invoke the method. In its simplest form, the annotation declaration -requires the name of the cache associated with the annotated method, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable("books") - public Book findBook(ISBN isbn) {...} ----- - -In the preceding snippet, the `findBook` method is associated with the cache named `books`. -Each time the method is called, the cache is checked to see whether the invocation has -already been run and does not have to be repeated. While in most cases, only one -cache is declared, the annotation lets multiple names be specified so that more than one -cache is being used. In this case, each of the caches is checked before invoking the -method -- if at least one cache is hit, the associated value is returned. - -NOTE: All the other caches that do not contain the value are also updated, even though -the cached method was not actually invoked. - -The following example uses `@Cacheable` on the `findBook` method with multiple caches: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable({"books", "isbns"}) - public Book findBook(ISBN isbn) {...} ----- - -[[cache-annotations-cacheable-default-key]] -==== Default Key Generation - -Since caches are essentially key-value stores, each invocation of a cached method -needs to be translated into a suitable key for cache access. The caching abstraction -uses a simple `KeyGenerator` based on the following algorithm: - -* If no parameters are given, return `SimpleKey.EMPTY`. -* If only one parameter is given, return that instance. -* If more than one parameter is given, return a `SimpleKey` that contains all parameters. - -This approach works well for most use-cases, as long as parameters have natural keys -and implement valid `hashCode()` and `equals()` methods. If that is not the case, -you need to change the strategy. - -To provide a different default key generator, you need to implement the -`org.springframework.cache.interceptor.KeyGenerator` interface. - -[NOTE] -==== -The default key generation strategy changed with the release of Spring 4.0. Earlier -versions of Spring used a key generation strategy that, for multiple key parameters, -considered only the `hashCode()` of parameters and not `equals()`. This could cause -unexpected key collisions (see https://jira.spring.io/browse/SPR-10237[SPR-10237] -for background). The new `SimpleKeyGenerator` uses a compound key for such scenarios. - -If you want to keep using the previous key strategy, you can configure the deprecated -`org.springframework.cache.interceptor.DefaultKeyGenerator` class or create a custom -hash-based `KeyGenerator` implementation. -==== - -[[cache-annotations-cacheable-key]] -==== Custom Key Generation Declaration - -Since caching is generic, the target methods are quite likely to have various signatures -that cannot be readily mapped on top of the cache structure. This tends to become obvious -when the target method has multiple arguments out of which only some are suitable for -caching (while the rest are used only by the method logic). Consider the following example: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable("books") - public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) ----- - -At first glance, while the two `boolean` arguments influence the way the book is found, -they are no use for the cache. Furthermore, what if only one of the two is important -while the other is not? - -For such cases, the `@Cacheable` annotation lets you specify how the key is generated -through its `key` attribute. You can use <<core.adoc#expressions, SpEL>> to pick the -arguments of interest (or their nested properties), perform operations, or even -invoke arbitrary methods without having to write any code or implement any interface. -This is the recommended approach over the -<<cache-annotations-cacheable-default-key, default generator>>, since methods tend to be -quite different in signatures as the code base grows. While the default strategy might -work for some methods, it rarely works for all methods. - -The following examples use various SpEL declarations (if you are not familiar with SpEL, -do yourself a favor and read <<core.adoc#expressions, Spring Expression Language>>): - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheNames="books", key="#isbn") - public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) - - @Cacheable(cacheNames="books", key="#isbn.rawNumber") - public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) - - @Cacheable(cacheNames="books", key="T(someType).hash(#isbn)") - public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) ----- - -The preceding snippets show how easy it is to select a certain argument, one of its -properties, or even an arbitrary (static) method. - -If the algorithm responsible for generating the key is too specific or if it needs -to be shared, you can define a custom `keyGenerator` on the operation. To do so, -specify the name of the `KeyGenerator` bean implementation to use, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheNames="books", keyGenerator="myKeyGenerator") - public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) ----- - -NOTE: The `key` and `keyGenerator` parameters are mutually exclusive and an operation -that specifies both results in an exception. - -[[cache-annotations-cacheable-default-cache-resolver]] -==== Default Cache Resolution - -The caching abstraction uses a simple `CacheResolver` that -retrieves the caches defined at the operation level by using the configured -`CacheManager`. - -To provide a different default cache resolver, you need to implement the -`org.springframework.cache.interceptor.CacheResolver` interface. - -[[cache-annotations-cacheable-cache-resolver]] -==== Custom Cache Resolution - -The default cache resolution fits well for applications that work with a -single `CacheManager` and have no complex cache resolution requirements. - -For applications that work with several cache managers, you can set the -`cacheManager` to use for each operation, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheNames="books", cacheManager="anotherCacheManager") <1> - public Book findBook(ISBN isbn) {...} ----- -<1> Specifying `anotherCacheManager`. - - -You can also replace the `CacheResolver` entirely in a fashion similar to that of -replacing <<cache-annotations-cacheable-key, key generation>>. The resolution is -requested for every cache operation, letting the implementation actually resolve -the caches to use based on runtime arguments. The following example shows how to -specify a `CacheResolver`: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheResolver="runtimeCacheResolver") <1> - public Book findBook(ISBN isbn) {...} ----- -<1> Specifying the `CacheResolver`. - - -[NOTE] -==== -Since Spring 4.1, the `value` attribute of the cache annotations are no longer -mandatory, since this particular information can be provided by the `CacheResolver` -regardless of the content of the annotation. - -Similarly to `key` and `keyGenerator`, the `cacheManager` and `cacheResolver` -parameters are mutually exclusive, and an operation specifying both -results in an exception, as a custom `CacheManager` is ignored by the -`CacheResolver` implementation. This is probably not what you expect. -==== - -[[cache-annotations-cacheable-synchronized]] -==== Synchronized Caching - -In a multi-threaded environment, certain operations might be concurrently invoked for -the same argument (typically on startup). By default, the cache abstraction does not -lock anything, and the same value may be computed several times, defeating the purpose -of caching. - -For those particular cases, you can use the `sync` attribute to instruct the underlying -cache provider to lock the cache entry while the value is being computed. As a result, -only one thread is busy computing the value, while the others are blocked until the entry -is updated in the cache. The following example shows how to use the `sync` attribute: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheNames="foos", sync=true) <1> - public Foo executeExpensiveOperation(String id) {...} ----- -<1> Using the `sync` attribute. - -NOTE: This is an optional feature, and your favorite cache library may not support it. -All `CacheManager` implementations provided by the core framework support it. See the -documentation of your cache provider for more details. - -[[cache-annotations-cacheable-condition]] -==== Conditional Caching - -Sometimes, a method might not be suitable for caching all the time (for example, it might -depend on the given arguments). The cache annotations support such use cases through the -`condition` parameter, which takes a `SpEL` expression that is evaluated to either `true` -or `false`. If `true`, the method is cached. If not, it behaves as if the method is not -cached (that is, the method is invoked every time no matter what values are in the cache -or what arguments are used). For example, the following method is cached only if the -argument `name` has a length shorter than 32: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheNames="book", condition="#name.length() < 32") <1> - public Book findBook(String name) ----- -<1> Setting a condition on `@Cacheable`. - - -In addition to the `condition` parameter, you can use the `unless` parameter to veto the -adding of a value to the cache. Unlike `condition`, `unless` expressions are evaluated -after the method has been invoked. To expand on the previous example, perhaps we only -want to cache paperback books, as the following example does: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheNames="book", condition="#name.length() < 32", unless="#result.hardback") <1> - public Book findBook(String name) ----- -<1> Using the `unless` attribute to block hardbacks. - - -The cache abstraction supports `java.util.Optional` return types. If an `Optional` value -is _present_, it will be stored in the associated cache. If an `Optional` value is not -present, `null` will be stored in the associated cache. `#result` always refers to the -business entity and never a supported wrapper, so the previous example can be rewritten -as follows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheNames="book", condition="#name.length() < 32", unless="#result?.hardback") - public Optional<Book> findBook(String name) ----- - -Note that `#result` still refers to `Book` and not `Optional<Book>`. Since it might be -`null`, we use SpEL's <<core.adoc#expressions-operator-safe-navigation, safe navigation operator>>. - -[[cache-spel-context]] -==== Available Caching SpEL Evaluation Context - -Each `SpEL` expression evaluates against a dedicated <<core.adoc#expressions-language-ref, `context`>>. -In addition to the built-in parameters, the framework provides dedicated caching-related -metadata, such as the argument names. The following table describes the items made -available to the context so that you can use them for key and conditional computations: - -[[cache-spel-context-tbl]] -.Cache SpEL available metadata -|=== -| Name| Location| Description| Example - -| `methodName` -| Root object -| The name of the method being invoked -| `#root.methodName` - -| `method` -| Root object -| The method being invoked -| `#root.method.name` - -| `target` -| Root object -| The target object being invoked -| `#root.target` - -| `targetClass` -| Root object -| The class of the target being invoked -| `#root.targetClass` - -| `args` -| Root object -| The arguments (as array) used for invoking the target -| `#root.args[0]` - -| `caches` -| Root object -| Collection of caches against which the current method is run -| `#root.caches[0].name` - -| Argument name -| Evaluation context -| Name of any of the method arguments. If the names are not available - (perhaps due to having no debug information), the argument names are also available under the `#a<#arg>` - where `#arg` stands for the argument index (starting from `0`). -| `#iban` or `#a0` (you can also use `#p0` or `#p<#arg>` notation as an alias). - -| `result` -| Evaluation context -| The result of the method call (the value to be cached). Only available in `unless` - expressions, `cache put` expressions (to compute the `key`), or `cache evict` - expressions (when `beforeInvocation` is `false`). For supported wrappers (such as - `Optional`), `#result` refers to the actual object, not the wrapper. -| `#result` -|=== - - -[[cache-annotations-put]] -=== The `@CachePut` Annotation - -When the cache needs to be updated without interfering with the method execution, -you can use the `@CachePut` annotation. That is, the method is always invoked and its -result is placed into the cache (according to the `@CachePut` options). It supports -the same options as `@Cacheable` and should be used for cache population rather than -method flow optimization. The following example uses the `@CachePut` annotation: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @CachePut(cacheNames="book", key="#isbn") - public Book updateBook(ISBN isbn, BookDescriptor descriptor) ----- - -IMPORTANT: Using `@CachePut` and `@Cacheable` annotations on the same method is generally -strongly discouraged because they have different behaviors. While the latter causes the -method invocation to be skipped by using the cache, the former forces the invocation in -order to run a cache update. This leads to unexpected behavior and, with the exception -of specific corner-cases (such as annotations having conditions that exclude them from each -other), such declarations should be avoided. Note also that such conditions should not rely -on the result object (that is, the `#result` variable), as these are validated up-front to -confirm the exclusion. - - -[[cache-annotations-evict]] -=== The `@CacheEvict` annotation - -The cache abstraction allows not just population of a cache store but also eviction. -This process is useful for removing stale or unused data from the cache. As opposed to -`@Cacheable`, `@CacheEvict` demarcates methods that perform cache -eviction (that is, methods that act as triggers for removing data from the cache). -Similarly to its sibling, `@CacheEvict` requires specifying one or more caches -that are affected by the action, allows a custom cache and key resolution or a -condition to be specified, and features an extra parameter -(`allEntries`) that indicates whether a cache-wide eviction needs to be performed -rather than just an entry eviction (based on the key). The following example evicts -all entries from the `books` cache: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @CacheEvict(cacheNames="books", allEntries=true) <1> - public void loadBooks(InputStream batch) ----- -<1> Using the `allEntries` attribute to evict all entries from the cache. - -This option comes in handy when an entire cache region needs to be cleared out. -Rather than evicting each entry (which would take a long time, since it is inefficient), -all the entries are removed in one operation, as the preceding example shows. -Note that the framework ignores any key specified in this scenario as it does not apply -(the entire cache is evicted, not only one entry). - -You can also indicate whether the eviction should occur after (the default) or before -the method is invoked by using the `beforeInvocation` attribute. The former provides the -same semantics as the rest of the annotations: Once the method completes successfully, -an action (in this case, eviction) on the cache is run. If the method does not -run (as it might be cached) or an exception is thrown, the eviction does not occur. -The latter (`beforeInvocation=true`) causes the eviction to always occur before the -method is invoked. This is useful in cases where the eviction does not need to be tied -to the method outcome. - -Note that `void` methods can be used with `@CacheEvict` - as the methods act as a -trigger, the return values are ignored (as they do not interact with the cache). This is -not the case with `@Cacheable` which adds data to the cache or updates data in the cache -and, thus, requires a result. - - -[[cache-annotations-caching]] -=== The `@Caching` Annotation - -Sometimes, multiple annotations of the same type (such as `@CacheEvict` or -`@CachePut`) need to be specified -- for example, because the condition or the key -expression is different between different caches. `@Caching` lets multiple nested -`@Cacheable`, `@CachePut`, and `@CacheEvict` annotations be used on the same method. -The following example uses two `@CacheEvict` annotations: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Caching(evict = { @CacheEvict("primary"), @CacheEvict(cacheNames="secondary", key="#p0") }) - public Book importBooks(String deposit, Date date) ----- - - -[[cache-annotations-config]] -=== The `@CacheConfig` annotation - -So far, we have seen that caching operations offer many customization options and that -you can set these options for each operation. However, some of the customization options -can be tedious to configure if they apply to all operations of the class. For -instance, specifying the name of the cache to use for every cache operation of the -class can be replaced by a single class-level definition. This is where `@CacheConfig` -comes into play. The following examples uses `@CacheConfig` to set the name of the cache: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @CacheConfig("books") <1> - public class BookRepositoryImpl implements BookRepository { - - @Cacheable - public Book findBook(ISBN isbn) {...} - } ----- -<1> Using `@CacheConfig` to set the name of the cache. - -`@CacheConfig` is a class-level annotation that allows sharing the cache names, -the custom `KeyGenerator`, the custom `CacheManager`, and the custom `CacheResolver`. -Placing this annotation on the class does not turn on any caching operation. - -An operation-level customization always overrides a customization set on `@CacheConfig`. -Therefore, this gives three levels of customizations for each cache operation: - -* Globally configured, available for `CacheManager`, `KeyGenerator`. -* At the class level, using `@CacheConfig`. -* At the operation level. - - -[[cache-annotation-enable]] -=== Enabling Caching Annotations - -It is important to note that even though declaring the cache annotations does not -automatically trigger their actions - like many things in Spring, the feature has to be -declaratively enabled (which means if you ever suspect caching is to blame, you can -disable it by removing only one configuration line rather than all the annotations in -your code). - -To enable caching annotations add the annotation `@EnableCaching` to one of your -`@Configuration` classes: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableCaching - public class AppConfig { - } ----- - -Alternatively, for XML configuration you can use the `cache:annotation-driven` element: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans xmlns="http://www.springframework.org/schema/beans" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xmlns:cache="http://www.springframework.org/schema/cache" - xsi:schemaLocation=" - http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd - http://www.springframework.org/schema/cache https://www.springframework.org/schema/cache/spring-cache.xsd"> - - <cache:annotation-driven/> - </beans> ----- - -Both the `cache:annotation-driven` element and the `@EnableCaching` annotation let you -specify various options that influence the way the caching behavior is added to the -application through AOP. The configuration is intentionally similar with that of -<<data-access.adoc#tx-annotation-driven-settings, `@Transactional`>>. - -NOTE: The default advice mode for processing caching annotations is `proxy`, which allows -for interception of calls through the proxy only. Local calls within the same class -cannot get intercepted that way. For a more advanced mode of interception, consider -switching to `aspectj` mode in combination with compile-time or load-time weaving. - -NOTE: For more detail about advanced customizations (using Java configuration) that are -required to implement `CachingConfigurer`, see the -{api-spring-framework}/cache/annotation/CachingConfigurer.html[javadoc]. - -[[cache-annotation-driven-settings]] -.Cache annotation settings -[cols="1,1,1,3"] -|=== -| XML Attribute | Annotation Attribute | Default | Description - -| `cache-manager` -| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) -| `cacheManager` -| The name of the cache manager to use. A default `CacheResolver` is initialized behind - the scenes with this cache manager (or `cacheManager` if not set). For more - fine-grained management of the cache resolution, consider setting the 'cache-resolver' - attribute. - -| `cache-resolver` -| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) -| A `SimpleCacheResolver` using the configured `cacheManager`. -| The bean name of the CacheResolver that is to be used to resolve the backing caches. - This attribute is not required and needs to be specified only as an alternative to - the 'cache-manager' attribute. - -| `key-generator` -| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) -| `SimpleKeyGenerator` -| Name of the custom key generator to use. - -| `error-handler` -| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) -| `SimpleCacheErrorHandler` -| The name of the custom cache error handler to use. By default, any exception thrown during - a cache related operation is thrown back at the client. - -| `mode` -| `mode` -| `proxy` -| The default mode (`proxy`) processes annotated beans to be proxied by using Spring's AOP - framework (following proxy semantics, as discussed earlier, applying to method calls - coming in through the proxy only). The alternative mode (`aspectj`) instead weaves the - affected classes with Spring's AspectJ caching aspect, modifying the target class byte - code to apply to any kind of method call. AspectJ weaving requires `spring-aspects.jar` - in the classpath as well as load-time weaving (or compile-time weaving) enabled. (See - <<core.adoc#aop-aj-ltw-spring, Spring configuration>> for details on how to set up - load-time weaving.) - -| `proxy-target-class` -| `proxyTargetClass` -| `false` -| Applies to proxy mode only. Controls what type of caching proxies are created for - classes annotated with the `@Cacheable` or `@CacheEvict` annotations. If the - `proxy-target-class` attribute is set to `true`, class-based proxies are created. - If `proxy-target-class` is `false` or if the attribute is omitted, standard JDK - interface-based proxies are created. (See <<core.adoc#aop-proxying, Proxying Mechanisms>> - for a detailed examination of the different proxy types.) - -| `order` -| `order` -| Ordered.LOWEST_PRECEDENCE -| Defines the order of the cache advice that is applied to beans annotated with - `@Cacheable` or `@CacheEvict`. (For more information about the rules related to - ordering AOP advice, see <<core.adoc#aop-ataspectj-advice-ordering, Advice Ordering>>.) - No specified ordering means that the AOP subsystem determines the order of the advice. -|=== - -NOTE: `<cache:annotation-driven/>` looks for `@Cacheable/@CachePut/@CacheEvict/@Caching` -only on beans in the same application context in which it is defined. This means that, -if you put `<cache:annotation-driven/>` in a `WebApplicationContext` for a -`DispatcherServlet`, it checks for beans only in your controllers, not your services. -See <<web.adoc#mvc-servlet, the MVC section>> for more information. - -.Method visibility and cache annotations -**** -When you use proxies, you should apply the cache annotations only to methods with -public visibility. If you do annotate protected, private, or package-visible methods -with these annotations, no error is raised, but the annotated method does not exhibit -the configured caching settings. Consider using AspectJ (see the rest of this section) -if you need to annotate non-public methods, as it changes the bytecode itself. -**** - -TIP: Spring recommends that you only annotate concrete classes (and methods of concrete -classes) with the `@Cache{asterisk}` annotations, as opposed to annotating interfaces. -You certainly can place an `@Cache{asterisk}` annotation on an interface (or an interface -method), but this works only if you use the proxy mode (`mode="proxy"`). If you use the -weaving-based aspect (`mode="aspectj"`), the caching settings are not recognized on -interface-level declarations by the weaving infrastructure. - -NOTE: In proxy mode (the default), only external method calls coming in through the -proxy are intercepted. This means that self-invocation (in effect, a method within the -target object that calls another method of the target object) does not lead to actual -caching at runtime even if the invoked method is marked with `@Cacheable`. Consider -using the `aspectj` mode in this case. Also, the proxy must be fully initialized to -provide the expected behavior, so you should not rely on this feature in your -initialization code (that is, `@PostConstruct`). - - -[[cache-annotation-stereotype]] -=== Using Custom Annotations - -.Custom annotation and AspectJ -**** -This feature works only with the proxy-based approach but can be enabled -with a bit of extra effort by using AspectJ. - -The `spring-aspects` module defines an aspect for the standard annotations only. -If you have defined your own annotations, you also need to define an aspect for -those. Check `AnnotationCacheAspect` for an example. -**** - -The caching abstraction lets you use your own annotations to identify what method -triggers cache population or eviction. This is quite handy as a template mechanism, -as it eliminates the need to duplicate cache annotation declarations, which is -especially useful if the key or condition are specified or if the foreign imports -(`org.springframework`) are not allowed in your code base. Similarly to the rest -of the <<core.adoc#beans-stereotype-annotations, stereotype>> annotations, you can -use `@Cacheable`, `@CachePut`, `@CacheEvict`, and `@CacheConfig` as -<<core.adoc#beans-meta-annotations, meta-annotations>> (that is, annotations that -can annotate other annotations). In the following example, we replace a common -`@Cacheable` declaration with our own custom annotation: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Retention(RetentionPolicy.RUNTIME) - @Target({ElementType.METHOD}) - @Cacheable(cacheNames="books", key="#isbn") - public @interface SlowService { - } ----- - -In the preceding example, we have defined our own `SlowService` annotation, -which itself is annotated with `@Cacheable`. Now we can replace the following code: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheNames="books", key="#isbn") - public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) ----- - -The following example shows the custom annotation with which we can replace the -preceding code: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @SlowService - public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) ----- - -Even though `@SlowService` is not a Spring annotation, the container automatically picks -up its declaration at runtime and understands its meaning. Note that, as mentioned -<<cache-annotation-enable, earlier>>, annotation-driven behavior needs to be enabled. - - - -[[cache-jsr-107]] -== JCache (JSR-107) Annotations - -Since version 4.1, Spring's caching abstraction fully supports the JCache standard -(JSR-107) annotations: `@CacheResult`, `@CachePut`, `@CacheRemove`, and `@CacheRemoveAll` -as well as the `@CacheDefaults`, `@CacheKey`, and `@CacheValue` companions. -You can use these annotations even without migrating your cache store to JSR-107. -The internal implementation uses Spring's caching abstraction and provides default -`CacheResolver` and `KeyGenerator` implementations that are compliant with the -specification. In other words, if you are already using Spring's caching abstraction, -you can switch to these standard annotations without changing your cache storage -(or configuration, for that matter). - - -[[cache-jsr-107-summary]] -=== Feature Summary - -For those who are familiar with Spring's caching annotations, the following table -describes the main differences between the Spring annotations and their JSR-107 -counterparts: - -.Spring vs. JSR-107 caching annotations -[cols="1,1,3"] -|=== -| Spring | JSR-107 | Remark - -| `@Cacheable` -| `@CacheResult` -| Fairly similar. `@CacheResult` can cache specific exceptions and force the - execution of the method regardless of the content of the cache. - -| `@CachePut` -| `@CachePut` -| While Spring updates the cache with the result of the method invocation, JCache - requires that it be passed it as an argument that is annotated with `@CacheValue`. - Due to this difference, JCache allows updating the cache before or after the - actual method invocation. - -| `@CacheEvict` -| `@CacheRemove` -| Fairly similar. `@CacheRemove` supports conditional eviction when the - method invocation results in an exception. - -| `@CacheEvict(allEntries=true)` -| `@CacheRemoveAll` -| See `@CacheRemove`. - -| `@CacheConfig` -| `@CacheDefaults` -| Lets you configure the same concepts, in a similar fashion. -|=== - -JCache has the notion of `javax.cache.annotation.CacheResolver`, which is identical -to the Spring's `CacheResolver` interface, except that JCache supports only a single -cache. By default, a simple implementation retrieves the cache to use based on the -name declared on the annotation. It should be noted that, if no cache name is -specified on the annotation, a default is automatically generated. See the javadoc -of `@CacheResult#cacheName()` for more information. - -`CacheResolver` instances are retrieved by a `CacheResolverFactory`. It is possible -to customize the factory for each cache operation, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @CacheResult(cacheNames="books", cacheResolverFactory=MyCacheResolverFactory.class) <1> - public Book findBook(ISBN isbn) ----- -<1> Customizing the factory for this operation. - -NOTE: For all referenced classes, Spring tries to locate a bean with the given type. -If more than one match exists, a new instance is created and can use the regular -bean lifecycle callbacks, such as dependency injection. - -Keys are generated by a `javax.cache.annotation.CacheKeyGenerator` that serves the -same purpose as Spring's `KeyGenerator`. By default, all method arguments are taken -into account, unless at least one parameter is annotated with `@CacheKey`. This is -similar to Spring's <<cache-annotations-cacheable-key, custom key generation -declaration>>. For instance, the following are identical operations, one using -Spring's abstraction and the other using JCache: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Cacheable(cacheNames="books", key="#isbn") - public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) - - @CacheResult(cacheName="books") - public Book findBook(@CacheKey ISBN isbn, boolean checkWarehouse, boolean includeUsed) ----- - -You can also specify the `CacheKeyResolver` on the operation, similar to how you can -specify the `CacheResolverFactory`. - -JCache can manage exceptions thrown by annotated methods. This can prevent an update of -the cache, but it can also cache the exception as an indicator of the failure instead of -calling the method again. Assume that `InvalidIsbnNotFoundException` is thrown if the -structure of the ISBN is invalid. This is a permanent failure (no book could ever be -retrieved with such a parameter). The following caches the exception so that further -calls with the same, invalid, ISBN throw the cached exception directly instead of -invoking the method again: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @CacheResult(cacheName="books", exceptionCacheName="failures" - cachedExceptions = InvalidIsbnNotFoundException.class) - public Book findBook(ISBN isbn) ----- - - -[[enabling-jsr-107-support]] -=== Enabling JSR-107 Support - -You do not need to do anything specific to enable the JSR-107 support alongside Spring's -declarative annotation support. Both `@EnableCaching` and the `cache:annotation-driven` -XML element automatically enable the JCache support if both the JSR-107 API and the -`spring-context-support` module are present in the classpath. - -NOTE: Depending on your use case, the choice is basically yours. You can even mix and -match services by using the JSR-107 API on some and using Spring's own annotations on -others. However, if these services impact the same caches, you should use a consistent -and identical key generation implementation. - - - -[[cache-declarative-xml]] -== Declarative XML-based Caching - -If annotations are not an option (perhaps due to having no access to the sources -or no external code), you can use XML for declarative caching. So, instead of -annotating the methods for caching, you can specify the target method and the -caching directives externally (similar to the declarative transaction management -<<data-access.adoc#transaction-declarative-first-example, advice>>). The example -from the previous section can be translated into the following example: - -[source,xml,indent=0] -[subs="verbatim"] ----- - <!-- the service we want to make cacheable --> - <bean id="bookService" class="x.y.service.DefaultBookService"/> - - <!-- cache definitions --> - <cache:advice id="cacheAdvice" cache-manager="cacheManager"> - <cache:caching cache="books"> - <cache:cacheable method="findBook" key="#isbn"/> - <cache:cache-evict method="loadBooks" all-entries="true"/> - </cache:caching> - </cache:advice> - - <!-- apply the cacheable behavior to all BookService interfaces --> - <aop:config> - <aop:advisor advice-ref="cacheAdvice" pointcut="execution(* x.y.BookService.*(..))"/> - </aop:config> - - <!-- cache manager definition omitted --> ----- - -In the preceding configuration, the `bookService` is made cacheable. The caching semantics -to apply are encapsulated in the `cache:advice` definition, which causes the `findBooks` -method to be used for putting data into the cache and the `loadBooks` method for evicting -data. Both definitions work against the `books` cache. - -The `aop:config` definition applies the cache advice to the appropriate points in the -program by using the AspectJ pointcut expression (more information is available in -<<core.adoc#aop, Aspect Oriented Programming with Spring>>). In the preceding example, -all methods from the `BookService` are considered and the cache advice is applied to them. - -The declarative XML caching supports all of the annotation-based model, so moving between -the two should be fairly easy. Furthermore, both can be used inside the same application. -The XML-based approach does not touch the target code. However, it is inherently more -verbose. When dealing with classes that have overloaded methods that are targeted for -caching, identifying the proper methods does take an extra effort, since the `method` -argument is not a good discriminator. In these cases, you can use the AspectJ pointcut -to cherry pick the target methods and apply the appropriate caching functionality. -However, through XML, it is easier to apply package or group or interface-wide caching -(again, due to the AspectJ pointcut) and to create template-like definitions (as we did -in the preceding example by defining the target cache through the `cache:definitions` -`cache` attribute). - - - -[[cache-store-configuration]] -== Configuring the Cache Storage - -The cache abstraction provides several storage integration options. To use them, you need -to declare an appropriate `CacheManager` (an entity that controls and manages `Cache` -instances and that can be used to retrieve these for storage). - - -[[cache-store-configuration-jdk]] -=== JDK `ConcurrentMap`-based Cache - -The JDK-based `Cache` implementation resides under -`org.springframework.cache.concurrent` package. It lets you use `ConcurrentHashMap` -as a backing `Cache` store. The following example shows how to configure two caches: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <!-- simple cache manager --> - <bean id="cacheManager" class="org.springframework.cache.support.SimpleCacheManager"> - <property name="caches"> - <set> - <bean class="org.springframework.cache.concurrent.ConcurrentMapCacheFactoryBean" p:name="default"/> - <bean class="org.springframework.cache.concurrent.ConcurrentMapCacheFactoryBean" p:name="books"/> - </set> - </property> - </bean> ----- - -The preceding snippet uses the `SimpleCacheManager` to create a `CacheManager` for the -two nested `ConcurrentMapCache` instances named `default` and `books`. Note that the -names are configured directly for each cache. - -As the cache is created by the application, it is bound to its lifecycle, making it -suitable for basic use cases, tests, or simple applications. The cache scales well -and is very fast, but it does not provide any management, persistence capabilities, -or eviction contracts. - - -[[cache-store-configuration-eviction]] -=== Ehcache-based Cache - -Ehcache 3.x is fully JSR-107 compliant and no dedicated support is required for it. See -<<cache-store-configuration-jsr107>> for details. - - -[[cache-store-configuration-caffeine]] -=== Caffeine Cache - -Caffeine is a Java 8 rewrite of Guava's cache, and its implementation is located in the -`org.springframework.cache.caffeine` package and provides access to several features -of Caffeine. - -The following example configures a `CacheManager` that creates the cache on demand: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="cacheManager" - class="org.springframework.cache.caffeine.CaffeineCacheManager"/> ----- - -You can also provide the caches to use explicitly. In that case, only those -are made available by the manager. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="cacheManager" class="org.springframework.cache.caffeine.CaffeineCacheManager"> - <property name="cacheNames"> - <set> - <value>default</value> - <value>books</value> - </set> - </property> - </bean> ----- - -The Caffeine `CacheManager` also supports custom `Caffeine` and `CacheLoader`. -See the https://github.com/ben-manes/caffeine/wiki[Caffeine documentation] -for more information about those. - - -[[cache-store-configuration-gemfire]] -=== GemFire-based Cache - -GemFire is a memory-oriented, disk-backed, elastically scalable, continuously available, -active (with built-in pattern-based subscription notifications), globally replicated -database and provides fully-featured edge caching. For further information on how to -use GemFire as a `CacheManager` (and more), see the -{docs-spring-gemfire}/html/[Spring Data GemFire reference documentation]. - - -[[cache-store-configuration-jsr107]] -=== JSR-107 Cache - -Spring's caching abstraction can also use JSR-107-compliant caches. The JCache -implementation is located in the `org.springframework.cache.jcache` package. - -Again, to use it, you need to declare the appropriate `CacheManager`. -The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="cacheManager" - class="org.springframework.cache.jcache.JCacheCacheManager" - p:cache-manager-ref="jCacheManager"/> - - <!-- JSR-107 cache manager setup --> - <bean id="jCacheManager" .../> ----- - - -[[cache-store-configuration-noop]] -=== Dealing with Caches without a Backing Store - -Sometimes, when switching environments or doing testing, you might have cache -declarations without having an actual backing cache configured. As this is an invalid -configuration, an exception is thrown at runtime, since the caching infrastructure -is unable to find a suitable store. In situations like this, rather than removing the -cache declarations (which can prove tedious), you can wire in a simple dummy cache that -performs no caching -- that is, it forces the cached methods to be invoked every time. -The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="cacheManager" class="org.springframework.cache.support.CompositeCacheManager"> - <property name="cacheManagers"> - <list> - <ref bean="jdkCache"/> - <ref bean="gemfireCache"/> - </list> - </property> - <property name="fallbackToNoOpCache" value="true"/> - </bean> ----- - -The `CompositeCacheManager` in the preceding chains multiple `CacheManager` instances and, -through the `fallbackToNoOpCache` flag, adds a no-op cache for all the definitions not -handled by the configured cache managers. That is, every cache definition not found in -either `jdkCache` or `gemfireCache` (configured earlier in the example) is handled by -the no-op cache, which does not store any information, causing the target method to be -invoked every time. - - - -[[cache-plug]] -== Plugging-in Different Back-end Caches - -Clearly, there are plenty of caching products out there that you can use as a backing -store. For those that do not support JSR-107 you need to provide a `CacheManager` and a -`Cache` implementation. This may sound harder than it is, since, in practice, the classes -tend to be simple https://en.wikipedia.org/wiki/Adapter_pattern[adapters] that map the -caching abstraction framework on top of the storage API, as the _Caffeine_ classes do. -Most `CacheManager` classes can use the classes in the -`org.springframework.cache.support` package (such as `AbstractCacheManager` which takes -care of the boiler-plate code, leaving only the actual mapping to be completed). - - - -[[cache-specific-config]] -== How can I Set the TTL/TTI/Eviction policy/XXX feature? - -Directly through your cache provider. The cache abstraction is an abstraction, -not a cache implementation. The solution you use might support various data -policies and different topologies that other solutions do not support (for example, -the JDK `ConcurrentHashMap` -- exposing that in the cache abstraction would be useless -because there would no backing support). Such functionality should be controlled -directly through the backing cache (when configuring it) or through its native API. - diff --git a/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc new file mode 100644 index 000000000000..a602e14f0384 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc @@ -0,0 +1,636 @@ +[[cache-annotations]] += Declarative Annotation-based Caching + +For caching declaration, Spring's caching abstraction provides a set of Java annotations: + +* `@Cacheable`: Triggers cache population. +* `@CacheEvict`: Triggers cache eviction. +* `@CachePut`: Updates the cache without interfering with the method execution. +* `@Caching`: Regroups multiple cache operations to be applied on a method. +* `@CacheConfig`: Shares some common cache-related settings at class-level. + + +[[cache-annotations-cacheable]] +== The `@Cacheable` Annotation + +As the name implies, you can use `@Cacheable` to demarcate methods that are cacheable -- +that is, methods for which the result is stored in the cache so that, on subsequent +invocations (with the same arguments), the value in the cache is returned without +having to actually invoke the method. In its simplest form, the annotation declaration +requires the name of the cache associated with the annotated method, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable("books") + public Book findBook(ISBN isbn) {...} +---- + +In the preceding snippet, the `findBook` method is associated with the cache named `books`. +Each time the method is called, the cache is checked to see whether the invocation has +already been run and does not have to be repeated. While in most cases, only one +cache is declared, the annotation lets multiple names be specified so that more than one +cache is being used. In this case, each of the caches is checked before invoking the +method -- if at least one cache is hit, the associated value is returned. + +NOTE: All the other caches that do not contain the value are also updated, even though +the cached method was not actually invoked. + +The following example uses `@Cacheable` on the `findBook` method with multiple caches: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable({"books", "isbns"}) + public Book findBook(ISBN isbn) {...} +---- + +[[cache-annotations-cacheable-default-key]] +=== Default Key Generation + +Since caches are essentially key-value stores, each invocation of a cached method +needs to be translated into a suitable key for cache access. The caching abstraction +uses a simple `KeyGenerator` based on the following algorithm: + +* If no parameters are given, return `SimpleKey.EMPTY`. +* If only one parameter is given, return that instance. +* If more than one parameter is given, return a `SimpleKey` that contains all parameters. + +This approach works well for most use-cases, as long as parameters have natural keys +and implement valid `hashCode()` and `equals()` methods. If that is not the case, +you need to change the strategy. + +To provide a different default key generator, you need to implement the +`org.springframework.cache.interceptor.KeyGenerator` interface. + +[NOTE] +==== +The default key generation strategy changed with the release of Spring 4.0. Earlier +versions of Spring used a key generation strategy that, for multiple key parameters, +considered only the `hashCode()` of parameters and not `equals()`. This could cause +unexpected key collisions (see https://jira.spring.io/browse/SPR-10237[SPR-10237] +for background). The new `SimpleKeyGenerator` uses a compound key for such scenarios. + +If you want to keep using the previous key strategy, you can configure the deprecated +`org.springframework.cache.interceptor.DefaultKeyGenerator` class or create a custom +hash-based `KeyGenerator` implementation. +==== + +[[cache-annotations-cacheable-key]] +=== Custom Key Generation Declaration + +Since caching is generic, the target methods are quite likely to have various signatures +that cannot be readily mapped on top of the cache structure. This tends to become obvious +when the target method has multiple arguments out of which only some are suitable for +caching (while the rest are used only by the method logic). Consider the following example: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable("books") + public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) +---- + +At first glance, while the two `boolean` arguments influence the way the book is found, +they are no use for the cache. Furthermore, what if only one of the two is important +while the other is not? + +For such cases, the `@Cacheable` annotation lets you specify how the key is generated +through its `key` attribute. You can use <<core.adoc#expressions, SpEL>> to pick the +arguments of interest (or their nested properties), perform operations, or even +invoke arbitrary methods without having to write any code or implement any interface. +This is the recommended approach over the +<<cache-annotations-cacheable-default-key, default generator>>, since methods tend to be +quite different in signatures as the code base grows. While the default strategy might +work for some methods, it rarely works for all methods. + +The following examples use various SpEL declarations (if you are not familiar with SpEL, +do yourself a favor and read <<core.adoc#expressions, Spring Expression Language>>): + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheNames="books", key="#isbn") + public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) + + @Cacheable(cacheNames="books", key="#isbn.rawNumber") + public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) + + @Cacheable(cacheNames="books", key="T(someType).hash(#isbn)") + public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) +---- + +The preceding snippets show how easy it is to select a certain argument, one of its +properties, or even an arbitrary (static) method. + +If the algorithm responsible for generating the key is too specific or if it needs +to be shared, you can define a custom `keyGenerator` on the operation. To do so, +specify the name of the `KeyGenerator` bean implementation to use, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheNames="books", keyGenerator="myKeyGenerator") + public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) +---- + +NOTE: The `key` and `keyGenerator` parameters are mutually exclusive and an operation +that specifies both results in an exception. + +[[cache-annotations-cacheable-default-cache-resolver]] +=== Default Cache Resolution + +The caching abstraction uses a simple `CacheResolver` that +retrieves the caches defined at the operation level by using the configured +`CacheManager`. + +To provide a different default cache resolver, you need to implement the +`org.springframework.cache.interceptor.CacheResolver` interface. + +[[cache-annotations-cacheable-cache-resolver]] +=== Custom Cache Resolution + +The default cache resolution fits well for applications that work with a +single `CacheManager` and have no complex cache resolution requirements. + +For applications that work with several cache managers, you can set the +`cacheManager` to use for each operation, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheNames="books", cacheManager="anotherCacheManager") <1> + public Book findBook(ISBN isbn) {...} +---- +<1> Specifying `anotherCacheManager`. + + +You can also replace the `CacheResolver` entirely in a fashion similar to that of +replacing <<cache-annotations-cacheable-key, key generation>>. The resolution is +requested for every cache operation, letting the implementation actually resolve +the caches to use based on runtime arguments. The following example shows how to +specify a `CacheResolver`: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheResolver="runtimeCacheResolver") <1> + public Book findBook(ISBN isbn) {...} +---- +<1> Specifying the `CacheResolver`. + + +[NOTE] +==== +Since Spring 4.1, the `value` attribute of the cache annotations are no longer +mandatory, since this particular information can be provided by the `CacheResolver` +regardless of the content of the annotation. + +Similarly to `key` and `keyGenerator`, the `cacheManager` and `cacheResolver` +parameters are mutually exclusive, and an operation specifying both +results in an exception, as a custom `CacheManager` is ignored by the +`CacheResolver` implementation. This is probably not what you expect. +==== + +[[cache-annotations-cacheable-synchronized]] +=== Synchronized Caching + +In a multi-threaded environment, certain operations might be concurrently invoked for +the same argument (typically on startup). By default, the cache abstraction does not +lock anything, and the same value may be computed several times, defeating the purpose +of caching. + +For those particular cases, you can use the `sync` attribute to instruct the underlying +cache provider to lock the cache entry while the value is being computed. As a result, +only one thread is busy computing the value, while the others are blocked until the entry +is updated in the cache. The following example shows how to use the `sync` attribute: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheNames="foos", sync=true) <1> + public Foo executeExpensiveOperation(String id) {...} +---- +<1> Using the `sync` attribute. + +NOTE: This is an optional feature, and your favorite cache library may not support it. +All `CacheManager` implementations provided by the core framework support it. See the +documentation of your cache provider for more details. + +[[cache-annotations-cacheable-condition]] +=== Conditional Caching + +Sometimes, a method might not be suitable for caching all the time (for example, it might +depend on the given arguments). The cache annotations support such use cases through the +`condition` parameter, which takes a `SpEL` expression that is evaluated to either `true` +or `false`. If `true`, the method is cached. If not, it behaves as if the method is not +cached (that is, the method is invoked every time no matter what values are in the cache +or what arguments are used). For example, the following method is cached only if the +argument `name` has a length shorter than 32: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheNames="book", condition="#name.length() < 32") <1> + public Book findBook(String name) +---- +<1> Setting a condition on `@Cacheable`. + + +In addition to the `condition` parameter, you can use the `unless` parameter to veto the +adding of a value to the cache. Unlike `condition`, `unless` expressions are evaluated +after the method has been invoked. To expand on the previous example, perhaps we only +want to cache paperback books, as the following example does: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheNames="book", condition="#name.length() < 32", unless="#result.hardback") <1> + public Book findBook(String name) +---- +<1> Using the `unless` attribute to block hardbacks. + + +The cache abstraction supports `java.util.Optional` return types. If an `Optional` value +is _present_, it will be stored in the associated cache. If an `Optional` value is not +present, `null` will be stored in the associated cache. `#result` always refers to the +business entity and never a supported wrapper, so the previous example can be rewritten +as follows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheNames="book", condition="#name.length() < 32", unless="#result?.hardback") + public Optional<Book> findBook(String name) +---- + +Note that `#result` still refers to `Book` and not `Optional<Book>`. Since it might be +`null`, we use SpEL's <<core.adoc#expressions-operator-safe-navigation, safe navigation operator>>. + +[[cache-spel-context]] +=== Available Caching SpEL Evaluation Context + +Each `SpEL` expression evaluates against a dedicated <<core.adoc#expressions-language-ref, `context`>>. +In addition to the built-in parameters, the framework provides dedicated caching-related +metadata, such as the argument names. The following table describes the items made +available to the context so that you can use them for key and conditional computations: + +[[cache-spel-context-tbl]] +.Cache SpEL available metadata +|=== +| Name| Location| Description| Example + +| `methodName` +| Root object +| The name of the method being invoked +| `#root.methodName` + +| `method` +| Root object +| The method being invoked +| `#root.method.name` + +| `target` +| Root object +| The target object being invoked +| `#root.target` + +| `targetClass` +| Root object +| The class of the target being invoked +| `#root.targetClass` + +| `args` +| Root object +| The arguments (as array) used for invoking the target +| `#root.args[0]` + +| `caches` +| Root object +| Collection of caches against which the current method is run +| `#root.caches[0].name` + +| Argument name +| Evaluation context +| Name of any of the method arguments. If the names are not available + (perhaps due to having no debug information), the argument names are also available under the `#a<#arg>` + where `#arg` stands for the argument index (starting from `0`). +| `#iban` or `#a0` (you can also use `#p0` or `#p<#arg>` notation as an alias). + +| `result` +| Evaluation context +| The result of the method call (the value to be cached). Only available in `unless` + expressions, `cache put` expressions (to compute the `key`), or `cache evict` + expressions (when `beforeInvocation` is `false`). For supported wrappers (such as + `Optional`), `#result` refers to the actual object, not the wrapper. +| `#result` +|=== + + +[[cache-annotations-put]] +== The `@CachePut` Annotation + +When the cache needs to be updated without interfering with the method execution, +you can use the `@CachePut` annotation. That is, the method is always invoked and its +result is placed into the cache (according to the `@CachePut` options). It supports +the same options as `@Cacheable` and should be used for cache population rather than +method flow optimization. The following example uses the `@CachePut` annotation: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @CachePut(cacheNames="book", key="#isbn") + public Book updateBook(ISBN isbn, BookDescriptor descriptor) +---- + +IMPORTANT: Using `@CachePut` and `@Cacheable` annotations on the same method is generally +strongly discouraged because they have different behaviors. While the latter causes the +method invocation to be skipped by using the cache, the former forces the invocation in +order to run a cache update. This leads to unexpected behavior and, with the exception +of specific corner-cases (such as annotations having conditions that exclude them from each +other), such declarations should be avoided. Note also that such conditions should not rely +on the result object (that is, the `#result` variable), as these are validated up-front to +confirm the exclusion. + + +[[cache-annotations-evict]] +== The `@CacheEvict` annotation + +The cache abstraction allows not just population of a cache store but also eviction. +This process is useful for removing stale or unused data from the cache. As opposed to +`@Cacheable`, `@CacheEvict` demarcates methods that perform cache +eviction (that is, methods that act as triggers for removing data from the cache). +Similarly to its sibling, `@CacheEvict` requires specifying one or more caches +that are affected by the action, allows a custom cache and key resolution or a +condition to be specified, and features an extra parameter +(`allEntries`) that indicates whether a cache-wide eviction needs to be performed +rather than just an entry eviction (based on the key). The following example evicts +all entries from the `books` cache: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @CacheEvict(cacheNames="books", allEntries=true) <1> + public void loadBooks(InputStream batch) +---- +<1> Using the `allEntries` attribute to evict all entries from the cache. + +This option comes in handy when an entire cache region needs to be cleared out. +Rather than evicting each entry (which would take a long time, since it is inefficient), +all the entries are removed in one operation, as the preceding example shows. +Note that the framework ignores any key specified in this scenario as it does not apply +(the entire cache is evicted, not only one entry). + +You can also indicate whether the eviction should occur after (the default) or before +the method is invoked by using the `beforeInvocation` attribute. The former provides the +same semantics as the rest of the annotations: Once the method completes successfully, +an action (in this case, eviction) on the cache is run. If the method does not +run (as it might be cached) or an exception is thrown, the eviction does not occur. +The latter (`beforeInvocation=true`) causes the eviction to always occur before the +method is invoked. This is useful in cases where the eviction does not need to be tied +to the method outcome. + +Note that `void` methods can be used with `@CacheEvict` - as the methods act as a +trigger, the return values are ignored (as they do not interact with the cache). This is +not the case with `@Cacheable` which adds data to the cache or updates data in the cache +and, thus, requires a result. + + +[[cache-annotations-caching]] +== The `@Caching` Annotation + +Sometimes, multiple annotations of the same type (such as `@CacheEvict` or +`@CachePut`) need to be specified -- for example, because the condition or the key +expression is different between different caches. `@Caching` lets multiple nested +`@Cacheable`, `@CachePut`, and `@CacheEvict` annotations be used on the same method. +The following example uses two `@CacheEvict` annotations: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Caching(evict = { @CacheEvict("primary"), @CacheEvict(cacheNames="secondary", key="#p0") }) + public Book importBooks(String deposit, Date date) +---- + + +[[cache-annotations-config]] +== The `@CacheConfig` annotation + +So far, we have seen that caching operations offer many customization options and that +you can set these options for each operation. However, some of the customization options +can be tedious to configure if they apply to all operations of the class. For +instance, specifying the name of the cache to use for every cache operation of the +class can be replaced by a single class-level definition. This is where `@CacheConfig` +comes into play. The following examples uses `@CacheConfig` to set the name of the cache: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @CacheConfig("books") <1> + public class BookRepositoryImpl implements BookRepository { + + @Cacheable + public Book findBook(ISBN isbn) {...} + } +---- +<1> Using `@CacheConfig` to set the name of the cache. + +`@CacheConfig` is a class-level annotation that allows sharing the cache names, +the custom `KeyGenerator`, the custom `CacheManager`, and the custom `CacheResolver`. +Placing this annotation on the class does not turn on any caching operation. + +An operation-level customization always overrides a customization set on `@CacheConfig`. +Therefore, this gives three levels of customizations for each cache operation: + +* Globally configured, available for `CacheManager`, `KeyGenerator`. +* At the class level, using `@CacheConfig`. +* At the operation level. + + +[[cache-annotation-enable]] +== Enabling Caching Annotations + +It is important to note that even though declaring the cache annotations does not +automatically trigger their actions - like many things in Spring, the feature has to be +declaratively enabled (which means if you ever suspect caching is to blame, you can +disable it by removing only one configuration line rather than all the annotations in +your code). + +To enable caching annotations add the annotation `@EnableCaching` to one of your +`@Configuration` classes: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableCaching + public class AppConfig { + } +---- + +Alternatively, for XML configuration you can use the `cache:annotation-driven` element: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:cache="http://www.springframework.org/schema/cache" + xsi:schemaLocation=" + http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/cache https://www.springframework.org/schema/cache/spring-cache.xsd"> + + <cache:annotation-driven/> + </beans> +---- + +Both the `cache:annotation-driven` element and the `@EnableCaching` annotation let you +specify various options that influence the way the caching behavior is added to the +application through AOP. The configuration is intentionally similar with that of +<<data-access.adoc#tx-annotation-driven-settings, `@Transactional`>>. + +NOTE: The default advice mode for processing caching annotations is `proxy`, which allows +for interception of calls through the proxy only. Local calls within the same class +cannot get intercepted that way. For a more advanced mode of interception, consider +switching to `aspectj` mode in combination with compile-time or load-time weaving. + +NOTE: For more detail about advanced customizations (using Java configuration) that are +required to implement `CachingConfigurer`, see the +{api-spring-framework}/cache/annotation/CachingConfigurer.html[javadoc]. + +[[cache-annotation-driven-settings]] +.Cache annotation settings +[cols="1,1,1,3"] +|=== +| XML Attribute | Annotation Attribute | Default | Description + +| `cache-manager` +| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) +| `cacheManager` +| The name of the cache manager to use. A default `CacheResolver` is initialized behind + the scenes with this cache manager (or `cacheManager` if not set). For more + fine-grained management of the cache resolution, consider setting the 'cache-resolver' + attribute. + +| `cache-resolver` +| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) +| A `SimpleCacheResolver` using the configured `cacheManager`. +| The bean name of the CacheResolver that is to be used to resolve the backing caches. + This attribute is not required and needs to be specified only as an alternative to + the 'cache-manager' attribute. + +| `key-generator` +| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) +| `SimpleKeyGenerator` +| Name of the custom key generator to use. + +| `error-handler` +| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) +| `SimpleCacheErrorHandler` +| The name of the custom cache error handler to use. By default, any exception thrown during + a cache related operation is thrown back at the client. + +| `mode` +| `mode` +| `proxy` +| The default mode (`proxy`) processes annotated beans to be proxied by using Spring's AOP + framework (following proxy semantics, as discussed earlier, applying to method calls + coming in through the proxy only). The alternative mode (`aspectj`) instead weaves the + affected classes with Spring's AspectJ caching aspect, modifying the target class byte + code to apply to any kind of method call. AspectJ weaving requires `spring-aspects.jar` + in the classpath as well as load-time weaving (or compile-time weaving) enabled. (See + <<core.adoc#aop-aj-ltw-spring, Spring configuration>> for details on how to set up + load-time weaving.) + +| `proxy-target-class` +| `proxyTargetClass` +| `false` +| Applies to proxy mode only. Controls what type of caching proxies are created for + classes annotated with the `@Cacheable` or `@CacheEvict` annotations. If the + `proxy-target-class` attribute is set to `true`, class-based proxies are created. + If `proxy-target-class` is `false` or if the attribute is omitted, standard JDK + interface-based proxies are created. (See <<core.adoc#aop-proxying, Proxying Mechanisms>> + for a detailed examination of the different proxy types.) + +| `order` +| `order` +| Ordered.LOWEST_PRECEDENCE +| Defines the order of the cache advice that is applied to beans annotated with + `@Cacheable` or `@CacheEvict`. (For more information about the rules related to + ordering AOP advice, see <<core.adoc#aop-ataspectj-advice-ordering, Advice Ordering>>.) + No specified ordering means that the AOP subsystem determines the order of the advice. +|=== + +NOTE: `<cache:annotation-driven/>` looks for `@Cacheable/@CachePut/@CacheEvict/@Caching` +only on beans in the same application context in which it is defined. This means that, +if you put `<cache:annotation-driven/>` in a `WebApplicationContext` for a +`DispatcherServlet`, it checks for beans only in your controllers, not your services. +See <<web.adoc#mvc-servlet, the MVC section>> for more information. + +.Method visibility and cache annotations +**** +When you use proxies, you should apply the cache annotations only to methods with +public visibility. If you do annotate protected, private, or package-visible methods +with these annotations, no error is raised, but the annotated method does not exhibit +the configured caching settings. Consider using AspectJ (see the rest of this section) +if you need to annotate non-public methods, as it changes the bytecode itself. +**** + +TIP: Spring recommends that you only annotate concrete classes (and methods of concrete +classes) with the `@Cache{asterisk}` annotations, as opposed to annotating interfaces. +You certainly can place an `@Cache{asterisk}` annotation on an interface (or an interface +method), but this works only if you use the proxy mode (`mode="proxy"`). If you use the +weaving-based aspect (`mode="aspectj"`), the caching settings are not recognized on +interface-level declarations by the weaving infrastructure. + +NOTE: In proxy mode (the default), only external method calls coming in through the +proxy are intercepted. This means that self-invocation (in effect, a method within the +target object that calls another method of the target object) does not lead to actual +caching at runtime even if the invoked method is marked with `@Cacheable`. Consider +using the `aspectj` mode in this case. Also, the proxy must be fully initialized to +provide the expected behavior, so you should not rely on this feature in your +initialization code (that is, `@PostConstruct`). + + +[[cache-annotation-stereotype]] +== Using Custom Annotations + +.Custom annotation and AspectJ +**** +This feature works only with the proxy-based approach but can be enabled +with a bit of extra effort by using AspectJ. + +The `spring-aspects` module defines an aspect for the standard annotations only. +If you have defined your own annotations, you also need to define an aspect for +those. Check `AnnotationCacheAspect` for an example. +**** + +The caching abstraction lets you use your own annotations to identify what method +triggers cache population or eviction. This is quite handy as a template mechanism, +as it eliminates the need to duplicate cache annotation declarations, which is +especially useful if the key or condition are specified or if the foreign imports +(`org.springframework`) are not allowed in your code base. Similarly to the rest +of the <<core.adoc#beans-stereotype-annotations, stereotype>> annotations, you can +use `@Cacheable`, `@CachePut`, `@CacheEvict`, and `@CacheConfig` as +<<core.adoc#beans-meta-annotations, meta-annotations>> (that is, annotations that +can annotate other annotations). In the following example, we replace a common +`@Cacheable` declaration with our own custom annotation: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Retention(RetentionPolicy.RUNTIME) + @Target({ElementType.METHOD}) + @Cacheable(cacheNames="books", key="#isbn") + public @interface SlowService { + } +---- + +In the preceding example, we have defined our own `SlowService` annotation, +which itself is annotated with `@Cacheable`. Now we can replace the following code: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheNames="books", key="#isbn") + public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) +---- + +The following example shows the custom annotation with which we can replace the +preceding code: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @SlowService + public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) +---- + +Even though `@SlowService` is not a Spring annotation, the container automatically picks +up its declaration at runtime and understands its meaning. Note that, as mentioned +<<cache-annotation-enable, earlier>>, annotation-driven behavior needs to be enabled. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc b/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc new file mode 100644 index 000000000000..b62a6a5e5d5a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc @@ -0,0 +1,56 @@ +[[cache-declarative-xml]] += Declarative XML-based Caching + +If annotations are not an option (perhaps due to having no access to the sources +or no external code), you can use XML for declarative caching. So, instead of +annotating the methods for caching, you can specify the target method and the +caching directives externally (similar to the declarative transaction management +<<data-access.adoc#transaction-declarative-first-example, advice>>). The example +from the previous section can be translated into the following example: + +[source,xml,indent=0] +[subs="verbatim"] +---- + <!-- the service we want to make cacheable --> + <bean id="bookService" class="x.y.service.DefaultBookService"/> + + <!-- cache definitions --> + <cache:advice id="cacheAdvice" cache-manager="cacheManager"> + <cache:caching cache="books"> + <cache:cacheable method="findBook" key="#isbn"/> + <cache:cache-evict method="loadBooks" all-entries="true"/> + </cache:caching> + </cache:advice> + + <!-- apply the cacheable behavior to all BookService interfaces --> + <aop:config> + <aop:advisor advice-ref="cacheAdvice" pointcut="execution(* x.y.BookService.*(..))"/> + </aop:config> + + <!-- cache manager definition omitted --> +---- + +In the preceding configuration, the `bookService` is made cacheable. The caching semantics +to apply are encapsulated in the `cache:advice` definition, which causes the `findBooks` +method to be used for putting data into the cache and the `loadBooks` method for evicting +data. Both definitions work against the `books` cache. + +The `aop:config` definition applies the cache advice to the appropriate points in the +program by using the AspectJ pointcut expression (more information is available in +<<core.adoc#aop, Aspect Oriented Programming with Spring>>). In the preceding example, +all methods from the `BookService` are considered and the cache advice is applied to them. + +The declarative XML caching supports all of the annotation-based model, so moving between +the two should be fairly easy. Furthermore, both can be used inside the same application. +The XML-based approach does not touch the target code. However, it is inherently more +verbose. When dealing with classes that have overloaded methods that are targeted for +caching, identifying the proper methods does take an extra effort, since the `method` +argument is not a good discriminator. In these cases, you can use the AspectJ pointcut +to cherry pick the target methods and apply the appropriate caching functionality. +However, through XML, it is easier to apply package or group or interface-wide caching +(again, due to the AspectJ pointcut) and to create template-like definitions (as we did +in the preceding example by defining the target cache through the `cache:definitions` +`cache` attribute). + + + diff --git a/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc b/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc new file mode 100644 index 000000000000..20f2735545ba --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc @@ -0,0 +1,123 @@ +[[cache-jsr-107]] += JCache (JSR-107) Annotations + +Since version 4.1, Spring's caching abstraction fully supports the JCache standard +(JSR-107) annotations: `@CacheResult`, `@CachePut`, `@CacheRemove`, and `@CacheRemoveAll` +as well as the `@CacheDefaults`, `@CacheKey`, and `@CacheValue` companions. +You can use these annotations even without migrating your cache store to JSR-107. +The internal implementation uses Spring's caching abstraction and provides default +`CacheResolver` and `KeyGenerator` implementations that are compliant with the +specification. In other words, if you are already using Spring's caching abstraction, +you can switch to these standard annotations without changing your cache storage +(or configuration, for that matter). + + +[[cache-jsr-107-summary]] +== Feature Summary + +For those who are familiar with Spring's caching annotations, the following table +describes the main differences between the Spring annotations and their JSR-107 +counterparts: + +.Spring vs. JSR-107 caching annotations +[cols="1,1,3"] +|=== +| Spring | JSR-107 | Remark + +| `@Cacheable` +| `@CacheResult` +| Fairly similar. `@CacheResult` can cache specific exceptions and force the + execution of the method regardless of the content of the cache. + +| `@CachePut` +| `@CachePut` +| While Spring updates the cache with the result of the method invocation, JCache + requires that it be passed it as an argument that is annotated with `@CacheValue`. + Due to this difference, JCache allows updating the cache before or after the + actual method invocation. + +| `@CacheEvict` +| `@CacheRemove` +| Fairly similar. `@CacheRemove` supports conditional eviction when the + method invocation results in an exception. + +| `@CacheEvict(allEntries=true)` +| `@CacheRemoveAll` +| See `@CacheRemove`. + +| `@CacheConfig` +| `@CacheDefaults` +| Lets you configure the same concepts, in a similar fashion. +|=== + +JCache has the notion of `javax.cache.annotation.CacheResolver`, which is identical +to the Spring's `CacheResolver` interface, except that JCache supports only a single +cache. By default, a simple implementation retrieves the cache to use based on the +name declared on the annotation. It should be noted that, if no cache name is +specified on the annotation, a default is automatically generated. See the javadoc +of `@CacheResult#cacheName()` for more information. + +`CacheResolver` instances are retrieved by a `CacheResolverFactory`. It is possible +to customize the factory for each cache operation, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @CacheResult(cacheNames="books", cacheResolverFactory=MyCacheResolverFactory.class) <1> + public Book findBook(ISBN isbn) +---- +<1> Customizing the factory for this operation. + +NOTE: For all referenced classes, Spring tries to locate a bean with the given type. +If more than one match exists, a new instance is created and can use the regular +bean lifecycle callbacks, such as dependency injection. + +Keys are generated by a `javax.cache.annotation.CacheKeyGenerator` that serves the +same purpose as Spring's `KeyGenerator`. By default, all method arguments are taken +into account, unless at least one parameter is annotated with `@CacheKey`. This is +similar to Spring's <<cache-annotations-cacheable-key, custom key generation +declaration>>. For instance, the following are identical operations, one using +Spring's abstraction and the other using JCache: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Cacheable(cacheNames="books", key="#isbn") + public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed) + + @CacheResult(cacheName="books") + public Book findBook(@CacheKey ISBN isbn, boolean checkWarehouse, boolean includeUsed) +---- + +You can also specify the `CacheKeyResolver` on the operation, similar to how you can +specify the `CacheResolverFactory`. + +JCache can manage exceptions thrown by annotated methods. This can prevent an update of +the cache, but it can also cache the exception as an indicator of the failure instead of +calling the method again. Assume that `InvalidIsbnNotFoundException` is thrown if the +structure of the ISBN is invalid. This is a permanent failure (no book could ever be +retrieved with such a parameter). The following caches the exception so that further +calls with the same, invalid, ISBN throw the cached exception directly instead of +invoking the method again: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @CacheResult(cacheName="books", exceptionCacheName="failures" + cachedExceptions = InvalidIsbnNotFoundException.class) + public Book findBook(ISBN isbn) +---- + + +[[enabling-jsr-107-support]] +== Enabling JSR-107 Support + +You do not need to do anything specific to enable the JSR-107 support alongside Spring's +declarative annotation support. Both `@EnableCaching` and the `cache:annotation-driven` +XML element automatically enable the JCache support if both the JSR-107 API and the +`spring-context-support` module are present in the classpath. + +NOTE: Depending on your use case, the choice is basically yours. You can even mix and +match services by using the JSR-107 API on some and using Spring's own annotations on +others. However, if these services impact the same caches, you should use a consistent +and identical key generation implementation. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/cache/plug.adoc b/framework-docs/modules/ROOT/pages/integration/cache/plug.adoc new file mode 100644 index 000000000000..a4fb38ebb886 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/cache/plug.adoc @@ -0,0 +1,14 @@ +[[cache-plug]] += Plugging-in Different Back-end Caches + +Clearly, there are plenty of caching products out there that you can use as a backing +store. For those that do not support JSR-107 you need to provide a `CacheManager` and a +`Cache` implementation. This may sound harder than it is, since, in practice, the classes +tend to be simple https://en.wikipedia.org/wiki/Adapter_pattern[adapters] that map the +caching abstraction framework on top of the storage API, as the _Caffeine_ classes do. +Most `CacheManager` classes can use the classes in the +`org.springframework.cache.support` package (such as `AbstractCacheManager` which takes +care of the boiler-plate code, leaving only the actual mapping to be completed). + + + diff --git a/framework-docs/modules/ROOT/pages/integration/cache/specific-config.adoc b/framework-docs/modules/ROOT/pages/integration/cache/specific-config.adoc new file mode 100644 index 000000000000..ddddb0ea1478 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/cache/specific-config.adoc @@ -0,0 +1,10 @@ +[[cache-specific-config]] += How can I Set the TTL/TTI/Eviction policy/XXX feature? + +Directly through your cache provider. The cache abstraction is an abstraction, +not a cache implementation. The solution you use might support various data +policies and different topologies that other solutions do not support (for example, +the JDK `ConcurrentHashMap` -- exposing that in the cache abstraction would be useless +because there would no backing support). Such functionality should be controlled +directly through the backing cache (when configuring it) or through its native API. + diff --git a/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc b/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc new file mode 100644 index 000000000000..1bda81c330d8 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc @@ -0,0 +1,143 @@ +[[cache-store-configuration]] += Configuring the Cache Storage + +The cache abstraction provides several storage integration options. To use them, you need +to declare an appropriate `CacheManager` (an entity that controls and manages `Cache` +instances and that can be used to retrieve these for storage). + + +[[cache-store-configuration-jdk]] +== JDK `ConcurrentMap`-based Cache + +The JDK-based `Cache` implementation resides under +`org.springframework.cache.concurrent` package. It lets you use `ConcurrentHashMap` +as a backing `Cache` store. The following example shows how to configure two caches: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <!-- simple cache manager --> + <bean id="cacheManager" class="org.springframework.cache.support.SimpleCacheManager"> + <property name="caches"> + <set> + <bean class="org.springframework.cache.concurrent.ConcurrentMapCacheFactoryBean" p:name="default"/> + <bean class="org.springframework.cache.concurrent.ConcurrentMapCacheFactoryBean" p:name="books"/> + </set> + </property> + </bean> +---- + +The preceding snippet uses the `SimpleCacheManager` to create a `CacheManager` for the +two nested `ConcurrentMapCache` instances named `default` and `books`. Note that the +names are configured directly for each cache. + +As the cache is created by the application, it is bound to its lifecycle, making it +suitable for basic use cases, tests, or simple applications. The cache scales well +and is very fast, but it does not provide any management, persistence capabilities, +or eviction contracts. + + +[[cache-store-configuration-eviction]] +== Ehcache-based Cache + +Ehcache 3.x is fully JSR-107 compliant and no dedicated support is required for it. See +<<cache-store-configuration-jsr107>> for details. + + +[[cache-store-configuration-caffeine]] +== Caffeine Cache + +Caffeine is a Java 8 rewrite of Guava's cache, and its implementation is located in the +`org.springframework.cache.caffeine` package and provides access to several features +of Caffeine. + +The following example configures a `CacheManager` that creates the cache on demand: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="cacheManager" + class="org.springframework.cache.caffeine.CaffeineCacheManager"/> +---- + +You can also provide the caches to use explicitly. In that case, only those +are made available by the manager. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="cacheManager" class="org.springframework.cache.caffeine.CaffeineCacheManager"> + <property name="cacheNames"> + <set> + <value>default</value> + <value>books</value> + </set> + </property> + </bean> +---- + +The Caffeine `CacheManager` also supports custom `Caffeine` and `CacheLoader`. +See the https://github.com/ben-manes/caffeine/wiki[Caffeine documentation] +for more information about those. + + +[[cache-store-configuration-gemfire]] +== GemFire-based Cache + +GemFire is a memory-oriented, disk-backed, elastically scalable, continuously available, +active (with built-in pattern-based subscription notifications), globally replicated +database and provides fully-featured edge caching. For further information on how to +use GemFire as a `CacheManager` (and more), see the +{docs-spring-gemfire}/html/[Spring Data GemFire reference documentation]. + + +[[cache-store-configuration-jsr107]] +== JSR-107 Cache + +Spring's caching abstraction can also use JSR-107-compliant caches. The JCache +implementation is located in the `org.springframework.cache.jcache` package. + +Again, to use it, you need to declare the appropriate `CacheManager`. +The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="cacheManager" + class="org.springframework.cache.jcache.JCacheCacheManager" + p:cache-manager-ref="jCacheManager"/> + + <!-- JSR-107 cache manager setup --> + <bean id="jCacheManager" .../> +---- + + +[[cache-store-configuration-noop]] +== Dealing with Caches without a Backing Store + +Sometimes, when switching environments or doing testing, you might have cache +declarations without having an actual backing cache configured. As this is an invalid +configuration, an exception is thrown at runtime, since the caching infrastructure +is unable to find a suitable store. In situations like this, rather than removing the +cache declarations (which can prove tedious), you can wire in a simple dummy cache that +performs no caching -- that is, it forces the cached methods to be invoked every time. +The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="cacheManager" class="org.springframework.cache.support.CompositeCacheManager"> + <property name="cacheManagers"> + <list> + <ref bean="jdkCache"/> + <ref bean="gemfireCache"/> + </list> + </property> + <property name="fallbackToNoOpCache" value="true"/> + </bean> +---- + +The `CompositeCacheManager` in the preceding chains multiple `CacheManager` instances and, +through the `fallbackToNoOpCache` flag, adds a no-op cache for all the definitions not +handled by the configured cache managers. That is, every cache definition not found in +either `jdkCache` or `gemfireCache` (configured earlier in the example) is handled by +the no-op cache, which does not store any information, causing the target method to be +invoked every time. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc b/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc new file mode 100644 index 000000000000..826a4e9c8a6f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc @@ -0,0 +1,76 @@ +[[cache-strategies]] += Understanding the Cache Abstraction + +.Cache vs Buffer +**** + +The terms, "`buffer`" and "`cache,`" tend to be used interchangeably. Note, however, +that they represent different things. Traditionally, a buffer is used as an intermediate +temporary store for data between a fast and a slow entity. As one party would have to wait +for the other (which affects performance), the buffer alleviates this by allowing entire +blocks of data to move at once rather than in small chunks. The data is written and read +only once from the buffer. Furthermore, the buffers are visible to at least one party +that is aware of it. + +A cache, on the other hand, is, by definition, hidden, and neither party is aware that +caching occurs. It also improves performance but does so by letting the same data be +read multiple times in a fast fashion. + +You can find a further explanation of the differences between a buffer and a cache +https://en.wikipedia.org/wiki/Cache_(computing)#The_difference_between_buffer_and_cache[here]. +**** + +At its core, the cache abstraction applies caching to Java methods, thus reducing the +number of executions based on the information available in the cache. That is, each time +a targeted method is invoked, the abstraction applies a caching behavior that checks +whether the method has been already invoked for the given arguments. If it has been +invoked, the cached result is returned without having to invoke the actual method. +If the method has not been invoked, then it is invoked, and the result is cached and +returned to the user so that, the next time the method is invoked, the cached result is +returned. This way, expensive methods (whether CPU- or IO-bound) can be invoked only +once for a given set of parameters and the result reused without having to actually +invoke the method again. The caching logic is applied transparently without any +interference to the invoker. + +IMPORTANT: This approach works only for methods that are guaranteed to return the same +output (result) for a given input (or arguments) no matter how many times they are invoked. + +The caching abstraction provides other cache-related operations, such as the ability +to update the content of the cache or to remove one or all entries. These are useful if +the cache deals with data that can change during the course of the application. + +As with other services in the Spring Framework, the caching service is an abstraction +(not a cache implementation) and requires the use of actual storage to store the cache data -- +that is, the abstraction frees you from having to write the caching logic but does not +provide the actual data store. This abstraction is materialized by the +`org.springframework.cache.Cache` and `org.springframework.cache.CacheManager` interfaces. + +Spring provides <<cache-store-configuration, a few implementations>> of that abstraction: +JDK `java.util.concurrent.ConcurrentMap` based caches, Gemfire cache, +https://github.com/ben-manes/caffeine/wiki[Caffeine], and JSR-107 compliant caches (such +as Ehcache 3.x). See <<cache-plug>> for more information on plugging in other cache +stores and providers. + +IMPORTANT: The caching abstraction has no special handling for multi-threaded and +multi-process environments, as such features are handled by the cache implementation. + +If you have a multi-process environment (that is, an application deployed on several nodes), +you need to configure your cache provider accordingly. Depending on your use cases, a copy +of the same data on several nodes can be enough. However, if you change the data during +the course of the application, you may need to enable other propagation mechanisms. + +Caching a particular item is a direct equivalent of the typical +get-if-not-found-then-proceed-and-put-eventually code blocks +found with programmatic cache interaction. +No locks are applied, and several threads may try to load the same item concurrently. +The same applies to eviction. If several threads are trying to update or evict data +concurrently, you may use stale data. Certain cache providers offer advanced features +in that area. See the documentation of your cache provider for more details. + +To use the cache abstraction, you need to take care of two aspects: + +* Caching declaration: Identify the methods that need to be cached and their policies. +* Cache configuration: The backing cache where the data is stored and from which it is read. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jms.adoc b/framework-docs/modules/ROOT/pages/integration/jms.adoc index 10ce2f37c07d..ee207db0e088 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms.adoc @@ -62,1413 +62,3 @@ support such a scenario. However, please consider this for transition scenarios -[[jms-using]] -== Using Spring JMS - -This section describes how to use Spring's JMS components. - - -[[jms-jmstemplate]] -=== Using `JmsTemplate` - -The `JmsTemplate` class is the central class in the JMS core package. It simplifies the -use of JMS, since it handles the creation and release of resources when sending or -synchronously receiving messages. - -Code that uses the `JmsTemplate` needs only to implement callback interfaces that give them -a clearly defined high-level contract. The `MessageCreator` callback interface creates a -message when given a `Session` provided by the calling code in `JmsTemplate`. To -allow for more complex usage of the JMS API, `SessionCallback` provides the -JMS session, and `ProducerCallback` exposes a `Session` and -`MessageProducer` pair. - -The JMS API exposes two types of send methods, one that takes delivery mode, priority, -and time-to-live as Quality of Service (QOS) parameters and one that takes no QOS -parameters and uses default values. Since `JmsTemplate` has many send methods, -setting the QOS parameters have been exposed as bean properties to -avoid duplication in the number of send methods. Similarly, the timeout value for -synchronous receive calls is set by using the `setReceiveTimeout` property. - -Some JMS providers allow the setting of default QOS values administratively through the -configuration of the `ConnectionFactory`. This has the effect that a call to a -`MessageProducer` instance's `send` method (`send(Destination destination, Message message)`) -uses different QOS default values than those specified in the JMS specification. In order -to provide consistent management of QOS values, the `JmsTemplate` must, therefore, be -specifically enabled to use its own QOS values by setting the boolean property -`isExplicitQosEnabled` to `true`. - -For convenience, `JmsTemplate` also exposes a basic request-reply operation that allows -for sending a message and waiting for a reply on a temporary queue that is created as part of -the operation. - -IMPORTANT: Instances of the `JmsTemplate` class are thread-safe, once configured. This is -important, because it means that you can configure a single instance of a `JmsTemplate` -and then safely inject this shared reference into multiple collaborators. To be -clear, the `JmsTemplate` is stateful, in that it maintains a reference to a -`ConnectionFactory`, but this state is not conversational state. - -As of Spring Framework 4.1, `JmsMessagingTemplate` is built on top of `JmsTemplate` -and provides an integration with the messaging abstraction -- that is, -`org.springframework.messaging.Message`. This lets you create the message to -send in a generic manner. - - -[[jms-connections]] -=== Connections - -The `JmsTemplate` requires a reference to a `ConnectionFactory`. The `ConnectionFactory` -is part of the JMS specification and serves as the entry point for working with JMS. It -is used by the client application as a factory to create connections with the JMS -provider and encapsulates various configuration parameters, many of which are -vendor-specific, such as SSL configuration options. - -When using JMS inside an EJB, the vendor provides implementations of the JMS interfaces -so that they can participate in declarative transaction management and perform pooling -of connections and sessions. In order to use this implementation, Jakarta EE containers -typically require that you declare a JMS connection factory as a `resource-ref` inside -the EJB or servlet deployment descriptors. To ensure the use of these features with the -`JmsTemplate` inside an EJB, the client application should ensure that it references the -managed implementation of the `ConnectionFactory`. - -[[jms-caching-resources]] -==== Caching Messaging Resources - -The standard API involves creating many intermediate objects. To send a message, the -following 'API' walk is performed: - -[literal] -[subs="verbatim,quotes"] ----- -ConnectionFactory->Connection->Session->MessageProducer->send ----- - -Between the `ConnectionFactory` and the `Send` operation, three intermediate -objects are created and destroyed. To optimize the resource usage and increase -performance, Spring provides two implementations of `ConnectionFactory`. - -[[jms-connection-factory]] -==== Using `SingleConnectionFactory` - -Spring provides an implementation of the `ConnectionFactory` interface, -`SingleConnectionFactory`, that returns the same `Connection` on all -`createConnection()` calls and ignores calls to `close()`. This is useful for testing and -standalone environments so that the same connection can be used for multiple -`JmsTemplate` calls that may span any number of transactions. `SingleConnectionFactory` -takes a reference to a standard `ConnectionFactory` that would typically come from JNDI. - -[[jdbc-connection-factory-caching]] -==== Using `CachingConnectionFactory` - -The `CachingConnectionFactory` extends the functionality of `SingleConnectionFactory` -and adds the caching of `Session`, `MessageProducer`, and `MessageConsumer` instances. -The initial cache size is set to `1`. You can use the `sessionCacheSize` property to -increase the number of cached sessions. Note that the number of actual cached sessions -is more than that number, as sessions are cached based on their acknowledgment mode, -so there can be up to four cached session instances (one for each acknowledgment mode) -when `sessionCacheSize` is set to one. `MessageProducer` and `MessageConsumer` instances -are cached within their owning session and also take into account the unique properties -of the producers and consumers when caching. MessageProducers are cached based on their -destination. MessageConsumers are cached based on a key composed of the destination, selector, -noLocal delivery flag, and the durable subscription name (if creating durable consumers). - -[NOTE] -==== -MessageProducers and MessageConsumers for temporary queues and topics -(TemporaryQueue/TemporaryTopic) will never be cached. Unfortunately, WebLogic JMS happens -to implement the temporary queue/topic interfaces on its regular destination implementation, -mis-indicating that none of its destinations can be cached. Please use a different connection -pool/cache on WebLogic, or customize `CachingConnectionFactory` for WebLogic purposes. -==== - - -[[jms-destinations]] -=== Destination Management - -Destinations, as `ConnectionFactory` instances, are JMS administered objects that you can store -and retrieve in JNDI. When configuring a Spring application context, you can use the -JNDI `JndiObjectFactoryBean` factory class or `<jee:jndi-lookup>` to perform dependency -injection on your object's references to JMS destinations. However, this strategy -is often cumbersome if there are a large number of destinations in the application or if there -are advanced destination management features unique to the JMS provider. Examples of -such advanced destination management include the creation of dynamic destinations or -support for a hierarchical namespace of destinations. The `JmsTemplate` delegates the -resolution of a destination name to a JMS destination object that implements the -`DestinationResolver` interface. `DynamicDestinationResolver` is the default -implementation used by `JmsTemplate` and accommodates resolving dynamic destinations. A -`JndiDestinationResolver` is also provided to act as a service locator for -destinations contained in JNDI and optionally falls back to the behavior contained in -`DynamicDestinationResolver`. - -Quite often, the destinations used in a JMS application are only known at runtime and, -therefore, cannot be administratively created when the application is deployed. This is -often because there is shared application logic between interacting system components -that create destinations at runtime according to a well-known naming convention. Even -though the creation of dynamic destinations is not part of the JMS specification, most -vendors have provided this functionality. Dynamic destinations are created with a user-defined name, -which differentiates them from temporary destinations, and are often -not registered in JNDI. The API used to create dynamic destinations varies from provider -to provider since the properties associated with the destination are vendor-specific. -However, a simple implementation choice that is sometimes made by vendors is to -disregard the warnings in the JMS specification and to use the method `TopicSession` -`createTopic(String topicName)` or the `QueueSession` `createQueue(String -queueName)` method to create a new destination with default destination properties. Depending -on the vendor implementation, `DynamicDestinationResolver` can then also create a -physical destination instead of only resolving one. - -The boolean property `pubSubDomain` is used to configure the `JmsTemplate` with -knowledge of what JMS domain is being used. By default, the value of this property is -false, indicating that the point-to-point domain, `Queues`, is to be used. This property -(used by `JmsTemplate`) determines the behavior of dynamic destination resolution through -implementations of the `DestinationResolver` interface. - -You can also configure the `JmsTemplate` with a default destination through the -property `defaultDestination`. The default destination is with send and receive -operations that do not refer to a specific destination. - - -[[jms-mdp]] -=== Message Listener Containers - -One of the most common uses of JMS messages in the EJB world is to drive message-driven -beans (MDBs). Spring offers a solution to create message-driven POJOs (MDPs) in a way -that does not tie a user to an EJB container. (See <<jms-receiving-async>> for detailed -coverage of Spring's MDP support.) Since Spring Framework 4.1, endpoint methods can be -annotated with `@JmsListener` -- see <<jms-annotated>> for more details. - -A message listener container is used to receive messages from a JMS message queue and -drive the `MessageListener` that is injected into it. The listener container is -responsible for all threading of message reception and dispatches into the listener for -processing. A message listener container is the intermediary between an MDP and a -messaging provider and takes care of registering to receive messages, participating in -transactions, resource acquisition and release, exception conversion, and so on. This -lets you write the (possibly complex) business logic -associated with receiving a message (and possibly respond to it), and delegates -boilerplate JMS infrastructure concerns to the framework. - -There are two standard JMS message listener containers packaged with Spring, each with -its specialized feature set. - -* <<jms-mdp-simple, `SimpleMessageListenerContainer`>> -* <<jms-mdp-default, `DefaultMessageListenerContainer`>> - -[[jms-mdp-simple]] -==== Using `SimpleMessageListenerContainer` - -This message listener container is the simpler of the two standard flavors. It creates -a fixed number of JMS sessions and consumers at startup, registers the listener by using -the standard JMS `MessageConsumer.setMessageListener()` method, and leaves it up the JMS -provider to perform listener callbacks. This variant does not allow for dynamic adaption -to runtime demands or for participation in externally managed transactions. -Compatibility-wise, it stays very close to the spirit of the standalone JMS -specification, but is generally not compatible with Jakarta EE's JMS restrictions. - -NOTE: While `SimpleMessageListenerContainer` does not allow for participation in externally -managed transactions, it does support native JMS transactions. To enable this feature, -you can switch the `sessionTransacted` flag to `true` or, in the XML namespace, set the -`acknowledge` attribute to `transacted`. Exceptions thrown from your listener then lead -to a rollback, with the message getting redelivered. Alternatively, consider using -`CLIENT_ACKNOWLEDGE` mode, which provides redelivery in case of an exception as well but -does not use transacted `Session` instances and, therefore, does not include any other -`Session` operations (such as sending response messages) in the transaction protocol. - -IMPORTANT: The default `AUTO_ACKNOWLEDGE` mode does not provide proper reliability guarantees. -Messages can get lost when listener execution fails (since the provider automatically -acknowledges each message after listener invocation, with no exceptions to be propagated to -the provider) or when the listener container shuts down (you can configure this by setting -the `acceptMessagesWhileStopping` flag). Make sure to use transacted sessions in case of -reliability needs (for example, for reliable queue handling and durable topic subscriptions). - -[[jms-mdp-default]] -==== Using `DefaultMessageListenerContainer` - -This message listener container is used in most cases. In contrast to -`SimpleMessageListenerContainer`, this container variant allows for dynamic adaptation -to runtime demands and is able to participate in externally managed transactions. -Each received message is registered with an XA transaction when configured with a -`JtaTransactionManager`. As a result, processing may take advantage of XA transaction -semantics. This listener container strikes a good balance between low requirements on -the JMS provider, advanced functionality (such as participation in externally managed -transactions), and compatibility with Jakarta EE environments. - -You can customize the cache level of the container. Note that, when no caching is enabled, -a new connection and a new session is created for each message reception. Combining this -with a non-durable subscription with high loads may lead to message loss. Make sure to -use a proper cache level in such a case. - -This container also has recoverable capabilities when the broker goes down. By default, -a simple `BackOff` implementation retries every five seconds. You can specify -a custom `BackOff` implementation for more fine-grained recovery options. See -{api-spring-framework}/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example. - -NOTE: Like its sibling (<<jms-mdp-simple, `SimpleMessageListenerContainer`>>), -`DefaultMessageListenerContainer` supports native JMS transactions and allows for -customizing the acknowledgment mode. If feasible for your scenario, This is strongly -recommended over externally managed transactions -- that is, if you can live with -occasional duplicate messages in case of the JVM dying. Custom duplicate message -detection steps in your business logic can cover such situations -- for example, -in the form of a business entity existence check or a protocol table check. -Any such arrangements are significantly more efficient than the alternative: -wrapping your entire processing with an XA transaction (through configuring your -`DefaultMessageListenerContainer` with an `JtaTransactionManager`) to cover the -reception of the JMS message as well as the execution of the business logic in your -message listener (including database operations, etc.). - -IMPORTANT: The default `AUTO_ACKNOWLEDGE` mode does not provide proper reliability guarantees. -Messages can get lost when listener execution fails (since the provider automatically -acknowledges each message after listener invocation, with no exceptions to be propagated to -the provider) or when the listener container shuts down (you can configure this by setting -the `acceptMessagesWhileStopping` flag). Make sure to use transacted sessions in case of -reliability needs (for example, for reliable queue handling and durable topic subscriptions). - - -[[jms-tx]] -=== Transaction Management - -Spring provides a `JmsTransactionManager` that manages transactions for a single JMS -`ConnectionFactory`. This lets JMS applications leverage the managed-transaction -features of Spring, as described in -<<data-access.adoc#transaction, Transaction Management section of the Data Access chapter>>. -The `JmsTransactionManager` performs local resource transactions, binding a JMS -Connection/Session pair from the specified `ConnectionFactory` to the thread. -`JmsTemplate` automatically detects such transactional resources and operates -on them accordingly. - -In a Jakarta EE environment, the `ConnectionFactory` pools Connection and Session instances, -so those resources are efficiently reused across transactions. In a standalone environment, -using Spring's `SingleConnectionFactory` result in a shared JMS `Connection`, with -each transaction having its own independent `Session`. Alternatively, consider the use -of a provider-specific pooling adapter, such as ActiveMQ's `PooledConnectionFactory` -class. - -You can also use `JmsTemplate` with the `JtaTransactionManager` and an XA-capable JMS -`ConnectionFactory` to perform distributed transactions. Note that this requires the -use of a JTA transaction manager as well as a properly XA-configured ConnectionFactory. -(Check your Jakarta EE server's or JMS provider's documentation.) - -Reusing code across a managed and unmanaged transactional environment can be confusing -when using the JMS API to create a `Session` from a `Connection`. This is because the -JMS API has only one factory method to create a `Session`, and it requires values for the -transaction and acknowledgment modes. In a managed environment, setting these values is -the responsibility of the environment's transactional infrastructure, so these values -are ignored by the vendor's wrapper to the JMS Connection. When you use the `JmsTemplate` -in an unmanaged environment, you can specify these values through the use of the -properties `sessionTransacted` and `sessionAcknowledgeMode`. When you use a -`PlatformTransactionManager` with `JmsTemplate`, the template is always given a -transactional JMS `Session`. - - - -[[jms-sending]] -== Sending a Message - -The `JmsTemplate` contains many convenience methods to send a message. Send -methods specify the destination by using a `jakarta.jms.Destination` object, and others -specify the destination by using a `String` in a JNDI lookup. The `send` method -that takes no destination argument uses the default destination. - -The following example uses the `MessageCreator` callback to create a text message from the -supplied `Session` object: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - import jakarta.jms.ConnectionFactory; - import jakarta.jms.JMSException; - import jakarta.jms.Message; - import jakarta.jms.Queue; - import jakarta.jms.Session; - - import org.springframework.jms.core.MessageCreator; - import org.springframework.jms.core.JmsTemplate; - - public class JmsQueueSender { - - private JmsTemplate jmsTemplate; - private Queue queue; - - public void setConnectionFactory(ConnectionFactory cf) { - this.jmsTemplate = new JmsTemplate(cf); - } - - public void setQueue(Queue queue) { - this.queue = queue; - } - - public void simpleSend() { - this.jmsTemplate.send(this.queue, new MessageCreator() { - public Message createMessage(Session session) throws JMSException { - return session.createTextMessage("hello queue world"); - } - }); - } - } ----- - -In the preceding example, the `JmsTemplate` is constructed by passing a reference to a -`ConnectionFactory`. As an alternative, a zero-argument constructor and -`connectionFactory` is provided and can be used for constructing the instance in -JavaBean style (using a `BeanFactory` or plain Java code). Alternatively, consider -deriving from Spring's `JmsGatewaySupport` convenience base class, which provides -pre-built bean properties for JMS configuration. - -The `send(String destinationName, MessageCreator creator)` method lets you send a -message by using the string name of the destination. If these names are registered in JNDI, -you should set the `destinationResolver` property of the template to an instance of -`JndiDestinationResolver`. - -If you created the `JmsTemplate` and specified a default destination, the -`send(MessageCreator c)` sends a message to that destination. - - -[[jms-msg-conversion]] -=== Using Message Converters - -To facilitate the sending of domain model objects, the `JmsTemplate` has -various send methods that take a Java object as an argument for a message's data -content. The overloaded methods `convertAndSend()` and `receiveAndConvert()` methods in -`JmsTemplate` delegate the conversion process to an instance of the `MessageConverter` -interface. This interface defines a simple contract to convert between Java objects and -JMS messages. The default implementation (`SimpleMessageConverter`) supports conversion -between `String` and `TextMessage`, `byte[]` and `BytesMessage`, and `java.util.Map` -and `MapMessage`. By using the converter, you and your application code can focus on the -business object that is being sent or received through JMS and not be concerned with the -details of how it is represented as a JMS message. - -The sandbox currently includes a `MapMessageConverter`, which uses reflection to convert -between a JavaBean and a `MapMessage`. Other popular implementation choices you might -implement yourself are converters that use an existing XML marshalling package (such as -JAXB or XStream) to create a `TextMessage` that represents the object. - -To accommodate the setting of a message's properties, headers, and body that can not be -generically encapsulated inside a converter class, the `MessagePostProcessor` interface -gives you access to the message after it has been converted but before it is sent. The -following example shows how to modify a message header and a property after a -`java.util.Map` is converted to a message: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public void sendWithConversion() { - Map map = new HashMap(); - map.put("Name", "Mark"); - map.put("Age", new Integer(47)); - jmsTemplate.convertAndSend("testQueue", map, new MessagePostProcessor() { - public Message postProcessMessage(Message message) throws JMSException { - message.setIntProperty("AccountID", 1234); - message.setJMSCorrelationID("123-00001"); - return message; - } - }); - } ----- - -This results in a message of the following form: - -[literal] -[subs="verbatim,quotes"] ----- -MapMessage={ - Header={ - ... standard headers ... - CorrelationID={123-00001} - } - Properties={ - AccountID={Integer:1234} - } - Fields={ - Name={String:Mark} - Age={Integer:47} - } -} ----- - - -[[jms-callbacks]] -=== Using `SessionCallback` and `ProducerCallback` - -While the send operations cover many common usage scenarios, you might sometimes -want to perform multiple operations on a JMS `Session` or `MessageProducer`. The -`SessionCallback` and `ProducerCallback` expose the JMS `Session` and `Session` / -`MessageProducer` pair, respectively. The `execute()` methods on `JmsTemplate` run -these callback methods. - - - -[[jms-receiving]] -== Receiving a Message - -This describes how to receive messages with JMS in Spring. - - -[[jms-receiving-sync]] -=== Synchronous Reception - -While JMS is typically associated with asynchronous processing, you can -consume messages synchronously. The overloaded `receive(..)` methods provide this -functionality. During a synchronous receive, the calling thread blocks until a message -becomes available. This can be a dangerous operation, since the calling thread can -potentially be blocked indefinitely. The `receiveTimeout` property specifies how long -the receiver should wait before giving up waiting for a message. - - -[[jms-receiving-async]] -=== Asynchronous reception: Message-Driven POJOs - -NOTE: Spring also supports annotated-listener endpoints through the use of the `@JmsListener` -annotation and provides an open infrastructure to register endpoints programmatically. -This is, by far, the most convenient way to setup an asynchronous receiver. -See <<jms-annotated-support>> for more details. - -In a fashion similar to a Message-Driven Bean (MDB) in the EJB world, the Message-Driven -POJO (MDP) acts as a receiver for JMS messages. The one restriction (but see -<<jms-receiving-async-message-listener-adapter>>) on an MDP is that it must implement -the `jakarta.jms.MessageListener` interface. Note that, if your POJO receives messages -on multiple threads, it is important to ensure that your implementation is thread-safe. - -The following example shows a simple implementation of an MDP: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - import jakarta.jms.JMSException; - import jakarta.jms.Message; - import jakarta.jms.MessageListener; - import jakarta.jms.TextMessage; - - public class ExampleListener implements MessageListener { - - public void onMessage(Message message) { - if (message instanceof TextMessage textMessage) { - try { - System.out.println(textMessage.getText()); - } - catch (JMSException ex) { - throw new RuntimeException(ex); - } - } - else { - throw new IllegalArgumentException("Message must be of type TextMessage"); - } - } - } ----- - -Once you have implemented your `MessageListener`, it is time to create a message listener -container. - -The following example shows how to define and configure one of the message listener -containers that ships with Spring (in this case, `DefaultMessageListenerContainer`): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <!-- this is the Message Driven POJO (MDP) --> - <bean id="messageListener" class="jmsexample.ExampleListener"/> - - <!-- and this is the message listener container --> - <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"> - <property name="connectionFactory" ref="connectionFactory"/> - <property name="destination" ref="destination"/> - <property name="messageListener" ref="messageListener"/> - </bean> ----- - -See the Spring javadoc of the various message listener containers (all of which implement -{api-spring-framework}/jms/listener/MessageListenerContainer.html[MessageListenerContainer]) -for a full description of the features supported by each implementation. - - -[[jms-receiving-async-session-aware-message-listener]] -=== Using the `SessionAwareMessageListener` Interface - -The `SessionAwareMessageListener` interface is a Spring-specific interface that provides -a similar contract to the JMS `MessageListener` interface but also gives the message-handling -method access to the JMS `Session` from which the `Message` was received. -The following listing shows the definition of the `SessionAwareMessageListener` interface: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.jms.listener; - - public interface SessionAwareMessageListener { - - void onMessage(Message message, Session session) throws JMSException; - } ----- - -You can choose to have your MDPs implement this interface (in preference to the standard -JMS `MessageListener` interface) if you want your MDPs to be able to respond to any -received messages (by using the `Session` supplied in the `onMessage(Message, Session)` -method). All of the message listener container implementations that ship with Spring -have support for MDPs that implement either the `MessageListener` or -`SessionAwareMessageListener` interface. Classes that implement the -`SessionAwareMessageListener` come with the caveat that they are then tied to Spring -through the interface. The choice of whether or not to use it is left entirely up to you -as an application developer or architect. - -Note that the `onMessage(..)` method of the `SessionAwareMessageListener` -interface throws `JMSException`. In contrast to the standard JMS `MessageListener` -interface, when using the `SessionAwareMessageListener` interface, it is the -responsibility of the client code to handle any thrown exceptions. - - -[[jms-receiving-async-message-listener-adapter]] -=== Using `MessageListenerAdapter` - -The `MessageListenerAdapter` class is the final component in Spring's asynchronous -messaging support. In a nutshell, it lets you expose almost any class as an MDP -(though there are some constraints). - -Consider the following interface definition: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface MessageDelegate { - - void handleMessage(String message); - - void handleMessage(Map message); - - void handleMessage(byte[] message); - - void handleMessage(Serializable message); - } ----- - -Notice that, although the interface extends neither the `MessageListener` nor the -`SessionAwareMessageListener` interface, you can still use it as an MDP by using the -`MessageListenerAdapter` class. Notice also how the various message handling methods are -strongly typed according to the contents of the various `Message` types that they can -receive and handle. - -Now consider the following implementation of the `MessageDelegate` interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public class DefaultMessageDelegate implements MessageDelegate { - // implementation elided for clarity... - } ----- - -In particular, note how the preceding implementation of the `MessageDelegate` interface (the -`DefaultMessageDelegate` class) has no JMS dependencies at all. It truly is a -POJO that we can make into an MDP through the following configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <!-- this is the Message Driven POJO (MDP) --> - <bean id="messageListener" class="org.springframework.jms.listener.adapter.MessageListenerAdapter"> - <constructor-arg> - <bean class="jmsexample.DefaultMessageDelegate"/> - </constructor-arg> - </bean> - - <!-- and this is the message listener container... --> - <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"> - <property name="connectionFactory" ref="connectionFactory"/> - <property name="destination" ref="destination"/> - <property name="messageListener" ref="messageListener"/> - </bean> ----- - -The next example shows another MDP that can handle only receiving JMS -`TextMessage` messages. Notice how the message handling method is actually called -`receive` (the name of the message handling method in a `MessageListenerAdapter` -defaults to `handleMessage`), but it is configurable (as you can see later in this section). Notice -also how the `receive(..)` method is strongly typed to receive and respond only to JMS -`TextMessage` messages. -The following listing shows the definition of the `TextMessageDelegate` interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface TextMessageDelegate { - - void receive(TextMessage message); - } ----- - -The following listing shows a class that implements the `TextMessageDelegate` interface: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public class DefaultTextMessageDelegate implements TextMessageDelegate { - // implementation elided for clarity... - } ----- - -The configuration of the attendant `MessageListenerAdapter` would then be as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="messageListener" class="org.springframework.jms.listener.adapter.MessageListenerAdapter"> - <constructor-arg> - <bean class="jmsexample.DefaultTextMessageDelegate"/> - </constructor-arg> - <property name="defaultListenerMethod" value="receive"/> - <!-- we don't want automatic message context extraction --> - <property name="messageConverter"> - <null/> - </property> - </bean> ----- - -Note that, if the `messageListener` receives a JMS `Message` of a type -other than `TextMessage`, an `IllegalStateException` is thrown (and subsequently -swallowed). Another of the capabilities of the `MessageListenerAdapter` class is the -ability to automatically send back a response `Message` if a handler method returns a -non-void value. Consider the following interface and class: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface ResponsiveTextMessageDelegate { - - // notice the return type... - String receive(TextMessage message); - } ----- - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public class DefaultResponsiveTextMessageDelegate implements ResponsiveTextMessageDelegate { - // implementation elided for clarity... - } ----- - -If you use the `DefaultResponsiveTextMessageDelegate` in conjunction with a -`MessageListenerAdapter`, any non-null value that is returned from the execution of -the `'receive(..)'` method is (in the default configuration) converted into a -`TextMessage`. The resulting `TextMessage` is then sent to the `Destination` (if -one exists) defined in the JMS `Reply-To` property of the original `Message` or the -default `Destination` set on the `MessageListenerAdapter` (if one has been configured). -If no `Destination` is found, an `InvalidDestinationException` is thrown -(note that this exception is not swallowed and propagates up the -call stack). - - -[[jms-tx-participation]] -=== Processing Messages Within Transactions - -Invoking a message listener within a transaction requires only reconfiguration of the -listener container. - -You can activate local resource transactions through the `sessionTransacted` flag -on the listener container definition. Each message listener invocation then operates -within an active JMS transaction, with message reception rolled back in case of listener -execution failure. Sending a response message (through `SessionAwareMessageListener`) is -part of the same local transaction, but any other resource operations (such as -database access) operate independently. This usually requires duplicate message -detection in the listener implementation, to cover the case where database processing -has committed but message processing failed to commit. - -Consider the following bean definition: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"> - <property name="connectionFactory" ref="connectionFactory"/> - <property name="destination" ref="destination"/> - <property name="messageListener" ref="messageListener"/> - <property name="sessionTransacted" value="true"/> - </bean> ----- - -To participate in an externally managed transaction, you need to configure a -transaction manager and use a listener container that supports externally managed -transactions (typically, `DefaultMessageListenerContainer`). - -To configure a message listener container for XA transaction participation, you want -to configure a `JtaTransactionManager` (which, by default, delegates to the Jakarta EE -server's transaction subsystem). Note that the underlying JMS `ConnectionFactory` needs to -be XA-capable and properly registered with your JTA transaction coordinator. (Check your -Jakarta EE server's configuration of JNDI resources.) This lets message reception as well -as (for example) database access be part of the same transaction (with unified commit -semantics, at the expense of XA transaction log overhead). - -The following bean definition creates a transaction manager: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="transactionManager" class="org.springframework.transaction.jta.JtaTransactionManager"/> ----- - -Then we need to add it to our earlier container configuration. The container -takes care of the rest. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"> - <property name="connectionFactory" ref="connectionFactory"/> - <property name="destination" ref="destination"/> - <property name="messageListener" ref="messageListener"/> - <property name="transactionManager" ref="transactionManager"/> <1> - </bean> ----- -<1> Our transaction manager. - - - -[[jms-jca-message-endpoint-manager]] -== Support for JCA Message Endpoints - -Beginning with version 2.5, Spring also provides support for a JCA-based -`MessageListener` container. The `JmsMessageEndpointManager` tries to -automatically determine the `ActivationSpec` class name from the provider's -`ResourceAdapter` class name. Therefore, it is typically possible to provide -Spring's generic `JmsActivationSpecConfig`, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean class="org.springframework.jms.listener.endpoint.JmsMessageEndpointManager"> - <property name="resourceAdapter" ref="resourceAdapter"/> - <property name="activationSpecConfig"> - <bean class="org.springframework.jms.listener.endpoint.JmsActivationSpecConfig"> - <property name="destinationName" value="myQueue"/> - </bean> - </property> - <property name="messageListener" ref="myMessageListener"/> - </bean> ----- - -Alternatively, you can set up a `JmsMessageEndpointManager` with a given -`ActivationSpec` object. The `ActivationSpec` object may also come from a JNDI lookup -(using `<jee:jndi-lookup>`). The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean class="org.springframework.jms.listener.endpoint.JmsMessageEndpointManager"> - <property name="resourceAdapter" ref="resourceAdapter"/> - <property name="activationSpec"> - <bean class="org.apache.activemq.ra.ActiveMQActivationSpec"> - <property name="destination" value="myQueue"/> - <property name="destinationType" value="jakarta.jms.Queue"/> - </bean> - </property> - <property name="messageListener" ref="myMessageListener"/> - </bean> ----- - -Using Spring's `ResourceAdapterFactoryBean`, you can configure the target `ResourceAdapter` -locally, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="resourceAdapter" class="org.springframework.jca.support.ResourceAdapterFactoryBean"> - <property name="resourceAdapter"> - <bean class="org.apache.activemq.ra.ActiveMQResourceAdapter"> - <property name="serverUrl" value="tcp://localhost:61616"/> - </bean> - </property> - <property name="workManager"> - <bean class="org.springframework.jca.work.SimpleTaskWorkManager"/> - </property> - </bean> ----- - -The specified `WorkManager` can also point to an environment-specific thread pool -- -typically through a `SimpleTaskWorkManager` instance's `asyncTaskExecutor` property. Consider -defining a shared thread pool for all your `ResourceAdapter` instances if you happen to -use multiple adapters. - -In some environments (such as WebLogic 9 or above), you can instead obtain the entire `ResourceAdapter` object -from JNDI (by using `<jee:jndi-lookup>`). The Spring-based message -listeners can then interact with the server-hosted `ResourceAdapter`, which also use the -server's built-in `WorkManager`. - -See the javadoc for {api-spring-framework}/jms/listener/endpoint/JmsMessageEndpointManager.html[`JmsMessageEndpointManager`], -{api-spring-framework}/jms/listener/endpoint/JmsActivationSpecConfig.html[`JmsActivationSpecConfig`], -and {api-spring-framework}/jca/support/ResourceAdapterFactoryBean.html[`ResourceAdapterFactoryBean`] -for more details. - -Spring also provides a generic JCA message endpoint manager that is not tied to JMS: -`org.springframework.jca.endpoint.GenericMessageEndpointManager`. This component allows -for using any message listener type (such as a JMS `MessageListener`) and any -provider-specific `ActivationSpec` object. See your JCA provider's documentation to -find out about the actual capabilities of your connector, and see the -{api-spring-framework}/jca/endpoint/GenericMessageEndpointManager.html[`GenericMessageEndpointManager`] -javadoc for the Spring-specific configuration details. - -NOTE: JCA-based message endpoint management is very analogous to EJB 2.1 Message-Driven Beans. -It uses the same underlying resource provider contract. As with EJB 2.1 MDBs, you can use any -message listener interface supported by your JCA provider in the Spring context as well. -Spring nevertheless provides explicit "`convenience`" support for JMS, because JMS is the -most common endpoint API used with the JCA endpoint management contract. - - - -[[jms-annotated]] -== Annotation-driven Listener Endpoints - -The easiest way to receive a message asynchronously is to use the annotated listener -endpoint infrastructure. In a nutshell, it lets you expose a method of a managed -bean as a JMS listener endpoint. The following example shows how to use it: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Component - public class MyService { - - @JmsListener(destination = "myDestination") - public void processOrder(String data) { ... } - } ----- - -The idea of the preceding example is that, whenever a message is available on the -`jakarta.jms.Destination` `myDestination`, the `processOrder` method is invoked -accordingly (in this case, with the content of the JMS message, similar to -what the <<jms-receiving-async-message-listener-adapter, `MessageListenerAdapter`>> -provides). - -The annotated endpoint infrastructure creates a message listener container -behind the scenes for each annotated method, by using a `JmsListenerContainerFactory`. -Such a container is not registered against the application context but can be easily -located for management purposes by using the `JmsListenerEndpointRegistry` bean. - -TIP: `@JmsListener` is a repeatable annotation on Java 8, so you can associate -several JMS destinations with the same method by adding additional `@JmsListener` -declarations to it. - - -[[jms-annotated-support]] -=== Enable Listener Endpoint Annotations - -To enable support for `@JmsListener` annotations, you can add `@EnableJms` to one of -your `@Configuration` classes, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableJms - public class AppConfig { - - @Bean - public DefaultJmsListenerContainerFactory jmsListenerContainerFactory() { - DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory(); - factory.setConnectionFactory(connectionFactory()); - factory.setDestinationResolver(destinationResolver()); - factory.setSessionTransacted(true); - factory.setConcurrency("3-10"); - return factory; - } - } ----- - -By default, the infrastructure looks for a bean named `jmsListenerContainerFactory` -as the source for the factory to use to create message listener containers. In this -case (and ignoring the JMS infrastructure setup), you can invoke the `processOrder` -method with a core poll size of three threads and a maximum pool size of ten threads. - -You can customize the listener container factory to use for each annotation or you can -configure an explicit default by implementing the `JmsListenerConfigurer` interface. -The default is required only if at least one endpoint is registered without a specific -container factory. See the javadoc of classes that implement -{api-spring-framework}/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`] -for details and examples. - -If you prefer <<jms-namespace, XML configuration>>, you can use the `<jms:annotation-driven>` -element, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <jms:annotation-driven/> - - <bean id="jmsListenerContainerFactory" - class="org.springframework.jms.config.DefaultJmsListenerContainerFactory"> - <property name="connectionFactory" ref="connectionFactory"/> - <property name="destinationResolver" ref="destinationResolver"/> - <property name="sessionTransacted" value="true"/> - <property name="concurrency" value="3-10"/> - </bean> ----- - - -[[jms-annotated-programmatic-registration]] -=== Programmatic Endpoint Registration - -`JmsListenerEndpoint` provides a model of a JMS endpoint and is responsible for configuring -the container for that model. The infrastructure lets you programmatically configure endpoints -in addition to the ones that are detected by the `JmsListener` annotation. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableJms - public class AppConfig implements JmsListenerConfigurer { - - @Override - public void configureJmsListeners(JmsListenerEndpointRegistrar registrar) { - SimpleJmsListenerEndpoint endpoint = new SimpleJmsListenerEndpoint(); - endpoint.setId("myJmsEndpoint"); - endpoint.setDestination("anotherQueue"); - endpoint.setMessageListener(message -> { - // processing - }); - registrar.registerEndpoint(endpoint); - } - } ----- - -In the preceding example, we used `SimpleJmsListenerEndpoint`, which provides the actual -`MessageListener` to invoke. However, you could also build your own endpoint variant -to describe a custom invocation mechanism. - -Note that you could skip the use of `@JmsListener` altogether -and programmatically register only your endpoints through `JmsListenerConfigurer`. - - -[[jms-annotated-method-signature]] -=== Annotated Endpoint Method Signature - -So far, we have been injecting a simple `String` in our endpoint, but it can actually -have a very flexible method signature. In the following example, we rewrite it to inject the `Order` with -a custom header: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Component - public class MyService { - - @JmsListener(destination = "myDestination") - public void processOrder(Order order, @Header("order_type") String orderType) { - ... - } - } ----- - -The main elements you can inject in JMS listener endpoints are as follows: - -* The raw `jakarta.jms.Message` or any of its subclasses (provided that it - matches the incoming message type). -* The `jakarta.jms.Session` for optional access to the native JMS API (for example, for sending - a custom reply). -* The `org.springframework.messaging.Message` that represents the incoming JMS message. - Note that this message holds both the custom and the standard headers (as defined - by `JmsHeaders`). -* `@Header`-annotated method arguments to extract a specific header value, including - standard JMS headers. -* A `@Headers`-annotated argument that must also be assignable to `java.util.Map` for - getting access to all headers. -* A non-annotated element that is not one of the supported types (`Message` or - `Session`) is considered to be the payload. You can make that explicit by annotating - the parameter with `@Payload`. You can also turn on validation by adding an extra - `@Valid`. - -The ability to inject Spring's `Message` abstraction is particularly useful to benefit -from all the information stored in the transport-specific message without relying on -transport-specific API. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @JmsListener(destination = "myDestination") - public void processOrder(Message<Order> order) { ... } ----- - -Handling of method arguments is provided by `DefaultMessageHandlerMethodFactory`, which you can -further customize to support additional method arguments. You can customize the conversion and validation -support there as well. - -For instance, if we want to make sure our `Order` is valid before processing it, we can -annotate the payload with `@Valid` and configure the necessary validator, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableJms - public class AppConfig implements JmsListenerConfigurer { - - @Override - public void configureJmsListeners(JmsListenerEndpointRegistrar registrar) { - registrar.setMessageHandlerMethodFactory(myJmsHandlerMethodFactory()); - } - - @Bean - public DefaultMessageHandlerMethodFactory myHandlerMethodFactory() { - DefaultMessageHandlerMethodFactory factory = new DefaultMessageHandlerMethodFactory(); - factory.setValidator(myValidator()); - return factory; - } - } ----- - - -[[jms-annotated-response]] -=== Response Management - -The existing support in <<jms-receiving-async-message-listener-adapter, `MessageListenerAdapter`>> -already lets your method have a non-`void` return type. When that is the case, the result of -the invocation is encapsulated in a `jakarta.jms.Message`, sent either in the destination specified -in the `JMSReplyTo` header of the original message or in the default destination configured on -the listener. You can now set that default destination by using the `@SendTo` annotation of the -messaging abstraction. - -Assuming that our `processOrder` method should now return an `OrderStatus`, we can write it -to automatically send a response, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @JmsListener(destination = "myDestination") - @SendTo("status") - public OrderStatus processOrder(Order order) { - // order processing - return status; - } ----- - -TIP: If you have several `@JmsListener`-annotated methods, you can also place the `@SendTo` -annotation at the class level to share a default reply destination. - -If you need to set additional headers in a transport-independent manner, you can return a -`Message` instead, with a method similar to the following: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @JmsListener(destination = "myDestination") - @SendTo("status") - public Message<OrderStatus> processOrder(Order order) { - // order processing - return MessageBuilder - .withPayload(status) - .setHeader("code", 1234) - .build(); - } ----- - -If you need to compute the response destination at runtime, you can encapsulate your response -in a `JmsResponse` instance that also provides the destination to use at runtime. We can rewrite the previous -example as follows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @JmsListener(destination = "myDestination") - public JmsResponse<Message<OrderStatus>> processOrder(Order order) { - // order processing - Message<OrderStatus> response = MessageBuilder - .withPayload(status) - .setHeader("code", 1234) - .build(); - return JmsResponse.forQueue(response, "status"); - } ----- - -Finally, if you need to specify some QoS values for the response such as the priority or -the time to live, you can configure the `JmsListenerContainerFactory` accordingly, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableJms - public class AppConfig { - - @Bean - public DefaultJmsListenerContainerFactory jmsListenerContainerFactory() { - DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory(); - factory.setConnectionFactory(connectionFactory()); - QosSettings replyQosSettings = new QosSettings(); - replyQosSettings.setPriority(2); - replyQosSettings.setTimeToLive(10000); - factory.setReplyQosSettings(replyQosSettings); - return factory; - } - } ----- - - - -[[jms-namespace]] -== JMS Namespace Support - -Spring provides an XML namespace for simplifying JMS configuration. To use the JMS -namespace elements, you need to reference the JMS schema, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <?xml version="1.0" encoding="UTF-8"?> - <beans xmlns="http://www.springframework.org/schema/beans" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xmlns:jms="http://www.springframework.org/schema/jms" <1> - xsi:schemaLocation=" - http://www.springframework.org/schema/beans - https://www.springframework.org/schema/beans/spring-beans.xsd - http://www.springframework.org/schema/jms - https://www.springframework.org/schema/jms/spring-jms.xsd"> - - <!-- bean definitions here --> - - </beans> ----- -<1> Referencing the JMS schema. - - -The namespace consists of three top-level elements: `<annotation-driven/>`, `<listener-container/>` -and `<jca-listener-container/>`. `<annotation-driven/>` enables the use of <<jms-annotated, -annotation-driven listener endpoints>>. `<listener-container/>` and `<jca-listener-container/>` -define shared listener container configuration and can contain `<listener/>` child elements. -The following example shows a basic configuration for two listeners: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <jms:listener-container> - - <jms:listener destination="queue.orders" ref="orderService" method="placeOrder"/> - - <jms:listener destination="queue.confirmations" ref="confirmationLogger" method="log"/> - - </jms:listener-container> ----- - -The preceding example is equivalent to creating two distinct listener container bean -definitions and two distinct `MessageListenerAdapter` bean definitions, as shown -in <<jms-receiving-async-message-listener-adapter>>. In addition to the attributes shown -in the preceding example, the `listener` element can contain several optional ones. -The following table describes all of the available attributes: - -[[jms-namespace-listener-tbl]] -.Attributes of the JMS <listener> element -[cols="1,6"] -|=== -| Attribute | Description - -| `id` -| A bean name for the hosting listener container. If not specified, a bean name is - automatically generated. - -| `destination` (required) -| The destination name for this listener, resolved through the `DestinationResolver` - strategy. - -| `ref` (required) -| The bean name of the handler object. - -| `method` -| The name of the handler method to invoke. If the `ref` attribute points to a `MessageListener` - or Spring `SessionAwareMessageListener`, you can omit this attribute. - -| `response-destination` -| The name of the default response destination to which to send response messages. This is - applied in case of a request message that does not carry a `JMSReplyTo` field. The - type of this destination is determined by the listener-container's - `response-destination-type` attribute. Note that this applies only to a listener method with a - return value, for which each result object is converted into a response message. - -| `subscription` -| The name of the durable subscription, if any. - -| `selector` -| An optional message selector for this listener. - -| `concurrency` -| The number of concurrent sessions or consumers to start for this listener. This value can either be - a simple number indicating the maximum number (for example, `5`) or a range indicating the lower - as well as the upper limit (for example, `3-5`). Note that a specified minimum is only a hint - and might be ignored at runtime. The default is the value provided by the container. -|=== - -The `<listener-container/>` element also accepts several optional attributes. This -allows for customization of the various strategies (for example, `taskExecutor` and -`destinationResolver`) as well as basic JMS settings and resource references. By using -these attributes, you can define highly-customized listener containers while -still benefiting from the convenience of the namespace. - -You can automatically expose such settings as a `JmsListenerContainerFactory` by -specifying the `id` of the bean to expose through the `factory-id` attribute, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <jms:listener-container connection-factory="myConnectionFactory" - task-executor="myTaskExecutor" - destination-resolver="myDestinationResolver" - transaction-manager="myTransactionManager" - concurrency="10"> - - <jms:listener destination="queue.orders" ref="orderService" method="placeOrder"/> - - <jms:listener destination="queue.confirmations" ref="confirmationLogger" method="log"/> - - </jms:listener-container> ----- - -The following table describes all available attributes. See the class-level javadoc -of the {api-spring-framework}/jms/listener/AbstractMessageListenerContainer.html[`AbstractMessageListenerContainer`] -and its concrete subclasses for more details on the individual properties. The javadoc -also provides a discussion of transaction choices and message redelivery scenarios. - -[[jms-namespace-listener-container-tbl]] -.Attributes of the JMS <listener-container> element -[cols="1,6"] -|=== -| Attribute | Description - -| `container-type` -| The type of this listener container. The available options are `default`, `simple`, - `default102`, or `simple102` (the default option is `default`). - -| `container-class` -| A custom listener container implementation class as a fully qualified class name. - The default is Spring's standard `DefaultMessageListenerContainer` or - `SimpleMessageListenerContainer`, according to the `container-type` attribute. - -| `factory-id` -| Exposes the settings defined by this element as a `JmsListenerContainerFactory` - with the specified `id` so that they can be reused with other endpoints. - -| `connection-factory` -| A reference to the JMS `ConnectionFactory` bean (the default bean name is - `connectionFactory`). - -| `task-executor` -| A reference to the Spring `TaskExecutor` for the JMS listener invokers. - -| `destination-resolver` -| A reference to the `DestinationResolver` strategy for resolving JMS `Destination` instances. - -| `message-converter` -| A reference to the `MessageConverter` strategy for converting JMS Messages to listener - method arguments. The default is a `SimpleMessageConverter`. - -| `error-handler` -| A reference to an `ErrorHandler` strategy for handling any uncaught exceptions that - may occur during the execution of the `MessageListener`. - -| `destination-type` -| The JMS destination type for this listener: `queue`, `topic`, `durableTopic`, `sharedTopic`, - or `sharedDurableTopic`. This potentially enables the `pubSubDomain`, `subscriptionDurable` - and `subscriptionShared` properties of the container. The default is `queue` (which disables - those three properties). - -| `response-destination-type` -| The JMS destination type for responses: `queue` or `topic`. The default is the value of the - `destination-type` attribute. - -| `client-id` -| The JMS client ID for this listener container. You must specify it when you use - durable subscriptions. - -| `cache` -| The cache level for JMS resources: `none`, `connection`, `session`, `consumer`, or - `auto`. By default (`auto`), the cache level is effectively `consumer`, unless - an external transaction manager has been specified -- in which case, the effective - default will be `none` (assuming Jakarta EE-style transaction management, where the given - ConnectionFactory is an XA-aware pool). - -| `acknowledge` -| The native JMS acknowledge mode: `auto`, `client`, `dups-ok`, or `transacted`. A value - of `transacted` activates a locally transacted `Session`. As an alternative, you can specify - the `transaction-manager` attribute, described later in table. The default is `auto`. - -| `transaction-manager` -| A reference to an external `PlatformTransactionManager` (typically an XA-based - transaction coordinator, such as Spring's `JtaTransactionManager`). If not specified, - native acknowledging is used (see the `acknowledge` attribute). - -| `concurrency` -| The number of concurrent sessions or consumers to start for each listener. It can either be - a simple number indicating the maximum number (for example, `5`) or a range indicating the - lower as well as the upper limit (for example, `3-5`). Note that a specified minimum is just a - hint and might be ignored at runtime. The default is `1`. You should keep concurrency limited to `1` in - case of a topic listener or if queue ordering is important. Consider raising it for - general queues. - -| `prefetch` -| The maximum number of messages to load into a single session. Note that raising this - number might lead to starvation of concurrent consumers. - -| `receive-timeout` -| The timeout (in milliseconds) to use for receive calls. The default is `1000` (one - second). `-1` indicates no timeout. - -| `back-off` -| Specifies the `BackOff` instance to use to compute the interval between recovery - attempts. If the `BackOffExecution` implementation returns `BackOffExecution#STOP`, - the listener container does not further try to recover. The `recovery-interval` - value is ignored when this property is set. The default is a `FixedBackOff` with - an interval of 5000 milliseconds (that is, five seconds). - -| `recovery-interval` -| Specifies the interval between recovery attempts, in milliseconds. It offers a convenient - way to create a `FixedBackOff` with the specified interval. For more recovery - options, consider specifying a `BackOff` instance instead. The default is 5000 milliseconds - (that is, five seconds). - -| `phase` -| The lifecycle phase within which this container should start and stop. The lower the - value, the earlier this container starts and the later it stops. The default is - `Integer.MAX_VALUE`, meaning that the container starts as late as possible and stops as - soon as possible. -|=== - -Configuring a JCA-based listener container with the `jms` schema support is very similar, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <jms:jca-listener-container resource-adapter="myResourceAdapter" - destination-resolver="myDestinationResolver" - transaction-manager="myTransactionManager" - concurrency="10"> - - <jms:listener destination="queue.orders" ref="myMessageListener"/> - - </jms:jca-listener-container> ----- - -The following table describes the available configuration options for the JCA variant: - -[[jms-namespace-jca-listener-container-tbl]] -.Attributes of the JMS <jca-listener-container/> element -[cols="1,6"] -|=== -| Attribute | Description - -| `factory-id` -| Exposes the settings defined by this element as a `JmsListenerContainerFactory` - with the specified `id` so that they can be reused with other endpoints. - -| `resource-adapter` -| A reference to the JCA `ResourceAdapter` bean (the default bean name is - `resourceAdapter`). - -| `activation-spec-factory` -| A reference to the `JmsActivationSpecFactory`. The default is to autodetect the JMS - provider and its `ActivationSpec` class (see {api-spring-framework}/jms/listener/endpoint/DefaultJmsActivationSpecFactory.html[`DefaultJmsActivationSpecFactory`]). - -| `destination-resolver` -| A reference to the `DestinationResolver` strategy for resolving JMS `Destinations`. - -| `message-converter` -| A reference to the `MessageConverter` strategy for converting JMS Messages to listener - method arguments. The default is `SimpleMessageConverter`. - -| `destination-type` -| The JMS destination type for this listener: `queue`, `topic`, `durableTopic`, `sharedTopic`. - or `sharedDurableTopic`. This potentially enables the `pubSubDomain`, `subscriptionDurable`, - and `subscriptionShared` properties of the container. The default is `queue` (which disables - those three properties). - -| `response-destination-type` -| The JMS destination type for responses: `queue` or `topic`. The default is the value of the - `destination-type` attribute. - -| `client-id` -| The JMS client ID for this listener container. It needs to be specified when using - durable subscriptions. - -| `acknowledge` -| The native JMS acknowledge mode: `auto`, `client`, `dups-ok`, or `transacted`. A value - of `transacted` activates a locally transacted `Session`. As an alternative, you can specify - the `transaction-manager` attribute described later. The default is `auto`. - -| `transaction-manager` -| A reference to a Spring `JtaTransactionManager` or a - `jakarta.transaction.TransactionManager` for kicking off an XA transaction for each - incoming message. If not specified, native acknowledging is used (see the - `acknowledge` attribute). - -| `concurrency` -| The number of concurrent sessions or consumers to start for each listener. It can either be - a simple number indicating the maximum number (for example `5`) or a range indicating the - lower as well as the upper limit (for example, `3-5`). Note that a specified minimum is only a - hint and is typically ignored at runtime when you use a JCA listener container. - The default is 1. - -| `prefetch` -| The maximum number of messages to load into a single session. Note that raising this - number might lead to starvation of concurrent consumers. -|=== diff --git a/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc b/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc new file mode 100644 index 000000000000..e42387063a25 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc @@ -0,0 +1,280 @@ +[[jms-annotated]] += Annotation-driven Listener Endpoints + +The easiest way to receive a message asynchronously is to use the annotated listener +endpoint infrastructure. In a nutshell, it lets you expose a method of a managed +bean as a JMS listener endpoint. The following example shows how to use it: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Component + public class MyService { + + @JmsListener(destination = "myDestination") + public void processOrder(String data) { ... } + } +---- + +The idea of the preceding example is that, whenever a message is available on the +`jakarta.jms.Destination` `myDestination`, the `processOrder` method is invoked +accordingly (in this case, with the content of the JMS message, similar to +what the <<jms-receiving-async-message-listener-adapter, `MessageListenerAdapter`>> +provides). + +The annotated endpoint infrastructure creates a message listener container +behind the scenes for each annotated method, by using a `JmsListenerContainerFactory`. +Such a container is not registered against the application context but can be easily +located for management purposes by using the `JmsListenerEndpointRegistry` bean. + +TIP: `@JmsListener` is a repeatable annotation on Java 8, so you can associate +several JMS destinations with the same method by adding additional `@JmsListener` +declarations to it. + + +[[jms-annotated-support]] +== Enable Listener Endpoint Annotations + +To enable support for `@JmsListener` annotations, you can add `@EnableJms` to one of +your `@Configuration` classes, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableJms + public class AppConfig { + + @Bean + public DefaultJmsListenerContainerFactory jmsListenerContainerFactory() { + DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory(); + factory.setConnectionFactory(connectionFactory()); + factory.setDestinationResolver(destinationResolver()); + factory.setSessionTransacted(true); + factory.setConcurrency("3-10"); + return factory; + } + } +---- + +By default, the infrastructure looks for a bean named `jmsListenerContainerFactory` +as the source for the factory to use to create message listener containers. In this +case (and ignoring the JMS infrastructure setup), you can invoke the `processOrder` +method with a core poll size of three threads and a maximum pool size of ten threads. + +You can customize the listener container factory to use for each annotation or you can +configure an explicit default by implementing the `JmsListenerConfigurer` interface. +The default is required only if at least one endpoint is registered without a specific +container factory. See the javadoc of classes that implement +{api-spring-framework}/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`] +for details and examples. + +If you prefer <<jms-namespace, XML configuration>>, you can use the `<jms:annotation-driven>` +element, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <jms:annotation-driven/> + + <bean id="jmsListenerContainerFactory" + class="org.springframework.jms.config.DefaultJmsListenerContainerFactory"> + <property name="connectionFactory" ref="connectionFactory"/> + <property name="destinationResolver" ref="destinationResolver"/> + <property name="sessionTransacted" value="true"/> + <property name="concurrency" value="3-10"/> + </bean> +---- + + +[[jms-annotated-programmatic-registration]] +== Programmatic Endpoint Registration + +`JmsListenerEndpoint` provides a model of a JMS endpoint and is responsible for configuring +the container for that model. The infrastructure lets you programmatically configure endpoints +in addition to the ones that are detected by the `JmsListener` annotation. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableJms + public class AppConfig implements JmsListenerConfigurer { + + @Override + public void configureJmsListeners(JmsListenerEndpointRegistrar registrar) { + SimpleJmsListenerEndpoint endpoint = new SimpleJmsListenerEndpoint(); + endpoint.setId("myJmsEndpoint"); + endpoint.setDestination("anotherQueue"); + endpoint.setMessageListener(message -> { + // processing + }); + registrar.registerEndpoint(endpoint); + } + } +---- + +In the preceding example, we used `SimpleJmsListenerEndpoint`, which provides the actual +`MessageListener` to invoke. However, you could also build your own endpoint variant +to describe a custom invocation mechanism. + +Note that you could skip the use of `@JmsListener` altogether +and programmatically register only your endpoints through `JmsListenerConfigurer`. + + +[[jms-annotated-method-signature]] +== Annotated Endpoint Method Signature + +So far, we have been injecting a simple `String` in our endpoint, but it can actually +have a very flexible method signature. In the following example, we rewrite it to inject the `Order` with +a custom header: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Component + public class MyService { + + @JmsListener(destination = "myDestination") + public void processOrder(Order order, @Header("order_type") String orderType) { + ... + } + } +---- + +The main elements you can inject in JMS listener endpoints are as follows: + +* The raw `jakarta.jms.Message` or any of its subclasses (provided that it + matches the incoming message type). +* The `jakarta.jms.Session` for optional access to the native JMS API (for example, for sending + a custom reply). +* The `org.springframework.messaging.Message` that represents the incoming JMS message. + Note that this message holds both the custom and the standard headers (as defined + by `JmsHeaders`). +* `@Header`-annotated method arguments to extract a specific header value, including + standard JMS headers. +* A `@Headers`-annotated argument that must also be assignable to `java.util.Map` for + getting access to all headers. +* A non-annotated element that is not one of the supported types (`Message` or + `Session`) is considered to be the payload. You can make that explicit by annotating + the parameter with `@Payload`. You can also turn on validation by adding an extra + `@Valid`. + +The ability to inject Spring's `Message` abstraction is particularly useful to benefit +from all the information stored in the transport-specific message without relying on +transport-specific API. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @JmsListener(destination = "myDestination") + public void processOrder(Message<Order> order) { ... } +---- + +Handling of method arguments is provided by `DefaultMessageHandlerMethodFactory`, which you can +further customize to support additional method arguments. You can customize the conversion and validation +support there as well. + +For instance, if we want to make sure our `Order` is valid before processing it, we can +annotate the payload with `@Valid` and configure the necessary validator, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableJms + public class AppConfig implements JmsListenerConfigurer { + + @Override + public void configureJmsListeners(JmsListenerEndpointRegistrar registrar) { + registrar.setMessageHandlerMethodFactory(myJmsHandlerMethodFactory()); + } + + @Bean + public DefaultMessageHandlerMethodFactory myHandlerMethodFactory() { + DefaultMessageHandlerMethodFactory factory = new DefaultMessageHandlerMethodFactory(); + factory.setValidator(myValidator()); + return factory; + } + } +---- + + +[[jms-annotated-response]] +== Response Management + +The existing support in <<jms-receiving-async-message-listener-adapter, `MessageListenerAdapter`>> +already lets your method have a non-`void` return type. When that is the case, the result of +the invocation is encapsulated in a `jakarta.jms.Message`, sent either in the destination specified +in the `JMSReplyTo` header of the original message or in the default destination configured on +the listener. You can now set that default destination by using the `@SendTo` annotation of the +messaging abstraction. + +Assuming that our `processOrder` method should now return an `OrderStatus`, we can write it +to automatically send a response, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @JmsListener(destination = "myDestination") + @SendTo("status") + public OrderStatus processOrder(Order order) { + // order processing + return status; + } +---- + +TIP: If you have several `@JmsListener`-annotated methods, you can also place the `@SendTo` +annotation at the class level to share a default reply destination. + +If you need to set additional headers in a transport-independent manner, you can return a +`Message` instead, with a method similar to the following: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @JmsListener(destination = "myDestination") + @SendTo("status") + public Message<OrderStatus> processOrder(Order order) { + // order processing + return MessageBuilder + .withPayload(status) + .setHeader("code", 1234) + .build(); + } +---- + +If you need to compute the response destination at runtime, you can encapsulate your response +in a `JmsResponse` instance that also provides the destination to use at runtime. We can rewrite the previous +example as follows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @JmsListener(destination = "myDestination") + public JmsResponse<Message<OrderStatus>> processOrder(Order order) { + // order processing + Message<OrderStatus> response = MessageBuilder + .withPayload(status) + .setHeader("code", 1234) + .build(); + return JmsResponse.forQueue(response, "status"); + } +---- + +Finally, if you need to specify some QoS values for the response such as the priority or +the time to live, you can configure the `JmsListenerContainerFactory` accordingly, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableJms + public class AppConfig { + + @Bean + public DefaultJmsListenerContainerFactory jmsListenerContainerFactory() { + DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory(); + factory.setConnectionFactory(connectionFactory()); + QosSettings replyQosSettings = new QosSettings(); + replyQosSettings.setPriority(2); + replyQosSettings.setTimeToLive(10000); + factory.setReplyQosSettings(replyQosSettings); + return factory; + } + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jms/jca-message-endpoint-manager.adoc b/framework-docs/modules/ROOT/pages/integration/jms/jca-message-endpoint-manager.adoc new file mode 100644 index 000000000000..a36d935806ca --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jms/jca-message-endpoint-manager.adoc @@ -0,0 +1,88 @@ +[[jms-jca-message-endpoint-manager]] += Support for JCA Message Endpoints + +Beginning with version 2.5, Spring also provides support for a JCA-based +`MessageListener` container. The `JmsMessageEndpointManager` tries to +automatically determine the `ActivationSpec` class name from the provider's +`ResourceAdapter` class name. Therefore, it is typically possible to provide +Spring's generic `JmsActivationSpecConfig`, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean class="org.springframework.jms.listener.endpoint.JmsMessageEndpointManager"> + <property name="resourceAdapter" ref="resourceAdapter"/> + <property name="activationSpecConfig"> + <bean class="org.springframework.jms.listener.endpoint.JmsActivationSpecConfig"> + <property name="destinationName" value="myQueue"/> + </bean> + </property> + <property name="messageListener" ref="myMessageListener"/> + </bean> +---- + +Alternatively, you can set up a `JmsMessageEndpointManager` with a given +`ActivationSpec` object. The `ActivationSpec` object may also come from a JNDI lookup +(using `<jee:jndi-lookup>`). The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean class="org.springframework.jms.listener.endpoint.JmsMessageEndpointManager"> + <property name="resourceAdapter" ref="resourceAdapter"/> + <property name="activationSpec"> + <bean class="org.apache.activemq.ra.ActiveMQActivationSpec"> + <property name="destination" value="myQueue"/> + <property name="destinationType" value="jakarta.jms.Queue"/> + </bean> + </property> + <property name="messageListener" ref="myMessageListener"/> + </bean> +---- + +Using Spring's `ResourceAdapterFactoryBean`, you can configure the target `ResourceAdapter` +locally, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="resourceAdapter" class="org.springframework.jca.support.ResourceAdapterFactoryBean"> + <property name="resourceAdapter"> + <bean class="org.apache.activemq.ra.ActiveMQResourceAdapter"> + <property name="serverUrl" value="tcp://localhost:61616"/> + </bean> + </property> + <property name="workManager"> + <bean class="org.springframework.jca.work.SimpleTaskWorkManager"/> + </property> + </bean> +---- + +The specified `WorkManager` can also point to an environment-specific thread pool -- +typically through a `SimpleTaskWorkManager` instance's `asyncTaskExecutor` property. Consider +defining a shared thread pool for all your `ResourceAdapter` instances if you happen to +use multiple adapters. + +In some environments (such as WebLogic 9 or above), you can instead obtain the entire `ResourceAdapter` object +from JNDI (by using `<jee:jndi-lookup>`). The Spring-based message +listeners can then interact with the server-hosted `ResourceAdapter`, which also use the +server's built-in `WorkManager`. + +See the javadoc for {api-spring-framework}/jms/listener/endpoint/JmsMessageEndpointManager.html[`JmsMessageEndpointManager`], +{api-spring-framework}/jms/listener/endpoint/JmsActivationSpecConfig.html[`JmsActivationSpecConfig`], +and {api-spring-framework}/jca/support/ResourceAdapterFactoryBean.html[`ResourceAdapterFactoryBean`] +for more details. + +Spring also provides a generic JCA message endpoint manager that is not tied to JMS: +`org.springframework.jca.endpoint.GenericMessageEndpointManager`. This component allows +for using any message listener type (such as a JMS `MessageListener`) and any +provider-specific `ActivationSpec` object. See your JCA provider's documentation to +find out about the actual capabilities of your connector, and see the +{api-spring-framework}/jca/endpoint/GenericMessageEndpointManager.html[`GenericMessageEndpointManager`] +javadoc for the Spring-specific configuration details. + +NOTE: JCA-based message endpoint management is very analogous to EJB 2.1 Message-Driven Beans. +It uses the same underlying resource provider contract. As with EJB 2.1 MDBs, you can use any +message listener interface supported by your JCA provider in the Spring context as well. +Spring nevertheless provides explicit "`convenience`" support for JMS, because JMS is the +most common endpoint API used with the JCA endpoint management contract. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc b/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc new file mode 100644 index 000000000000..b6e2f580e0da --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc @@ -0,0 +1,301 @@ +[[jms-namespace]] += JMS Namespace Support + +Spring provides an XML namespace for simplifying JMS configuration. To use the JMS +namespace elements, you need to reference the JMS schema, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:jms="http://www.springframework.org/schema/jms" <1> + xsi:schemaLocation=" + http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/jms + https://www.springframework.org/schema/jms/spring-jms.xsd"> + + <!-- bean definitions here --> + + </beans> +---- +<1> Referencing the JMS schema. + + +The namespace consists of three top-level elements: `<annotation-driven/>`, `<listener-container/>` +and `<jca-listener-container/>`. `<annotation-driven/>` enables the use of <<jms-annotated, +annotation-driven listener endpoints>>. `<listener-container/>` and `<jca-listener-container/>` +define shared listener container configuration and can contain `<listener/>` child elements. +The following example shows a basic configuration for two listeners: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <jms:listener-container> + + <jms:listener destination="queue.orders" ref="orderService" method="placeOrder"/> + + <jms:listener destination="queue.confirmations" ref="confirmationLogger" method="log"/> + + </jms:listener-container> +---- + +The preceding example is equivalent to creating two distinct listener container bean +definitions and two distinct `MessageListenerAdapter` bean definitions, as shown +in <<jms-receiving-async-message-listener-adapter>>. In addition to the attributes shown +in the preceding example, the `listener` element can contain several optional ones. +The following table describes all of the available attributes: + +[[jms-namespace-listener-tbl]] +.Attributes of the JMS <listener> element +[cols="1,6"] +|=== +| Attribute | Description + +| `id` +| A bean name for the hosting listener container. If not specified, a bean name is + automatically generated. + +| `destination` (required) +| The destination name for this listener, resolved through the `DestinationResolver` + strategy. + +| `ref` (required) +| The bean name of the handler object. + +| `method` +| The name of the handler method to invoke. If the `ref` attribute points to a `MessageListener` + or Spring `SessionAwareMessageListener`, you can omit this attribute. + +| `response-destination` +| The name of the default response destination to which to send response messages. This is + applied in case of a request message that does not carry a `JMSReplyTo` field. The + type of this destination is determined by the listener-container's + `response-destination-type` attribute. Note that this applies only to a listener method with a + return value, for which each result object is converted into a response message. + +| `subscription` +| The name of the durable subscription, if any. + +| `selector` +| An optional message selector for this listener. + +| `concurrency` +| The number of concurrent sessions or consumers to start for this listener. This value can either be + a simple number indicating the maximum number (for example, `5`) or a range indicating the lower + as well as the upper limit (for example, `3-5`). Note that a specified minimum is only a hint + and might be ignored at runtime. The default is the value provided by the container. +|=== + +The `<listener-container/>` element also accepts several optional attributes. This +allows for customization of the various strategies (for example, `taskExecutor` and +`destinationResolver`) as well as basic JMS settings and resource references. By using +these attributes, you can define highly-customized listener containers while +still benefiting from the convenience of the namespace. + +You can automatically expose such settings as a `JmsListenerContainerFactory` by +specifying the `id` of the bean to expose through the `factory-id` attribute, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <jms:listener-container connection-factory="myConnectionFactory" + task-executor="myTaskExecutor" + destination-resolver="myDestinationResolver" + transaction-manager="myTransactionManager" + concurrency="10"> + + <jms:listener destination="queue.orders" ref="orderService" method="placeOrder"/> + + <jms:listener destination="queue.confirmations" ref="confirmationLogger" method="log"/> + + </jms:listener-container> +---- + +The following table describes all available attributes. See the class-level javadoc +of the {api-spring-framework}/jms/listener/AbstractMessageListenerContainer.html[`AbstractMessageListenerContainer`] +and its concrete subclasses for more details on the individual properties. The javadoc +also provides a discussion of transaction choices and message redelivery scenarios. + +[[jms-namespace-listener-container-tbl]] +.Attributes of the JMS <listener-container> element +[cols="1,6"] +|=== +| Attribute | Description + +| `container-type` +| The type of this listener container. The available options are `default`, `simple`, + `default102`, or `simple102` (the default option is `default`). + +| `container-class` +| A custom listener container implementation class as a fully qualified class name. + The default is Spring's standard `DefaultMessageListenerContainer` or + `SimpleMessageListenerContainer`, according to the `container-type` attribute. + +| `factory-id` +| Exposes the settings defined by this element as a `JmsListenerContainerFactory` + with the specified `id` so that they can be reused with other endpoints. + +| `connection-factory` +| A reference to the JMS `ConnectionFactory` bean (the default bean name is + `connectionFactory`). + +| `task-executor` +| A reference to the Spring `TaskExecutor` for the JMS listener invokers. + +| `destination-resolver` +| A reference to the `DestinationResolver` strategy for resolving JMS `Destination` instances. + +| `message-converter` +| A reference to the `MessageConverter` strategy for converting JMS Messages to listener + method arguments. The default is a `SimpleMessageConverter`. + +| `error-handler` +| A reference to an `ErrorHandler` strategy for handling any uncaught exceptions that + may occur during the execution of the `MessageListener`. + +| `destination-type` +| The JMS destination type for this listener: `queue`, `topic`, `durableTopic`, `sharedTopic`, + or `sharedDurableTopic`. This potentially enables the `pubSubDomain`, `subscriptionDurable` + and `subscriptionShared` properties of the container. The default is `queue` (which disables + those three properties). + +| `response-destination-type` +| The JMS destination type for responses: `queue` or `topic`. The default is the value of the + `destination-type` attribute. + +| `client-id` +| The JMS client ID for this listener container. You must specify it when you use + durable subscriptions. + +| `cache` +| The cache level for JMS resources: `none`, `connection`, `session`, `consumer`, or + `auto`. By default (`auto`), the cache level is effectively `consumer`, unless + an external transaction manager has been specified -- in which case, the effective + default will be `none` (assuming Jakarta EE-style transaction management, where the given + ConnectionFactory is an XA-aware pool). + +| `acknowledge` +| The native JMS acknowledge mode: `auto`, `client`, `dups-ok`, or `transacted`. A value + of `transacted` activates a locally transacted `Session`. As an alternative, you can specify + the `transaction-manager` attribute, described later in table. The default is `auto`. + +| `transaction-manager` +| A reference to an external `PlatformTransactionManager` (typically an XA-based + transaction coordinator, such as Spring's `JtaTransactionManager`). If not specified, + native acknowledging is used (see the `acknowledge` attribute). + +| `concurrency` +| The number of concurrent sessions or consumers to start for each listener. It can either be + a simple number indicating the maximum number (for example, `5`) or a range indicating the + lower as well as the upper limit (for example, `3-5`). Note that a specified minimum is just a + hint and might be ignored at runtime. The default is `1`. You should keep concurrency limited to `1` in + case of a topic listener or if queue ordering is important. Consider raising it for + general queues. + +| `prefetch` +| The maximum number of messages to load into a single session. Note that raising this + number might lead to starvation of concurrent consumers. + +| `receive-timeout` +| The timeout (in milliseconds) to use for receive calls. The default is `1000` (one + second). `-1` indicates no timeout. + +| `back-off` +| Specifies the `BackOff` instance to use to compute the interval between recovery + attempts. If the `BackOffExecution` implementation returns `BackOffExecution#STOP`, + the listener container does not further try to recover. The `recovery-interval` + value is ignored when this property is set. The default is a `FixedBackOff` with + an interval of 5000 milliseconds (that is, five seconds). + +| `recovery-interval` +| Specifies the interval between recovery attempts, in milliseconds. It offers a convenient + way to create a `FixedBackOff` with the specified interval. For more recovery + options, consider specifying a `BackOff` instance instead. The default is 5000 milliseconds + (that is, five seconds). + +| `phase` +| The lifecycle phase within which this container should start and stop. The lower the + value, the earlier this container starts and the later it stops. The default is + `Integer.MAX_VALUE`, meaning that the container starts as late as possible and stops as + soon as possible. +|=== + +Configuring a JCA-based listener container with the `jms` schema support is very similar, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <jms:jca-listener-container resource-adapter="myResourceAdapter" + destination-resolver="myDestinationResolver" + transaction-manager="myTransactionManager" + concurrency="10"> + + <jms:listener destination="queue.orders" ref="myMessageListener"/> + + </jms:jca-listener-container> +---- + +The following table describes the available configuration options for the JCA variant: + +[[jms-namespace-jca-listener-container-tbl]] +.Attributes of the JMS <jca-listener-container/> element +[cols="1,6"] +|=== +| Attribute | Description + +| `factory-id` +| Exposes the settings defined by this element as a `JmsListenerContainerFactory` + with the specified `id` so that they can be reused with other endpoints. + +| `resource-adapter` +| A reference to the JCA `ResourceAdapter` bean (the default bean name is + `resourceAdapter`). + +| `activation-spec-factory` +| A reference to the `JmsActivationSpecFactory`. The default is to autodetect the JMS + provider and its `ActivationSpec` class (see {api-spring-framework}/jms/listener/endpoint/DefaultJmsActivationSpecFactory.html[`DefaultJmsActivationSpecFactory`]). + +| `destination-resolver` +| A reference to the `DestinationResolver` strategy for resolving JMS `Destinations`. + +| `message-converter` +| A reference to the `MessageConverter` strategy for converting JMS Messages to listener + method arguments. The default is `SimpleMessageConverter`. + +| `destination-type` +| The JMS destination type for this listener: `queue`, `topic`, `durableTopic`, `sharedTopic`. + or `sharedDurableTopic`. This potentially enables the `pubSubDomain`, `subscriptionDurable`, + and `subscriptionShared` properties of the container. The default is `queue` (which disables + those three properties). + +| `response-destination-type` +| The JMS destination type for responses: `queue` or `topic`. The default is the value of the + `destination-type` attribute. + +| `client-id` +| The JMS client ID for this listener container. It needs to be specified when using + durable subscriptions. + +| `acknowledge` +| The native JMS acknowledge mode: `auto`, `client`, `dups-ok`, or `transacted`. A value + of `transacted` activates a locally transacted `Session`. As an alternative, you can specify + the `transaction-manager` attribute described later. The default is `auto`. + +| `transaction-manager` +| A reference to a Spring `JtaTransactionManager` or a + `jakarta.transaction.TransactionManager` for kicking off an XA transaction for each + incoming message. If not specified, native acknowledging is used (see the + `acknowledge` attribute). + +| `concurrency` +| The number of concurrent sessions or consumers to start for each listener. It can either be + a simple number indicating the maximum number (for example `5`) or a range indicating the + lower as well as the upper limit (for example, `3-5`). Note that a specified minimum is only a + hint and is typically ignored at runtime when you use a JCA listener container. + The default is 1. + +| `prefetch` +| The maximum number of messages to load into a single session. Note that raising this + number might lead to starvation of concurrent consumers. +|=== diff --git a/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc b/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc new file mode 100644 index 000000000000..72658c5464b6 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc @@ -0,0 +1,311 @@ +[[jms-receiving]] += Receiving a Message + +This describes how to receive messages with JMS in Spring. + + +[[jms-receiving-sync]] +== Synchronous Reception + +While JMS is typically associated with asynchronous processing, you can +consume messages synchronously. The overloaded `receive(..)` methods provide this +functionality. During a synchronous receive, the calling thread blocks until a message +becomes available. This can be a dangerous operation, since the calling thread can +potentially be blocked indefinitely. The `receiveTimeout` property specifies how long +the receiver should wait before giving up waiting for a message. + + +[[jms-receiving-async]] +== Asynchronous reception: Message-Driven POJOs + +NOTE: Spring also supports annotated-listener endpoints through the use of the `@JmsListener` +annotation and provides an open infrastructure to register endpoints programmatically. +This is, by far, the most convenient way to setup an asynchronous receiver. +See <<jms-annotated-support>> for more details. + +In a fashion similar to a Message-Driven Bean (MDB) in the EJB world, the Message-Driven +POJO (MDP) acts as a receiver for JMS messages. The one restriction (but see +<<jms-receiving-async-message-listener-adapter>>) on an MDP is that it must implement +the `jakarta.jms.MessageListener` interface. Note that, if your POJO receives messages +on multiple threads, it is important to ensure that your implementation is thread-safe. + +The following example shows a simple implementation of an MDP: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + import jakarta.jms.JMSException; + import jakarta.jms.Message; + import jakarta.jms.MessageListener; + import jakarta.jms.TextMessage; + + public class ExampleListener implements MessageListener { + + public void onMessage(Message message) { + if (message instanceof TextMessage textMessage) { + try { + System.out.println(textMessage.getText()); + } + catch (JMSException ex) { + throw new RuntimeException(ex); + } + } + else { + throw new IllegalArgumentException("Message must be of type TextMessage"); + } + } + } +---- + +Once you have implemented your `MessageListener`, it is time to create a message listener +container. + +The following example shows how to define and configure one of the message listener +containers that ships with Spring (in this case, `DefaultMessageListenerContainer`): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <!-- this is the Message Driven POJO (MDP) --> + <bean id="messageListener" class="jmsexample.ExampleListener"/> + + <!-- and this is the message listener container --> + <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"> + <property name="connectionFactory" ref="connectionFactory"/> + <property name="destination" ref="destination"/> + <property name="messageListener" ref="messageListener"/> + </bean> +---- + +See the Spring javadoc of the various message listener containers (all of which implement +{api-spring-framework}/jms/listener/MessageListenerContainer.html[MessageListenerContainer]) +for a full description of the features supported by each implementation. + + +[[jms-receiving-async-session-aware-message-listener]] +== Using the `SessionAwareMessageListener` Interface + +The `SessionAwareMessageListener` interface is a Spring-specific interface that provides +a similar contract to the JMS `MessageListener` interface but also gives the message-handling +method access to the JMS `Session` from which the `Message` was received. +The following listing shows the definition of the `SessionAwareMessageListener` interface: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.jms.listener; + + public interface SessionAwareMessageListener { + + void onMessage(Message message, Session session) throws JMSException; + } +---- + +You can choose to have your MDPs implement this interface (in preference to the standard +JMS `MessageListener` interface) if you want your MDPs to be able to respond to any +received messages (by using the `Session` supplied in the `onMessage(Message, Session)` +method). All of the message listener container implementations that ship with Spring +have support for MDPs that implement either the `MessageListener` or +`SessionAwareMessageListener` interface. Classes that implement the +`SessionAwareMessageListener` come with the caveat that they are then tied to Spring +through the interface. The choice of whether or not to use it is left entirely up to you +as an application developer or architect. + +Note that the `onMessage(..)` method of the `SessionAwareMessageListener` +interface throws `JMSException`. In contrast to the standard JMS `MessageListener` +interface, when using the `SessionAwareMessageListener` interface, it is the +responsibility of the client code to handle any thrown exceptions. + + +[[jms-receiving-async-message-listener-adapter]] +== Using `MessageListenerAdapter` + +The `MessageListenerAdapter` class is the final component in Spring's asynchronous +messaging support. In a nutshell, it lets you expose almost any class as an MDP +(though there are some constraints). + +Consider the following interface definition: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface MessageDelegate { + + void handleMessage(String message); + + void handleMessage(Map message); + + void handleMessage(byte[] message); + + void handleMessage(Serializable message); + } +---- + +Notice that, although the interface extends neither the `MessageListener` nor the +`SessionAwareMessageListener` interface, you can still use it as an MDP by using the +`MessageListenerAdapter` class. Notice also how the various message handling methods are +strongly typed according to the contents of the various `Message` types that they can +receive and handle. + +Now consider the following implementation of the `MessageDelegate` interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public class DefaultMessageDelegate implements MessageDelegate { + // implementation elided for clarity... + } +---- + +In particular, note how the preceding implementation of the `MessageDelegate` interface (the +`DefaultMessageDelegate` class) has no JMS dependencies at all. It truly is a +POJO that we can make into an MDP through the following configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <!-- this is the Message Driven POJO (MDP) --> + <bean id="messageListener" class="org.springframework.jms.listener.adapter.MessageListenerAdapter"> + <constructor-arg> + <bean class="jmsexample.DefaultMessageDelegate"/> + </constructor-arg> + </bean> + + <!-- and this is the message listener container... --> + <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"> + <property name="connectionFactory" ref="connectionFactory"/> + <property name="destination" ref="destination"/> + <property name="messageListener" ref="messageListener"/> + </bean> +---- + +The next example shows another MDP that can handle only receiving JMS +`TextMessage` messages. Notice how the message handling method is actually called +`receive` (the name of the message handling method in a `MessageListenerAdapter` +defaults to `handleMessage`), but it is configurable (as you can see later in this section). Notice +also how the `receive(..)` method is strongly typed to receive and respond only to JMS +`TextMessage` messages. +The following listing shows the definition of the `TextMessageDelegate` interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface TextMessageDelegate { + + void receive(TextMessage message); + } +---- + +The following listing shows a class that implements the `TextMessageDelegate` interface: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public class DefaultTextMessageDelegate implements TextMessageDelegate { + // implementation elided for clarity... + } +---- + +The configuration of the attendant `MessageListenerAdapter` would then be as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="messageListener" class="org.springframework.jms.listener.adapter.MessageListenerAdapter"> + <constructor-arg> + <bean class="jmsexample.DefaultTextMessageDelegate"/> + </constructor-arg> + <property name="defaultListenerMethod" value="receive"/> + <!-- we don't want automatic message context extraction --> + <property name="messageConverter"> + <null/> + </property> + </bean> +---- + +Note that, if the `messageListener` receives a JMS `Message` of a type +other than `TextMessage`, an `IllegalStateException` is thrown (and subsequently +swallowed). Another of the capabilities of the `MessageListenerAdapter` class is the +ability to automatically send back a response `Message` if a handler method returns a +non-void value. Consider the following interface and class: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface ResponsiveTextMessageDelegate { + + // notice the return type... + String receive(TextMessage message); + } +---- + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public class DefaultResponsiveTextMessageDelegate implements ResponsiveTextMessageDelegate { + // implementation elided for clarity... + } +---- + +If you use the `DefaultResponsiveTextMessageDelegate` in conjunction with a +`MessageListenerAdapter`, any non-null value that is returned from the execution of +the `'receive(..)'` method is (in the default configuration) converted into a +`TextMessage`. The resulting `TextMessage` is then sent to the `Destination` (if +one exists) defined in the JMS `Reply-To` property of the original `Message` or the +default `Destination` set on the `MessageListenerAdapter` (if one has been configured). +If no `Destination` is found, an `InvalidDestinationException` is thrown +(note that this exception is not swallowed and propagates up the +call stack). + + +[[jms-tx-participation]] +== Processing Messages Within Transactions + +Invoking a message listener within a transaction requires only reconfiguration of the +listener container. + +You can activate local resource transactions through the `sessionTransacted` flag +on the listener container definition. Each message listener invocation then operates +within an active JMS transaction, with message reception rolled back in case of listener +execution failure. Sending a response message (through `SessionAwareMessageListener`) is +part of the same local transaction, but any other resource operations (such as +database access) operate independently. This usually requires duplicate message +detection in the listener implementation, to cover the case where database processing +has committed but message processing failed to commit. + +Consider the following bean definition: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"> + <property name="connectionFactory" ref="connectionFactory"/> + <property name="destination" ref="destination"/> + <property name="messageListener" ref="messageListener"/> + <property name="sessionTransacted" value="true"/> + </bean> +---- + +To participate in an externally managed transaction, you need to configure a +transaction manager and use a listener container that supports externally managed +transactions (typically, `DefaultMessageListenerContainer`). + +To configure a message listener container for XA transaction participation, you want +to configure a `JtaTransactionManager` (which, by default, delegates to the Jakarta EE +server's transaction subsystem). Note that the underlying JMS `ConnectionFactory` needs to +be XA-capable and properly registered with your JTA transaction coordinator. (Check your +Jakarta EE server's configuration of JNDI resources.) This lets message reception as well +as (for example) database access be part of the same transaction (with unified commit +semantics, at the expense of XA transaction log overhead). + +The following bean definition creates a transaction manager: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="transactionManager" class="org.springframework.transaction.jta.JtaTransactionManager"/> +---- + +Then we need to add it to our earlier container configuration. The container +takes care of the rest. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer"> + <property name="connectionFactory" ref="connectionFactory"/> + <property name="destination" ref="destination"/> + <property name="messageListener" ref="messageListener"/> + <property name="transactionManager" ref="transactionManager"/> <1> + </bean> +---- +<1> Our transaction manager. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jms/sending.adoc b/framework-docs/modules/ROOT/pages/integration/jms/sending.adoc new file mode 100644 index 000000000000..a5f479b0ea63 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jms/sending.adoc @@ -0,0 +1,134 @@ +[[jms-sending]] += Sending a Message + +The `JmsTemplate` contains many convenience methods to send a message. Send +methods specify the destination by using a `jakarta.jms.Destination` object, and others +specify the destination by using a `String` in a JNDI lookup. The `send` method +that takes no destination argument uses the default destination. + +The following example uses the `MessageCreator` callback to create a text message from the +supplied `Session` object: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + import jakarta.jms.ConnectionFactory; + import jakarta.jms.JMSException; + import jakarta.jms.Message; + import jakarta.jms.Queue; + import jakarta.jms.Session; + + import org.springframework.jms.core.MessageCreator; + import org.springframework.jms.core.JmsTemplate; + + public class JmsQueueSender { + + private JmsTemplate jmsTemplate; + private Queue queue; + + public void setConnectionFactory(ConnectionFactory cf) { + this.jmsTemplate = new JmsTemplate(cf); + } + + public void setQueue(Queue queue) { + this.queue = queue; + } + + public void simpleSend() { + this.jmsTemplate.send(this.queue, new MessageCreator() { + public Message createMessage(Session session) throws JMSException { + return session.createTextMessage("hello queue world"); + } + }); + } + } +---- + +In the preceding example, the `JmsTemplate` is constructed by passing a reference to a +`ConnectionFactory`. As an alternative, a zero-argument constructor and +`connectionFactory` is provided and can be used for constructing the instance in +JavaBean style (using a `BeanFactory` or plain Java code). Alternatively, consider +deriving from Spring's `JmsGatewaySupport` convenience base class, which provides +pre-built bean properties for JMS configuration. + +The `send(String destinationName, MessageCreator creator)` method lets you send a +message by using the string name of the destination. If these names are registered in JNDI, +you should set the `destinationResolver` property of the template to an instance of +`JndiDestinationResolver`. + +If you created the `JmsTemplate` and specified a default destination, the +`send(MessageCreator c)` sends a message to that destination. + + +[[jms-msg-conversion]] +== Using Message Converters + +To facilitate the sending of domain model objects, the `JmsTemplate` has +various send methods that take a Java object as an argument for a message's data +content. The overloaded methods `convertAndSend()` and `receiveAndConvert()` methods in +`JmsTemplate` delegate the conversion process to an instance of the `MessageConverter` +interface. This interface defines a simple contract to convert between Java objects and +JMS messages. The default implementation (`SimpleMessageConverter`) supports conversion +between `String` and `TextMessage`, `byte[]` and `BytesMessage`, and `java.util.Map` +and `MapMessage`. By using the converter, you and your application code can focus on the +business object that is being sent or received through JMS and not be concerned with the +details of how it is represented as a JMS message. + +The sandbox currently includes a `MapMessageConverter`, which uses reflection to convert +between a JavaBean and a `MapMessage`. Other popular implementation choices you might +implement yourself are converters that use an existing XML marshalling package (such as +JAXB or XStream) to create a `TextMessage` that represents the object. + +To accommodate the setting of a message's properties, headers, and body that can not be +generically encapsulated inside a converter class, the `MessagePostProcessor` interface +gives you access to the message after it has been converted but before it is sent. The +following example shows how to modify a message header and a property after a +`java.util.Map` is converted to a message: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public void sendWithConversion() { + Map map = new HashMap(); + map.put("Name", "Mark"); + map.put("Age", new Integer(47)); + jmsTemplate.convertAndSend("testQueue", map, new MessagePostProcessor() { + public Message postProcessMessage(Message message) throws JMSException { + message.setIntProperty("AccountID", 1234); + message.setJMSCorrelationID("123-00001"); + return message; + } + }); + } +---- + +This results in a message of the following form: + +[literal] +[subs="verbatim,quotes"] +---- +MapMessage={ + Header={ + ... standard headers ... + CorrelationID={123-00001} + } + Properties={ + AccountID={Integer:1234} + } + Fields={ + Name={String:Mark} + Age={Integer:47} + } +} +---- + + +[[jms-callbacks]] +== Using `SessionCallback` and `ProducerCallback` + +While the send operations cover many common usage scenarios, you might sometimes +want to perform multiple operations on a JMS `Session` or `MessageProducer`. The +`SessionCallback` and `ProducerCallback` expose the JMS `Session` and `Session` / +`MessageProducer` pair, respectively. The `execute()` methods on `JmsTemplate` run +these callback methods. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jms/using.adoc b/framework-docs/modules/ROOT/pages/integration/jms/using.adoc new file mode 100644 index 000000000000..53883f7fa387 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jms/using.adoc @@ -0,0 +1,296 @@ +[[jms-using]] += Using Spring JMS + +This section describes how to use Spring's JMS components. + + +[[jms-jmstemplate]] +== Using `JmsTemplate` + +The `JmsTemplate` class is the central class in the JMS core package. It simplifies the +use of JMS, since it handles the creation and release of resources when sending or +synchronously receiving messages. + +Code that uses the `JmsTemplate` needs only to implement callback interfaces that give them +a clearly defined high-level contract. The `MessageCreator` callback interface creates a +message when given a `Session` provided by the calling code in `JmsTemplate`. To +allow for more complex usage of the JMS API, `SessionCallback` provides the +JMS session, and `ProducerCallback` exposes a `Session` and +`MessageProducer` pair. + +The JMS API exposes two types of send methods, one that takes delivery mode, priority, +and time-to-live as Quality of Service (QOS) parameters and one that takes no QOS +parameters and uses default values. Since `JmsTemplate` has many send methods, +setting the QOS parameters have been exposed as bean properties to +avoid duplication in the number of send methods. Similarly, the timeout value for +synchronous receive calls is set by using the `setReceiveTimeout` property. + +Some JMS providers allow the setting of default QOS values administratively through the +configuration of the `ConnectionFactory`. This has the effect that a call to a +`MessageProducer` instance's `send` method (`send(Destination destination, Message message)`) +uses different QOS default values than those specified in the JMS specification. In order +to provide consistent management of QOS values, the `JmsTemplate` must, therefore, be +specifically enabled to use its own QOS values by setting the boolean property +`isExplicitQosEnabled` to `true`. + +For convenience, `JmsTemplate` also exposes a basic request-reply operation that allows +for sending a message and waiting for a reply on a temporary queue that is created as part of +the operation. + +IMPORTANT: Instances of the `JmsTemplate` class are thread-safe, once configured. This is +important, because it means that you can configure a single instance of a `JmsTemplate` +and then safely inject this shared reference into multiple collaborators. To be +clear, the `JmsTemplate` is stateful, in that it maintains a reference to a +`ConnectionFactory`, but this state is not conversational state. + +As of Spring Framework 4.1, `JmsMessagingTemplate` is built on top of `JmsTemplate` +and provides an integration with the messaging abstraction -- that is, +`org.springframework.messaging.Message`. This lets you create the message to +send in a generic manner. + + +[[jms-connections]] +== Connections + +The `JmsTemplate` requires a reference to a `ConnectionFactory`. The `ConnectionFactory` +is part of the JMS specification and serves as the entry point for working with JMS. It +is used by the client application as a factory to create connections with the JMS +provider and encapsulates various configuration parameters, many of which are +vendor-specific, such as SSL configuration options. + +When using JMS inside an EJB, the vendor provides implementations of the JMS interfaces +so that they can participate in declarative transaction management and perform pooling +of connections and sessions. In order to use this implementation, Jakarta EE containers +typically require that you declare a JMS connection factory as a `resource-ref` inside +the EJB or servlet deployment descriptors. To ensure the use of these features with the +`JmsTemplate` inside an EJB, the client application should ensure that it references the +managed implementation of the `ConnectionFactory`. + +[[jms-caching-resources]] +=== Caching Messaging Resources + +The standard API involves creating many intermediate objects. To send a message, the +following 'API' walk is performed: + +[literal] +[subs="verbatim,quotes"] +---- +ConnectionFactory->Connection->Session->MessageProducer->send +---- + +Between the `ConnectionFactory` and the `Send` operation, three intermediate +objects are created and destroyed. To optimize the resource usage and increase +performance, Spring provides two implementations of `ConnectionFactory`. + +[[jms-connection-factory]] +=== Using `SingleConnectionFactory` + +Spring provides an implementation of the `ConnectionFactory` interface, +`SingleConnectionFactory`, that returns the same `Connection` on all +`createConnection()` calls and ignores calls to `close()`. This is useful for testing and +standalone environments so that the same connection can be used for multiple +`JmsTemplate` calls that may span any number of transactions. `SingleConnectionFactory` +takes a reference to a standard `ConnectionFactory` that would typically come from JNDI. + +[[jdbc-connection-factory-caching]] +=== Using `CachingConnectionFactory` + +The `CachingConnectionFactory` extends the functionality of `SingleConnectionFactory` +and adds the caching of `Session`, `MessageProducer`, and `MessageConsumer` instances. +The initial cache size is set to `1`. You can use the `sessionCacheSize` property to +increase the number of cached sessions. Note that the number of actual cached sessions +is more than that number, as sessions are cached based on their acknowledgment mode, +so there can be up to four cached session instances (one for each acknowledgment mode) +when `sessionCacheSize` is set to one. `MessageProducer` and `MessageConsumer` instances +are cached within their owning session and also take into account the unique properties +of the producers and consumers when caching. MessageProducers are cached based on their +destination. MessageConsumers are cached based on a key composed of the destination, selector, +noLocal delivery flag, and the durable subscription name (if creating durable consumers). + +[NOTE] +==== +MessageProducers and MessageConsumers for temporary queues and topics +(TemporaryQueue/TemporaryTopic) will never be cached. Unfortunately, WebLogic JMS happens +to implement the temporary queue/topic interfaces on its regular destination implementation, +mis-indicating that none of its destinations can be cached. Please use a different connection +pool/cache on WebLogic, or customize `CachingConnectionFactory` for WebLogic purposes. +==== + + +[[jms-destinations]] +== Destination Management + +Destinations, as `ConnectionFactory` instances, are JMS administered objects that you can store +and retrieve in JNDI. When configuring a Spring application context, you can use the +JNDI `JndiObjectFactoryBean` factory class or `<jee:jndi-lookup>` to perform dependency +injection on your object's references to JMS destinations. However, this strategy +is often cumbersome if there are a large number of destinations in the application or if there +are advanced destination management features unique to the JMS provider. Examples of +such advanced destination management include the creation of dynamic destinations or +support for a hierarchical namespace of destinations. The `JmsTemplate` delegates the +resolution of a destination name to a JMS destination object that implements the +`DestinationResolver` interface. `DynamicDestinationResolver` is the default +implementation used by `JmsTemplate` and accommodates resolving dynamic destinations. A +`JndiDestinationResolver` is also provided to act as a service locator for +destinations contained in JNDI and optionally falls back to the behavior contained in +`DynamicDestinationResolver`. + +Quite often, the destinations used in a JMS application are only known at runtime and, +therefore, cannot be administratively created when the application is deployed. This is +often because there is shared application logic between interacting system components +that create destinations at runtime according to a well-known naming convention. Even +though the creation of dynamic destinations is not part of the JMS specification, most +vendors have provided this functionality. Dynamic destinations are created with a user-defined name, +which differentiates them from temporary destinations, and are often +not registered in JNDI. The API used to create dynamic destinations varies from provider +to provider since the properties associated with the destination are vendor-specific. +However, a simple implementation choice that is sometimes made by vendors is to +disregard the warnings in the JMS specification and to use the method `TopicSession` +`createTopic(String topicName)` or the `QueueSession` `createQueue(String +queueName)` method to create a new destination with default destination properties. Depending +on the vendor implementation, `DynamicDestinationResolver` can then also create a +physical destination instead of only resolving one. + +The boolean property `pubSubDomain` is used to configure the `JmsTemplate` with +knowledge of what JMS domain is being used. By default, the value of this property is +false, indicating that the point-to-point domain, `Queues`, is to be used. This property +(used by `JmsTemplate`) determines the behavior of dynamic destination resolution through +implementations of the `DestinationResolver` interface. + +You can also configure the `JmsTemplate` with a default destination through the +property `defaultDestination`. The default destination is with send and receive +operations that do not refer to a specific destination. + + +[[jms-mdp]] +== Message Listener Containers + +One of the most common uses of JMS messages in the EJB world is to drive message-driven +beans (MDBs). Spring offers a solution to create message-driven POJOs (MDPs) in a way +that does not tie a user to an EJB container. (See <<jms-receiving-async>> for detailed +coverage of Spring's MDP support.) Since Spring Framework 4.1, endpoint methods can be +annotated with `@JmsListener` -- see <<jms-annotated>> for more details. + +A message listener container is used to receive messages from a JMS message queue and +drive the `MessageListener` that is injected into it. The listener container is +responsible for all threading of message reception and dispatches into the listener for +processing. A message listener container is the intermediary between an MDP and a +messaging provider and takes care of registering to receive messages, participating in +transactions, resource acquisition and release, exception conversion, and so on. This +lets you write the (possibly complex) business logic +associated with receiving a message (and possibly respond to it), and delegates +boilerplate JMS infrastructure concerns to the framework. + +There are two standard JMS message listener containers packaged with Spring, each with +its specialized feature set. + +* <<jms-mdp-simple, `SimpleMessageListenerContainer`>> +* <<jms-mdp-default, `DefaultMessageListenerContainer`>> + +[[jms-mdp-simple]] +=== Using `SimpleMessageListenerContainer` + +This message listener container is the simpler of the two standard flavors. It creates +a fixed number of JMS sessions and consumers at startup, registers the listener by using +the standard JMS `MessageConsumer.setMessageListener()` method, and leaves it up the JMS +provider to perform listener callbacks. This variant does not allow for dynamic adaption +to runtime demands or for participation in externally managed transactions. +Compatibility-wise, it stays very close to the spirit of the standalone JMS +specification, but is generally not compatible with Jakarta EE's JMS restrictions. + +NOTE: While `SimpleMessageListenerContainer` does not allow for participation in externally +managed transactions, it does support native JMS transactions. To enable this feature, +you can switch the `sessionTransacted` flag to `true` or, in the XML namespace, set the +`acknowledge` attribute to `transacted`. Exceptions thrown from your listener then lead +to a rollback, with the message getting redelivered. Alternatively, consider using +`CLIENT_ACKNOWLEDGE` mode, which provides redelivery in case of an exception as well but +does not use transacted `Session` instances and, therefore, does not include any other +`Session` operations (such as sending response messages) in the transaction protocol. + +IMPORTANT: The default `AUTO_ACKNOWLEDGE` mode does not provide proper reliability guarantees. +Messages can get lost when listener execution fails (since the provider automatically +acknowledges each message after listener invocation, with no exceptions to be propagated to +the provider) or when the listener container shuts down (you can configure this by setting +the `acceptMessagesWhileStopping` flag). Make sure to use transacted sessions in case of +reliability needs (for example, for reliable queue handling and durable topic subscriptions). + +[[jms-mdp-default]] +=== Using `DefaultMessageListenerContainer` + +This message listener container is used in most cases. In contrast to +`SimpleMessageListenerContainer`, this container variant allows for dynamic adaptation +to runtime demands and is able to participate in externally managed transactions. +Each received message is registered with an XA transaction when configured with a +`JtaTransactionManager`. As a result, processing may take advantage of XA transaction +semantics. This listener container strikes a good balance between low requirements on +the JMS provider, advanced functionality (such as participation in externally managed +transactions), and compatibility with Jakarta EE environments. + +You can customize the cache level of the container. Note that, when no caching is enabled, +a new connection and a new session is created for each message reception. Combining this +with a non-durable subscription with high loads may lead to message loss. Make sure to +use a proper cache level in such a case. + +This container also has recoverable capabilities when the broker goes down. By default, +a simple `BackOff` implementation retries every five seconds. You can specify +a custom `BackOff` implementation for more fine-grained recovery options. See +{api-spring-framework}/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example. + +NOTE: Like its sibling (<<jms-mdp-simple, `SimpleMessageListenerContainer`>>), +`DefaultMessageListenerContainer` supports native JMS transactions and allows for +customizing the acknowledgment mode. If feasible for your scenario, This is strongly +recommended over externally managed transactions -- that is, if you can live with +occasional duplicate messages in case of the JVM dying. Custom duplicate message +detection steps in your business logic can cover such situations -- for example, +in the form of a business entity existence check or a protocol table check. +Any such arrangements are significantly more efficient than the alternative: +wrapping your entire processing with an XA transaction (through configuring your +`DefaultMessageListenerContainer` with an `JtaTransactionManager`) to cover the +reception of the JMS message as well as the execution of the business logic in your +message listener (including database operations, etc.). + +IMPORTANT: The default `AUTO_ACKNOWLEDGE` mode does not provide proper reliability guarantees. +Messages can get lost when listener execution fails (since the provider automatically +acknowledges each message after listener invocation, with no exceptions to be propagated to +the provider) or when the listener container shuts down (you can configure this by setting +the `acceptMessagesWhileStopping` flag). Make sure to use transacted sessions in case of +reliability needs (for example, for reliable queue handling and durable topic subscriptions). + + +[[jms-tx]] +== Transaction Management + +Spring provides a `JmsTransactionManager` that manages transactions for a single JMS +`ConnectionFactory`. This lets JMS applications leverage the managed-transaction +features of Spring, as described in +<<data-access.adoc#transaction, Transaction Management section of the Data Access chapter>>. +The `JmsTransactionManager` performs local resource transactions, binding a JMS +Connection/Session pair from the specified `ConnectionFactory` to the thread. +`JmsTemplate` automatically detects such transactional resources and operates +on them accordingly. + +In a Jakarta EE environment, the `ConnectionFactory` pools Connection and Session instances, +so those resources are efficiently reused across transactions. In a standalone environment, +using Spring's `SingleConnectionFactory` result in a shared JMS `Connection`, with +each transaction having its own independent `Session`. Alternatively, consider the use +of a provider-specific pooling adapter, such as ActiveMQ's `PooledConnectionFactory` +class. + +You can also use `JmsTemplate` with the `JtaTransactionManager` and an XA-capable JMS +`ConnectionFactory` to perform distributed transactions. Note that this requires the +use of a JTA transaction manager as well as a properly XA-configured ConnectionFactory. +(Check your Jakarta EE server's or JMS provider's documentation.) + +Reusing code across a managed and unmanaged transactional environment can be confusing +when using the JMS API to create a `Session` from a `Connection`. This is because the +JMS API has only one factory method to create a `Session`, and it requires values for the +transaction and acknowledgment modes. In a managed environment, setting these values is +the responsibility of the environment's transactional infrastructure, so these values +are ignored by the vendor's wrapper to the JMS Connection. When you use the `JmsTemplate` +in an unmanaged environment, you can specify these values through the use of the +properties `sessionTransacted` and `sessionAcknowledgeMode`. When you use a +`PlatformTransactionManager` with `JmsTemplate`, the template is always given a +transactional JMS `Session`. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jmx.adoc b/framework-docs/modules/ROOT/pages/integration/jmx.adoc index c6f1e4299e25..10a8c063d8a1 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx.adoc @@ -24,1352 +24,3 @@ Spring JMX features. -[[jmx-exporting]] -== Exporting Your Beans to JMX - -The core class in Spring's JMX framework is the `MBeanExporter`. This class is -responsible for taking your Spring beans and registering them with a JMX `MBeanServer`. -For example, consider the following class: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages",chomp="-packages"] ----- - package org.springframework.jmx; - - public class JmxTestBean implements IJmxTestBean { - - private String name; - private int age; - private boolean isSuperman; - - public int getAge() { - return age; - } - - public void setAge(int age) { - this.age = age; - } - - public void setName(String name) { - this.name = name; - } - - public String getName() { - return name; - } - - public int add(int x, int y) { - return x + y; - } - - public void dontExposeMe() { - throw new RuntimeException(); - } - } ----- - -To expose the properties and methods of this bean as attributes and operations of an -MBean, you can configure an instance of the `MBeanExporter` class in your -configuration file and pass in the bean, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <!-- this bean must not be lazily initialized if the exporting is to happen --> - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter" lazy-init="false"> - <property name="beans"> - <map> - <entry key="bean:name=testBean1" value-ref="testBean"/> - </map> - </property> - </bean> - <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - </beans> ----- - -The pertinent bean definition from the preceding configuration snippet is the `exporter` -bean. The `beans` property tells the `MBeanExporter` exactly which of your beans must be -exported to the JMX `MBeanServer`. In the default configuration, the key of each entry -in the `beans` `Map` is used as the `ObjectName` for the bean referenced by the -corresponding entry value. You can change this behavior, as described in <<jmx-naming>>. - -With this configuration, the `testBean` bean is exposed as an MBean under the -`ObjectName` `bean:name=testBean1`. By default, all `public` properties of the bean -are exposed as attributes and all `public` methods (except those inherited from the -`Object` class) are exposed as operations. - -NOTE: `MBeanExporter` is a `Lifecycle` bean (see <<core.adoc#beans-factory-lifecycle-processor, -Startup and Shutdown Callbacks>>). By default, MBeans are exported as late as possible during -the application lifecycle. You can configure the `phase` at which -the export happens or disable automatic registration by setting the `autoStartup` flag. - - -[[jmx-exporting-mbeanserver]] -=== Creating an MBeanServer - -The configuration shown in the <<jmx-exporting, preceding section>> assumes that the -application is running in an environment that has one (and only one) `MBeanServer` -already running. In this case, Spring tries to locate the running `MBeanServer` and -register your beans with that server (if any). This behavior is useful when your -application runs inside a container (such as Tomcat or IBM WebSphere) that has its -own `MBeanServer`. - -However, this approach is of no use in a standalone environment or when running inside -a container that does not provide an `MBeanServer`. To address this, you can create an -`MBeanServer` instance declaratively by adding an instance of the -`org.springframework.jmx.support.MBeanServerFactoryBean` class to your configuration. -You can also ensure that a specific `MBeanServer` is used by setting the value of the -`MBeanExporter` instance's `server` property to the `MBeanServer` value returned by an -`MBeanServerFactoryBean`, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean"/> - - <!-- - this bean needs to be eagerly pre-instantiated in order for the exporting to occur; - this means that it must not be marked as lazily initialized - --> - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="bean:name=testBean1" value-ref="testBean"/> - </map> - </property> - <property name="server" ref="mbeanServer"/> - </bean> - - <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - </beans> ----- - -In the preceding example, an instance of `MBeanServer` is created by the `MBeanServerFactoryBean` and is -supplied to the `MBeanExporter` through the `server` property. When you supply your own -`MBeanServer` instance, the `MBeanExporter` does not try to locate a running -`MBeanServer` and uses the supplied `MBeanServer` instance. For this to work -correctly, you must have a JMX implementation on your classpath. - - -[[jmx-mbean-server]] -=== Reusing an Existing `MBeanServer` - -If no server is specified, the `MBeanExporter` tries to automatically detect a running -`MBeanServer`. This works in most environments, where only one `MBeanServer` instance is -used. However, when multiple instances exist, the exporter might pick the wrong server. -In such cases, you should use the `MBeanServer` `agentId` to indicate which instance to -be used, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean"> - <!-- indicate to first look for a server --> - <property name="locateExistingServerIfPossible" value="true"/> - <!-- search for the MBeanServer instance with the given agentId --> - <property name="agentId" value="MBeanServer_instance_agentId>"/> - </bean> - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="server" ref="mbeanServer"/> - ... - </bean> - </beans> ----- - -For platforms or cases where the existing `MBeanServer` has a dynamic (or unknown) -`agentId` that is retrieved through lookup methods, you should use -<<core.adoc#beans-factory-class-static-factory-method, factory-method>>, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="server"> - <!-- Custom MBeanServerLocator --> - <bean class="platform.package.MBeanServerLocator" factory-method="locateMBeanServer"/> - </property> - </bean> - - <!-- other beans here --> - - </beans> ----- - - -[[jmx-exporting-lazy]] -=== Lazily Initialized MBeans - -If you configure a bean with an `MBeanExporter` that is also configured for lazy -initialization, the `MBeanExporter` does not break this contract and avoids -instantiating the bean. Instead, it registers a proxy with the `MBeanServer` and -defers obtaining the bean from the container until the first invocation on the proxy -occurs. - - -[[jmx-exporting-auto]] -=== Automatic Registration of MBeans - -Any beans that are exported through the `MBeanExporter` and are already valid MBeans are -registered as-is with the `MBeanServer` without further intervention from Spring. You can cause MBeans -to be automatically detected by the `MBeanExporter` by setting the `autodetect` -property to `true`, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="autodetect" value="true"/> - </bean> - - <bean name="spring:mbean=true" class="org.springframework.jmx.export.TestDynamicMBean"/> ----- - -In the preceding example, the bean called `spring:mbean=true` is already a valid JMX MBean -and is automatically registered by Spring. By default, a bean that is autodetected for JMX -registration has its bean name used as the `ObjectName`. You can override this behavior, -as detailed in <<jmx-naming>>. - - -[[jmx-exporting-registration-behavior]] -=== Controlling the Registration Behavior - -Consider the scenario where a Spring `MBeanExporter` attempts to register an `MBean` -with an `MBeanServer` by using the `ObjectName` `bean:name=testBean1`. If an `MBean` -instance has already been registered under that same `ObjectName`, the default behavior -is to fail (and throw an `InstanceAlreadyExistsException`). - -You can control exactly what happens when an `MBean` is -registered with an `MBeanServer`. Spring's JMX support allows for three different -registration behaviors to control the registration behavior when the registration -process finds that an `MBean` has already been registered under the same `ObjectName`. -The following table summarizes these registration behaviors: - -[[jmx-registration-behaviors]] -.Registration Behaviors -[cols="1,4"] -|=== -| Registration behavior | Explanation - -| `FAIL_ON_EXISTING` -| This is the default registration behavior. If an `MBean` instance has already been - registered under the same `ObjectName`, the `MBean` that is being registered is not - registered, and an `InstanceAlreadyExistsException` is thrown. The existing - `MBean` is unaffected. - -| `IGNORE_EXISTING` -| If an `MBean` instance has already been registered under the same `ObjectName`, the - `MBean` that is being registered is not registered. The existing `MBean` is - unaffected, and no `Exception` is thrown. This is useful in settings where - multiple applications want to share a common `MBean` in a shared `MBeanServer`. - -| `REPLACE_EXISTING` -| If an `MBean` instance has already been registered under the same `ObjectName`, the - existing `MBean` that was previously registered is unregistered, and the new - `MBean` is registered in its place (the new `MBean` effectively replaces the - previous instance). -|=== - -The values in the preceding table are defined as enums on the `RegistrationPolicy` class. -If you want to change the default registration behavior, you need to set the value of the -`registrationPolicy` property on your `MBeanExporter` definition to one of those -values. - -The following example shows how to change from the default registration -behavior to the `REPLACE_EXISTING` behavior: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="bean:name=testBean1" value-ref="testBean"/> - </map> - </property> - <property name="registrationPolicy" value="REPLACE_EXISTING"/> - </bean> - - <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - </beans> ----- - - - -[[jmx-interface]] -== Controlling the Management Interface of Your Beans - -In the example in the <<jmx-exporting-registration-behavior, preceding section>>, -you had little control over the management interface of your bean. All of the `public` -properties and methods of each exported bean were exposed as JMX attributes and -operations, respectively. To exercise finer-grained control over exactly which -properties and methods of your exported beans are actually exposed as JMX attributes -and operations, Spring JMX provides a comprehensive and extensible mechanism for -controlling the management interfaces of your beans. - - -[[jmx-interface-assembler]] -=== Using the `MBeanInfoAssembler` Interface - -Behind the scenes, the `MBeanExporter` delegates to an implementation of the -`org.springframework.jmx.export.assembler.MBeanInfoAssembler` interface, which is -responsible for defining the management interface of each bean that is exposed. -The default implementation, -`org.springframework.jmx.export.assembler.SimpleReflectiveMBeanInfoAssembler`, -defines a management interface that exposes all public properties and methods -(as you saw in the examples in the preceding sections). Spring provides two -additional implementations of the `MBeanInfoAssembler` interface that let you -control the generated management interface by using either source-level metadata -or any arbitrary interface. - - -[[jmx-interface-metadata]] -=== Using Source-level Metadata: Java Annotations - -By using the `MetadataMBeanInfoAssembler`, you can define the management interfaces -for your beans by using source-level metadata. The reading of metadata is encapsulated -by the `org.springframework.jmx.export.metadata.JmxAttributeSource` interface. -Spring JMX provides a default implementation that uses Java annotations, namely -`org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource`. -You must configure the `MetadataMBeanInfoAssembler` with an implementation instance of -the `JmxAttributeSource` interface for it to function correctly (there is no default). - -To mark a bean for export to JMX, you should annotate the bean class with the -`ManagedResource` annotation. You must mark each method you wish to expose as an operation -with the `ManagedOperation` annotation and mark each property you wish to expose -with the `ManagedAttribute` annotation. When marking properties, you can omit -either the annotation of the getter or the setter to create a write-only or read-only -attribute, respectively. - -NOTE: A `ManagedResource`-annotated bean must be public, as must the methods exposing -an operation or an attribute. - -The following example shows the annotated version of the `JmxTestBean` class that we -used in <<jmx-exporting-mbeanserver>>: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.jmx; - - import org.springframework.jmx.export.annotation.ManagedResource; - import org.springframework.jmx.export.annotation.ManagedOperation; - import org.springframework.jmx.export.annotation.ManagedAttribute; - - @ManagedResource( - objectName="bean:name=testBean4", - description="My Managed Bean", - log=true, - logFile="jmx.log", - currencyTimeLimit=15, - persistPolicy="OnUpdate", - persistPeriod=200, - persistLocation="foo", - persistName="bar") - public class AnnotationTestBean implements IJmxTestBean { - - private String name; - private int age; - - @ManagedAttribute(description="The Age Attribute", currencyTimeLimit=15) - public int getAge() { - return age; - } - - public void setAge(int age) { - this.age = age; - } - - @ManagedAttribute(description="The Name Attribute", - currencyTimeLimit=20, - defaultValue="bar", - persistPolicy="OnUpdate") - public void setName(String name) { - this.name = name; - } - - @ManagedAttribute(defaultValue="foo", persistPeriod=300) - public String getName() { - return name; - } - - @ManagedOperation(description="Add two numbers") - @ManagedOperationParameters({ - @ManagedOperationParameter(name = "x", description = "The first number"), - @ManagedOperationParameter(name = "y", description = "The second number")}) - public int add(int x, int y) { - return x + y; - } - - public void dontExposeMe() { - throw new RuntimeException(); - } - - } ----- - -In the preceding example, you can see that the `JmxTestBean` class is marked with the -`ManagedResource` annotation and that this `ManagedResource` annotation is configured -with a set of properties. These properties can be used to configure various aspects -of the MBean that is generated by the `MBeanExporter` and are explained in greater -detail later in <<jmx-interface-metadata-types>>. - -Both the `age` and `name` properties are annotated with the `ManagedAttribute` -annotation, but, in the case of the `age` property, only the getter is marked. -This causes both of these properties to be included in the management interface -as attributes, but the `age` attribute is read-only. - -Finally, the `add(int, int)` method is marked with the `ManagedOperation` attribute, -whereas the `dontExposeMe()` method is not. This causes the management interface to -contain only one operation (`add(int, int)`) when you use the `MetadataMBeanInfoAssembler`. - -The following configuration shows how you can configure the `MBeanExporter` to use the -`MetadataMBeanInfoAssembler`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="assembler" ref="assembler"/> - <property name="namingStrategy" ref="namingStrategy"/> - <property name="autodetect" value="true"/> - </bean> - - <bean id="jmxAttributeSource" - class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/> - - <!-- will create management interface using annotation metadata --> - <bean id="assembler" - class="org.springframework.jmx.export.assembler.MetadataMBeanInfoAssembler"> - <property name="attributeSource" ref="jmxAttributeSource"/> - </bean> - - <!-- will pick up the ObjectName from the annotation --> - <bean id="namingStrategy" - class="org.springframework.jmx.export.naming.MetadataNamingStrategy"> - <property name="attributeSource" ref="jmxAttributeSource"/> - </bean> - - <bean id="testBean" class="org.springframework.jmx.AnnotationTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - </beans> ----- - -In the preceding example, an `MetadataMBeanInfoAssembler` bean has been configured with an -instance of the `AnnotationJmxAttributeSource` class and passed to the `MBeanExporter` -through the assembler property. This is all that is required to take advantage of -metadata-driven management interfaces for your Spring-exposed MBeans. - - -[[jmx-interface-metadata-types]] -=== Source-level Metadata Types - -The following table describes the source-level metadata types that are available for use in Spring JMX: - -[[jmx-metadata-types]] -.Source-level metadata types -|=== -| Purpose| Annotation| Annotation Type - -| Mark all instances of a `Class` as JMX managed resources. -| `@ManagedResource` -| Class - -| Mark a method as a JMX operation. -| `@ManagedOperation` -| Method - -| Mark a getter or setter as one half of a JMX attribute. -| `@ManagedAttribute` -| Method (only getters and setters) - -| Define descriptions for operation parameters. -| `@ManagedOperationParameter` and `@ManagedOperationParameters` -| Method -|=== - -The following table describes the configuration parameters that are available for use on these source-level -metadata types: - -[[jmx-metadata-parameters]] -.Source-level metadata parameters -[cols="1,3,1"] -|=== -| Parameter | Description | Applies to - -| `ObjectName` -| Used by `MetadataNamingStrategy` to determine the `ObjectName` of a managed resource. -| `ManagedResource` - -| `description` -| Sets the friendly description of the resource, attribute or operation. -| `ManagedResource`, `ManagedAttribute`, `ManagedOperation`, or `ManagedOperationParameter` - -| `currencyTimeLimit` -| Sets the value of the `currencyTimeLimit` descriptor field. -| `ManagedResource` or `ManagedAttribute` - -| `defaultValue` -| Sets the value of the `defaultValue` descriptor field. -| `ManagedAttribute` - -| `log` -| Sets the value of the `log` descriptor field. -| `ManagedResource` - -| `logFile` -| Sets the value of the `logFile` descriptor field. -| `ManagedResource` - -| `persistPolicy` -| Sets the value of the `persistPolicy` descriptor field. -| `ManagedResource` - -| `persistPeriod` -| Sets the value of the `persistPeriod` descriptor field. -| `ManagedResource` - -| `persistLocation` -| Sets the value of the `persistLocation` descriptor field. -| `ManagedResource` - -| `persistName` -| Sets the value of the `persistName` descriptor field. -| `ManagedResource` - -| `name` -| Sets the display name of an operation parameter. -| `ManagedOperationParameter` - -| `index` -| Sets the index of an operation parameter. -| `ManagedOperationParameter` -|=== - - -[[jmx-interface-autodetect]] -=== Using the `AutodetectCapableMBeanInfoAssembler` Interface - -To simplify configuration even further, Spring includes the -`AutodetectCapableMBeanInfoAssembler` interface, which extends the `MBeanInfoAssembler` -interface to add support for autodetection of MBean resources. If you configure the -`MBeanExporter` with an instance of `AutodetectCapableMBeanInfoAssembler`, it is -allowed to "`vote`" on the inclusion of beans for exposure to JMX. - -The only implementation of the `AutodetectCapableMBeanInfo` interface is -the `MetadataMBeanInfoAssembler`, which votes to include any bean that is marked -with the `ManagedResource` attribute. The default approach in this case is to use the -bean name as the `ObjectName`, which results in a configuration similar to the following: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <!-- notice how no 'beans' are explicitly configured here --> - <property name="autodetect" value="true"/> - <property name="assembler" ref="assembler"/> - </bean> - - <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - <bean id="assembler" class="org.springframework.jmx.export.assembler.MetadataMBeanInfoAssembler"> - <property name="attributeSource"> - <bean class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/> - </property> - </bean> - - </beans> ----- - -Notice that, in the preceding configuration, no beans are passed to the `MBeanExporter`. -However, the `JmxTestBean` is still registered, since it is marked with the `ManagedResource` -attribute and the `MetadataMBeanInfoAssembler` detects this and votes to include it. -The only problem with this approach is that the name of the `JmxTestBean` now has business -meaning. You can address this issue by changing the default behavior for `ObjectName` -creation as defined in <<jmx-naming>>. - - -[[jmx-interface-java]] -=== Defining Management Interfaces by Using Java Interfaces - -In addition to the `MetadataMBeanInfoAssembler`, Spring also includes the -`InterfaceBasedMBeanInfoAssembler`, which lets you constrain the methods and -properties that are exposed based on the set of methods defined in a collection of -interfaces. - -Although the standard mechanism for exposing MBeans is to use interfaces and a simple -naming scheme, `InterfaceBasedMBeanInfoAssembler` extends this functionality by -removing the need for naming conventions, letting you use more than one interface -and removing the need for your beans to implement the MBean interfaces. - -Consider the following interface, which is used to define a management interface for the -`JmxTestBean` class that we showed earlier: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public interface IJmxTestBean { - - public int add(int x, int y); - - public long myOperation(); - - public int getAge(); - - public void setAge(int age); - - public void setName(String name); - - public String getName(); - - } ----- - -This interface defines the methods and properties that are exposed as operations and -attributes on the JMX MBean. The following code shows how to configure Spring JMX to use -this interface as the definition for the management interface: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="bean:name=testBean5" value-ref="testBean"/> - </map> - </property> - <property name="assembler"> - <bean class="org.springframework.jmx.export.assembler.InterfaceBasedMBeanInfoAssembler"> - <property name="managedInterfaces"> - <value>org.springframework.jmx.IJmxTestBean</value> - </property> - </bean> - </property> - </bean> - - <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - </beans> ----- - -In the preceding example, the `InterfaceBasedMBeanInfoAssembler` is configured to use the -`IJmxTestBean` interface when constructing the management interface for any bean. It is -important to understand that beans processed by the `InterfaceBasedMBeanInfoAssembler` -are not required to implement the interface used to generate the JMX management -interface. - -In the preceding case, the `IJmxTestBean` interface is used to construct all management -interfaces for all beans. In many cases, this is not the desired behavior, and you may -want to use different interfaces for different beans. In this case, you can pass -`InterfaceBasedMBeanInfoAssembler` a `Properties` instance through the `interfaceMappings` -property, where the key of each entry is the bean name and the value of each entry is a -comma-separated list of interface names to use for that bean. - -If no management interface is specified through either the `managedInterfaces` or -`interfaceMappings` properties, the `InterfaceBasedMBeanInfoAssembler` reflects -on the bean and uses all of the interfaces implemented by that bean to create the -management interface. - - -[[jmx-interface-methodnames]] -=== Using `MethodNameBasedMBeanInfoAssembler` - -`MethodNameBasedMBeanInfoAssembler` lets you specify a list of method names -that are exposed to JMX as attributes and operations. The following code shows a sample -configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="bean:name=testBean5" value-ref="testBean"/> - </map> - </property> - <property name="assembler"> - <bean class="org.springframework.jmx.export.assembler.MethodNameBasedMBeanInfoAssembler"> - <property name="managedMethods"> - <value>add,myOperation,getName,setName,getAge</value> - </property> - </bean> - </property> - </bean> ----- - -In the preceding example, you can see that the `add` and `myOperation` methods are exposed as JMX -operations, and `getName()`, `setName(String)`, and `getAge()` are exposed as the -appropriate half of a JMX attribute. In the preceding code, the method mappings apply to -beans that are exposed to JMX. To control method exposure on a bean-by-bean basis, you can use -the `methodMappings` property of `MethodNameMBeanInfoAssembler` to map bean names to -lists of method names. - - - -[[jmx-naming]] -== Controlling `ObjectName` Instances for Your Beans - -Behind the scenes, the `MBeanExporter` delegates to an implementation of the -`ObjectNamingStrategy` to obtain an `ObjectName` instance for each of the beans it registers. -By default, the default implementation, `KeyNamingStrategy` uses the key of the -`beans` `Map` as the `ObjectName`. In addition, the `KeyNamingStrategy` can map the key -of the `beans` `Map` to an entry in a `Properties` file (or files) to resolve the -`ObjectName`. In addition to the `KeyNamingStrategy`, Spring provides two additional -`ObjectNamingStrategy` implementations: the `IdentityNamingStrategy` (which builds an -`ObjectName` based on the JVM identity of the bean) and the `MetadataNamingStrategy` (which -uses source-level metadata to obtain the `ObjectName`). - - -[[jmx-naming-properties]] -=== Reading `ObjectName` Instances from Properties - -You can configure your own `KeyNamingStrategy` instance and configure it to read -`ObjectName` instances from a `Properties` instance rather than use a bean key. The -`KeyNamingStrategy` tries to locate an entry in the `Properties` with a key -that corresponds to the bean key. If no entry is found or if the `Properties` instance is -`null`, the bean key itself is used. - -The following code shows a sample configuration for the `KeyNamingStrategy`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="testBean" value-ref="testBean"/> - </map> - </property> - <property name="namingStrategy" ref="namingStrategy"/> - </bean> - - <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - <bean id="namingStrategy" class="org.springframework.jmx.export.naming.KeyNamingStrategy"> - <property name="mappings"> - <props> - <prop key="testBean">bean:name=testBean1</prop> - </props> - </property> - <property name="mappingLocations"> - <value>names1.properties,names2.properties</value> - </property> - </bean> - - </beans> ----- - -The preceding example configures an instance of `KeyNamingStrategy` with a `Properties` instance that -is merged from the `Properties` instance defined by the mapping property and the -properties files located in the paths defined by the mappings property. In this -configuration, the `testBean` bean is given an `ObjectName` of `bean:name=testBean1`, -since this is the entry in the `Properties` instance that has a key corresponding to the -bean key. - -If no entry in the `Properties` instance can be found, the bean key name is used as -the `ObjectName`. - - -[[jmx-naming-metadata]] -=== Using `MetadataNamingStrategy` - -`MetadataNamingStrategy` uses the `objectName` property of the `ManagedResource` -attribute on each bean to create the `ObjectName`. The following code shows the -configuration for the `MetadataNamingStrategy`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="testBean" value-ref="testBean"/> - </map> - </property> - <property name="namingStrategy" ref="namingStrategy"/> - </bean> - - <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - <bean id="namingStrategy" class="org.springframework.jmx.export.naming.MetadataNamingStrategy"> - <property name="attributeSource" ref="attributeSource"/> - </bean> - - <bean id="attributeSource" - class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/> - - </beans> ----- - -If no `objectName` has been provided for the `ManagedResource` attribute, an -`ObjectName` is created with the following -format: _[fully-qualified-package-name]:type=[short-classname],name=[bean-name]_. For -example, the generated `ObjectName` for the following bean would be -`com.example:type=MyClass,name=myBean`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="myBean" class="com.example.MyClass"/> ----- - - -[[jmx-context-mbeanexport]] -=== Configuring Annotation-based MBean Export - -If you prefer to use <<jmx-interface-metadata, the annotation-based approach>> to define -your management interfaces, a convenience subclass of `MBeanExporter` is available: -`AnnotationMBeanExporter`. When defining an instance of this subclass, you no longer need the -`namingStrategy`, `assembler`, and `attributeSource` configuration, -since it always uses standard Java annotation-based metadata (autodetection is -always enabled as well). In fact, rather than defining an `MBeanExporter` bean, an even -simpler syntax is supported by the `@EnableMBeanExport` `@Configuration` annotation, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableMBeanExport - public class AppConfig { - - } ----- - -If you prefer XML-based configuration, the `<context:mbean-export/>` element serves the -same purpose and is shown in the following listing: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <context:mbean-export/> ----- - -If necessary, you can provide a reference to a particular MBean `server`, and the -`defaultDomain` attribute (a property of `AnnotationMBeanExporter`) accepts an alternate -value for the generated MBean `ObjectName` domains. This is used in place of the -fully qualified package name as described in the previous section on -<<jmx-naming-metadata, MetadataNamingStrategy>>, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @EnableMBeanExport(server="myMBeanServer", defaultDomain="myDomain") - @Configuration - ContextConfiguration { - - } ----- - -The following example shows the XML equivalent of the preceding annotation-based example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <context:mbean-export server="myMBeanServer" default-domain="myDomain"/> ----- - -CAUTION: Do not use interface-based AOP proxies in combination with autodetection of JMX -annotations in your bean classes. Interface-based proxies "`hide`" the target class, which -also hides the JMX-managed resource annotations. Hence, you should use target-class proxies in that -case (through setting the 'proxy-target-class' flag on `<aop:config/>`, -`<tx:annotation-driven/>` and so on). Otherwise, your JMX beans might be silently ignored at -startup. - - - -[[jmx-jsr160]] -== Using JSR-160 Connectors - -For remote access, Spring JMX module offers two `FactoryBean` implementations inside the -`org.springframework.jmx.support` package for creating both server- and client-side -connectors. - - -[[jmx-jsr160-server]] -=== Server-side Connectors - -To have Spring JMX create, start, and expose a JSR-160 `JMXConnectorServer`, you can use the -following configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="serverConnector" class="org.springframework.jmx.support.ConnectorServerFactoryBean"/> ----- - -By default, `ConnectorServerFactoryBean` creates a `JMXConnectorServer` bound to -`service:jmx:jmxmp://localhost:9875`. The `serverConnector` bean thus exposes the -local `MBeanServer` to clients through the JMXMP protocol on localhost, port 9875. Note -that the JMXMP protocol is marked as optional by the JSR 160 specification. Currently, -the main open-source JMX implementation, MX4J, and the one provided with the JDK -do not support JMXMP. - -To specify another URL and register the `JMXConnectorServer` itself with the -`MBeanServer`, you can use the `serviceUrl` and `ObjectName` properties, respectively, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="serverConnector" - class="org.springframework.jmx.support.ConnectorServerFactoryBean"> - <property name="objectName" value="connector:name=rmi"/> - <property name="serviceUrl" - value="service:jmx:rmi://localhost/jndi/rmi://localhost:1099/myconnector"/> - </bean> ----- - -If the `ObjectName` property is set, Spring automatically registers your connector -with the `MBeanServer` under that `ObjectName`. The following example shows the full set of -parameters that you can pass to the `ConnectorServerFactoryBean` when creating a -`JMXConnector`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="serverConnector" - class="org.springframework.jmx.support.ConnectorServerFactoryBean"> - <property name="objectName" value="connector:name=iiop"/> - <property name="serviceUrl" - value="service:jmx:iiop://localhost/jndi/iiop://localhost:900/myconnector"/> - <property name="threaded" value="true"/> - <property name="daemon" value="true"/> - <property name="environment"> - <map> - <entry key="someKey" value="someValue"/> - </map> - </property> - </bean> ----- - -Note that, when you use a RMI-based connector, you need the lookup service (`tnameserv` or -`rmiregistry`) to be started in order for the name registration to complete. - - -[[jmx-jsr160-client]] -=== Client-side Connectors - -To create an `MBeanServerConnection` to a remote JSR-160-enabled `MBeanServer`, you can use the -`MBeanServerConnectionFactoryBean`, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="clientConnector" class="org.springframework.jmx.support.MBeanServerConnectionFactoryBean"> - <property name="serviceUrl" value="service:jmx:rmi://localhost/jndi/rmi://localhost:1099/jmxrmi"/> - </bean> ----- - - -[[jmx-jsr160-protocols]] -=== JMX over Hessian or SOAP - -JSR-160 permits extensions to the way in which communication is done between the client -and the server. The examples shown in the preceding sections use the mandatory RMI-based implementation -required by the JSR-160 specification (IIOP and JRMP) and the (optional) JMXMP. By using -other providers or JMX implementations (such as http://mx4j.sourceforge.net[MX4J]) you -can take advantage of protocols such as SOAP or Hessian over simple HTTP or SSL and others, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="serverConnector" class="org.springframework.jmx.support.ConnectorServerFactoryBean"> - <property name="objectName" value="connector:name=burlap"/> - <property name="serviceUrl" value="service:jmx:burlap://localhost:9874"/> - </bean> ----- - -In the preceding example, we used MX4J 3.0.0. See the official MX4J -documentation for more information. - - - -[[jmx-proxy]] -== Accessing MBeans through Proxies - -Spring JMX lets you create proxies that re-route calls to MBeans that are registered in a -local or remote `MBeanServer`. These proxies provide you with a standard Java interface, -through which you can interact with your MBeans. The following code shows how to configure a -proxy for an MBean running in a local `MBeanServer`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="proxy" class="org.springframework.jmx.access.MBeanProxyFactoryBean"> - <property name="objectName" value="bean:name=testBean"/> - <property name="proxyInterface" value="org.springframework.jmx.IJmxTestBean"/> - </bean> ----- - -In the preceding example, you can see that a proxy is created for the MBean registered under the -`ObjectName` of `bean:name=testBean`. The set of interfaces that the proxy implements -is controlled by the `proxyInterfaces` property, and the rules for mapping methods and -properties on these interfaces to operations and attributes on the MBean are the same -rules used by the `InterfaceBasedMBeanInfoAssembler`. - -The `MBeanProxyFactoryBean` can create a proxy to any MBean that is accessible through an -`MBeanServerConnection`. By default, the local `MBeanServer` is located and used, but -you can override this and provide an `MBeanServerConnection` that points to a remote -`MBeanServer` to cater for proxies that point to remote MBeans: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="clientConnector" - class="org.springframework.jmx.support.MBeanServerConnectionFactoryBean"> - <property name="serviceUrl" value="service:jmx:rmi://remotehost:9875"/> - </bean> - - <bean id="proxy" class="org.springframework.jmx.access.MBeanProxyFactoryBean"> - <property name="objectName" value="bean:name=testBean"/> - <property name="proxyInterface" value="org.springframework.jmx.IJmxTestBean"/> - <property name="server" ref="clientConnector"/> - </bean> ----- - -In the preceding example, we create an `MBeanServerConnection` that points to a remote machine -that uses the `MBeanServerConnectionFactoryBean`. This `MBeanServerConnection` is then -passed to the `MBeanProxyFactoryBean` through the `server` property. The proxy that is -created forwards all invocations to the `MBeanServer` through this -`MBeanServerConnection`. - - - -[[jmx-notifications]] -== Notifications - -Spring's JMX offering includes comprehensive support for JMX notifications. - - -[[jmx-notifications-listeners]] -=== Registering Listeners for Notifications - -Spring's JMX support makes it easy to register any number of -`NotificationListeners` with any number of MBeans (this includes MBeans exported by -Spring's `MBeanExporter` and MBeans registered through some other mechanism). For -example, consider the scenario where one would like to be informed (through a -`Notification`) each and every time an attribute of a target MBean changes. The following -example writes notifications to the console: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package com.example; - - import javax.management.AttributeChangeNotification; - import javax.management.Notification; - import javax.management.NotificationFilter; - import javax.management.NotificationListener; - - public class ConsoleLoggingNotificationListener - implements NotificationListener, NotificationFilter { - - public void handleNotification(Notification notification, Object handback) { - System.out.println(notification); - System.out.println(handback); - } - - public boolean isNotificationEnabled(Notification notification) { - return AttributeChangeNotification.class.isAssignableFrom(notification.getClass()); - } - - } ----- - -The following example adds `ConsoleLoggingNotificationListener` (defined in the preceding -example) to `notificationListenerMappings`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="bean:name=testBean1" value-ref="testBean"/> - </map> - </property> - <property name="notificationListenerMappings"> - <map> - <entry key="bean:name=testBean1"> - <bean class="com.example.ConsoleLoggingNotificationListener"/> - </entry> - </map> - </property> - </bean> - - <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - </beans> ----- - -With the preceding configuration in place, every time a JMX `Notification` is broadcast from -the target MBean (`bean:name=testBean1`), the `ConsoleLoggingNotificationListener` bean -that was registered as a listener through the `notificationListenerMappings` property is -notified. The `ConsoleLoggingNotificationListener` bean can then take whatever action -it deems appropriate in response to the `Notification`. - -You can also use straight bean names as the link between exported beans and listeners, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="bean:name=testBean1" value-ref="testBean"/> - </map> - </property> - <property name="notificationListenerMappings"> - <map> - <entry key="__testBean__"> - <bean class="com.example.ConsoleLoggingNotificationListener"/> - </entry> - </map> - </property> - </bean> - - <bean id="__testBean__" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - </beans> ----- - -If you want to register a single `NotificationListener` instance for all of the beans -that the enclosing `MBeanExporter` exports, you can use the special wildcard (`{asterisk}`) -as the key for an entry in the `notificationListenerMappings` property -map, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <property name="notificationListenerMappings"> - <map> - <entry key="*"> - <bean class="com.example.ConsoleLoggingNotificationListener"/> - </entry> - </map> - </property> ----- - -If you need to do the inverse (that is, register a number of distinct listeners against -an MBean), you must instead use the `notificationListeners` list property (in -preference to the `notificationListenerMappings` property). This time, instead of -configuring a `NotificationListener` for a single MBean, we configure -`NotificationListenerBean` instances. A `NotificationListenerBean` encapsulates a -`NotificationListener` and the `ObjectName` (or `ObjectNames`) that it is to be -registered against in an `MBeanServer`. The `NotificationListenerBean` also encapsulates -a number of other properties, such as a `NotificationFilter` and an arbitrary handback -object that can be used in advanced JMX notification scenarios. - -The configuration when using `NotificationListenerBean` instances is not wildly -different to what was presented previously, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="bean:name=testBean1" value-ref="testBean"/> - </map> - </property> - <property name="notificationListeners"> - <list> - <bean class="org.springframework.jmx.export.NotificationListenerBean"> - <constructor-arg> - <bean class="com.example.ConsoleLoggingNotificationListener"/> - </constructor-arg> - <property name="mappedObjectNames"> - <list> - <value>bean:name=testBean1</value> - </list> - </property> - </bean> - </list> - </property> - </bean> - - <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - </beans> ----- - -The preceding example is equivalent to the first notification example. Assume, then, that -we want to be given a handback object every time a `Notification` is raised and that -we also want to filter out extraneous `Notifications` by supplying a -`NotificationFilter`. The following example accomplishes these goals: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> - <property name="beans"> - <map> - <entry key="bean:name=testBean1" value-ref="testBean1"/> - <entry key="bean:name=testBean2" value-ref="testBean2"/> - </map> - </property> - <property name="notificationListeners"> - <list> - <bean class="org.springframework.jmx.export.NotificationListenerBean"> - <constructor-arg ref="customerNotificationListener"/> - <property name="mappedObjectNames"> - <list> - <!-- handles notifications from two distinct MBeans --> - <value>bean:name=testBean1</value> - <value>bean:name=testBean2</value> - </list> - </property> - <property name="handback"> - <bean class="java.lang.String"> - <constructor-arg value="This could be anything..."/> - </bean> - </property> - <property name="notificationFilter" ref="customerNotificationListener"/> - </bean> - </list> - </property> - </bean> - - <!-- implements both the NotificationListener and NotificationFilter interfaces --> - <bean id="customerNotificationListener" class="com.example.ConsoleLoggingNotificationListener"/> - - <bean id="testBean1" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="TEST"/> - <property name="age" value="100"/> - </bean> - - <bean id="testBean2" class="org.springframework.jmx.JmxTestBean"> - <property name="name" value="ANOTHER TEST"/> - <property name="age" value="200"/> - </bean> - - </beans> ----- - -(For a full discussion of what a handback object is and, -indeed, what a `NotificationFilter` is, see the section of the JMX -specification (1.2) entitled 'The JMX Notification Model'.) - - -[[jmx-notifications-publishing]] -=== Publishing Notifications - -Spring provides support not only for registering to receive `Notifications` but also -for publishing `Notifications`. - -NOTE: This section is really only relevant to Spring-managed beans that have -been exposed as MBeans through an `MBeanExporter`. Any existing user-defined MBeans should -use the standard JMX APIs for notification publication. - -The key interface in Spring's JMX notification publication support is the -`NotificationPublisher` interface (defined in the -`org.springframework.jmx.export.notification` package). Any bean that is going to be -exported as an MBean through an `MBeanExporter` instance can implement the related -`NotificationPublisherAware` interface to gain access to a `NotificationPublisher` -instance. The `NotificationPublisherAware` interface supplies an instance of a -`NotificationPublisher` to the implementing bean through a simple setter method, -which the bean can then use to publish `Notifications`. - -As stated in the javadoc of the -{api-spring-framework}/jmx/export/notification/NotificationPublisher.html[`NotificationPublisher`] -interface, managed beans that publish events through the `NotificationPublisher` -mechanism are not responsible for the state management of notification listeners. -Spring's JMX support takes care of handling all the JMX infrastructure issues. -All you need to do, as an application developer, is implement the -`NotificationPublisherAware` interface and start publishing events by using the -supplied `NotificationPublisher` instance. Note that the `NotificationPublisher` -is set after the managed bean has been registered with an `MBeanServer`. - -Using a `NotificationPublisher` instance is quite straightforward. You create a JMX -`Notification` instance (or an instance of an appropriate `Notification` subclass), -populate the notification with the data pertinent to the event that is to be -published, and invoke the `sendNotification(Notification)` on the -`NotificationPublisher` instance, passing in the `Notification`. - -In the following example, exported instances of the `JmxTestBean` publish a -`NotificationEvent` every time the `add(int, int)` operation is invoked: - -[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ----- - package org.springframework.jmx; - - import org.springframework.jmx.export.notification.NotificationPublisherAware; - import org.springframework.jmx.export.notification.NotificationPublisher; - import javax.management.Notification; - - public class JmxTestBean implements IJmxTestBean, NotificationPublisherAware { - - private String name; - private int age; - private boolean isSuperman; - private NotificationPublisher publisher; - - // other getters and setters omitted for clarity - - public int add(int x, int y) { - int answer = x + y; - this.publisher.sendNotification(new Notification("add", this, 0)); - return answer; - } - - public void dontExposeMe() { - throw new RuntimeException(); - } - - public void setNotificationPublisher(NotificationPublisher notificationPublisher) { - this.publisher = notificationPublisher; - } - - } ----- - -The `NotificationPublisher` interface and the machinery to get it all working is one of -the nicer features of Spring's JMX support. It does, however, come with the price tag of -coupling your classes to both Spring and JMX. As always, the advice here is to be -pragmatic. If you need the functionality offered by the `NotificationPublisher` and -you can accept the coupling to both Spring and JMX, then do so. - - - -[[jmx-resources]] -== Further Resources - -This section contains links to further resources about JMX: - -* The https://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[JMX -homepage] at Oracle. -* The https://jcp.org/aboutJava/communityprocess/final/jsr003/index3.html[JMX - specification] (JSR-000003). -* The https://jcp.org/aboutJava/communityprocess/final/jsr160/index.html[JMX Remote API - specification] (JSR-000160). -* The http://mx4j.sourceforge.net/[MX4J homepage]. (MX4J is an open-source implementation of - various JMX specs.) - diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc new file mode 100644 index 000000000000..fb452d849f99 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc @@ -0,0 +1,283 @@ +[[jmx-exporting]] += Exporting Your Beans to JMX + +The core class in Spring's JMX framework is the `MBeanExporter`. This class is +responsible for taking your Spring beans and registering them with a JMX `MBeanServer`. +For example, consider the following class: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages",chomp="-packages"] +---- + package org.springframework.jmx; + + public class JmxTestBean implements IJmxTestBean { + + private String name; + private int age; + private boolean isSuperman; + + public int getAge() { + return age; + } + + public void setAge(int age) { + this.age = age; + } + + public void setName(String name) { + this.name = name; + } + + public String getName() { + return name; + } + + public int add(int x, int y) { + return x + y; + } + + public void dontExposeMe() { + throw new RuntimeException(); + } + } +---- + +To expose the properties and methods of this bean as attributes and operations of an +MBean, you can configure an instance of the `MBeanExporter` class in your +configuration file and pass in the bean, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <!-- this bean must not be lazily initialized if the exporting is to happen --> + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter" lazy-init="false"> + <property name="beans"> + <map> + <entry key="bean:name=testBean1" value-ref="testBean"/> + </map> + </property> + </bean> + <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + </beans> +---- + +The pertinent bean definition from the preceding configuration snippet is the `exporter` +bean. The `beans` property tells the `MBeanExporter` exactly which of your beans must be +exported to the JMX `MBeanServer`. In the default configuration, the key of each entry +in the `beans` `Map` is used as the `ObjectName` for the bean referenced by the +corresponding entry value. You can change this behavior, as described in <<jmx-naming>>. + +With this configuration, the `testBean` bean is exposed as an MBean under the +`ObjectName` `bean:name=testBean1`. By default, all `public` properties of the bean +are exposed as attributes and all `public` methods (except those inherited from the +`Object` class) are exposed as operations. + +NOTE: `MBeanExporter` is a `Lifecycle` bean (see <<core.adoc#beans-factory-lifecycle-processor, +Startup and Shutdown Callbacks>>). By default, MBeans are exported as late as possible during +the application lifecycle. You can configure the `phase` at which +the export happens or disable automatic registration by setting the `autoStartup` flag. + + +[[jmx-exporting-mbeanserver]] +== Creating an MBeanServer + +The configuration shown in the <<jmx-exporting, preceding section>> assumes that the +application is running in an environment that has one (and only one) `MBeanServer` +already running. In this case, Spring tries to locate the running `MBeanServer` and +register your beans with that server (if any). This behavior is useful when your +application runs inside a container (such as Tomcat or IBM WebSphere) that has its +own `MBeanServer`. + +However, this approach is of no use in a standalone environment or when running inside +a container that does not provide an `MBeanServer`. To address this, you can create an +`MBeanServer` instance declaratively by adding an instance of the +`org.springframework.jmx.support.MBeanServerFactoryBean` class to your configuration. +You can also ensure that a specific `MBeanServer` is used by setting the value of the +`MBeanExporter` instance's `server` property to the `MBeanServer` value returned by an +`MBeanServerFactoryBean`, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean"/> + + <!-- + this bean needs to be eagerly pre-instantiated in order for the exporting to occur; + this means that it must not be marked as lazily initialized + --> + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="bean:name=testBean1" value-ref="testBean"/> + </map> + </property> + <property name="server" ref="mbeanServer"/> + </bean> + + <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + </beans> +---- + +In the preceding example, an instance of `MBeanServer` is created by the `MBeanServerFactoryBean` and is +supplied to the `MBeanExporter` through the `server` property. When you supply your own +`MBeanServer` instance, the `MBeanExporter` does not try to locate a running +`MBeanServer` and uses the supplied `MBeanServer` instance. For this to work +correctly, you must have a JMX implementation on your classpath. + + +[[jmx-mbean-server]] +== Reusing an Existing `MBeanServer` + +If no server is specified, the `MBeanExporter` tries to automatically detect a running +`MBeanServer`. This works in most environments, where only one `MBeanServer` instance is +used. However, when multiple instances exist, the exporter might pick the wrong server. +In such cases, you should use the `MBeanServer` `agentId` to indicate which instance to +be used, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean"> + <!-- indicate to first look for a server --> + <property name="locateExistingServerIfPossible" value="true"/> + <!-- search for the MBeanServer instance with the given agentId --> + <property name="agentId" value="MBeanServer_instance_agentId>"/> + </bean> + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="server" ref="mbeanServer"/> + ... + </bean> + </beans> +---- + +For platforms or cases where the existing `MBeanServer` has a dynamic (or unknown) +`agentId` that is retrieved through lookup methods, you should use +<<core.adoc#beans-factory-class-static-factory-method, factory-method>>, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="server"> + <!-- Custom MBeanServerLocator --> + <bean class="platform.package.MBeanServerLocator" factory-method="locateMBeanServer"/> + </property> + </bean> + + <!-- other beans here --> + + </beans> +---- + + +[[jmx-exporting-lazy]] +== Lazily Initialized MBeans + +If you configure a bean with an `MBeanExporter` that is also configured for lazy +initialization, the `MBeanExporter` does not break this contract and avoids +instantiating the bean. Instead, it registers a proxy with the `MBeanServer` and +defers obtaining the bean from the container until the first invocation on the proxy +occurs. + + +[[jmx-exporting-auto]] +== Automatic Registration of MBeans + +Any beans that are exported through the `MBeanExporter` and are already valid MBeans are +registered as-is with the `MBeanServer` without further intervention from Spring. You can cause MBeans +to be automatically detected by the `MBeanExporter` by setting the `autodetect` +property to `true`, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="autodetect" value="true"/> + </bean> + + <bean name="spring:mbean=true" class="org.springframework.jmx.export.TestDynamicMBean"/> +---- + +In the preceding example, the bean called `spring:mbean=true` is already a valid JMX MBean +and is automatically registered by Spring. By default, a bean that is autodetected for JMX +registration has its bean name used as the `ObjectName`. You can override this behavior, +as detailed in <<jmx-naming>>. + + +[[jmx-exporting-registration-behavior]] +== Controlling the Registration Behavior + +Consider the scenario where a Spring `MBeanExporter` attempts to register an `MBean` +with an `MBeanServer` by using the `ObjectName` `bean:name=testBean1`. If an `MBean` +instance has already been registered under that same `ObjectName`, the default behavior +is to fail (and throw an `InstanceAlreadyExistsException`). + +You can control exactly what happens when an `MBean` is +registered with an `MBeanServer`. Spring's JMX support allows for three different +registration behaviors to control the registration behavior when the registration +process finds that an `MBean` has already been registered under the same `ObjectName`. +The following table summarizes these registration behaviors: + +[[jmx-registration-behaviors]] +.Registration Behaviors +[cols="1,4"] +|=== +| Registration behavior | Explanation + +| `FAIL_ON_EXISTING` +| This is the default registration behavior. If an `MBean` instance has already been + registered under the same `ObjectName`, the `MBean` that is being registered is not + registered, and an `InstanceAlreadyExistsException` is thrown. The existing + `MBean` is unaffected. + +| `IGNORE_EXISTING` +| If an `MBean` instance has already been registered under the same `ObjectName`, the + `MBean` that is being registered is not registered. The existing `MBean` is + unaffected, and no `Exception` is thrown. This is useful in settings where + multiple applications want to share a common `MBean` in a shared `MBeanServer`. + +| `REPLACE_EXISTING` +| If an `MBean` instance has already been registered under the same `ObjectName`, the + existing `MBean` that was previously registered is unregistered, and the new + `MBean` is registered in its place (the new `MBean` effectively replaces the + previous instance). +|=== + +The values in the preceding table are defined as enums on the `RegistrationPolicy` class. +If you want to change the default registration behavior, you need to set the value of the +`registrationPolicy` property on your `MBeanExporter` definition to one of those +values. + +The following example shows how to change from the default registration +behavior to the `REPLACE_EXISTING` behavior: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="bean:name=testBean1" value-ref="testBean"/> + </map> + </property> + <property name="registrationPolicy" value="REPLACE_EXISTING"/> + </bean> + + <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + </beans> +---- + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc new file mode 100644 index 000000000000..98598aefefd4 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc @@ -0,0 +1,417 @@ +[[jmx-interface]] += Controlling the Management Interface of Your Beans + +In the example in the <<jmx-exporting-registration-behavior, preceding section>>, +you had little control over the management interface of your bean. All of the `public` +properties and methods of each exported bean were exposed as JMX attributes and +operations, respectively. To exercise finer-grained control over exactly which +properties and methods of your exported beans are actually exposed as JMX attributes +and operations, Spring JMX provides a comprehensive and extensible mechanism for +controlling the management interfaces of your beans. + + +[[jmx-interface-assembler]] +== Using the `MBeanInfoAssembler` Interface + +Behind the scenes, the `MBeanExporter` delegates to an implementation of the +`org.springframework.jmx.export.assembler.MBeanInfoAssembler` interface, which is +responsible for defining the management interface of each bean that is exposed. +The default implementation, +`org.springframework.jmx.export.assembler.SimpleReflectiveMBeanInfoAssembler`, +defines a management interface that exposes all public properties and methods +(as you saw in the examples in the preceding sections). Spring provides two +additional implementations of the `MBeanInfoAssembler` interface that let you +control the generated management interface by using either source-level metadata +or any arbitrary interface. + + +[[jmx-interface-metadata]] +== Using Source-level Metadata: Java Annotations + +By using the `MetadataMBeanInfoAssembler`, you can define the management interfaces +for your beans by using source-level metadata. The reading of metadata is encapsulated +by the `org.springframework.jmx.export.metadata.JmxAttributeSource` interface. +Spring JMX provides a default implementation that uses Java annotations, namely +`org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource`. +You must configure the `MetadataMBeanInfoAssembler` with an implementation instance of +the `JmxAttributeSource` interface for it to function correctly (there is no default). + +To mark a bean for export to JMX, you should annotate the bean class with the +`ManagedResource` annotation. You must mark each method you wish to expose as an operation +with the `ManagedOperation` annotation and mark each property you wish to expose +with the `ManagedAttribute` annotation. When marking properties, you can omit +either the annotation of the getter or the setter to create a write-only or read-only +attribute, respectively. + +NOTE: A `ManagedResource`-annotated bean must be public, as must the methods exposing +an operation or an attribute. + +The following example shows the annotated version of the `JmxTestBean` class that we +used in <<jmx-exporting-mbeanserver>>: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.jmx; + + import org.springframework.jmx.export.annotation.ManagedResource; + import org.springframework.jmx.export.annotation.ManagedOperation; + import org.springframework.jmx.export.annotation.ManagedAttribute; + + @ManagedResource( + objectName="bean:name=testBean4", + description="My Managed Bean", + log=true, + logFile="jmx.log", + currencyTimeLimit=15, + persistPolicy="OnUpdate", + persistPeriod=200, + persistLocation="foo", + persistName="bar") + public class AnnotationTestBean implements IJmxTestBean { + + private String name; + private int age; + + @ManagedAttribute(description="The Age Attribute", currencyTimeLimit=15) + public int getAge() { + return age; + } + + public void setAge(int age) { + this.age = age; + } + + @ManagedAttribute(description="The Name Attribute", + currencyTimeLimit=20, + defaultValue="bar", + persistPolicy="OnUpdate") + public void setName(String name) { + this.name = name; + } + + @ManagedAttribute(defaultValue="foo", persistPeriod=300) + public String getName() { + return name; + } + + @ManagedOperation(description="Add two numbers") + @ManagedOperationParameters({ + @ManagedOperationParameter(name = "x", description = "The first number"), + @ManagedOperationParameter(name = "y", description = "The second number")}) + public int add(int x, int y) { + return x + y; + } + + public void dontExposeMe() { + throw new RuntimeException(); + } + + } +---- + +In the preceding example, you can see that the `JmxTestBean` class is marked with the +`ManagedResource` annotation and that this `ManagedResource` annotation is configured +with a set of properties. These properties can be used to configure various aspects +of the MBean that is generated by the `MBeanExporter` and are explained in greater +detail later in <<jmx-interface-metadata-types>>. + +Both the `age` and `name` properties are annotated with the `ManagedAttribute` +annotation, but, in the case of the `age` property, only the getter is marked. +This causes both of these properties to be included in the management interface +as attributes, but the `age` attribute is read-only. + +Finally, the `add(int, int)` method is marked with the `ManagedOperation` attribute, +whereas the `dontExposeMe()` method is not. This causes the management interface to +contain only one operation (`add(int, int)`) when you use the `MetadataMBeanInfoAssembler`. + +The following configuration shows how you can configure the `MBeanExporter` to use the +`MetadataMBeanInfoAssembler`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="assembler" ref="assembler"/> + <property name="namingStrategy" ref="namingStrategy"/> + <property name="autodetect" value="true"/> + </bean> + + <bean id="jmxAttributeSource" + class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/> + + <!-- will create management interface using annotation metadata --> + <bean id="assembler" + class="org.springframework.jmx.export.assembler.MetadataMBeanInfoAssembler"> + <property name="attributeSource" ref="jmxAttributeSource"/> + </bean> + + <!-- will pick up the ObjectName from the annotation --> + <bean id="namingStrategy" + class="org.springframework.jmx.export.naming.MetadataNamingStrategy"> + <property name="attributeSource" ref="jmxAttributeSource"/> + </bean> + + <bean id="testBean" class="org.springframework.jmx.AnnotationTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + </beans> +---- + +In the preceding example, an `MetadataMBeanInfoAssembler` bean has been configured with an +instance of the `AnnotationJmxAttributeSource` class and passed to the `MBeanExporter` +through the assembler property. This is all that is required to take advantage of +metadata-driven management interfaces for your Spring-exposed MBeans. + + +[[jmx-interface-metadata-types]] +== Source-level Metadata Types + +The following table describes the source-level metadata types that are available for use in Spring JMX: + +[[jmx-metadata-types]] +.Source-level metadata types +|=== +| Purpose| Annotation| Annotation Type + +| Mark all instances of a `Class` as JMX managed resources. +| `@ManagedResource` +| Class + +| Mark a method as a JMX operation. +| `@ManagedOperation` +| Method + +| Mark a getter or setter as one half of a JMX attribute. +| `@ManagedAttribute` +| Method (only getters and setters) + +| Define descriptions for operation parameters. +| `@ManagedOperationParameter` and `@ManagedOperationParameters` +| Method +|=== + +The following table describes the configuration parameters that are available for use on these source-level +metadata types: + +[[jmx-metadata-parameters]] +.Source-level metadata parameters +[cols="1,3,1"] +|=== +| Parameter | Description | Applies to + +| `ObjectName` +| Used by `MetadataNamingStrategy` to determine the `ObjectName` of a managed resource. +| `ManagedResource` + +| `description` +| Sets the friendly description of the resource, attribute or operation. +| `ManagedResource`, `ManagedAttribute`, `ManagedOperation`, or `ManagedOperationParameter` + +| `currencyTimeLimit` +| Sets the value of the `currencyTimeLimit` descriptor field. +| `ManagedResource` or `ManagedAttribute` + +| `defaultValue` +| Sets the value of the `defaultValue` descriptor field. +| `ManagedAttribute` + +| `log` +| Sets the value of the `log` descriptor field. +| `ManagedResource` + +| `logFile` +| Sets the value of the `logFile` descriptor field. +| `ManagedResource` + +| `persistPolicy` +| Sets the value of the `persistPolicy` descriptor field. +| `ManagedResource` + +| `persistPeriod` +| Sets the value of the `persistPeriod` descriptor field. +| `ManagedResource` + +| `persistLocation` +| Sets the value of the `persistLocation` descriptor field. +| `ManagedResource` + +| `persistName` +| Sets the value of the `persistName` descriptor field. +| `ManagedResource` + +| `name` +| Sets the display name of an operation parameter. +| `ManagedOperationParameter` + +| `index` +| Sets the index of an operation parameter. +| `ManagedOperationParameter` +|=== + + +[[jmx-interface-autodetect]] +== Using the `AutodetectCapableMBeanInfoAssembler` Interface + +To simplify configuration even further, Spring includes the +`AutodetectCapableMBeanInfoAssembler` interface, which extends the `MBeanInfoAssembler` +interface to add support for autodetection of MBean resources. If you configure the +`MBeanExporter` with an instance of `AutodetectCapableMBeanInfoAssembler`, it is +allowed to "`vote`" on the inclusion of beans for exposure to JMX. + +The only implementation of the `AutodetectCapableMBeanInfo` interface is +the `MetadataMBeanInfoAssembler`, which votes to include any bean that is marked +with the `ManagedResource` attribute. The default approach in this case is to use the +bean name as the `ObjectName`, which results in a configuration similar to the following: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <!-- notice how no 'beans' are explicitly configured here --> + <property name="autodetect" value="true"/> + <property name="assembler" ref="assembler"/> + </bean> + + <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + <bean id="assembler" class="org.springframework.jmx.export.assembler.MetadataMBeanInfoAssembler"> + <property name="attributeSource"> + <bean class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/> + </property> + </bean> + + </beans> +---- + +Notice that, in the preceding configuration, no beans are passed to the `MBeanExporter`. +However, the `JmxTestBean` is still registered, since it is marked with the `ManagedResource` +attribute and the `MetadataMBeanInfoAssembler` detects this and votes to include it. +The only problem with this approach is that the name of the `JmxTestBean` now has business +meaning. You can address this issue by changing the default behavior for `ObjectName` +creation as defined in <<jmx-naming>>. + + +[[jmx-interface-java]] +== Defining Management Interfaces by Using Java Interfaces + +In addition to the `MetadataMBeanInfoAssembler`, Spring also includes the +`InterfaceBasedMBeanInfoAssembler`, which lets you constrain the methods and +properties that are exposed based on the set of methods defined in a collection of +interfaces. + +Although the standard mechanism for exposing MBeans is to use interfaces and a simple +naming scheme, `InterfaceBasedMBeanInfoAssembler` extends this functionality by +removing the need for naming conventions, letting you use more than one interface +and removing the need for your beans to implement the MBean interfaces. + +Consider the following interface, which is used to define a management interface for the +`JmxTestBean` class that we showed earlier: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public interface IJmxTestBean { + + public int add(int x, int y); + + public long myOperation(); + + public int getAge(); + + public void setAge(int age); + + public void setName(String name); + + public String getName(); + + } +---- + +This interface defines the methods and properties that are exposed as operations and +attributes on the JMX MBean. The following code shows how to configure Spring JMX to use +this interface as the definition for the management interface: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="bean:name=testBean5" value-ref="testBean"/> + </map> + </property> + <property name="assembler"> + <bean class="org.springframework.jmx.export.assembler.InterfaceBasedMBeanInfoAssembler"> + <property name="managedInterfaces"> + <value>org.springframework.jmx.IJmxTestBean</value> + </property> + </bean> + </property> + </bean> + + <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + </beans> +---- + +In the preceding example, the `InterfaceBasedMBeanInfoAssembler` is configured to use the +`IJmxTestBean` interface when constructing the management interface for any bean. It is +important to understand that beans processed by the `InterfaceBasedMBeanInfoAssembler` +are not required to implement the interface used to generate the JMX management +interface. + +In the preceding case, the `IJmxTestBean` interface is used to construct all management +interfaces for all beans. In many cases, this is not the desired behavior, and you may +want to use different interfaces for different beans. In this case, you can pass +`InterfaceBasedMBeanInfoAssembler` a `Properties` instance through the `interfaceMappings` +property, where the key of each entry is the bean name and the value of each entry is a +comma-separated list of interface names to use for that bean. + +If no management interface is specified through either the `managedInterfaces` or +`interfaceMappings` properties, the `InterfaceBasedMBeanInfoAssembler` reflects +on the bean and uses all of the interfaces implemented by that bean to create the +management interface. + + +[[jmx-interface-methodnames]] +== Using `MethodNameBasedMBeanInfoAssembler` + +`MethodNameBasedMBeanInfoAssembler` lets you specify a list of method names +that are exposed to JMX as attributes and operations. The following code shows a sample +configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="bean:name=testBean5" value-ref="testBean"/> + </map> + </property> + <property name="assembler"> + <bean class="org.springframework.jmx.export.assembler.MethodNameBasedMBeanInfoAssembler"> + <property name="managedMethods"> + <value>add,myOperation,getName,setName,getAge</value> + </property> + </bean> + </property> + </bean> +---- + +In the preceding example, you can see that the `add` and `myOperation` methods are exposed as JMX +operations, and `getName()`, `setName(String)`, and `getAge()` are exposed as the +appropriate half of a JMX attribute. In the preceding code, the method mappings apply to +beans that are exposed to JMX. To control method exposure on a bean-by-bean basis, you can use +the `methodMappings` property of `MethodNameMBeanInfoAssembler` to map bean names to +lists of method names. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/jsr160.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/jsr160.adoc new file mode 100644 index 000000000000..7d9ce296d2b1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jmx/jsr160.adoc @@ -0,0 +1,103 @@ +[[jmx-jsr160]] += Using JSR-160 Connectors + +For remote access, Spring JMX module offers two `FactoryBean` implementations inside the +`org.springframework.jmx.support` package for creating both server- and client-side +connectors. + + +[[jmx-jsr160-server]] +== Server-side Connectors + +To have Spring JMX create, start, and expose a JSR-160 `JMXConnectorServer`, you can use the +following configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="serverConnector" class="org.springframework.jmx.support.ConnectorServerFactoryBean"/> +---- + +By default, `ConnectorServerFactoryBean` creates a `JMXConnectorServer` bound to +`service:jmx:jmxmp://localhost:9875`. The `serverConnector` bean thus exposes the +local `MBeanServer` to clients through the JMXMP protocol on localhost, port 9875. Note +that the JMXMP protocol is marked as optional by the JSR 160 specification. Currently, +the main open-source JMX implementation, MX4J, and the one provided with the JDK +do not support JMXMP. + +To specify another URL and register the `JMXConnectorServer` itself with the +`MBeanServer`, you can use the `serviceUrl` and `ObjectName` properties, respectively, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="serverConnector" + class="org.springframework.jmx.support.ConnectorServerFactoryBean"> + <property name="objectName" value="connector:name=rmi"/> + <property name="serviceUrl" + value="service:jmx:rmi://localhost/jndi/rmi://localhost:1099/myconnector"/> + </bean> +---- + +If the `ObjectName` property is set, Spring automatically registers your connector +with the `MBeanServer` under that `ObjectName`. The following example shows the full set of +parameters that you can pass to the `ConnectorServerFactoryBean` when creating a +`JMXConnector`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="serverConnector" + class="org.springframework.jmx.support.ConnectorServerFactoryBean"> + <property name="objectName" value="connector:name=iiop"/> + <property name="serviceUrl" + value="service:jmx:iiop://localhost/jndi/iiop://localhost:900/myconnector"/> + <property name="threaded" value="true"/> + <property name="daemon" value="true"/> + <property name="environment"> + <map> + <entry key="someKey" value="someValue"/> + </map> + </property> + </bean> +---- + +Note that, when you use a RMI-based connector, you need the lookup service (`tnameserv` or +`rmiregistry`) to be started in order for the name registration to complete. + + +[[jmx-jsr160-client]] +== Client-side Connectors + +To create an `MBeanServerConnection` to a remote JSR-160-enabled `MBeanServer`, you can use the +`MBeanServerConnectionFactoryBean`, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="clientConnector" class="org.springframework.jmx.support.MBeanServerConnectionFactoryBean"> + <property name="serviceUrl" value="service:jmx:rmi://localhost/jndi/rmi://localhost:1099/jmxrmi"/> + </bean> +---- + + +[[jmx-jsr160-protocols]] +== JMX over Hessian or SOAP + +JSR-160 permits extensions to the way in which communication is done between the client +and the server. The examples shown in the preceding sections use the mandatory RMI-based implementation +required by the JSR-160 specification (IIOP and JRMP) and the (optional) JMXMP. By using +other providers or JMX implementations (such as http://mx4j.sourceforge.net[MX4J]) you +can take advantage of protocols such as SOAP or Hessian over simple HTTP or SSL and others, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="serverConnector" class="org.springframework.jmx.support.ConnectorServerFactoryBean"> + <property name="objectName" value="connector:name=burlap"/> + <property name="serviceUrl" value="service:jmx:burlap://localhost:9874"/> + </bean> +---- + +In the preceding example, we used MX4J 3.0.0. See the official MX4J +documentation for more information. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc new file mode 100644 index 000000000000..0a0d423d3530 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc @@ -0,0 +1,175 @@ +[[jmx-naming]] += Controlling `ObjectName` Instances for Your Beans + +Behind the scenes, the `MBeanExporter` delegates to an implementation of the +`ObjectNamingStrategy` to obtain an `ObjectName` instance for each of the beans it registers. +By default, the default implementation, `KeyNamingStrategy` uses the key of the +`beans` `Map` as the `ObjectName`. In addition, the `KeyNamingStrategy` can map the key +of the `beans` `Map` to an entry in a `Properties` file (or files) to resolve the +`ObjectName`. In addition to the `KeyNamingStrategy`, Spring provides two additional +`ObjectNamingStrategy` implementations: the `IdentityNamingStrategy` (which builds an +`ObjectName` based on the JVM identity of the bean) and the `MetadataNamingStrategy` (which +uses source-level metadata to obtain the `ObjectName`). + + +[[jmx-naming-properties]] +== Reading `ObjectName` Instances from Properties + +You can configure your own `KeyNamingStrategy` instance and configure it to read +`ObjectName` instances from a `Properties` instance rather than use a bean key. The +`KeyNamingStrategy` tries to locate an entry in the `Properties` with a key +that corresponds to the bean key. If no entry is found or if the `Properties` instance is +`null`, the bean key itself is used. + +The following code shows a sample configuration for the `KeyNamingStrategy`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="testBean" value-ref="testBean"/> + </map> + </property> + <property name="namingStrategy" ref="namingStrategy"/> + </bean> + + <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + <bean id="namingStrategy" class="org.springframework.jmx.export.naming.KeyNamingStrategy"> + <property name="mappings"> + <props> + <prop key="testBean">bean:name=testBean1</prop> + </props> + </property> + <property name="mappingLocations"> + <value>names1.properties,names2.properties</value> + </property> + </bean> + + </beans> +---- + +The preceding example configures an instance of `KeyNamingStrategy` with a `Properties` instance that +is merged from the `Properties` instance defined by the mapping property and the +properties files located in the paths defined by the mappings property. In this +configuration, the `testBean` bean is given an `ObjectName` of `bean:name=testBean1`, +since this is the entry in the `Properties` instance that has a key corresponding to the +bean key. + +If no entry in the `Properties` instance can be found, the bean key name is used as +the `ObjectName`. + + +[[jmx-naming-metadata]] +== Using `MetadataNamingStrategy` + +`MetadataNamingStrategy` uses the `objectName` property of the `ManagedResource` +attribute on each bean to create the `ObjectName`. The following code shows the +configuration for the `MetadataNamingStrategy`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="testBean" value-ref="testBean"/> + </map> + </property> + <property name="namingStrategy" ref="namingStrategy"/> + </bean> + + <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + <bean id="namingStrategy" class="org.springframework.jmx.export.naming.MetadataNamingStrategy"> + <property name="attributeSource" ref="attributeSource"/> + </bean> + + <bean id="attributeSource" + class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/> + + </beans> +---- + +If no `objectName` has been provided for the `ManagedResource` attribute, an +`ObjectName` is created with the following +format: _[fully-qualified-package-name]:type=[short-classname],name=[bean-name]_. For +example, the generated `ObjectName` for the following bean would be +`com.example:type=MyClass,name=myBean`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="myBean" class="com.example.MyClass"/> +---- + + +[[jmx-context-mbeanexport]] +== Configuring Annotation-based MBean Export + +If you prefer to use <<jmx-interface-metadata, the annotation-based approach>> to define +your management interfaces, a convenience subclass of `MBeanExporter` is available: +`AnnotationMBeanExporter`. When defining an instance of this subclass, you no longer need the +`namingStrategy`, `assembler`, and `attributeSource` configuration, +since it always uses standard Java annotation-based metadata (autodetection is +always enabled as well). In fact, rather than defining an `MBeanExporter` bean, an even +simpler syntax is supported by the `@EnableMBeanExport` `@Configuration` annotation, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableMBeanExport + public class AppConfig { + + } +---- + +If you prefer XML-based configuration, the `<context:mbean-export/>` element serves the +same purpose and is shown in the following listing: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <context:mbean-export/> +---- + +If necessary, you can provide a reference to a particular MBean `server`, and the +`defaultDomain` attribute (a property of `AnnotationMBeanExporter`) accepts an alternate +value for the generated MBean `ObjectName` domains. This is used in place of the +fully qualified package name as described in the previous section on +<<jmx-naming-metadata, MetadataNamingStrategy>>, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @EnableMBeanExport(server="myMBeanServer", defaultDomain="myDomain") + @Configuration + ContextConfiguration { + + } +---- + +The following example shows the XML equivalent of the preceding annotation-based example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <context:mbean-export server="myMBeanServer" default-domain="myDomain"/> +---- + +CAUTION: Do not use interface-based AOP proxies in combination with autodetection of JMX +annotations in your bean classes. Interface-based proxies "`hide`" the target class, which +also hides the JMX-managed resource annotations. Hence, you should use target-class proxies in that +case (through setting the 'proxy-target-class' flag on `<aop:config/>`, +`<tx:annotation-driven/>` and so on). Otherwise, your JMX beans might be silently ignored at +startup. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/notifications.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/notifications.adoc new file mode 100644 index 000000000000..78e197acbbb4 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jmx/notifications.adoc @@ -0,0 +1,308 @@ +[[jmx-notifications]] += Notifications + +Spring's JMX offering includes comprehensive support for JMX notifications. + + +[[jmx-notifications-listeners]] +== Registering Listeners for Notifications + +Spring's JMX support makes it easy to register any number of +`NotificationListeners` with any number of MBeans (this includes MBeans exported by +Spring's `MBeanExporter` and MBeans registered through some other mechanism). For +example, consider the scenario where one would like to be informed (through a +`Notification`) each and every time an attribute of a target MBean changes. The following +example writes notifications to the console: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package com.example; + + import javax.management.AttributeChangeNotification; + import javax.management.Notification; + import javax.management.NotificationFilter; + import javax.management.NotificationListener; + + public class ConsoleLoggingNotificationListener + implements NotificationListener, NotificationFilter { + + public void handleNotification(Notification notification, Object handback) { + System.out.println(notification); + System.out.println(handback); + } + + public boolean isNotificationEnabled(Notification notification) { + return AttributeChangeNotification.class.isAssignableFrom(notification.getClass()); + } + + } +---- + +The following example adds `ConsoleLoggingNotificationListener` (defined in the preceding +example) to `notificationListenerMappings`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="bean:name=testBean1" value-ref="testBean"/> + </map> + </property> + <property name="notificationListenerMappings"> + <map> + <entry key="bean:name=testBean1"> + <bean class="com.example.ConsoleLoggingNotificationListener"/> + </entry> + </map> + </property> + </bean> + + <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + </beans> +---- + +With the preceding configuration in place, every time a JMX `Notification` is broadcast from +the target MBean (`bean:name=testBean1`), the `ConsoleLoggingNotificationListener` bean +that was registered as a listener through the `notificationListenerMappings` property is +notified. The `ConsoleLoggingNotificationListener` bean can then take whatever action +it deems appropriate in response to the `Notification`. + +You can also use straight bean names as the link between exported beans and listeners, +as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="bean:name=testBean1" value-ref="testBean"/> + </map> + </property> + <property name="notificationListenerMappings"> + <map> + <entry key="__testBean__"> + <bean class="com.example.ConsoleLoggingNotificationListener"/> + </entry> + </map> + </property> + </bean> + + <bean id="__testBean__" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + </beans> +---- + +If you want to register a single `NotificationListener` instance for all of the beans +that the enclosing `MBeanExporter` exports, you can use the special wildcard (`{asterisk}`) +as the key for an entry in the `notificationListenerMappings` property +map, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <property name="notificationListenerMappings"> + <map> + <entry key="*"> + <bean class="com.example.ConsoleLoggingNotificationListener"/> + </entry> + </map> + </property> +---- + +If you need to do the inverse (that is, register a number of distinct listeners against +an MBean), you must instead use the `notificationListeners` list property (in +preference to the `notificationListenerMappings` property). This time, instead of +configuring a `NotificationListener` for a single MBean, we configure +`NotificationListenerBean` instances. A `NotificationListenerBean` encapsulates a +`NotificationListener` and the `ObjectName` (or `ObjectNames`) that it is to be +registered against in an `MBeanServer`. The `NotificationListenerBean` also encapsulates +a number of other properties, such as a `NotificationFilter` and an arbitrary handback +object that can be used in advanced JMX notification scenarios. + +The configuration when using `NotificationListenerBean` instances is not wildly +different to what was presented previously, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="bean:name=testBean1" value-ref="testBean"/> + </map> + </property> + <property name="notificationListeners"> + <list> + <bean class="org.springframework.jmx.export.NotificationListenerBean"> + <constructor-arg> + <bean class="com.example.ConsoleLoggingNotificationListener"/> + </constructor-arg> + <property name="mappedObjectNames"> + <list> + <value>bean:name=testBean1</value> + </list> + </property> + </bean> + </list> + </property> + </bean> + + <bean id="testBean" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + </beans> +---- + +The preceding example is equivalent to the first notification example. Assume, then, that +we want to be given a handback object every time a `Notification` is raised and that +we also want to filter out extraneous `Notifications` by supplying a +`NotificationFilter`. The following example accomplishes these goals: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> + <property name="beans"> + <map> + <entry key="bean:name=testBean1" value-ref="testBean1"/> + <entry key="bean:name=testBean2" value-ref="testBean2"/> + </map> + </property> + <property name="notificationListeners"> + <list> + <bean class="org.springframework.jmx.export.NotificationListenerBean"> + <constructor-arg ref="customerNotificationListener"/> + <property name="mappedObjectNames"> + <list> + <!-- handles notifications from two distinct MBeans --> + <value>bean:name=testBean1</value> + <value>bean:name=testBean2</value> + </list> + </property> + <property name="handback"> + <bean class="java.lang.String"> + <constructor-arg value="This could be anything..."/> + </bean> + </property> + <property name="notificationFilter" ref="customerNotificationListener"/> + </bean> + </list> + </property> + </bean> + + <!-- implements both the NotificationListener and NotificationFilter interfaces --> + <bean id="customerNotificationListener" class="com.example.ConsoleLoggingNotificationListener"/> + + <bean id="testBean1" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="TEST"/> + <property name="age" value="100"/> + </bean> + + <bean id="testBean2" class="org.springframework.jmx.JmxTestBean"> + <property name="name" value="ANOTHER TEST"/> + <property name="age" value="200"/> + </bean> + + </beans> +---- + +(For a full discussion of what a handback object is and, +indeed, what a `NotificationFilter` is, see the section of the JMX +specification (1.2) entitled 'The JMX Notification Model'.) + + +[[jmx-notifications-publishing]] +== Publishing Notifications + +Spring provides support not only for registering to receive `Notifications` but also +for publishing `Notifications`. + +NOTE: This section is really only relevant to Spring-managed beans that have +been exposed as MBeans through an `MBeanExporter`. Any existing user-defined MBeans should +use the standard JMX APIs for notification publication. + +The key interface in Spring's JMX notification publication support is the +`NotificationPublisher` interface (defined in the +`org.springframework.jmx.export.notification` package). Any bean that is going to be +exported as an MBean through an `MBeanExporter` instance can implement the related +`NotificationPublisherAware` interface to gain access to a `NotificationPublisher` +instance. The `NotificationPublisherAware` interface supplies an instance of a +`NotificationPublisher` to the implementing bean through a simple setter method, +which the bean can then use to publish `Notifications`. + +As stated in the javadoc of the +{api-spring-framework}/jmx/export/notification/NotificationPublisher.html[`NotificationPublisher`] +interface, managed beans that publish events through the `NotificationPublisher` +mechanism are not responsible for the state management of notification listeners. +Spring's JMX support takes care of handling all the JMX infrastructure issues. +All you need to do, as an application developer, is implement the +`NotificationPublisherAware` interface and start publishing events by using the +supplied `NotificationPublisher` instance. Note that the `NotificationPublisher` +is set after the managed bean has been registered with an `MBeanServer`. + +Using a `NotificationPublisher` instance is quite straightforward. You create a JMX +`Notification` instance (or an instance of an appropriate `Notification` subclass), +populate the notification with the data pertinent to the event that is to be +published, and invoke the `sendNotification(Notification)` on the +`NotificationPublisher` instance, passing in the `Notification`. + +In the following example, exported instances of the `JmxTestBean` publish a +`NotificationEvent` every time the `add(int, int)` operation is invoked: + +[source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] +---- + package org.springframework.jmx; + + import org.springframework.jmx.export.notification.NotificationPublisherAware; + import org.springframework.jmx.export.notification.NotificationPublisher; + import javax.management.Notification; + + public class JmxTestBean implements IJmxTestBean, NotificationPublisherAware { + + private String name; + private int age; + private boolean isSuperman; + private NotificationPublisher publisher; + + // other getters and setters omitted for clarity + + public int add(int x, int y) { + int answer = x + y; + this.publisher.sendNotification(new Notification("add", this, 0)); + return answer; + } + + public void dontExposeMe() { + throw new RuntimeException(); + } + + public void setNotificationPublisher(NotificationPublisher notificationPublisher) { + this.publisher = notificationPublisher; + } + + } +---- + +The `NotificationPublisher` interface and the machinery to get it all working is one of +the nicer features of Spring's JMX support. It does, however, come with the price tag of +coupling your classes to both Spring and JMX. As always, the advice here is to be +pragmatic. If you need the functionality offered by the `NotificationPublisher` and +you can accept the coupling to both Spring and JMX, then do so. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/proxy.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/proxy.adoc new file mode 100644 index 000000000000..317d9409689c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jmx/proxy.adoc @@ -0,0 +1,49 @@ +[[jmx-proxy]] += Accessing MBeans through Proxies + +Spring JMX lets you create proxies that re-route calls to MBeans that are registered in a +local or remote `MBeanServer`. These proxies provide you with a standard Java interface, +through which you can interact with your MBeans. The following code shows how to configure a +proxy for an MBean running in a local `MBeanServer`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="proxy" class="org.springframework.jmx.access.MBeanProxyFactoryBean"> + <property name="objectName" value="bean:name=testBean"/> + <property name="proxyInterface" value="org.springframework.jmx.IJmxTestBean"/> + </bean> +---- + +In the preceding example, you can see that a proxy is created for the MBean registered under the +`ObjectName` of `bean:name=testBean`. The set of interfaces that the proxy implements +is controlled by the `proxyInterfaces` property, and the rules for mapping methods and +properties on these interfaces to operations and attributes on the MBean are the same +rules used by the `InterfaceBasedMBeanInfoAssembler`. + +The `MBeanProxyFactoryBean` can create a proxy to any MBean that is accessible through an +`MBeanServerConnection`. By default, the local `MBeanServer` is located and used, but +you can override this and provide an `MBeanServerConnection` that points to a remote +`MBeanServer` to cater for proxies that point to remote MBeans: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="clientConnector" + class="org.springframework.jmx.support.MBeanServerConnectionFactoryBean"> + <property name="serviceUrl" value="service:jmx:rmi://remotehost:9875"/> + </bean> + + <bean id="proxy" class="org.springframework.jmx.access.MBeanProxyFactoryBean"> + <property name="objectName" value="bean:name=testBean"/> + <property name="proxyInterface" value="org.springframework.jmx.IJmxTestBean"/> + <property name="server" ref="clientConnector"/> + </bean> +---- + +In the preceding example, we create an `MBeanServerConnection` that points to a remote machine +that uses the `MBeanServerConnectionFactoryBean`. This `MBeanServerConnection` is then +passed to the `MBeanProxyFactoryBean` through the `server` property. The proxy that is +created forwards all invocations to the `MBeanServer` through this +`MBeanServerConnection`. + + + diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc new file mode 100644 index 000000000000..8c38b77fd46b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc @@ -0,0 +1,14 @@ +[[jmx-resources]] += Further Resources + +This section contains links to further resources about JMX: + +* The https://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[JMX +homepage] at Oracle. +* The https://jcp.org/aboutJava/communityprocess/final/jsr003/index3.html[JMX + specification] (JSR-000003). +* The https://jcp.org/aboutJava/communityprocess/final/jsr160/index.html[JMX Remote API + specification] (JSR-000160). +* The http://mx4j.sourceforge.net/[MX4J homepage]. (MX4J is an open-source implementation of + various JMX specs.) + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin.adoc index 33342da13b94..3a6b2482076e 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin.adoc @@ -23,1105 +23,3 @@ https://stackoverflow.com/questions/tagged/spring+kotlin[Stackoverflow] if you n -[[kotlin-requirements]] -== Requirements - -Spring Framework supports Kotlin 1.3+ and requires -https://search.maven.org/artifact/org.jetbrains.kotlin/kotlin-stdlib[`kotlin-stdlib`] -(or one of its variants, such as https://search.maven.org/artifact/org.jetbrains.kotlin/kotlin-stdlib-jdk8[`kotlin-stdlib-jdk8`]) -and https://search.maven.org/artifact/org.jetbrains.kotlin/kotlin-reflect[`kotlin-reflect`] -to be present on the classpath. They are provided by default if you bootstrap a Kotlin project on -https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io]. - -WARNING: Kotlin https://kotlinlang.org/docs/inline-classes.html[inline classes] are not yet supported. - -NOTE: The https://github.com/FasterXML/jackson-module-kotlin[Jackson Kotlin module] is required -for serializing or deserializing JSON data for Kotlin classes with Jackson, so make sure to add the -`com.fasterxml.jackson.module:jackson-module-kotlin` dependency to your project if you have such need. -It is automatically registered when found in the classpath. - - - - -[[kotlin-extensions]] -== Extensions - -Kotlin https://kotlinlang.org/docs/reference/extensions.html[extensions] provide the ability -to extend existing classes with additional functionality. The Spring Framework Kotlin APIs -use these extensions to add new Kotlin-specific conveniences to existing Spring APIs. - -The {docs-spring-framework}/kdoc-api/[Spring Framework KDoc API] lists -and documents all available Kotlin extensions and DSLs. - -NOTE: Keep in mind that Kotlin extensions need to be imported to be used. This means, -for example, that the `GenericApplicationContext.registerBean` Kotlin extension -is available only if `org.springframework.context.support.registerBean` is imported. -That said, similar to static imports, an IDE should automatically suggest the import in most cases. - -For example, https://kotlinlang.org/docs/reference/inline-functions.html#reified-type-parameters[Kotlin reified type parameters] -provide a workaround for JVM https://docs.oracle.com/javase/tutorial/java/generics/erasure.html[generics type erasure], -and the Spring Framework provides some extensions to take advantage of this feature. -This allows for a better Kotlin API `RestTemplate`, for the new `WebClient` from Spring -WebFlux, and for various other APIs. - -NOTE: Other libraries, such as Reactor and Spring Data, also provide Kotlin extensions -for their APIs, thus giving a better Kotlin development experience overall. - -To retrieve a list of `User` objects in Java, you would normally write the following: - -[source,java,indent=0] ----- - Flux<User> users = client.get().retrieve().bodyToFlux(User.class) ----- - -With Kotlin and the Spring Framework extensions, you can instead write the following: - -[source,kotlin,indent=0] ----- - val users = client.get().retrieve().bodyToFlux<User>() - // or (both are equivalent) - val users : Flux<User> = client.get().retrieve().bodyToFlux() ----- - -As in Java, `users` in Kotlin is strongly typed, but Kotlin's clever type inference allows -for shorter syntax. - - - - -[[kotlin-null-safety]] -== Null-safety - -One of Kotlin's key features is https://kotlinlang.org/docs/reference/null-safety.html[null-safety], -which cleanly deals with `null` values at compile time rather than bumping into the famous -`NullPointerException` at runtime. This makes applications safer through nullability -declarations and expressing "`value or no value`" semantics without paying the cost of wrappers, such as `Optional`. -(Kotlin allows using functional constructs with nullable values. See this -https://www.baeldung.com/kotlin-null-safety[comprehensive guide to Kotlin null-safety].) - -Although Java does not let you express null-safety in its type-system, the Spring Framework -provides <<core#null-safety, null-safety of the whole Spring Framework API>> -via tooling-friendly annotations declared in the `org.springframework.lang` package. -By default, types from Java APIs used in Kotlin are recognized as -https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], -for which null-checks are relaxed. -https://kotlinlang.org/docs/reference/java-interop.html#jsr-305-support[Kotlin support for JSR-305 annotations] -and Spring nullability annotations provide null-safety for the whole Spring Framework API to Kotlin developers, -with the advantage of dealing with `null`-related issues at compile time. - -NOTE: Libraries such as Reactor or Spring Data provide null-safe APIs to leverage this feature. - -You can configure JSR-305 checks by adding the `-Xjsr305` compiler flag with the following -options: `-Xjsr305={strict|warn|ignore}`. - -For kotlin versions 1.1+, the default behavior is the same as `-Xjsr305=warn`. -The `strict` value is required to have Spring Framework API null-safety taken into account -in Kotlin types inferred from Spring API but should be used with the knowledge that Spring -API nullability declaration could evolve even between minor releases and that more checks may -be added in the future. - -NOTE: Generic type arguments, varargs, and array elements nullability are not supported yet, -but should be in an upcoming release. See https://github.com/Kotlin/KEEP/issues/79[this discussion] -for up-to-date information. - - - - -[[kotlin-classes-interfaces]] -== Classes and Interfaces - -The Spring Framework supports various Kotlin constructs, such as instantiating Kotlin classes -through primary constructors, immutable classes data binding, and function optional parameters -with default values. - -Kotlin parameter names are recognized through a dedicated `KotlinReflectionParameterNameDiscoverer`, -which allows finding interface method parameter names without requiring the Java 8 `-parameters` -compiler flag to be enabled during compilation. (For completeness, we nevertheless recommend -running the Kotlin compiler with its `-java-parameters` flag for standard Java parameter exposure.) - -You can declare configuration classes as -https://kotlinlang.org/docs/reference/nested-classes.html[top level or nested but not inner], -since the later requires a reference to the outer class. - - - - -[[kotlin-annotations]] -== Annotations - -The Spring Framework also takes advantage of https://kotlinlang.org/docs/reference/null-safety.html[Kotlin null-safety] -to determine if an HTTP parameter is required without having to explicitly -define the `required` attribute. That means `@RequestParam name: String?` is treated -as not required and, conversely, `@RequestParam name: String` is treated as being required. -This feature is also supported on the Spring Messaging `@Header` annotation. - -In a similar fashion, Spring bean injection with `@Autowired`, `@Bean`, or `@Inject` uses -this information to determine if a bean is required or not. - -For example, `@Autowired lateinit var thing: Thing` implies that a bean -of type `Thing` must be registered in the application context, while `@Autowired lateinit var thing: Thing?` -does not raise an error if such a bean does not exist. - -Following the same principle, `@Bean fun play(toy: Toy, car: Car?) = Baz(toy, Car)` implies -that a bean of type `Toy` must be registered in the application context, while a bean of -type `Car` may or may not exist. The same behavior applies to autowired constructor parameters. - -NOTE: If you use bean validation on classes with properties or a primary constructor -parameters, you may need to use -https://kotlinlang.org/docs/reference/annotations.html#annotation-use-site-targets[annotation use-site targets], -such as `@field:NotNull` or `@get:Size(min=5, max=15)`, as described in -https://stackoverflow.com/a/35853200/1092077[this Stack Overflow response]. - - - - -[[kotlin-bean-definition-dsl]] -== Bean Definition DSL - -Spring Framework supports registering beans in a functional way by using lambdas -as an alternative to XML or Java configuration (`@Configuration` and `@Bean`). In a nutshell, -it lets you register beans with a lambda that acts as a `FactoryBean`. -This mechanism is very efficient, as it does not require any reflection or CGLIB proxies. - -In Java, you can, for example, write the following: - -[source,java,indent=0] ----- - class Foo {} - - class Bar { - private final Foo foo; - public Bar(Foo foo) { - this.foo = foo; - } - } - - GenericApplicationContext context = new GenericApplicationContext(); - context.registerBean(Foo.class); - context.registerBean(Bar.class, () -> new Bar(context.getBean(Foo.class))); ----- - -In Kotlin, with reified type parameters and `GenericApplicationContext` Kotlin extensions, -you can instead write the following: - -[source,kotlin,indent=0] ----- - class Foo - - class Bar(private val foo: Foo) - - val context = GenericApplicationContext().apply { - registerBean<Foo>() - registerBean { Bar(it.getBean()) } - } ----- -==== - -When the class `Bar` has a single constructor, you can even just specify the bean class, -the constructor parameters will be autowired by type: - -==== -[source,kotlin,indent=0] ----- - val context = GenericApplicationContext().apply { - registerBean<Foo>() - registerBean<Bar>() - } ----- - -In order to allow a more declarative approach and cleaner syntax, Spring Framework provides -a {docs-spring-framework}/kdoc-api/spring-context/org.springframework.context.support/-bean-definition-dsl/index.html[Kotlin bean definition DSL] -It declares an `ApplicationContextInitializer` through a clean declarative API, -which lets you deal with profiles and `Environment` for customizing -how beans are registered. - -In the following example notice that: - -* Type inference usually allows to avoid specifying the type for bean references like `ref("bazBean")` -* It is possible to use Kotlin top level functions to declare beans using callable references like `bean(::myRouter)` in this example -* When specifying `bean<Bar>()` or `bean(::myRouter)`, parameters are autowired by type -* The `FooBar` bean will be registered only if the `foobar` profile is active - -[source,kotlin,indent=0] ----- - class Foo - class Bar(private val foo: Foo) - class Baz(var message: String = "") - class FooBar(private val baz: Baz) - - val myBeans = beans { - bean<Foo>() - bean<Bar>() - bean("bazBean") { - Baz().apply { - message = "Hello world" - } - } - profile("foobar") { - bean { FooBar(ref("bazBean")) } - } - bean(::myRouter) - } - - fun myRouter(foo: Foo, bar: Bar, baz: Baz) = router { - // ... - } ----- - -NOTE: This DSL is programmatic, meaning it allows custom registration logic of beans -through an `if` expression, a `for` loop, or any other Kotlin constructs. - -You can then use this `beans()` function to register beans on the application context, -as the following example shows: - -[source,kotlin,indent=0] ----- - val context = GenericApplicationContext().apply { - myBeans.initialize(this) - refresh() - } ----- - -NOTE: Spring Boot is based on JavaConfig and -https://github.com/spring-projects/spring-boot/issues/8115[does not yet provide specific support for functional bean definition], -but you can experimentally use functional bean definitions through Spring Boot's `ApplicationContextInitializer` support. -See https://stackoverflow.com/questions/45935931/how-to-use-functional-bean-definition-kotlin-dsl-with-spring-boot-and-spring-w/46033685#46033685[this Stack Overflow answer] -for more details and up-to-date information. See also the experimental Kofu DSL developed in https://github.com/spring-projects/spring-fu[Spring Fu incubator]. - - - - -[[kotlin-web]] -== Web - - - -[[router-dsl]] -=== Router DSL - -Spring Framework comes with a Kotlin router DSL available in 3 flavors: - -* WebMvc.fn DSL with {docs-spring-framework}/kdoc-api/spring-webmvc/org.springframework.web.servlet.function/router.html[router { }] -* WebFlux.fn <<web-reactive#webflux-fn, Reactive>> DSL with {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/router.html[router { }] -* WebFlux.fn <<Coroutines>> DSL with {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] - -These DSL let you write clean and idiomatic Kotlin code to build a `RouterFunction` instance as the following example shows: - -[source,kotlin,indent=0] ----- -@Configuration -class RouterRouterConfiguration { - - @Bean - fun mainRouter(userHandler: UserHandler) = router { - accept(TEXT_HTML).nest { - GET("/") { ok().render("index") } - GET("/sse") { ok().render("sse") } - GET("/users", userHandler::findAllView) - } - "/api".nest { - accept(APPLICATION_JSON).nest { - GET("/users", userHandler::findAll) - } - accept(TEXT_EVENT_STREAM).nest { - GET("/users", userHandler::stream) - } - } - resources("/**", ClassPathResource("static/")) - } -} ----- - -NOTE: This DSL is programmatic, meaning that it allows custom registration logic of beans -through an `if` expression, a `for` loop, or any other Kotlin constructs. That can be useful -when you need to register routes depending on dynamic data (for example, from a database). - -See https://github.com/mixitconf/mixit/[MiXiT project] for a concrete example. - - - -[[mockmvc-dsl]] -=== MockMvc DSL - -A Kotlin DSL is provided via `MockMvc` Kotlin extensions in order to provide a more -idiomatic Kotlin API and to allow better discoverability (no usage of static methods). - -[source,kotlin,indent=0] ----- -val mockMvc: MockMvc = ... -mockMvc.get("/person/{name}", "Lee") { - secure = true - accept = APPLICATION_JSON - headers { - contentLanguage = Locale.FRANCE - } - principal = Principal { "foo" } -}.andExpect { - status { isOk } - content { contentType(APPLICATION_JSON) } - jsonPath("$.name") { value("Lee") } - content { json("""{"someBoolean": false}""", false) } -}.andDo { - print() -} ----- - - - -[[kotlin-script-templates]] -=== Kotlin Script Templates - -Spring Framework provides a -https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/view/script/ScriptTemplateView.html[`ScriptTemplateView`] -which supports https://www.jcp.org/en/jsr/detail?id=223[JSR-223] to render templates by using script engines. - -By leveraging `scripting-jsr223` dependencies, it -is possible to use such feature to render Kotlin-based templates with -https://github.com/Kotlin/kotlinx.html[kotlinx.html] DSL or Kotlin multiline interpolated `String`. - -`build.gradle.kts` -[source,kotlin,indent=0] ----- -dependencies { - runtime("org.jetbrains.kotlin:kotlin-scripting-jsr223:${kotlinVersion}") -} ----- - -Configuration is usually done with `ScriptTemplateConfigurer` and `ScriptTemplateViewResolver` beans. - -`KotlinScriptConfiguration.kt` -[source,kotlin,indent=0] ----- -@Configuration -class KotlinScriptConfiguration { - - @Bean - fun kotlinScriptConfigurer() = ScriptTemplateConfigurer().apply { - engineName = "kotlin" - setScripts("scripts/render.kts") - renderFunction = "render" - isSharedEngine = false - } - - @Bean - fun kotlinScriptViewResolver() = ScriptTemplateViewResolver().apply { - setPrefix("templates/") - setSuffix(".kts") - } -} ----- - -See the https://github.com/sdeleuze/kotlin-script-templating[kotlin-script-templating] example -project for more details. - - - -[[kotlin-multiplatform-serialization]] -=== Kotlin multiplatform serialization - -As of Spring Framework 5.3, https://github.com/Kotlin/kotlinx.serialization[Kotlin multiplatform serialization] is -supported in Spring MVC, Spring WebFlux and Spring Messaging (RSocket). The builtin support currently targets CBOR, JSON, and ProtoBuf formats. - -To enable it, follow https://github.com/Kotlin/kotlinx.serialization#setup[those instructions] to add the related dependency and plugin. -With Spring MVC and WebFlux, both Kotlin serialization and Jackson will be configured by default if they are in the classpath since -Kotlin serialization is designed to serialize only Kotlin classes annotated with `@Serializable`. -With Spring Messaging (RSocket), make sure that neither Jackson, GSON or JSONB are in the classpath if you want automatic configuration, -if Jackson is needed configure `KotlinSerializationJsonMessageConverter` manually. - - - - -[[coroutines]] -== Coroutines - -Kotlin https://kotlinlang.org/docs/reference/coroutines-overview.html[Coroutines] are Kotlin -lightweight threads allowing to write non-blocking code in an imperative way. On language side, -suspending functions provides an abstraction for asynchronous operations while on library side -https://github.com/Kotlin/kotlinx.coroutines[kotlinx.coroutines] provides functions like -https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html[`async { }`] -and types like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`]. - -Spring Framework provides support for Coroutines on the following scope: - -* https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html[Deferred] and https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[Flow] return values support in Spring MVC and WebFlux annotated `@Controller` -* Suspending function support in Spring MVC and WebFlux annotated `@Controller` -* Extensions for WebFlux {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.client/index.html[client] and {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/index.html[server] functional API. -* WebFlux.fn {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] DSL -* Suspending function and `Flow` support in RSocket `@MessageMapping` annotated methods -* Extensions for {docs-spring-framework}/kdoc-api/spring-messaging/org.springframework.messaging.rsocket/index.html[`RSocketRequester`] - - - -[[dependencies]] -=== Dependencies - -Coroutines support is enabled when `kotlinx-coroutines-core` and `kotlinx-coroutines-reactor` -dependencies are in the classpath: - -`build.gradle.kts` -[source,kotlin,indent=0] ----- -dependencies { - - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:${coroutinesVersion}") - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor:${coroutinesVersion}") -} ----- - -Version `1.4.0` and above are supported. - - - -[[how-reactive-translates-to-coroutines?]] -=== How Reactive translates to Coroutines? - -For return values, the translation from Reactive to Coroutines APIs is the following: - -* `fun handler(): Mono<Void>` becomes `suspend fun handler()` -* `fun handler(): Mono<T>` becomes `suspend fun handler(): T` or `suspend fun handler(): T?` depending on if the `Mono` can be empty or not (with the advantage of being more statically typed) -* `fun handler(): Flux<T>` becomes `fun handler(): Flow<T>` - -For input parameters: - -* If laziness is not needed, `fun handler(mono: Mono<T>)` becomes `fun handler(value: T)` since a suspending functions can be invoked to get the value parameter. -* If laziness is needed, `fun handler(mono: Mono<T>)` becomes `fun handler(supplier: suspend () -> T)` or `fun handler(supplier: suspend () -> T?)` - -https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`] is `Flux` equivalent in Coroutines world, suitable for hot or cold stream, finite or infinite streams, with the following main differences: - -* `Flow` is push-based while `Flux` is push-pull hybrid -* Backpressure is implemented via suspending functions -* `Flow` has only a https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/collect.html[single suspending `collect` method] and operators are implemented as https://kotlinlang.org/docs/reference/extensions.html[extensions] -* https://github.com/Kotlin/kotlinx.coroutines/tree/master/kotlinx-coroutines-core/common/src/flow/operators[Operators are easy to implement] thanks to Coroutines -* Extensions allow to add custom operators to `Flow` -* Collect operations are suspending functions -* https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/map.html[`map` operator] supports asynchronous operation (no need for `flatMap`) since it takes a suspending function parameter - -Read this blog post about https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow[Going Reactive with Spring, Coroutines and Kotlin Flow] -for more details, including how to run code concurrently with Coroutines. - - - -[[controllers]] -=== Controllers - -Here is an example of a Coroutines `@RestController`. - -[source,kotlin,indent=0] ----- -@RestController -class CoroutinesRestController(client: WebClient, banner: Banner) { - - @GetMapping("/suspend") - suspend fun suspendingEndpoint(): Banner { - delay(10) - return banner - } - - @GetMapping("/flow") - fun flowEndpoint() = flow { - delay(10) - emit(banner) - delay(10) - emit(banner) - } - - @GetMapping("/deferred") - fun deferredEndpoint() = GlobalScope.async { - delay(10) - banner - } - - @GetMapping("/sequential") - suspend fun sequential(): List<Banner> { - val banner1 = client - .get() - .uri("/suspend") - .accept(MediaType.APPLICATION_JSON) - .awaitExchange() - .awaitBody<Banner>() - val banner2 = client - .get() - .uri("/suspend") - .accept(MediaType.APPLICATION_JSON) - .awaitExchange() - .awaitBody<Banner>() - return listOf(banner1, banner2) - } - - @GetMapping("/parallel") - suspend fun parallel(): List<Banner> = coroutineScope { - val deferredBanner1: Deferred<Banner> = async { - client - .get() - .uri("/suspend") - .accept(MediaType.APPLICATION_JSON) - .awaitExchange() - .awaitBody<Banner>() - } - val deferredBanner2: Deferred<Banner> = async { - client - .get() - .uri("/suspend") - .accept(MediaType.APPLICATION_JSON) - .awaitExchange() - .awaitBody<Banner>() - } - listOf(deferredBanner1.await(), deferredBanner2.await()) - } - - @GetMapping("/error") - suspend fun error() { - throw IllegalStateException() - } - - @GetMapping("/cancel") - suspend fun cancel() { - throw CancellationException() - } - -} ----- - -View rendering with a `@Controller` is also supported. - -[source,kotlin,indent=0] ----- -@Controller -class CoroutinesViewController(banner: Banner) { - - @GetMapping("/") - suspend fun render(model: Model): String { - delay(10) - model["banner"] = banner - return "index" - } -} ----- - - - -[[webflux-fn]] -=== WebFlux.fn - -Here is an example of Coroutines router defined via the {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] DSL and related handlers. - -[source,kotlin,indent=0] ----- -@Configuration -class RouterConfiguration { - - @Bean - fun mainRouter(userHandler: UserHandler) = coRouter { - GET("/", userHandler::listView) - GET("/api/user", userHandler::listApi) - } -} ----- - -[source,kotlin,indent=0] ----- -class UserHandler(builder: WebClient.Builder) { - - private val client = builder.baseUrl("...").build() - - suspend fun listView(request: ServerRequest): ServerResponse = - ServerResponse.ok().renderAndAwait("users", mapOf("users" to - client.get().uri("...").awaitExchange().awaitBody<User>())) - - suspend fun listApi(request: ServerRequest): ServerResponse = - ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).bodyAndAwait( - client.get().uri("...").awaitExchange().awaitBody<User>()) -} ----- - - - -[[transactions]] -=== Transactions - -Transactions on Coroutines are supported via the programmatic variant of the Reactive -transaction management provided as of Spring Framework 5.2. - -For suspending functions, a `TransactionalOperator.executeAndAwait` extension is provided. - -[source,kotlin,indent=0] ----- - import org.springframework.transaction.reactive.executeAndAwait - - class PersonRepository(private val operator: TransactionalOperator) { - - suspend fun initDatabase() = operator.executeAndAwait { - insertPerson1() - insertPerson2() - } - - private suspend fun insertPerson1() { - // INSERT SQL statement - } - - private suspend fun insertPerson2() { - // INSERT SQL statement - } - } ----- - -For Kotlin `Flow`, a `Flow<T>.transactional` extension is provided. - -[source,kotlin,indent=0] ----- - import org.springframework.transaction.reactive.transactional - - class PersonRepository(private val operator: TransactionalOperator) { - - fun updatePeople() = findPeople().map(::updatePerson).transactional(operator) - - private fun findPeople(): Flow<Person> { - // SELECT SQL statement - } - - private suspend fun updatePerson(person: Person): Person { - // UPDATE SQL statement - } - } ----- - - - - -[[kotlin-spring-projects-in-kotlin]] -== Spring Projects in Kotlin - -This section provides some specific hints and recommendations worth for developing Spring projects -in Kotlin. - - - -[[final-by-default]] -=== Final by Default - -By default, https://discuss.kotlinlang.org/t/classes-final-by-default/166[all classes in Kotlin are `final`]. -The `open` modifier on a class is the opposite of Java's `final`: It allows others to inherit from this -class. This also applies to member functions, in that they need to be marked as `open` to be overridden. - -While Kotlin's JVM-friendly design is generally frictionless with Spring, this specific Kotlin feature -can prevent the application from starting, if this fact is not taken into consideration. This is because -Spring beans (such as `@Configuration` annotated classes which by default need to be extended at runtime for technical -reasons) are normally proxied by CGLIB. The workaround is to add an `open` keyword on each class and -member function of Spring beans that are proxied by CGLIB, which can -quickly become painful and is against the Kotlin principle of keeping code concise and predictable. - -NOTE: It is also possible to avoid CGLIB proxies for configuration classes by using `@Configuration(proxyBeanMethods = false)`. -See {api-spring-framework}/context/annotation/Configuration.html#proxyBeanMethods--[`proxyBeanMethods` Javadoc] for more details. - -Fortunately, Kotlin provides a -https://kotlinlang.org/docs/reference/compiler-plugins.html#kotlin-spring-compiler-plugin[`kotlin-spring`] -plugin (a preconfigured version of the `kotlin-allopen` plugin) that automatically opens classes -and their member functions for types that are annotated or meta-annotated with one of the following -annotations: - -* `@Component` -* `@Async` -* `@Transactional` -* `@Cacheable` - -Meta-annotation support means that types annotated with `@Configuration`, `@Controller`, -`@RestController`, `@Service`, or `@Repository` are automatically opened since these -annotations are meta-annotated with `@Component`. - -https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io] enables -the `kotlin-spring` plugin by default. So, in practice, you can write your Kotlin beans -without any additional `open` keyword, as in Java. - -NOTE: The Kotlin code samples in Spring Framework documentation do not explicitly specify -`open` on the classes and their member functions. The samples are written for projects -using the `kotlin-allopen` plugin, since this is the most commonly used setup. - - - -[[using-immutable-class-instances-for-persistence]] -=== Using Immutable Class Instances for Persistence - -In Kotlin, it is convenient and considered to be a best practice to declare read-only properties -within the primary constructor, as in the following example: - -[source,kotlin,indent=0] ----- - class Person(val name: String, val age: Int) ----- - -You can optionally add https://kotlinlang.org/docs/reference/data-classes.html[the `data` keyword] -to make the compiler automatically derive the following members from all properties declared -in the primary constructor: - -* `equals()` and `hashCode()` -* `toString()` of the form `"User(name=John, age=42)"` -* `componentN()` functions that correspond to the properties in their order of declaration -* `copy()` function - -As the following example shows, this allows for easy changes to individual properties, even if `Person` properties are read-only: - -[source,kotlin,indent=0] ----- - data class Person(val name: String, val age: Int) - - val jack = Person(name = "Jack", age = 1) - val olderJack = jack.copy(age = 2) ----- - -Common persistence technologies (such as JPA) require a default constructor, preventing this -kind of design. Fortunately, there is a workaround for this -https://stackoverflow.com/questions/32038177/kotlin-with-jpa-default-constructor-hell["`default constructor hell`"], -since Kotlin provides a https://kotlinlang.org/docs/reference/compiler-plugins.html#kotlin-jpa-compiler-plugin[`kotlin-jpa`] -plugin that generates synthetic no-arg constructor for classes annotated with JPA annotations. - -If you need to leverage this kind of mechanism for other persistence technologies, you can configure -the https://kotlinlang.org/docs/reference/compiler-plugins.html#how-to-use-no-arg-plugin[`kotlin-noarg`] -plugin. - -NOTE: As of the Kay release train, Spring Data supports Kotlin immutable class instances and -does not require the `kotlin-noarg` plugin if the module uses Spring Data object mappings -(such as MongoDB, Redis, Cassandra, and others). - - - -[[injecting-dependencies]] -=== Injecting Dependencies - -Our recommendation is to try to favor constructor injection with `val` read-only (and -non-nullable when possible) https://kotlinlang.org/docs/reference/properties.html[properties], -as the following example shows: - -[source,kotlin,indent=0] ----- - @Component - class YourBean( - private val mongoTemplate: MongoTemplate, - private val solrClient: SolrClient - ) ----- - -NOTE: Classes with a single constructor have their parameters automatically autowired. -That's why there is no need for an explicit `@Autowired constructor` in the example shown -above. - -If you really need to use field injection, you can use the `lateinit var` construct, -as the following example shows: - -[source,kotlin,indent=0] ----- - @Component - class YourBean { - - @Autowired - lateinit var mongoTemplate: MongoTemplate - - @Autowired - lateinit var solrClient: SolrClient - } ----- - - - -[[injecting-configuration-properties]] -=== Injecting Configuration Properties - -In Java, you can inject configuration properties by using annotations (such as pass:q[`@Value("${property}")`)]. -However, in Kotlin, `$` is a reserved character that is used for -https://kotlinlang.org/docs/reference/idioms.html#string-interpolation[string interpolation]. - -Therefore, if you wish to use the `@Value` annotation in Kotlin, you need to escape the `$` -character by writing pass:q[`@Value("\${property}")`]. - -NOTE: If you use Spring Boot, you should probably use -https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-typesafe-configuration-properties[`@ConfigurationProperties`] -instead of `@Value` annotations. - -As an alternative, you can customize the property placeholder prefix by declaring the -following configuration beans: - -[source,kotlin,indent=0] ----- - @Bean - fun propertyConfigurer() = PropertySourcesPlaceholderConfigurer().apply { - setPlaceholderPrefix("%{") - } ----- - -You can customize existing code (such as Spring Boot actuators or `@LocalServerPort`) -that uses the `${...}` syntax, with configuration beans, as the following example shows: - -[source,kotlin,indent=0] ----- - @Bean - fun kotlinPropertyConfigurer() = PropertySourcesPlaceholderConfigurer().apply { - setPlaceholderPrefix("%{") - setIgnoreUnresolvablePlaceholders(true) - } - - @Bean - fun defaultPropertyConfigurer() = PropertySourcesPlaceholderConfigurer() ----- - - - -[[checked-exceptions]] -=== Checked Exceptions - -Java and https://kotlinlang.org/docs/reference/exceptions.html[Kotlin exception handling] -are pretty close, with the main difference being that Kotlin treats all exceptions as -unchecked exceptions. However, when using proxied objects (for example classes or methods -annotated with `@Transactional`), checked exceptions thrown will be wrapped by default in -an `UndeclaredThrowableException`. - -To get the original exception thrown like in Java, methods should be annotated with -https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.jvm/-throws/index.html[`@Throws`] -to specify explicitly the checked exceptions thrown (for example `@Throws(IOException::class)`). - - - -[[annotation-array-attributes]] -=== Annotation Array Attributes - -Kotlin annotations are mostly similar to Java annotations, but array attributes (which are -extensively used in Spring) behave differently. As explained in the -https://kotlinlang.org/docs/reference/annotations.html[Kotlin documentation] you can omit -the `value` attribute name, unlike other attributes, and specify it as a `vararg` parameter. - -To understand what that means, consider `@RequestMapping` (which is one of the most widely -used Spring annotations) as an example. This Java annotation is declared as follows: - -[source,java,indent=0] ----- - public @interface RequestMapping { - - @AliasFor("path") - String[] value() default {}; - - @AliasFor("value") - String[] path() default {}; - - RequestMethod[] method() default {}; - - // ... - } ----- - -The typical use case for `@RequestMapping` is to map a handler method to a specific path -and method. In Java, you can specify a single value for the annotation array attribute, -and it is automatically converted to an array. - -That is why one can write -`@RequestMapping(value = "/toys", method = RequestMethod.GET)` or -`@RequestMapping(path = "/toys", method = RequestMethod.GET)`. - -However, in Kotlin, you must write `@RequestMapping("/toys", method = [RequestMethod.GET])` -or `@RequestMapping(path = ["/toys"], method = [RequestMethod.GET])` (square brackets need -to be specified with named array attributes). - -An alternative for this specific `method` attribute (the most common one) is to -use a shortcut annotation, such as `@GetMapping`, `@PostMapping`, and others. - -NOTE: If the `@RequestMapping` `method` attribute is not specified, all HTTP methods will -be matched, not only the `GET` method. - - - -[[testing]] -=== Testing - -This section addresses testing with the combination of Kotlin and Spring Framework. -The recommended testing framework is https://junit.org/junit5/[JUnit 5] along with -https://mockk.io/[Mockk] for mocking. - -NOTE: If you are using Spring Boot, see -https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-kotlin-testing[this related documentation]. - - -[[constructor-injection]] -==== Constructor injection - -As described in the <<testing#testcontext-junit-jupiter-di, dedicated section>>, -JUnit 5 allows constructor injection of beans which is pretty useful with Kotlin -in order to use `val` instead of `lateinit var`. You can use -{api-spring-framework}/test/context/TestConstructor.html[`@TestConstructor(autowireMode = AutowireMode.ALL)`] -to enable autowiring for all parameters. - -==== -[source,kotlin,indent=0] ----- -@SpringJUnitConfig(TestConfig::class) -@TestConstructor(autowireMode = AutowireMode.ALL) -class OrderServiceIntegrationTests(val orderService: OrderService, - val customerService: CustomerService) { - - // tests that use the injected OrderService and CustomerService -} ----- -==== - - -[[per_class-lifecycle]] -==== `PER_CLASS` Lifecycle - -Kotlin lets you specify meaningful test function names between backticks (```). -As of JUnit 5, Kotlin test classes can use the `@TestInstance(TestInstance.Lifecycle.PER_CLASS)` -annotation to enable single instantiation of test classes, which allows the use of `@BeforeAll` -and `@AfterAll` annotations on non-static methods, which is a good fit for Kotlin. - -You can also change the default behavior to `PER_CLASS` thanks to a `junit-platform.properties` -file with a `junit.jupiter.testinstance.lifecycle.default = per_class` property. - -The following example demonstrates `@BeforeAll` and `@AfterAll` annotations on non-static methods: - -[source,kotlin,indent=0] ----- -@TestInstance(TestInstance.Lifecycle.PER_CLASS) -class IntegrationTests { - - val application = Application(8181) - val client = WebClient.create("http://localhost:8181") - - @BeforeAll - fun beforeAll() { - application.start() - } - - @Test - fun `Find all users on HTML page`() { - client.get().uri("/users") - .accept(TEXT_HTML) - .retrieve() - .bodyToMono<String>() - .test() - .expectNextMatches { it.contains("Foo") } - .verifyComplete() - } - - @AfterAll - fun afterAll() { - application.stop() - } -} ----- - - -[[specification-like-tests]] -==== Specification-like Tests - -You can create specification-like tests with JUnit 5 and Kotlin. -The following example shows how to do so: - -[source,kotlin,indent=0] ----- -class SpecificationLikeTests { - - @Nested - @DisplayName("a calculator") - inner class Calculator { - val calculator = SampleCalculator() - - @Test - fun `should return the result of adding the first number to the second number`() { - val sum = calculator.sum(2, 4) - assertEquals(6, sum) - } - - @Test - fun `should return the result of subtracting the second number from the first number`() { - val subtract = calculator.subtract(4, 2) - assertEquals(2, subtract) - } - } -} ----- - - -[[kotlin-webtestclient-issue]] -==== `WebTestClient` Type Inference Issue in Kotlin - -Due to a https://youtrack.jetbrains.com/issue/KT-5464[type inference issue], you must -use the Kotlin `expectBody` extension (such as `.expectBody<String>().isEqualTo("toys")`), -since it provides a workaround for the Kotlin issue with the Java API. - -See also the related https://jira.spring.io/browse/SPR-16057[SPR-16057] issue. - - - - -[[kotlin-getting-started]] -== Getting Started - -The easiest way to learn how to build a Spring application with Kotlin is to follow -https://spring.io/guides/tutorials/spring-boot-kotlin/[the dedicated tutorial]. - - - -[[start-spring-io]] -=== `start.spring.io` - -The easiest way to start a new Spring Framework project in Kotlin is to create a new Spring -Boot 2 project on https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io]. - - - -[[choosing-the-web-flavor]] -=== Choosing the Web Flavor - -Spring Framework now comes with two different web stacks: <<web#mvc, Spring MVC>> and -<<web-reactive#spring-web-reactive, Spring WebFlux>>. - -Spring WebFlux is recommended if you want to create applications that will deal with latency, -long-lived connections, streaming scenarios or if you want to use the web functional -Kotlin DSL. - -For other use cases, especially if you are using blocking technologies such as JPA, Spring -MVC and its annotation-based programming model is the recommended choice. - - - - -[[kotlin-resources]] -== Resources - -We recommend the following resources for people learning how to build applications with -Kotlin and the Spring Framework: - -* https://kotlinlang.org/docs/reference/[Kotlin language reference] -* https://slack.kotlinlang.org/[Kotlin Slack] (with a dedicated #spring channel) -* https://stackoverflow.com/questions/tagged/spring+kotlin[Stackoverflow, with `spring` and `kotlin` tags] -* https://play.kotlinlang.org/[Try Kotlin in your browser] -* https://blog.jetbrains.com/kotlin/[Kotlin blog] -* https://kotlin.link/[Awesome Kotlin] - - - -[[examples]] -=== Examples - -The following Github projects offer examples that you can learn from and possibly even extend: - -* https://github.com/sdeleuze/spring-boot-kotlin-demo[spring-boot-kotlin-demo]: Regular Spring Boot and Spring Data JPA project -* https://github.com/mixitconf/mixit[mixit]: Spring Boot 2, WebFlux, and Reactive Spring Data MongoDB -* https://github.com/sdeleuze/spring-kotlin-functional[spring-kotlin-functional]: Standalone WebFlux and functional bean definition DSL -* https://github.com/sdeleuze/spring-kotlin-fullstack[spring-kotlin-fullstack]: WebFlux Kotlin fullstack example with Kotlin2js for frontend instead of JavaScript or TypeScript -* https://github.com/spring-petclinic/spring-petclinic-kotlin[spring-petclinic-kotlin]: Kotlin version of the Spring PetClinic Sample Application -* https://github.com/sdeleuze/spring-kotlin-deepdive[spring-kotlin-deepdive]: A step-by-step migration guide for Boot 1.0 and Java to Boot 2.0 and Kotlin -* https://github.com/spring-cloud/spring-cloud-gcp/tree/master/spring-cloud-gcp-kotlin-samples/spring-cloud-gcp-kotlin-app-sample[spring-cloud-gcp-kotlin-app-sample]: Spring Boot with Google Cloud Platform Integrations - - - -[[issues]] -=== Issues - -The following list categorizes the pending issues related to Spring and Kotlin support: - -* Spring Framework -** https://github.com/spring-projects/spring-framework/issues/20606[Unable to use WebTestClient with mock server in Kotlin] -** https://github.com/spring-projects/spring-framework/issues/20496[Support null-safety at generics, varargs and array elements level] -* Kotlin -** https://youtrack.jetbrains.com/issue/KT-6380[Parent issue for Spring Framework support] -** https://youtrack.jetbrains.com/issue/KT-5464[Kotlin requires type inference where Java doesn't] -** https://youtrack.jetbrains.com/issue/KT-20283[Smart cast regression with open classes] -** https://youtrack.jetbrains.com/issue/KT-14984[Impossible to pass not all SAM argument as function] -** https://youtrack.jetbrains.com/issue/KT-15125[Support JSR 223 bindings directly via script variables] -** https://youtrack.jetbrains.com/issue/KT-6653[Kotlin properties do not override Java-style getters and setters] diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/annotations.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/annotations.adoc new file mode 100644 index 000000000000..4a724caf0115 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/annotations.adoc @@ -0,0 +1,29 @@ +[[kotlin-annotations]] += Annotations + +The Spring Framework also takes advantage of https://kotlinlang.org/docs/reference/null-safety.html[Kotlin null-safety] +to determine if an HTTP parameter is required without having to explicitly +define the `required` attribute. That means `@RequestParam name: String?` is treated +as not required and, conversely, `@RequestParam name: String` is treated as being required. +This feature is also supported on the Spring Messaging `@Header` annotation. + +In a similar fashion, Spring bean injection with `@Autowired`, `@Bean`, or `@Inject` uses +this information to determine if a bean is required or not. + +For example, `@Autowired lateinit var thing: Thing` implies that a bean +of type `Thing` must be registered in the application context, while `@Autowired lateinit var thing: Thing?` +does not raise an error if such a bean does not exist. + +Following the same principle, `@Bean fun play(toy: Toy, car: Car?) = Baz(toy, Car)` implies +that a bean of type `Toy` must be registered in the application context, while a bean of +type `Car` may or may not exist. The same behavior applies to autowired constructor parameters. + +NOTE: If you use bean validation on classes with properties or a primary constructor +parameters, you may need to use +https://kotlinlang.org/docs/reference/annotations.html#annotation-use-site-targets[annotation use-site targets], +such as `@field:NotNull` or `@get:Size(min=5, max=15)`, as described in +https://stackoverflow.com/a/35853200/1092077[this Stack Overflow response]. + + + + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/bean-definition-dsl.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/bean-definition-dsl.adoc new file mode 100644 index 000000000000..5309da8d9213 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/bean-definition-dsl.adoc @@ -0,0 +1,116 @@ +[[kotlin-bean-definition-dsl]] += Bean Definition DSL + +Spring Framework supports registering beans in a functional way by using lambdas +as an alternative to XML or Java configuration (`@Configuration` and `@Bean`). In a nutshell, +it lets you register beans with a lambda that acts as a `FactoryBean`. +This mechanism is very efficient, as it does not require any reflection or CGLIB proxies. + +In Java, you can, for example, write the following: + +[source,java,indent=0] +---- + class Foo {} + + class Bar { + private final Foo foo; + public Bar(Foo foo) { + this.foo = foo; + } + } + + GenericApplicationContext context = new GenericApplicationContext(); + context.registerBean(Foo.class); + context.registerBean(Bar.class, () -> new Bar(context.getBean(Foo.class))); +---- + +In Kotlin, with reified type parameters and `GenericApplicationContext` Kotlin extensions, +you can instead write the following: + +[source,kotlin,indent=0] +---- + class Foo + + class Bar(private val foo: Foo) + + val context = GenericApplicationContext().apply { + registerBean<Foo>() + registerBean { Bar(it.getBean()) } + } +---- +==== + +When the class `Bar` has a single constructor, you can even just specify the bean class, +the constructor parameters will be autowired by type: + +==== +[source,kotlin,indent=0] +---- + val context = GenericApplicationContext().apply { + registerBean<Foo>() + registerBean<Bar>() + } +---- + +In order to allow a more declarative approach and cleaner syntax, Spring Framework provides +a {docs-spring-framework}/kdoc-api/spring-context/org.springframework.context.support/-bean-definition-dsl/index.html[Kotlin bean definition DSL] +It declares an `ApplicationContextInitializer` through a clean declarative API, +which lets you deal with profiles and `Environment` for customizing +how beans are registered. + +In the following example notice that: + +* Type inference usually allows to avoid specifying the type for bean references like `ref("bazBean")` +* It is possible to use Kotlin top level functions to declare beans using callable references like `bean(::myRouter)` in this example +* When specifying `bean<Bar>()` or `bean(::myRouter)`, parameters are autowired by type +* The `FooBar` bean will be registered only if the `foobar` profile is active + +[source,kotlin,indent=0] +---- + class Foo + class Bar(private val foo: Foo) + class Baz(var message: String = "") + class FooBar(private val baz: Baz) + + val myBeans = beans { + bean<Foo>() + bean<Bar>() + bean("bazBean") { + Baz().apply { + message = "Hello world" + } + } + profile("foobar") { + bean { FooBar(ref("bazBean")) } + } + bean(::myRouter) + } + + fun myRouter(foo: Foo, bar: Bar, baz: Baz) = router { + // ... + } +---- + +NOTE: This DSL is programmatic, meaning it allows custom registration logic of beans +through an `if` expression, a `for` loop, or any other Kotlin constructs. + +You can then use this `beans()` function to register beans on the application context, +as the following example shows: + +[source,kotlin,indent=0] +---- + val context = GenericApplicationContext().apply { + myBeans.initialize(this) + refresh() + } +---- + +NOTE: Spring Boot is based on JavaConfig and +https://github.com/spring-projects/spring-boot/issues/8115[does not yet provide specific support for functional bean definition], +but you can experimentally use functional bean definitions through Spring Boot's `ApplicationContextInitializer` support. +See https://stackoverflow.com/questions/45935931/how-to-use-functional-bean-definition-kotlin-dsl-with-spring-boot-and-spring-w/46033685#46033685[this Stack Overflow answer] +for more details and up-to-date information. See also the experimental Kofu DSL developed in https://github.com/spring-projects/spring-fu[Spring Fu incubator]. + + + + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/classes-interfaces.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/classes-interfaces.adoc new file mode 100644 index 000000000000..63a87b346512 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/classes-interfaces.adoc @@ -0,0 +1,19 @@ +[[kotlin-classes-interfaces]] += Classes and Interfaces + +The Spring Framework supports various Kotlin constructs, such as instantiating Kotlin classes +through primary constructors, immutable classes data binding, and function optional parameters +with default values. + +Kotlin parameter names are recognized through a dedicated `KotlinReflectionParameterNameDiscoverer`, +which allows finding interface method parameter names without requiring the Java 8 `-parameters` +compiler flag to be enabled during compilation. (For completeness, we nevertheless recommend +running the Kotlin compiler with its `-java-parameters` flag for standard Java parameter exposure.) + +You can declare configuration classes as +https://kotlinlang.org/docs/reference/nested-classes.html[top level or nested but not inner], +since the later requires a reference to the outer class. + + + + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/coroutines.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/coroutines.adoc new file mode 100644 index 000000000000..699ab8d43813 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/coroutines.adoc @@ -0,0 +1,257 @@ +[[coroutines]] += Coroutines + +Kotlin https://kotlinlang.org/docs/reference/coroutines-overview.html[Coroutines] are Kotlin +lightweight threads allowing to write non-blocking code in an imperative way. On language side, +suspending functions provides an abstraction for asynchronous operations while on library side +https://github.com/Kotlin/kotlinx.coroutines[kotlinx.coroutines] provides functions like +https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html[`async { }`] +and types like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`]. + +Spring Framework provides support for Coroutines on the following scope: + +* https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html[Deferred] and https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[Flow] return values support in Spring MVC and WebFlux annotated `@Controller` +* Suspending function support in Spring MVC and WebFlux annotated `@Controller` +* Extensions for WebFlux {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.client/index.html[client] and {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/index.html[server] functional API. +* WebFlux.fn {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] DSL +* Suspending function and `Flow` support in RSocket `@MessageMapping` annotated methods +* Extensions for {docs-spring-framework}/kdoc-api/spring-messaging/org.springframework.messaging.rsocket/index.html[`RSocketRequester`] + + + +[[dependencies]] +== Dependencies + +Coroutines support is enabled when `kotlinx-coroutines-core` and `kotlinx-coroutines-reactor` +dependencies are in the classpath: + +`build.gradle.kts` +[source,kotlin,indent=0] +---- +dependencies { + + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:${coroutinesVersion}") + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor:${coroutinesVersion}") +} +---- + +Version `1.4.0` and above are supported. + + + +[[how-reactive-translates-to-coroutines?]] +== How Reactive translates to Coroutines? + +For return values, the translation from Reactive to Coroutines APIs is the following: + +* `fun handler(): Mono<Void>` becomes `suspend fun handler()` +* `fun handler(): Mono<T>` becomes `suspend fun handler(): T` or `suspend fun handler(): T?` depending on if the `Mono` can be empty or not (with the advantage of being more statically typed) +* `fun handler(): Flux<T>` becomes `fun handler(): Flow<T>` + +For input parameters: + +* If laziness is not needed, `fun handler(mono: Mono<T>)` becomes `fun handler(value: T)` since a suspending functions can be invoked to get the value parameter. +* If laziness is needed, `fun handler(mono: Mono<T>)` becomes `fun handler(supplier: suspend () -> T)` or `fun handler(supplier: suspend () -> T?)` + +https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`] is `Flux` equivalent in Coroutines world, suitable for hot or cold stream, finite or infinite streams, with the following main differences: + +* `Flow` is push-based while `Flux` is push-pull hybrid +* Backpressure is implemented via suspending functions +* `Flow` has only a https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/collect.html[single suspending `collect` method] and operators are implemented as https://kotlinlang.org/docs/reference/extensions.html[extensions] +* https://github.com/Kotlin/kotlinx.coroutines/tree/master/kotlinx-coroutines-core/common/src/flow/operators[Operators are easy to implement] thanks to Coroutines +* Extensions allow to add custom operators to `Flow` +* Collect operations are suspending functions +* https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/map.html[`map` operator] supports asynchronous operation (no need for `flatMap`) since it takes a suspending function parameter + +Read this blog post about https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow[Going Reactive with Spring, Coroutines and Kotlin Flow] +for more details, including how to run code concurrently with Coroutines. + + + +[[controllers]] +== Controllers + +Here is an example of a Coroutines `@RestController`. + +[source,kotlin,indent=0] +---- +@RestController +class CoroutinesRestController(client: WebClient, banner: Banner) { + + @GetMapping("/suspend") + suspend fun suspendingEndpoint(): Banner { + delay(10) + return banner + } + + @GetMapping("/flow") + fun flowEndpoint() = flow { + delay(10) + emit(banner) + delay(10) + emit(banner) + } + + @GetMapping("/deferred") + fun deferredEndpoint() = GlobalScope.async { + delay(10) + banner + } + + @GetMapping("/sequential") + suspend fun sequential(): List<Banner> { + val banner1 = client + .get() + .uri("/suspend") + .accept(MediaType.APPLICATION_JSON) + .awaitExchange() + .awaitBody<Banner>() + val banner2 = client + .get() + .uri("/suspend") + .accept(MediaType.APPLICATION_JSON) + .awaitExchange() + .awaitBody<Banner>() + return listOf(banner1, banner2) + } + + @GetMapping("/parallel") + suspend fun parallel(): List<Banner> = coroutineScope { + val deferredBanner1: Deferred<Banner> = async { + client + .get() + .uri("/suspend") + .accept(MediaType.APPLICATION_JSON) + .awaitExchange() + .awaitBody<Banner>() + } + val deferredBanner2: Deferred<Banner> = async { + client + .get() + .uri("/suspend") + .accept(MediaType.APPLICATION_JSON) + .awaitExchange() + .awaitBody<Banner>() + } + listOf(deferredBanner1.await(), deferredBanner2.await()) + } + + @GetMapping("/error") + suspend fun error() { + throw IllegalStateException() + } + + @GetMapping("/cancel") + suspend fun cancel() { + throw CancellationException() + } + +} +---- + +View rendering with a `@Controller` is also supported. + +[source,kotlin,indent=0] +---- +@Controller +class CoroutinesViewController(banner: Banner) { + + @GetMapping("/") + suspend fun render(model: Model): String { + delay(10) + model["banner"] = banner + return "index" + } +} +---- + + + +[[webflux-fn]] +== WebFlux.fn + +Here is an example of Coroutines router defined via the {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] DSL and related handlers. + +[source,kotlin,indent=0] +---- +@Configuration +class RouterConfiguration { + + @Bean + fun mainRouter(userHandler: UserHandler) = coRouter { + GET("/", userHandler::listView) + GET("/api/user", userHandler::listApi) + } +} +---- + +[source,kotlin,indent=0] +---- +class UserHandler(builder: WebClient.Builder) { + + private val client = builder.baseUrl("...").build() + + suspend fun listView(request: ServerRequest): ServerResponse = + ServerResponse.ok().renderAndAwait("users", mapOf("users" to + client.get().uri("...").awaitExchange().awaitBody<User>())) + + suspend fun listApi(request: ServerRequest): ServerResponse = + ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).bodyAndAwait( + client.get().uri("...").awaitExchange().awaitBody<User>()) +} +---- + + + +[[transactions]] +== Transactions + +Transactions on Coroutines are supported via the programmatic variant of the Reactive +transaction management provided as of Spring Framework 5.2. + +For suspending functions, a `TransactionalOperator.executeAndAwait` extension is provided. + +[source,kotlin,indent=0] +---- + import org.springframework.transaction.reactive.executeAndAwait + + class PersonRepository(private val operator: TransactionalOperator) { + + suspend fun initDatabase() = operator.executeAndAwait { + insertPerson1() + insertPerson2() + } + + private suspend fun insertPerson1() { + // INSERT SQL statement + } + + private suspend fun insertPerson2() { + // INSERT SQL statement + } + } +---- + +For Kotlin `Flow`, a `Flow<T>.transactional` extension is provided. + +[source,kotlin,indent=0] +---- + import org.springframework.transaction.reactive.transactional + + class PersonRepository(private val operator: TransactionalOperator) { + + fun updatePeople() = findPeople().map(::updatePerson).transactional(operator) + + private fun findPeople(): Flow<Person> { + // SELECT SQL statement + } + + private suspend fun updatePerson(person: Person): Person { + // UPDATE SQL statement + } + } +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/extensions.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/extensions.adoc new file mode 100644 index 000000000000..d7da3aee5328 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/extensions.adoc @@ -0,0 +1,46 @@ +[[kotlin-extensions]] += Extensions + +Kotlin https://kotlinlang.org/docs/reference/extensions.html[extensions] provide the ability +to extend existing classes with additional functionality. The Spring Framework Kotlin APIs +use these extensions to add new Kotlin-specific conveniences to existing Spring APIs. + +The {docs-spring-framework}/kdoc-api/[Spring Framework KDoc API] lists +and documents all available Kotlin extensions and DSLs. + +NOTE: Keep in mind that Kotlin extensions need to be imported to be used. This means, +for example, that the `GenericApplicationContext.registerBean` Kotlin extension +is available only if `org.springframework.context.support.registerBean` is imported. +That said, similar to static imports, an IDE should automatically suggest the import in most cases. + +For example, https://kotlinlang.org/docs/reference/inline-functions.html#reified-type-parameters[Kotlin reified type parameters] +provide a workaround for JVM https://docs.oracle.com/javase/tutorial/java/generics/erasure.html[generics type erasure], +and the Spring Framework provides some extensions to take advantage of this feature. +This allows for a better Kotlin API `RestTemplate`, for the new `WebClient` from Spring +WebFlux, and for various other APIs. + +NOTE: Other libraries, such as Reactor and Spring Data, also provide Kotlin extensions +for their APIs, thus giving a better Kotlin development experience overall. + +To retrieve a list of `User` objects in Java, you would normally write the following: + +[source,java,indent=0] +---- + Flux<User> users = client.get().retrieve().bodyToFlux(User.class) +---- + +With Kotlin and the Spring Framework extensions, you can instead write the following: + +[source,kotlin,indent=0] +---- + val users = client.get().retrieve().bodyToFlux<User>() + // or (both are equivalent) + val users : Flux<User> = client.get().retrieve().bodyToFlux() +---- + +As in Java, `users` in Kotlin is strongly typed, but Kotlin's clever type inference allows +for shorter syntax. + + + + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc new file mode 100644 index 000000000000..78b32230f4a2 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc @@ -0,0 +1,32 @@ +[[kotlin-getting-started]] += Getting Started + +The easiest way to learn how to build a Spring application with Kotlin is to follow +https://spring.io/guides/tutorials/spring-boot-kotlin/[the dedicated tutorial]. + + + +[[start-spring-io]] +== `start.spring.io` + +The easiest way to start a new Spring Framework project in Kotlin is to create a new Spring +Boot 2 project on https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io]. + + + +[[choosing-the-web-flavor]] +== Choosing the Web Flavor + +Spring Framework now comes with two different web stacks: <<web#mvc, Spring MVC>> and +<<web-reactive#spring-web-reactive, Spring WebFlux>>. + +Spring WebFlux is recommended if you want to create applications that will deal with latency, +long-lived connections, streaming scenarios or if you want to use the web functional +Kotlin DSL. + +For other use cases, especially if you are using blocking technologies such as JPA, Spring +MVC and its annotation-based programming model is the recommended choice. + + + + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc new file mode 100644 index 000000000000..3c8cc756c7d1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc @@ -0,0 +1,38 @@ +[[kotlin-null-safety]] += Null-safety + +One of Kotlin's key features is https://kotlinlang.org/docs/reference/null-safety.html[null-safety], +which cleanly deals with `null` values at compile time rather than bumping into the famous +`NullPointerException` at runtime. This makes applications safer through nullability +declarations and expressing "`value or no value`" semantics without paying the cost of wrappers, such as `Optional`. +(Kotlin allows using functional constructs with nullable values. See this +https://www.baeldung.com/kotlin-null-safety[comprehensive guide to Kotlin null-safety].) + +Although Java does not let you express null-safety in its type-system, the Spring Framework +provides <<core#null-safety, null-safety of the whole Spring Framework API>> +via tooling-friendly annotations declared in the `org.springframework.lang` package. +By default, types from Java APIs used in Kotlin are recognized as +https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], +for which null-checks are relaxed. +https://kotlinlang.org/docs/reference/java-interop.html#jsr-305-support[Kotlin support for JSR-305 annotations] +and Spring nullability annotations provide null-safety for the whole Spring Framework API to Kotlin developers, +with the advantage of dealing with `null`-related issues at compile time. + +NOTE: Libraries such as Reactor or Spring Data provide null-safe APIs to leverage this feature. + +You can configure JSR-305 checks by adding the `-Xjsr305` compiler flag with the following +options: `-Xjsr305={strict|warn|ignore}`. + +For kotlin versions 1.1+, the default behavior is the same as `-Xjsr305=warn`. +The `strict` value is required to have Spring Framework API null-safety taken into account +in Kotlin types inferred from Spring API but should be used with the knowledge that Spring +API nullability declaration could evolve even between minor releases and that more checks may +be added in the future. + +NOTE: Generic type arguments, varargs, and array elements nullability are not supported yet, +but should be in an upcoming release. See https://github.com/Kotlin/KEEP/issues/79[this discussion] +for up-to-date information. + + + + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/requirements.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/requirements.adoc new file mode 100644 index 000000000000..6c453db075ae --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/requirements.adoc @@ -0,0 +1,20 @@ +[[kotlin-requirements]] += Requirements + +Spring Framework supports Kotlin 1.3+ and requires +https://search.maven.org/artifact/org.jetbrains.kotlin/kotlin-stdlib[`kotlin-stdlib`] +(or one of its variants, such as https://search.maven.org/artifact/org.jetbrains.kotlin/kotlin-stdlib-jdk8[`kotlin-stdlib-jdk8`]) +and https://search.maven.org/artifact/org.jetbrains.kotlin/kotlin-reflect[`kotlin-reflect`] +to be present on the classpath. They are provided by default if you bootstrap a Kotlin project on +https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io]. + +WARNING: Kotlin https://kotlinlang.org/docs/inline-classes.html[inline classes] are not yet supported. + +NOTE: The https://github.com/FasterXML/jackson-module-kotlin[Jackson Kotlin module] is required +for serializing or deserializing JSON data for Kotlin classes with Jackson, so make sure to add the +`com.fasterxml.jackson.module:jackson-module-kotlin` dependency to your project if you have such need. +It is automatically registered when found in the classpath. + + + + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/resources.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/resources.adoc new file mode 100644 index 000000000000..a99666581818 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/resources.adoc @@ -0,0 +1,45 @@ +[[kotlin-resources]] += Resources + +We recommend the following resources for people learning how to build applications with +Kotlin and the Spring Framework: + +* https://kotlinlang.org/docs/reference/[Kotlin language reference] +* https://slack.kotlinlang.org/[Kotlin Slack] (with a dedicated #spring channel) +* https://stackoverflow.com/questions/tagged/spring+kotlin[Stackoverflow, with `spring` and `kotlin` tags] +* https://play.kotlinlang.org/[Try Kotlin in your browser] +* https://blog.jetbrains.com/kotlin/[Kotlin blog] +* https://kotlin.link/[Awesome Kotlin] + + + +[[examples]] +== Examples + +The following Github projects offer examples that you can learn from and possibly even extend: + +* https://github.com/sdeleuze/spring-boot-kotlin-demo[spring-boot-kotlin-demo]: Regular Spring Boot and Spring Data JPA project +* https://github.com/mixitconf/mixit[mixit]: Spring Boot 2, WebFlux, and Reactive Spring Data MongoDB +* https://github.com/sdeleuze/spring-kotlin-functional[spring-kotlin-functional]: Standalone WebFlux and functional bean definition DSL +* https://github.com/sdeleuze/spring-kotlin-fullstack[spring-kotlin-fullstack]: WebFlux Kotlin fullstack example with Kotlin2js for frontend instead of JavaScript or TypeScript +* https://github.com/spring-petclinic/spring-petclinic-kotlin[spring-petclinic-kotlin]: Kotlin version of the Spring PetClinic Sample Application +* https://github.com/sdeleuze/spring-kotlin-deepdive[spring-kotlin-deepdive]: A step-by-step migration guide for Boot 1.0 and Java to Boot 2.0 and Kotlin +* https://github.com/spring-cloud/spring-cloud-gcp/tree/master/spring-cloud-gcp-kotlin-samples/spring-cloud-gcp-kotlin-app-sample[spring-cloud-gcp-kotlin-app-sample]: Spring Boot with Google Cloud Platform Integrations + + + +[[issues]] +== Issues + +The following list categorizes the pending issues related to Spring and Kotlin support: + +* Spring Framework +** https://github.com/spring-projects/spring-framework/issues/20606[Unable to use WebTestClient with mock server in Kotlin] +** https://github.com/spring-projects/spring-framework/issues/20496[Support null-safety at generics, varargs and array elements level] +* Kotlin +** https://youtrack.jetbrains.com/issue/KT-6380[Parent issue for Spring Framework support] +** https://youtrack.jetbrains.com/issue/KT-5464[Kotlin requires type inference where Java doesn't] +** https://youtrack.jetbrains.com/issue/KT-20283[Smart cast regression with open classes] +** https://youtrack.jetbrains.com/issue/KT-14984[Impossible to pass not all SAM argument as function] +** https://youtrack.jetbrains.com/issue/KT-15125[Support JSR 223 bindings directly via script variables] +** https://youtrack.jetbrains.com/issue/KT-6653[Kotlin properties do not override Java-style getters and setters] diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc new file mode 100644 index 000000000000..4bcb633c479f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc @@ -0,0 +1,360 @@ +[[kotlin-spring-projects-in-kotlin]] += Spring Projects in Kotlin + +This section provides some specific hints and recommendations worth for developing Spring projects +in Kotlin. + + + +[[final-by-default]] +== Final by Default + +By default, https://discuss.kotlinlang.org/t/classes-final-by-default/166[all classes in Kotlin are `final`]. +The `open` modifier on a class is the opposite of Java's `final`: It allows others to inherit from this +class. This also applies to member functions, in that they need to be marked as `open` to be overridden. + +While Kotlin's JVM-friendly design is generally frictionless with Spring, this specific Kotlin feature +can prevent the application from starting, if this fact is not taken into consideration. This is because +Spring beans (such as `@Configuration` annotated classes which by default need to be extended at runtime for technical +reasons) are normally proxied by CGLIB. The workaround is to add an `open` keyword on each class and +member function of Spring beans that are proxied by CGLIB, which can +quickly become painful and is against the Kotlin principle of keeping code concise and predictable. + +NOTE: It is also possible to avoid CGLIB proxies for configuration classes by using `@Configuration(proxyBeanMethods = false)`. +See {api-spring-framework}/context/annotation/Configuration.html#proxyBeanMethods--[`proxyBeanMethods` Javadoc] for more details. + +Fortunately, Kotlin provides a +https://kotlinlang.org/docs/reference/compiler-plugins.html#kotlin-spring-compiler-plugin[`kotlin-spring`] +plugin (a preconfigured version of the `kotlin-allopen` plugin) that automatically opens classes +and their member functions for types that are annotated or meta-annotated with one of the following +annotations: + +* `@Component` +* `@Async` +* `@Transactional` +* `@Cacheable` + +Meta-annotation support means that types annotated with `@Configuration`, `@Controller`, +`@RestController`, `@Service`, or `@Repository` are automatically opened since these +annotations are meta-annotated with `@Component`. + +https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io] enables +the `kotlin-spring` plugin by default. So, in practice, you can write your Kotlin beans +without any additional `open` keyword, as in Java. + +NOTE: The Kotlin code samples in Spring Framework documentation do not explicitly specify +`open` on the classes and their member functions. The samples are written for projects +using the `kotlin-allopen` plugin, since this is the most commonly used setup. + + + +[[using-immutable-class-instances-for-persistence]] +== Using Immutable Class Instances for Persistence + +In Kotlin, it is convenient and considered to be a best practice to declare read-only properties +within the primary constructor, as in the following example: + +[source,kotlin,indent=0] +---- + class Person(val name: String, val age: Int) +---- + +You can optionally add https://kotlinlang.org/docs/reference/data-classes.html[the `data` keyword] +to make the compiler automatically derive the following members from all properties declared +in the primary constructor: + +* `equals()` and `hashCode()` +* `toString()` of the form `"User(name=John, age=42)"` +* `componentN()` functions that correspond to the properties in their order of declaration +* `copy()` function + +As the following example shows, this allows for easy changes to individual properties, even if `Person` properties are read-only: + +[source,kotlin,indent=0] +---- + data class Person(val name: String, val age: Int) + + val jack = Person(name = "Jack", age = 1) + val olderJack = jack.copy(age = 2) +---- + +Common persistence technologies (such as JPA) require a default constructor, preventing this +kind of design. Fortunately, there is a workaround for this +https://stackoverflow.com/questions/32038177/kotlin-with-jpa-default-constructor-hell["`default constructor hell`"], +since Kotlin provides a https://kotlinlang.org/docs/reference/compiler-plugins.html#kotlin-jpa-compiler-plugin[`kotlin-jpa`] +plugin that generates synthetic no-arg constructor for classes annotated with JPA annotations. + +If you need to leverage this kind of mechanism for other persistence technologies, you can configure +the https://kotlinlang.org/docs/reference/compiler-plugins.html#how-to-use-no-arg-plugin[`kotlin-noarg`] +plugin. + +NOTE: As of the Kay release train, Spring Data supports Kotlin immutable class instances and +does not require the `kotlin-noarg` plugin if the module uses Spring Data object mappings +(such as MongoDB, Redis, Cassandra, and others). + + + +[[injecting-dependencies]] +== Injecting Dependencies + +Our recommendation is to try to favor constructor injection with `val` read-only (and +non-nullable when possible) https://kotlinlang.org/docs/reference/properties.html[properties], +as the following example shows: + +[source,kotlin,indent=0] +---- + @Component + class YourBean( + private val mongoTemplate: MongoTemplate, + private val solrClient: SolrClient + ) +---- + +NOTE: Classes with a single constructor have their parameters automatically autowired. +That's why there is no need for an explicit `@Autowired constructor` in the example shown +above. + +If you really need to use field injection, you can use the `lateinit var` construct, +as the following example shows: + +[source,kotlin,indent=0] +---- + @Component + class YourBean { + + @Autowired + lateinit var mongoTemplate: MongoTemplate + + @Autowired + lateinit var solrClient: SolrClient + } +---- + + + +[[injecting-configuration-properties]] +== Injecting Configuration Properties + +In Java, you can inject configuration properties by using annotations (such as pass:q[`@Value("${property}")`)]. +However, in Kotlin, `$` is a reserved character that is used for +https://kotlinlang.org/docs/reference/idioms.html#string-interpolation[string interpolation]. + +Therefore, if you wish to use the `@Value` annotation in Kotlin, you need to escape the `$` +character by writing pass:q[`@Value("\${property}")`]. + +NOTE: If you use Spring Boot, you should probably use +https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-typesafe-configuration-properties[`@ConfigurationProperties`] +instead of `@Value` annotations. + +As an alternative, you can customize the property placeholder prefix by declaring the +following configuration beans: + +[source,kotlin,indent=0] +---- + @Bean + fun propertyConfigurer() = PropertySourcesPlaceholderConfigurer().apply { + setPlaceholderPrefix("%{") + } +---- + +You can customize existing code (such as Spring Boot actuators or `@LocalServerPort`) +that uses the `${...}` syntax, with configuration beans, as the following example shows: + +[source,kotlin,indent=0] +---- + @Bean + fun kotlinPropertyConfigurer() = PropertySourcesPlaceholderConfigurer().apply { + setPlaceholderPrefix("%{") + setIgnoreUnresolvablePlaceholders(true) + } + + @Bean + fun defaultPropertyConfigurer() = PropertySourcesPlaceholderConfigurer() +---- + + + +[[checked-exceptions]] +== Checked Exceptions + +Java and https://kotlinlang.org/docs/reference/exceptions.html[Kotlin exception handling] +are pretty close, with the main difference being that Kotlin treats all exceptions as +unchecked exceptions. However, when using proxied objects (for example classes or methods +annotated with `@Transactional`), checked exceptions thrown will be wrapped by default in +an `UndeclaredThrowableException`. + +To get the original exception thrown like in Java, methods should be annotated with +https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.jvm/-throws/index.html[`@Throws`] +to specify explicitly the checked exceptions thrown (for example `@Throws(IOException::class)`). + + + +[[annotation-array-attributes]] +== Annotation Array Attributes + +Kotlin annotations are mostly similar to Java annotations, but array attributes (which are +extensively used in Spring) behave differently. As explained in the +https://kotlinlang.org/docs/reference/annotations.html[Kotlin documentation] you can omit +the `value` attribute name, unlike other attributes, and specify it as a `vararg` parameter. + +To understand what that means, consider `@RequestMapping` (which is one of the most widely +used Spring annotations) as an example. This Java annotation is declared as follows: + +[source,java,indent=0] +---- + public @interface RequestMapping { + + @AliasFor("path") + String[] value() default {}; + + @AliasFor("value") + String[] path() default {}; + + RequestMethod[] method() default {}; + + // ... + } +---- + +The typical use case for `@RequestMapping` is to map a handler method to a specific path +and method. In Java, you can specify a single value for the annotation array attribute, +and it is automatically converted to an array. + +That is why one can write +`@RequestMapping(value = "/toys", method = RequestMethod.GET)` or +`@RequestMapping(path = "/toys", method = RequestMethod.GET)`. + +However, in Kotlin, you must write `@RequestMapping("/toys", method = [RequestMethod.GET])` +or `@RequestMapping(path = ["/toys"], method = [RequestMethod.GET])` (square brackets need +to be specified with named array attributes). + +An alternative for this specific `method` attribute (the most common one) is to +use a shortcut annotation, such as `@GetMapping`, `@PostMapping`, and others. + +NOTE: If the `@RequestMapping` `method` attribute is not specified, all HTTP methods will +be matched, not only the `GET` method. + + + +[[testing]] +== Testing + +This section addresses testing with the combination of Kotlin and Spring Framework. +The recommended testing framework is https://junit.org/junit5/[JUnit 5] along with +https://mockk.io/[Mockk] for mocking. + +NOTE: If you are using Spring Boot, see +https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-kotlin-testing[this related documentation]. + + +[[constructor-injection]] +=== Constructor injection + +As described in the <<testing#testcontext-junit-jupiter-di, dedicated section>>, +JUnit 5 allows constructor injection of beans which is pretty useful with Kotlin +in order to use `val` instead of `lateinit var`. You can use +{api-spring-framework}/test/context/TestConstructor.html[`@TestConstructor(autowireMode = AutowireMode.ALL)`] +to enable autowiring for all parameters. + +==== +[source,kotlin,indent=0] +---- +@SpringJUnitConfig(TestConfig::class) +@TestConstructor(autowireMode = AutowireMode.ALL) +class OrderServiceIntegrationTests(val orderService: OrderService, + val customerService: CustomerService) { + + // tests that use the injected OrderService and CustomerService +} +---- +==== + + +[[per_class-lifecycle]] +=== `PER_CLASS` Lifecycle + +Kotlin lets you specify meaningful test function names between backticks (```). +As of JUnit 5, Kotlin test classes can use the `@TestInstance(TestInstance.Lifecycle.PER_CLASS)` +annotation to enable single instantiation of test classes, which allows the use of `@BeforeAll` +and `@AfterAll` annotations on non-static methods, which is a good fit for Kotlin. + +You can also change the default behavior to `PER_CLASS` thanks to a `junit-platform.properties` +file with a `junit.jupiter.testinstance.lifecycle.default = per_class` property. + +The following example demonstrates `@BeforeAll` and `@AfterAll` annotations on non-static methods: + +[source,kotlin,indent=0] +---- +@TestInstance(TestInstance.Lifecycle.PER_CLASS) +class IntegrationTests { + + val application = Application(8181) + val client = WebClient.create("http://localhost:8181") + + @BeforeAll + fun beforeAll() { + application.start() + } + + @Test + fun `Find all users on HTML page`() { + client.get().uri("/users") + .accept(TEXT_HTML) + .retrieve() + .bodyToMono<String>() + .test() + .expectNextMatches { it.contains("Foo") } + .verifyComplete() + } + + @AfterAll + fun afterAll() { + application.stop() + } +} +---- + + +[[specification-like-tests]] +=== Specification-like Tests + +You can create specification-like tests with JUnit 5 and Kotlin. +The following example shows how to do so: + +[source,kotlin,indent=0] +---- +class SpecificationLikeTests { + + @Nested + @DisplayName("a calculator") + inner class Calculator { + val calculator = SampleCalculator() + + @Test + fun `should return the result of adding the first number to the second number`() { + val sum = calculator.sum(2, 4) + assertEquals(6, sum) + } + + @Test + fun `should return the result of subtracting the second number from the first number`() { + val subtract = calculator.subtract(4, 2) + assertEquals(2, subtract) + } + } +} +---- + + +[[kotlin-webtestclient-issue]] +=== `WebTestClient` Type Inference Issue in Kotlin + +Due to a https://youtrack.jetbrains.com/issue/KT-5464[type inference issue], you must +use the Kotlin `expectBody` extension (such as `.expectBody<String>().isEqualTo("toys")`), +since it provides a workaround for the Kotlin issue with the Java API. + +See also the related https://jira.spring.io/browse/SPR-16057[SPR-16057] issue. + + + + diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/web.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/web.adoc new file mode 100644 index 000000000000..0b44ce3c7432 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/web.adoc @@ -0,0 +1,140 @@ +[[kotlin-web]] += Web + + + +[[router-dsl]] +== Router DSL + +Spring Framework comes with a Kotlin router DSL available in 3 flavors: + +* WebMvc.fn DSL with {docs-spring-framework}/kdoc-api/spring-webmvc/org.springframework.web.servlet.function/router.html[router { }] +* WebFlux.fn <<web-reactive#webflux-fn, Reactive>> DSL with {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/router.html[router { }] +* WebFlux.fn <<Coroutines>> DSL with {docs-spring-framework}/kdoc-api/spring-webflux/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] + +These DSL let you write clean and idiomatic Kotlin code to build a `RouterFunction` instance as the following example shows: + +[source,kotlin,indent=0] +---- +@Configuration +class RouterRouterConfiguration { + + @Bean + fun mainRouter(userHandler: UserHandler) = router { + accept(TEXT_HTML).nest { + GET("/") { ok().render("index") } + GET("/sse") { ok().render("sse") } + GET("/users", userHandler::findAllView) + } + "/api".nest { + accept(APPLICATION_JSON).nest { + GET("/users", userHandler::findAll) + } + accept(TEXT_EVENT_STREAM).nest { + GET("/users", userHandler::stream) + } + } + resources("/**", ClassPathResource("static/")) + } +} +---- + +NOTE: This DSL is programmatic, meaning that it allows custom registration logic of beans +through an `if` expression, a `for` loop, or any other Kotlin constructs. That can be useful +when you need to register routes depending on dynamic data (for example, from a database). + +See https://github.com/mixitconf/mixit/[MiXiT project] for a concrete example. + + + +[[mockmvc-dsl]] +== MockMvc DSL + +A Kotlin DSL is provided via `MockMvc` Kotlin extensions in order to provide a more +idiomatic Kotlin API and to allow better discoverability (no usage of static methods). + +[source,kotlin,indent=0] +---- +val mockMvc: MockMvc = ... +mockMvc.get("/person/{name}", "Lee") { + secure = true + accept = APPLICATION_JSON + headers { + contentLanguage = Locale.FRANCE + } + principal = Principal { "foo" } +}.andExpect { + status { isOk } + content { contentType(APPLICATION_JSON) } + jsonPath("$.name") { value("Lee") } + content { json("""{"someBoolean": false}""", false) } +}.andDo { + print() +} +---- + + + +[[kotlin-script-templates]] +== Kotlin Script Templates + +Spring Framework provides a +https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/view/script/ScriptTemplateView.html[`ScriptTemplateView`] +which supports https://www.jcp.org/en/jsr/detail?id=223[JSR-223] to render templates by using script engines. + +By leveraging `scripting-jsr223` dependencies, it +is possible to use such feature to render Kotlin-based templates with +https://github.com/Kotlin/kotlinx.html[kotlinx.html] DSL or Kotlin multiline interpolated `String`. + +`build.gradle.kts` +[source,kotlin,indent=0] +---- +dependencies { + runtime("org.jetbrains.kotlin:kotlin-scripting-jsr223:${kotlinVersion}") +} +---- + +Configuration is usually done with `ScriptTemplateConfigurer` and `ScriptTemplateViewResolver` beans. + +`KotlinScriptConfiguration.kt` +[source,kotlin,indent=0] +---- +@Configuration +class KotlinScriptConfiguration { + + @Bean + fun kotlinScriptConfigurer() = ScriptTemplateConfigurer().apply { + engineName = "kotlin" + setScripts("scripts/render.kts") + renderFunction = "render" + isSharedEngine = false + } + + @Bean + fun kotlinScriptViewResolver() = ScriptTemplateViewResolver().apply { + setPrefix("templates/") + setSuffix(".kts") + } +} +---- + +See the https://github.com/sdeleuze/kotlin-script-templating[kotlin-script-templating] example +project for more details. + + + +[[kotlin-multiplatform-serialization]] +== Kotlin multiplatform serialization + +As of Spring Framework 5.3, https://github.com/Kotlin/kotlinx.serialization[Kotlin multiplatform serialization] is +supported in Spring MVC, Spring WebFlux and Spring Messaging (RSocket). The builtin support currently targets CBOR, JSON, and ProtoBuf formats. + +To enable it, follow https://github.com/Kotlin/kotlinx.serialization#setup[those instructions] to add the related dependency and plugin. +With Spring MVC and WebFlux, both Kotlin serialization and Jackson will be configured by default if they are in the classpath since +Kotlin serialization is designed to serialize only Kotlin classes annotated with `@Serializable`. +With Spring Messaging (RSocket), make sure that neither Jackson, GSON or JSONB are in the classpath if you want automatic configuration, +if Jackson is needed configure `KotlinSerializationJsonMessageConverter` manually. + + + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations.adoc b/framework-docs/modules/ROOT/pages/testing/annotations.adoc index 9e6edbeb9b45..a13a911735e3 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations.adoc @@ -12,1919 +12,3 @@ It includes the following topics: -[[integration-testing-annotations-standard]] -== Standard Annotation Support - -The following annotations are supported with standard semantics for all configurations of -the Spring TestContext Framework. Note that these annotations are not specific to tests -and can be used anywhere in the Spring Framework. - -* `@Autowired` -* `@Qualifier` -* `@Value` -* `@Resource` (jakarta.annotation) if JSR-250 is present -* `@ManagedBean` (jakarta.annotation) if JSR-250 is present -* `@Inject` (jakarta.inject) if JSR-330 is present -* `@Named` (jakarta.inject) if JSR-330 is present -* `@PersistenceContext` (jakarta.persistence) if JPA is present -* `@PersistenceUnit` (jakarta.persistence) if JPA is present -* `@Transactional` (org.springframework.transaction.annotation) - _with <<testcontext-tx-attribute-support, limited attribute support>>_ - -.JSR-250 Lifecycle Annotations -[NOTE] -==== -In the Spring TestContext Framework, you can use `@PostConstruct` and `@PreDestroy` with -standard semantics on any application components configured in the `ApplicationContext`. -However, these lifecycle annotations have limited usage within an actual test class. - -If a method within a test class is annotated with `@PostConstruct`, that method runs -before any before methods of the underlying test framework (for example, methods -annotated with JUnit Jupiter's `@BeforeEach`), and that applies for every test method in -the test class. On the other hand, if a method within a test class is annotated with -`@PreDestroy`, that method never runs. Therefore, within a test class, we recommend that -you use test lifecycle callbacks from the underlying test framework instead of -`@PostConstruct` and `@PreDestroy`. -==== - - - -[[integration-testing-annotations-spring]] -== Spring Testing Annotations - -The Spring Framework provides the following set of Spring-specific annotations that you -can use in your unit and integration tests in conjunction with the TestContext framework. -See the corresponding javadoc for further information, including default attribute -values, attribute aliases, and other details. - -Spring's testing annotations include the following: - -* <<spring-testing-annotation-bootstrapwith>> -* <<spring-testing-annotation-contextconfiguration>> -* <<spring-testing-annotation-webappconfiguration>> -* <<spring-testing-annotation-contexthierarchy>> -* <<spring-testing-annotation-activeprofiles>> -* <<spring-testing-annotation-testpropertysource>> -* <<spring-testing-annotation-dynamicpropertysource>> -* <<spring-testing-annotation-dirtiescontext>> -* <<spring-testing-annotation-testexecutionlisteners>> -* <<spring-testing-annotation-recordapplicationevents>> -* <<spring-testing-annotation-commit>> -* <<spring-testing-annotation-rollback>> -* <<spring-testing-annotation-beforetransaction>> -* <<spring-testing-annotation-aftertransaction>> -* <<spring-testing-annotation-sql>> -* <<spring-testing-annotation-sqlconfig>> -* <<spring-testing-annotation-sqlmergemode>> -* <<spring-testing-annotation-sqlgroup>> - -[[spring-testing-annotation-bootstrapwith]] -=== `@BootstrapWith` - -`@BootstrapWith` is a class-level annotation that you can use to configure how the Spring -TestContext Framework is bootstrapped. Specifically, you can use `@BootstrapWith` to -specify a custom `TestContextBootstrapper`. See the section on -<<testcontext-bootstrapping, bootstrapping the TestContext framework>> for further details. - -[[spring-testing-annotation-contextconfiguration]] -=== `@ContextConfiguration` - -`@ContextConfiguration` defines class-level metadata that is used to determine how to -load and configure an `ApplicationContext` for integration tests. Specifically, -`@ContextConfiguration` declares the application context resource `locations` or the -component `classes` used to load the context. - -Resource locations are typically XML configuration files or Groovy scripts located in the -classpath, while component classes are typically `@Configuration` classes. However, -resource locations can also refer to files and scripts in the file system, and component -classes can be `@Component` classes, `@Service` classes, and so on. See -<<testcontext-ctx-management-javaconfig-component-classes>> for further details. - -The following example shows a `@ContextConfiguration` annotation that refers to an XML -file: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration("/test-config.xml") // <1> - class XmlApplicationContextTests { - // class body... - } ----- -<1> Referring to an XML file. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration("/test-config.xml") // <1> - class XmlApplicationContextTests { - // class body... - } ----- -<1> Referring to an XML file. - - -The following example shows a `@ContextConfiguration` annotation that refers to a class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration(classes = TestConfig.class) // <1> - class ConfigClassApplicationContextTests { - // class body... - } ----- -<1> Referring to a class. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration(classes = [TestConfig::class]) // <1> - class ConfigClassApplicationContextTests { - // class body... - } ----- -<1> Referring to a class. - - -As an alternative or in addition to declaring resource locations or component classes, -you can use `@ContextConfiguration` to declare `ApplicationContextInitializer` classes. -The following example shows such a case: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration(initializers = CustomContextInitializer.class) // <1> - class ContextInitializerTests { - // class body... - } ----- -<1> Declaring an initializer class. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration(initializers = [CustomContextInitializer::class]) // <1> - class ContextInitializerTests { - // class body... - } ----- -<1> Declaring an initializer class. - - -You can optionally use `@ContextConfiguration` to declare the `ContextLoader` strategy as -well. Note, however, that you typically do not need to explicitly configure the loader, -since the default loader supports `initializers` and either resource `locations` or -component `classes`. - -The following example uses both a location and a loader: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration(locations = "/test-context.xml", loader = CustomContextLoader.class) // <1> - class CustomLoaderXmlApplicationContextTests { - // class body... - } ----- -<1> Configuring both a location and a custom loader. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration("/test-context.xml", loader = CustomContextLoader::class) // <1> - class CustomLoaderXmlApplicationContextTests { - // class body... - } ----- -<1> Configuring both a location and a custom loader. - - -NOTE: `@ContextConfiguration` provides support for inheriting resource locations or -configuration classes as well as context initializers that are declared by superclasses -or enclosing classes. - -See <<testcontext-ctx-management>>, -<<testcontext-junit-jupiter-nested-test-configuration>>, and the `@ContextConfiguration` -javadocs for further details. - -[[spring-testing-annotation-webappconfiguration]] -=== `@WebAppConfiguration` - -`@WebAppConfiguration` is a class-level annotation that you can use to declare that the -`ApplicationContext` loaded for an integration test should be a `WebApplicationContext`. -The mere presence of `@WebAppConfiguration` on a test class ensures that a -`WebApplicationContext` is loaded for the test, using the default value of -`"file:src/main/webapp"` for the path to the root of the web application (that is, the -resource base path). The resource base path is used behind the scenes to create a -`MockServletContext`, which serves as the `ServletContext` for the test's -`WebApplicationContext`. - -The following example shows how to use the `@WebAppConfiguration` annotation: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @WebAppConfiguration // <1> - class WebAppTests { - // class body... - } ----- -<1> The `@WebAppConfiguration` annotation. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @WebAppConfiguration // <1> - class WebAppTests { - // class body... - } ----- -<1> The `@WebAppConfiguration` annotation. --- - - -To override the default, you can specify a different base resource path by using the -implicit `value` attribute. Both `classpath:` and `file:` resource prefixes are -supported. If no resource prefix is supplied, the path is assumed to be a file system -resource. The following example shows how to specify a classpath resource: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @WebAppConfiguration("classpath:test-web-resources") // <1> - class WebAppTests { - // class body... - } ----- -<1> Specifying a classpath resource. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @WebAppConfiguration("classpath:test-web-resources") // <1> - class WebAppTests { - // class body... - } ----- -<1> Specifying a classpath resource. --- - - -Note that `@WebAppConfiguration` must be used in conjunction with -`@ContextConfiguration`, either within a single test class or within a test class -hierarchy. See the -{api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`] -javadoc for further details. - -[[spring-testing-annotation-contexthierarchy]] -=== `@ContextHierarchy` - -`@ContextHierarchy` is a class-level annotation that is used to define a hierarchy of -`ApplicationContext` instances for integration tests. `@ContextHierarchy` should be -declared with a list of one or more `@ContextConfiguration` instances, each of which -defines a level in the context hierarchy. The following examples demonstrate the use of -`@ContextHierarchy` within a single test class (`@ContextHierarchy` can also be used -within a test class hierarchy): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextHierarchy({ - @ContextConfiguration("/parent-config.xml"), - @ContextConfiguration("/child-config.xml") - }) - class ContextHierarchyTests { - // class body... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextHierarchy( - ContextConfiguration("/parent-config.xml"), - ContextConfiguration("/child-config.xml")) - class ContextHierarchyTests { - // class body... - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @WebAppConfiguration - @ContextHierarchy({ - @ContextConfiguration(classes = AppConfig.class), - @ContextConfiguration(classes = WebConfig.class) - }) - class WebIntegrationTests { - // class body... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @WebAppConfiguration - @ContextHierarchy( - ContextConfiguration(classes = [AppConfig::class]), - ContextConfiguration(classes = [WebConfig::class])) - class WebIntegrationTests { - // class body... - } ----- - -If you need to merge or override the configuration for a given level of the context -hierarchy within a test class hierarchy, you must explicitly name that level by supplying -the same value to the `name` attribute in `@ContextConfiguration` at each corresponding -level in the class hierarchy. See <<testcontext-ctx-management-ctx-hierarchies>> and the -{api-spring-framework}/test/context/ContextHierarchy.html[`@ContextHierarchy`] javadoc -for further examples. - -[[spring-testing-annotation-activeprofiles]] -=== `@ActiveProfiles` - -`@ActiveProfiles` is a class-level annotation that is used to declare which bean -definition profiles should be active when loading an `ApplicationContext` for an -integration test. - -The following example indicates that the `dev` profile should be active: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @ActiveProfiles("dev") // <1> - class DeveloperTests { - // class body... - } ----- -<1> Indicate that the `dev` profile should be active. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @ActiveProfiles("dev") // <1> - class DeveloperTests { - // class body... - } ----- -<1> Indicate that the `dev` profile should be active. - - -The following example indicates that both the `dev` and the `integration` profiles should -be active: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @ActiveProfiles({"dev", "integration"}) // <1> - class DeveloperIntegrationTests { - // class body... - } ----- -<1> Indicate that the `dev` and `integration` profiles should be active. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @ActiveProfiles(["dev", "integration"]) // <1> - class DeveloperIntegrationTests { - // class body... - } ----- -<1> Indicate that the `dev` and `integration` profiles should be active. - - -NOTE: `@ActiveProfiles` provides support for inheriting active bean definition profiles -declared by superclasses and enclosing classes by default. You can also resolve active -bean definition profiles programmatically by implementing a custom -<<testcontext-ctx-management-env-profiles-ActiveProfilesResolver, `ActiveProfilesResolver`>> -and registering it by using the `resolver` attribute of `@ActiveProfiles`. - -See <<testcontext-ctx-management-env-profiles>>, -<<testcontext-junit-jupiter-nested-test-configuration>>, and the -{api-spring-framework}/test/context/ActiveProfiles.html[`@ActiveProfiles`] javadoc for -examples and further details. - -[[spring-testing-annotation-testpropertysource]] -=== `@TestPropertySource` - -`@TestPropertySource` is a class-level annotation that you can use to configure the -locations of properties files and inlined properties to be added to the set of -`PropertySources` in the `Environment` for an `ApplicationContext` loaded for an -integration test. - -The following example demonstrates how to declare a properties file from the classpath: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @TestPropertySource("/test.properties") // <1> - class MyIntegrationTests { - // class body... - } ----- -<1> Get properties from `test.properties` in the root of the classpath. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @TestPropertySource("/test.properties") // <1> - class MyIntegrationTests { - // class body... - } ----- -<1> Get properties from `test.properties` in the root of the classpath. - - -The following example demonstrates how to declare inlined properties: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @TestPropertySource(properties = { "timezone = GMT", "port: 4242" }) // <1> - class MyIntegrationTests { - // class body... - } ----- -<1> Declare `timezone` and `port` properties. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @TestPropertySource(properties = ["timezone = GMT", "port: 4242"]) // <1> - class MyIntegrationTests { - // class body... - } ----- -<1> Declare `timezone` and `port` properties. - -See <<testcontext-ctx-management-property-sources>> for examples and further details. - -[[spring-testing-annotation-dynamicpropertysource]] -=== `@DynamicPropertySource` - -`@DynamicPropertySource` is a method-level annotation that you can use to register -_dynamic_ properties to be added to the set of `PropertySources` in the `Environment` for -an `ApplicationContext` loaded for an integration test. Dynamic properties are useful -when you do not know the value of the properties upfront – for example, if the properties -are managed by an external resource such as for a container managed by the -https://www.testcontainers.org/[Testcontainers] project. - -The following example demonstrates how to register a dynamic property: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - class MyIntegrationTests { - - static MyExternalServer server = // ... - - @DynamicPropertySource // <1> - static void dynamicProperties(DynamicPropertyRegistry registry) { // <2> - registry.add("server.port", server::getPort); // <3> - } - - // tests ... - } ----- -<1> Annotate a `static` method with `@DynamicPropertySource`. -<2> Accept a `DynamicPropertyRegistry` as an argument. -<3> Register a dynamic `server.port` property to be retrieved lazily from the server. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - class MyIntegrationTests { - - companion object { - - @JvmStatic - val server: MyExternalServer = // ... - - @DynamicPropertySource // <1> - @JvmStatic - fun dynamicProperties(registry: DynamicPropertyRegistry) { // <2> - registry.add("server.port", server::getPort) // <3> - } - } - - // tests ... - } ----- -<1> Annotate a `static` method with `@DynamicPropertySource`. -<2> Accept a `DynamicPropertyRegistry` as an argument. -<3> Register a dynamic `server.port` property to be retrieved lazily from the server. - -See <<testcontext-ctx-management-dynamic-property-sources>> for further details. - -[[spring-testing-annotation-dirtiescontext]] -=== `@DirtiesContext` - -`@DirtiesContext` indicates that the underlying Spring `ApplicationContext` has been -dirtied during the execution of a test (that is, the test modified or corrupted it in -some manner -- for example, by changing the state of a singleton bean) and should be -closed. When an application context is marked as dirty, it is removed from the testing -framework's cache and closed. As a consequence, the underlying Spring container is -rebuilt for any subsequent test that requires a context with the same configuration -metadata. - -You can use `@DirtiesContext` as both a class-level and a method-level annotation within -the same class or class hierarchy. In such scenarios, the `ApplicationContext` is marked -as dirty before or after any such annotated method as well as before or after the current -test class, depending on the configured `methodMode` and `classMode`. - -The following examples explain when the context would be dirtied for various -configuration scenarios: - -* Before the current test class, when declared on a class with class mode set to -`BEFORE_CLASS`. -+ -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @DirtiesContext(classMode = BEFORE_CLASS) // <1> - class FreshContextTests { - // some tests that require a new Spring container - } ----- -<1> Dirty the context before the current test class. -+ -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @DirtiesContext(classMode = BEFORE_CLASS) // <1> - class FreshContextTests { - // some tests that require a new Spring container - } ----- -<1> Dirty the context before the current test class. - -* After the current test class, when declared on a class with class mode set to -`AFTER_CLASS` (i.e., the default class mode). -+ -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @DirtiesContext // <1> - class ContextDirtyingTests { - // some tests that result in the Spring container being dirtied - } ----- -<1> Dirty the context after the current test class. -+ -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @DirtiesContext // <1> - class ContextDirtyingTests { - // some tests that result in the Spring container being dirtied - } ----- -<1> Dirty the context after the current test class. - - -* Before each test method in the current test class, when declared on a class with class -mode set to `BEFORE_EACH_TEST_METHOD.` -+ -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @DirtiesContext(classMode = BEFORE_EACH_TEST_METHOD) // <1> - class FreshContextTests { - // some tests that require a new Spring container - } ----- -<1> Dirty the context before each test method. -+ -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @DirtiesContext(classMode = BEFORE_EACH_TEST_METHOD) // <1> - class FreshContextTests { - // some tests that require a new Spring container - } ----- -<1> Dirty the context before each test method. - - -* After each test method in the current test class, when declared on a class with class -mode set to `AFTER_EACH_TEST_METHOD.` -+ -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @DirtiesContext(classMode = AFTER_EACH_TEST_METHOD) // <1> - class ContextDirtyingTests { - // some tests that result in the Spring container being dirtied - } ----- -<1> Dirty the context after each test method. -+ -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @DirtiesContext(classMode = AFTER_EACH_TEST_METHOD) // <1> - class ContextDirtyingTests { - // some tests that result in the Spring container being dirtied - } ----- -<1> Dirty the context after each test method. - - -* Before the current test, when declared on a method with the method mode set to -`BEFORE_METHOD`. -+ -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @DirtiesContext(methodMode = BEFORE_METHOD) // <1> - @Test - void testProcessWhichRequiresFreshAppCtx() { - // some logic that requires a new Spring container - } ----- -<1> Dirty the context before the current test method. -+ -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @DirtiesContext(methodMode = BEFORE_METHOD) // <1> - @Test - fun testProcessWhichRequiresFreshAppCtx() { - // some logic that requires a new Spring container - } ----- -<1> Dirty the context before the current test method. - -* After the current test, when declared on a method with the method mode set to -`AFTER_METHOD` (i.e., the default method mode). -+ -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @DirtiesContext // <1> - @Test - void testProcessWhichDirtiesAppCtx() { - // some logic that results in the Spring container being dirtied - } ----- -<1> Dirty the context after the current test method. -+ -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @DirtiesContext // <1> - @Test - fun testProcessWhichDirtiesAppCtx() { - // some logic that results in the Spring container being dirtied - } ----- -<1> Dirty the context after the current test method. - - -If you use `@DirtiesContext` in a test whose context is configured as part of a context -hierarchy with `@ContextHierarchy`, you can use the `hierarchyMode` flag to control how -the context cache is cleared. By default, an exhaustive algorithm is used to clear the -context cache, including not only the current level but also all other context -hierarchies that share an ancestor context common to the current test. All -`ApplicationContext` instances that reside in a sub-hierarchy of the common ancestor -context are removed from the context cache and closed. If the exhaustive algorithm is -overkill for a particular use case, you can specify the simpler current level algorithm, -as the following example shows. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextHierarchy({ - @ContextConfiguration("/parent-config.xml"), - @ContextConfiguration("/child-config.xml") - }) - class BaseTests { - // class body... - } - - class ExtendedTests extends BaseTests { - - @Test - @DirtiesContext(hierarchyMode = CURRENT_LEVEL) // <1> - void test() { - // some logic that results in the child context being dirtied - } - } ----- -<1> Use the current-level algorithm. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextHierarchy( - ContextConfiguration("/parent-config.xml"), - ContextConfiguration("/child-config.xml")) - open class BaseTests { - // class body... - } - - class ExtendedTests : BaseTests() { - - @Test - @DirtiesContext(hierarchyMode = CURRENT_LEVEL) // <1> - fun test() { - // some logic that results in the child context being dirtied - } - } ----- -<1> Use the current-level algorithm. - - -For further details regarding the `EXHAUSTIVE` and `CURRENT_LEVEL` algorithms, see the -{api-spring-framework}/test/annotation/DirtiesContext.HierarchyMode.html[`DirtiesContext.HierarchyMode`] -javadoc. - -[[spring-testing-annotation-testexecutionlisteners]] -=== `@TestExecutionListeners` - -`@TestExecutionListeners` is used to register listeners for a particular test class, its -subclasses, and its nested classes. If you wish to register a listener globally, you -should register it via the automatic discovery mechanism described in -<<testcontext-tel-config>>. - -The following example shows how to register two `TestExecutionListener` implementations: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @TestExecutionListeners({CustomTestExecutionListener.class, AnotherTestExecutionListener.class}) // <1> - class CustomTestExecutionListenerTests { - // class body... - } ----- -<1> Register two `TestExecutionListener` implementations. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @TestExecutionListeners(CustomTestExecutionListener::class, AnotherTestExecutionListener::class) // <1> - class CustomTestExecutionListenerTests { - // class body... - } ----- -<1> Register two `TestExecutionListener` implementations. - - -By default, `@TestExecutionListeners` provides support for inheriting listeners from -superclasses or enclosing classes. See -<<testcontext-junit-jupiter-nested-test-configuration>> and the -{api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners` -javadoc] for an example and further details. If you discover that you need to switch -back to using the default `TestExecutionListener` implementations, see the note -in <<testcontext-tel-config-registering-tels>>. - -[[spring-testing-annotation-recordapplicationevents]] -=== `@RecordApplicationEvents` - -`@RecordApplicationEvents` is a class-level annotation that is used to instruct the -_Spring TestContext Framework_ to record all application events that are published in the -`ApplicationContext` during the execution of a single test. - -The recorded events can be accessed via the `ApplicationEvents` API within tests. - -See <<testcontext-application-events>> and the -{api-spring-framework}/test/context/event/RecordApplicationEvents.html[`@RecordApplicationEvents` -javadoc] for an example and further details. - -[[spring-testing-annotation-commit]] -=== `@Commit` - -`@Commit` indicates that the transaction for a transactional test method should be -committed after the test method has completed. You can use `@Commit` as a direct -replacement for `@Rollback(false)` to more explicitly convey the intent of the code. -Analogous to `@Rollback`, `@Commit` can also be declared as a class-level or method-level -annotation. - -The following example shows how to use the `@Commit` annotation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Commit // <1> - @Test - void testProcessWithoutRollback() { - // ... - } ----- -<1> Commit the result of the test to the database. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Commit // <1> - @Test - fun testProcessWithoutRollback() { - // ... - } ----- -<1> Commit the result of the test to the database. - - -[[spring-testing-annotation-rollback]] -=== `@Rollback` - -`@Rollback` indicates whether the transaction for a transactional test method should be -rolled back after the test method has completed. If `true`, the transaction is rolled -back. Otherwise, the transaction is committed (see also -<<spring-testing-annotation-commit>>). Rollback for integration tests in the Spring -TestContext Framework defaults to `true` even if `@Rollback` is not explicitly declared. - -When declared as a class-level annotation, `@Rollback` defines the default rollback -semantics for all test methods within the test class hierarchy. When declared as a -method-level annotation, `@Rollback` defines rollback semantics for the specific test -method, potentially overriding class-level `@Rollback` or `@Commit` semantics. - -The following example causes a test method's result to not be rolled back (that is, the -result is committed to the database): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Rollback(false) // <1> - @Test - void testProcessWithoutRollback() { - // ... - } ----- -<1> Do not roll back the result. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Rollback(false) // <1> - @Test - fun testProcessWithoutRollback() { - // ... - } ----- -<1> Do not roll back the result. - - -[[spring-testing-annotation-beforetransaction]] -=== `@BeforeTransaction` - -`@BeforeTransaction` indicates that the annotated `void` method should be run before a -transaction is started, for test methods that have been configured to run within a -transaction by using Spring's `@Transactional` annotation. `@BeforeTransaction` methods -are not required to be `public` and may be declared on Java 8-based interface default -methods. - -The following example shows how to use the `@BeforeTransaction` annotation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @BeforeTransaction // <1> - void beforeTransaction() { - // logic to be run before a transaction is started - } ----- -<1> Run this method before a transaction. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @BeforeTransaction // <1> - fun beforeTransaction() { - // logic to be run before a transaction is started - } ----- -<1> Run this method before a transaction. - - -[[spring-testing-annotation-aftertransaction]] -=== `@AfterTransaction` - -`@AfterTransaction` indicates that the annotated `void` method should be run after a -transaction is ended, for test methods that have been configured to run within a -transaction by using Spring's `@Transactional` annotation. `@AfterTransaction` methods -are not required to be `public` and may be declared on Java 8-based interface default -methods. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @AfterTransaction // <1> - void afterTransaction() { - // logic to be run after a transaction has ended - } ----- -<1> Run this method after a transaction. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @AfterTransaction // <1> - fun afterTransaction() { - // logic to be run after a transaction has ended - } ----- -<1> Run this method after a transaction. - - -[[spring-testing-annotation-sql]] -=== `@Sql` - -`@Sql` is used to annotate a test class or test method to configure SQL scripts to be run -against a given database during integration tests. The following example shows how to use -it: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Test - @Sql({"/test-schema.sql", "/test-user-data.sql"}) // <1> - void userTest() { - // run code that relies on the test schema and test data - } ----- -<1> Run two scripts for this test. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Test - @Sql("/test-schema.sql", "/test-user-data.sql") // <1> - fun userTest() { - // run code that relies on the test schema and test data - } ----- -<1> Run two scripts for this test. - -See <<testcontext-executing-sql-declaratively>> for further details. - - -[[spring-testing-annotation-sqlconfig]] -=== `@SqlConfig` - -`@SqlConfig` defines metadata that is used to determine how to parse and run SQL scripts -configured with the `@Sql` annotation. The following example shows how to use it: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Test - @Sql( - scripts = "/test-user-data.sql", - config = @SqlConfig(commentPrefix = "`", separator = "@@") // <1> - ) - void userTest() { - // run code that relies on the test data - } ----- -<1> Set the comment prefix and the separator in SQL scripts. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Test - @Sql("/test-user-data.sql", config = SqlConfig(commentPrefix = "`", separator = "@@")) // <1> - fun userTest() { - // run code that relies on the test data - } ----- -<1> Set the comment prefix and the separator in SQL scripts. - -[[spring-testing-annotation-sqlmergemode]] -=== `@SqlMergeMode` - -`@SqlMergeMode` is used to annotate a test class or test method to configure whether -method-level `@Sql` declarations are merged with class-level `@Sql` declarations. If -`@SqlMergeMode` is not declared on a test class or test method, the `OVERRIDE` merge mode -will be used by default. With the `OVERRIDE` mode, method-level `@Sql` declarations will -effectively override class-level `@Sql` declarations. - -Note that a method-level `@SqlMergeMode` declaration overrides a class-level declaration. - -The following example shows how to use `@SqlMergeMode` at the class level. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestConfig.class) - @Sql("/test-schema.sql") - @SqlMergeMode(MERGE) // <1> - class UserTests { - - @Test - @Sql("/user-test-data-001.sql") - void standardUserProfile() { - // run code that relies on test data set 001 - } - } ----- -<1> Set the `@Sql` merge mode to `MERGE` for all test methods in the class. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestConfig::class) - @Sql("/test-schema.sql") - @SqlMergeMode(MERGE) // <1> - class UserTests { - - @Test - @Sql("/user-test-data-001.sql") - fun standardUserProfile() { - // run code that relies on test data set 001 - } - } ----- -<1> Set the `@Sql` merge mode to `MERGE` for all test methods in the class. - -The following example shows how to use `@SqlMergeMode` at the method level. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestConfig.class) - @Sql("/test-schema.sql") - class UserTests { - - @Test - @Sql("/user-test-data-001.sql") - @SqlMergeMode(MERGE) // <1> - void standardUserProfile() { - // run code that relies on test data set 001 - } - } ----- -<1> Set the `@Sql` merge mode to `MERGE` for a specific test method. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestConfig::class) - @Sql("/test-schema.sql") - class UserTests { - - @Test - @Sql("/user-test-data-001.sql") - @SqlMergeMode(MERGE) // <1> - fun standardUserProfile() { - // run code that relies on test data set 001 - } - } ----- -<1> Set the `@Sql` merge mode to `MERGE` for a specific test method. - - -[[spring-testing-annotation-sqlgroup]] -=== `@SqlGroup` - -`@SqlGroup` is a container annotation that aggregates several `@Sql` annotations. You can -use `@SqlGroup` natively to declare several nested `@Sql` annotations, or you can use it -in conjunction with Java 8's support for repeatable annotations, where `@Sql` can be -declared several times on the same class or method, implicitly generating this container -annotation. The following example shows how to declare an SQL group: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Test - @SqlGroup({ // <1> - @Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")), - @Sql("/test-user-data.sql") - }) - void userTest() { - // run code that uses the test schema and test data - } ----- -<1> Declare a group of SQL scripts. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Test - @SqlGroup( // <1> - Sql("/test-schema.sql", config = SqlConfig(commentPrefix = "`")), - Sql("/test-user-data.sql")) - fun userTest() { - // run code that uses the test schema and test data - } ----- -<1> Declare a group of SQL scripts. - - - -[[integration-testing-annotations-junit4]] -== Spring JUnit 4 Testing Annotations - -The following annotations are supported only when used in conjunction with the -<<testcontext-junit4-runner, SpringRunner>>, <<testcontext-junit4-rules, Spring's JUnit 4 -rules>>, or <<testcontext-support-classes-junit4, Spring's JUnit 4 support classes>>: - -* <<integration-testing-annotations-junit4-ifprofilevalue>> -* <<integration-testing-annotations-junit4-profilevaluesourceconfiguration>> -* <<integration-testing-annotations-junit4-timed>> -* <<integration-testing-annotations-junit4-repeat>> - -[[integration-testing-annotations-junit4-ifprofilevalue]] -=== `@IfProfileValue` - -`@IfProfileValue` indicates that the annotated test is enabled for a specific testing -environment. If the configured `ProfileValueSource` returns a matching `value` for the -provided `name`, the test is enabled. Otherwise, the test is disabled and, effectively, -ignored. - -You can apply `@IfProfileValue` at the class level, the method level, or both. -Class-level usage of `@IfProfileValue` takes precedence over method-level usage for any -methods within that class or its subclasses. Specifically, a test is enabled if it is -enabled both at the class level and at the method level. The absence of `@IfProfileValue` -means the test is implicitly enabled. This is analogous to the semantics of JUnit 4's -`@Ignore` annotation, except that the presence of `@Ignore` always disables a test. - -The following example shows a test that has an `@IfProfileValue` annotation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @IfProfileValue(name="java.vendor", value="Oracle Corporation") // <1> - @Test - public void testProcessWhichRunsOnlyOnOracleJvm() { - // some logic that should run only on Java VMs from Oracle Corporation - } ----- -<1> Run this test only when the Java vendor is "Oracle Corporation". - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @IfProfileValue(name="java.vendor", value="Oracle Corporation") // <1> - @Test - fun testProcessWhichRunsOnlyOnOracleJvm() { - // some logic that should run only on Java VMs from Oracle Corporation - } ----- -<1> Run this test only when the Java vendor is "Oracle Corporation". - - -Alternatively, you can configure `@IfProfileValue` with a list of `values` (with `OR` -semantics) to achieve TestNG-like support for test groups in a JUnit 4 environment. -Consider the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @IfProfileValue(name="test-groups", values={"unit-tests", "integration-tests"}) // <1> - @Test - public void testProcessWhichRunsForUnitOrIntegrationTestGroups() { - // some logic that should run only for unit and integration test groups - } ----- -<1> Run this test for unit tests and integration tests. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @IfProfileValue(name="test-groups", values=["unit-tests", "integration-tests"]) // <1> - @Test - fun testProcessWhichRunsForUnitOrIntegrationTestGroups() { - // some logic that should run only for unit and integration test groups - } ----- -<1> Run this test for unit tests and integration tests. - - -[[integration-testing-annotations-junit4-profilevaluesourceconfiguration]] -=== `@ProfileValueSourceConfiguration` - -`@ProfileValueSourceConfiguration` is a class-level annotation that specifies what type -of `ProfileValueSource` to use when retrieving profile values configured through the -`@IfProfileValue` annotation. If `@ProfileValueSourceConfiguration` is not declared for a -test, `SystemProfileValueSource` is used by default. The following example shows how to -use `@ProfileValueSourceConfiguration`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ProfileValueSourceConfiguration(CustomProfileValueSource.class) // <1> - public class CustomProfileValueSourceTests { - // class body... - } ----- -<1> Use a custom profile value source. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ProfileValueSourceConfiguration(CustomProfileValueSource::class) // <1> - class CustomProfileValueSourceTests { - // class body... - } ----- -<1> Use a custom profile value source. - - -[[integration-testing-annotations-junit4-timed]] -=== `@Timed` - -`@Timed` indicates that the annotated test method must finish execution in a specified -time period (in milliseconds). If the text execution time exceeds the specified time -period, the test fails. - -The time period includes running the test method itself, any repetitions of the test (see -`@Repeat`), as well as any setting up or tearing down of the test fixture. The following -example shows how to use it: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Timed(millis = 1000) // <1> - public void testProcessWithOneSecondTimeout() { - // some logic that should not take longer than 1 second to run - } ----- -<1> Set the time period for the test to one second. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Timed(millis = 1000) // <1> - fun testProcessWithOneSecondTimeout() { - // some logic that should not take longer than 1 second to run - } ----- -<1> Set the time period for the test to one second. - - -Spring's `@Timed` annotation has different semantics than JUnit 4's `@Test(timeout=...)` -support. Specifically, due to the manner in which JUnit 4 handles test execution timeouts -(that is, by executing the test method in a separate `Thread`), `@Test(timeout=...)` -preemptively fails the test if the test takes too long. Spring's `@Timed`, on the other -hand, does not preemptively fail the test but rather waits for the test to complete -before failing. - -[[integration-testing-annotations-junit4-repeat]] -=== `@Repeat` - -`@Repeat` indicates that the annotated test method must be run repeatedly. The number of -times that the test method is to be run is specified in the annotation. - -The scope of execution to be repeated includes execution of the test method itself as -well as any setting up or tearing down of the test fixture. When used with the -<<testcontext-junit4-rules, `SpringMethodRule`>>, the scope additionally includes -preparation of the test instance by `TestExecutionListener` implementations. The -following example shows how to use the `@Repeat` annotation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Repeat(10) // <1> - @Test - public void testProcessRepeatedly() { - // ... - } ----- -<1> Repeat this test ten times. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Repeat(10) // <1> - @Test - fun testProcessRepeatedly() { - // ... - } ----- -<1> Repeat this test ten times. - - - -[[integration-testing-annotations-junit-jupiter]] -== Spring JUnit Jupiter Testing Annotations - -The following annotations are supported when used in conjunction with the -<<testcontext-junit-jupiter-extension, `SpringExtension`>> and JUnit Jupiter -(that is, the programming model in JUnit 5): - -* <<integration-testing-annotations-junit-jupiter-springjunitconfig>> -* <<integration-testing-annotations-junit-jupiter-springjunitwebconfig>> -* <<integration-testing-annotations-testconstructor>> -* <<integration-testing-annotations-nestedtestconfiguration>> -* <<integration-testing-annotations-junit-jupiter-enabledif>> -* <<integration-testing-annotations-junit-jupiter-disabledif>> - -[[integration-testing-annotations-junit-jupiter-springjunitconfig]] -=== `@SpringJUnitConfig` - -`@SpringJUnitConfig` is a composed annotation that combines -`@ExtendWith(SpringExtension.class)` from JUnit Jupiter with `@ContextConfiguration` from -the Spring TestContext Framework. It can be used at the class level as a drop-in -replacement for `@ContextConfiguration`. With regard to configuration options, the only -difference between `@ContextConfiguration` and `@SpringJUnitConfig` is that component -classes may be declared with the `value` attribute in `@SpringJUnitConfig`. - -The following example shows how to use the `@SpringJUnitConfig` annotation to specify a -configuration class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestConfig.class) // <1> - class ConfigurationClassJUnitJupiterSpringTests { - // class body... - } ----- -<1> Specify the configuration class. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestConfig::class) // <1> - class ConfigurationClassJUnitJupiterSpringTests { - // class body... - } ----- -<1> Specify the configuration class. - - -The following example shows how to use the `@SpringJUnitConfig` annotation to specify the -location of a configuration file: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(locations = "/test-config.xml") // <1> - class XmlJUnitJupiterSpringTests { - // class body... - } ----- -<1> Specify the location of a configuration file. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(locations = ["/test-config.xml"]) // <1> - class XmlJUnitJupiterSpringTests { - // class body... - } ----- -<1> Specify the location of a configuration file. - - -See <<testcontext-ctx-management>> as well as the javadoc for -{api-spring-framework}/test/context/junit/jupiter/SpringJUnitConfig.html[`@SpringJUnitConfig`] -and `@ContextConfiguration` for further details. - -[[integration-testing-annotations-junit-jupiter-springjunitwebconfig]] -=== `@SpringJUnitWebConfig` - -`@SpringJUnitWebConfig` is a composed annotation that combines -`@ExtendWith(SpringExtension.class)` from JUnit Jupiter with `@ContextConfiguration` and -`@WebAppConfiguration` from the Spring TestContext Framework. You can use it at the class -level as a drop-in replacement for `@ContextConfiguration` and `@WebAppConfiguration`. -With regard to configuration options, the only difference between `@ContextConfiguration` -and `@SpringJUnitWebConfig` is that you can declare component classes by using the -`value` attribute in `@SpringJUnitWebConfig`. In addition, you can override the `value` -attribute from `@WebAppConfiguration` only by using the `resourcePath` attribute in -`@SpringJUnitWebConfig`. - -The following example shows how to use the `@SpringJUnitWebConfig` annotation to specify -a configuration class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitWebConfig(TestConfig.class) // <1> - class ConfigurationClassJUnitJupiterSpringWebTests { - // class body... - } ----- -<1> Specify the configuration class. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitWebConfig(TestConfig::class) // <1> - class ConfigurationClassJUnitJupiterSpringWebTests { - // class body... - } ----- -<1> Specify the configuration class. - - -The following example shows how to use the `@SpringJUnitWebConfig` annotation to specify the -location of a configuration file: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitWebConfig(locations = "/test-config.xml") // <1> - class XmlJUnitJupiterSpringWebTests { - // class body... - } ----- -<1> Specify the location of a configuration file. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitWebConfig(locations = ["/test-config.xml"]) // <1> - class XmlJUnitJupiterSpringWebTests { - // class body... - } ----- -<1> Specify the location of a configuration file. - - -See <<testcontext-ctx-management>> as well as the javadoc for -{api-spring-framework}/test/context/junit/jupiter/web/SpringJUnitWebConfig.html[`@SpringJUnitWebConfig`], -{api-spring-framework}/test/context/ContextConfiguration.html[`@ContextConfiguration`], and -{api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`] -for further details. - -[[integration-testing-annotations-testconstructor]] -=== `@TestConstructor` - -`@TestConstructor` is a type-level annotation that is used to configure how the parameters -of a test class constructor are autowired from components in the test's -`ApplicationContext`. - -If `@TestConstructor` is not present or meta-present on a test class, the default _test -constructor autowire mode_ will be used. See the tip below for details on how to change -the default mode. Note, however, that a local declaration of `@Autowired` on a -constructor takes precedence over both `@TestConstructor` and the default mode. - -.Changing the default test constructor autowire mode -[TIP] -===== -The default _test constructor autowire mode_ can be changed by setting the -`spring.test.constructor.autowire.mode` JVM system property to `all`. Alternatively, the -default mode may be set via the -<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism. - -As of Spring Framework 5.3, the default mode may also be configured as a -https://junit.org/junit5/docs/current/user-guide/#running-tests-config-params[JUnit Platform configuration parameter]. - -If the `spring.test.constructor.autowire.mode` property is not set, test class -constructors will not be automatically autowired. -===== - -NOTE: As of Spring Framework 5.2, `@TestConstructor` is only supported in conjunction -with the `SpringExtension` for use with JUnit Jupiter. Note that the `SpringExtension` is -often automatically registered for you – for example, when using annotations such as -`@SpringJUnitConfig` and `@SpringJUnitWebConfig` or various test-related annotations from -Spring Boot Test. - -[[integration-testing-annotations-nestedtestconfiguration]] -=== `@NestedTestConfiguration` - -`@NestedTestConfiguration` is a type-level annotation that is used to configure how -Spring test configuration annotations are processed within enclosing class hierarchies -for inner test classes. - -If `@NestedTestConfiguration` is not present or meta-present on a test class, in its -supertype hierarchy, or in its enclosing class hierarchy, the default _enclosing -configuration inheritance mode_ will be used. See the tip below for details on how to -change the default mode. - -.Changing the default enclosing configuration inheritance mode -[TIP] -===== -The default _enclosing configuration inheritance mode_ is `INHERIT`, but it can be -changed by setting the `spring.test.enclosing.configuration` JVM system property to -`OVERRIDE`. Alternatively, the default mode may be set via the -<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism. -===== - -The <<testcontext-framework>> honors `@NestedTestConfiguration` semantics for the -following annotations. - -* <<spring-testing-annotation-bootstrapwith>> -* <<spring-testing-annotation-contextconfiguration>> -* <<spring-testing-annotation-webappconfiguration>> -* <<spring-testing-annotation-contexthierarchy>> -* <<spring-testing-annotation-activeprofiles>> -* <<spring-testing-annotation-testpropertysource>> -* <<spring-testing-annotation-dynamicpropertysource>> -* <<spring-testing-annotation-dirtiescontext>> -* <<spring-testing-annotation-testexecutionlisteners>> -* <<spring-testing-annotation-recordapplicationevents>> -* <<testcontext-tx,`@Transactional`>> -* <<spring-testing-annotation-commit>> -* <<spring-testing-annotation-rollback>> -* <<spring-testing-annotation-sql>> -* <<spring-testing-annotation-sqlconfig>> -* <<spring-testing-annotation-sqlmergemode>> -* <<integration-testing-annotations-testconstructor>> - -NOTE: The use of `@NestedTestConfiguration` typically only makes sense in conjunction -with `@Nested` test classes in JUnit Jupiter; however, there may be other testing -frameworks with support for Spring and nested test classes that make use of this -annotation. - -See <<testcontext-junit-jupiter-nested-test-configuration>> for an example and further -details. - -[[integration-testing-annotations-junit-jupiter-enabledif]] -=== `@EnabledIf` - -`@EnabledIf` is used to signal that the annotated JUnit Jupiter test class or test method -is enabled and should be run if the supplied `expression` evaluates to `true`. -Specifically, if the expression evaluates to `Boolean.TRUE` or a `String` equal to `true` -(ignoring case), the test is enabled. When applied at the class level, all test methods -within that class are automatically enabled by default as well. - -Expressions can be any of the following: - -* <<core.adoc#expressions, Spring Expression Language>> (SpEL) expression. For example: - `@EnabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")` -* Placeholder for a property available in the Spring <<core.adoc#beans-environment, `Environment`>>. - For example: `@EnabledIf("${smoke.tests.enabled}")` -* Text literal. For example: `@EnabledIf("true")` - -Note, however, that a text literal that is not the result of dynamic resolution of a -property placeholder is of zero practical value, since `@EnabledIf("false")` is -equivalent to `@Disabled` and `@EnabledIf("true")` is logically meaningless. - -You can use `@EnabledIf` as a meta-annotation to create custom composed annotations. For -example, you can create a custom `@EnabledOnMac` annotation as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target({ElementType.TYPE, ElementType.METHOD}) - @Retention(RetentionPolicy.RUNTIME) - @EnabledIf( - expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}", - reason = "Enabled on Mac OS" - ) - public @interface EnabledOnMac {} ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION) - @Retention(AnnotationRetention.RUNTIME) - @EnabledIf( - expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}", - reason = "Enabled on Mac OS" - ) - annotation class EnabledOnMac {} ----- - -[NOTE] -==== -`@EnabledOnMac` is meant only as an example of what is possible. If you have that exact -use case, please use the built-in `@EnabledOnOs(MAC)` support in JUnit Jupiter. -==== - -[WARNING] -==== -Since JUnit 5.7, JUnit Jupiter also has a condition annotation named `@EnabledIf`. Thus, -if you wish to use Spring's `@EnabledIf` support make sure you import the annotation type -from the correct package. -==== - -[[integration-testing-annotations-junit-jupiter-disabledif]] -=== `@DisabledIf` - -`@DisabledIf` is used to signal that the annotated JUnit Jupiter test class or test -method is disabled and should not be run if the supplied `expression` evaluates to -`true`. Specifically, if the expression evaluates to `Boolean.TRUE` or a `String` equal -to `true` (ignoring case), the test is disabled. When applied at the class level, all -test methods within that class are automatically disabled as well. - -Expressions can be any of the following: - -* <<core.adoc#expressions, Spring Expression Language>> (SpEL) expression. For example: - `@DisabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")` -* Placeholder for a property available in the Spring <<core.adoc#beans-environment, `Environment`>>. - For example: `@DisabledIf("${smoke.tests.disabled}")` -* Text literal. For example: `@DisabledIf("true")` - -Note, however, that a text literal that is not the result of dynamic resolution of a -property placeholder is of zero practical value, since `@DisabledIf("true")` is -equivalent to `@Disabled` and `@DisabledIf("false")` is logically meaningless. - -You can use `@DisabledIf` as a meta-annotation to create custom composed annotations. For -example, you can create a custom `@DisabledOnMac` annotation as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target({ElementType.TYPE, ElementType.METHOD}) - @Retention(RetentionPolicy.RUNTIME) - @DisabledIf( - expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}", - reason = "Disabled on Mac OS" - ) - public @interface DisabledOnMac {} ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION) - @Retention(AnnotationRetention.RUNTIME) - @DisabledIf( - expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}", - reason = "Disabled on Mac OS" - ) - annotation class DisabledOnMac {} ----- - -[NOTE] -==== -`@DisabledOnMac` is meant only as an example of what is possible. If you have that exact -use case, please use the built-in `@DisabledOnOs(MAC)` support in JUnit Jupiter. -==== - -[WARNING] -==== -Since JUnit 5.7, JUnit Jupiter also has a condition annotation named `@DisabledIf`. Thus, -if you wish to use Spring's `@DisabledIf` support make sure you import the annotation type -from the correct package. -==== - - - -[[integration-testing-annotations-meta]] -== Meta-Annotation Support for Testing - -You can use most test-related annotations as -<<core.adoc#beans-meta-annotations, meta-annotations>> to create custom composed -annotations and reduce configuration duplication across a test suite. - -You can use each of the following as a meta-annotation in conjunction with the -<<testcontext-framework, TestContext framework>>. - -* `@BootstrapWith` -* `@ContextConfiguration` -* `@ContextHierarchy` -* `@ActiveProfiles` -* `@TestPropertySource` -* `@DirtiesContext` -* `@WebAppConfiguration` -* `@TestExecutionListeners` -* `@Transactional` -* `@BeforeTransaction` -* `@AfterTransaction` -* `@Commit` -* `@Rollback` -* `@Sql` -* `@SqlConfig` -* `@SqlMergeMode` -* `@SqlGroup` -* `@Repeat` _(only supported on JUnit 4)_ -* `@Timed` _(only supported on JUnit 4)_ -* `@IfProfileValue` _(only supported on JUnit 4)_ -* `@ProfileValueSourceConfiguration` _(only supported on JUnit 4)_ -* `@SpringJUnitConfig` _(only supported on JUnit Jupiter)_ -* `@SpringJUnitWebConfig` _(only supported on JUnit Jupiter)_ -* `@TestConstructor` _(only supported on JUnit Jupiter)_ -* `@NestedTestConfiguration` _(only supported on JUnit Jupiter)_ -* `@EnabledIf` _(only supported on JUnit Jupiter)_ -* `@DisabledIf` _(only supported on JUnit Jupiter)_ - -Consider the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RunWith(SpringRunner.class) - @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) - @ActiveProfiles("dev") - @Transactional - public class OrderRepositoryTests { } - - @RunWith(SpringRunner.class) - @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) - @ActiveProfiles("dev") - @Transactional - public class UserRepositoryTests { } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RunWith(SpringRunner::class) - @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") - @ActiveProfiles("dev") - @Transactional - class OrderRepositoryTests { } - - @RunWith(SpringRunner::class) - @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") - @ActiveProfiles("dev") - @Transactional - class UserRepositoryTests { } ----- - -If we discover that we are repeating the preceding configuration across our JUnit 4-based -test suite, we can reduce the duplication by introducing a custom composed annotation -that centralizes the common test configuration for Spring, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target(ElementType.TYPE) - @Retention(RetentionPolicy.RUNTIME) - @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) - @ActiveProfiles("dev") - @Transactional - public @interface TransactionalDevTestConfig { } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.TYPE) - @Retention(AnnotationRetention.RUNTIME) - @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") - @ActiveProfiles("dev") - @Transactional - annotation class TransactionalDevTestConfig { } ----- - -Then we can use our custom `@TransactionalDevTestConfig` annotation to simplify the -configuration of individual JUnit 4 based test classes, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RunWith(SpringRunner.class) - @TransactionalDevTestConfig - public class OrderRepositoryTests { } - - @RunWith(SpringRunner.class) - @TransactionalDevTestConfig - public class UserRepositoryTests { } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RunWith(SpringRunner::class) - @TransactionalDevTestConfig - class OrderRepositoryTests - - @RunWith(SpringRunner::class) - @TransactionalDevTestConfig - class UserRepositoryTests ----- - -If we write tests that use JUnit Jupiter, we can reduce code duplication even further, -since annotations in JUnit 5 can also be used as meta-annotations. Consider the following -example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) - @ActiveProfiles("dev") - @Transactional - class OrderRepositoryTests { } - - @ExtendWith(SpringExtension.class) - @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) - @ActiveProfiles("dev") - @Transactional - class UserRepositoryTests { } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") - @ActiveProfiles("dev") - @Transactional - class OrderRepositoryTests { } - - @ExtendWith(SpringExtension::class) - @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") - @ActiveProfiles("dev") - @Transactional - class UserRepositoryTests { } ----- - -If we discover that we are repeating the preceding configuration across our JUnit -Jupiter-based test suite, we can reduce the duplication by introducing a custom composed -annotation that centralizes the common test configuration for Spring and JUnit Jupiter, -as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target(ElementType.TYPE) - @Retention(RetentionPolicy.RUNTIME) - @ExtendWith(SpringExtension.class) - @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) - @ActiveProfiles("dev") - @Transactional - public @interface TransactionalDevTestConfig { } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.TYPE) - @Retention(AnnotationRetention.RUNTIME) - @ExtendWith(SpringExtension::class) - @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") - @ActiveProfiles("dev") - @Transactional - annotation class TransactionalDevTestConfig { } ----- - -Then we can use our custom `@TransactionalDevTestConfig` annotation to simplify the -configuration of individual JUnit Jupiter based test classes, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @TransactionalDevTestConfig - class OrderRepositoryTests { } - - @TransactionalDevTestConfig - class UserRepositoryTests { } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @TransactionalDevTestConfig - class OrderRepositoryTests { } - - @TransactionalDevTestConfig - class UserRepositoryTests { } ----- - -Since JUnit Jupiter supports the use of `@Test`, `@RepeatedTest`, `ParameterizedTest`, -and others as meta-annotations, you can also create custom composed annotations at the -test method level. For example, if we wish to create a composed annotation that combines -the `@Test` and `@Tag` annotations from JUnit Jupiter with the `@Transactional` -annotation from Spring, we could create an `@TransactionalIntegrationTest` annotation, as -follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target(ElementType.METHOD) - @Retention(RetentionPolicy.RUNTIME) - @Transactional - @Tag("integration-test") // org.junit.jupiter.api.Tag - @Test // org.junit.jupiter.api.Test - public @interface TransactionalIntegrationTest { } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.TYPE) - @Retention(AnnotationRetention.RUNTIME) - @Transactional - @Tag("integration-test") // org.junit.jupiter.api.Tag - @Test // org.junit.jupiter.api.Test - annotation class TransactionalIntegrationTest { } ----- - -Then we can use our custom `@TransactionalIntegrationTest` annotation to simplify the -configuration of individual JUnit Jupiter based test methods, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @TransactionalIntegrationTest - void saveOrder() { } - - @TransactionalIntegrationTest - void deleteOrder() { } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @TransactionalIntegrationTest - fun saveOrder() { } - - @TransactionalIntegrationTest - fun deleteOrder() { } ----- - -For further details, see the -https://github.com/spring-projects/spring-framework/wiki/Spring-Annotation-Programming-Model[Spring Annotation Programming Model] -wiki page. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc new file mode 100644 index 000000000000..bc53256f22a3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc @@ -0,0 +1,349 @@ +[[integration-testing-annotations-junit-jupiter]] += Spring JUnit Jupiter Testing Annotations + +The following annotations are supported when used in conjunction with the +<<testcontext-junit-jupiter-extension, `SpringExtension`>> and JUnit Jupiter +(that is, the programming model in JUnit 5): + +* <<integration-testing-annotations-junit-jupiter-springjunitconfig>> +* <<integration-testing-annotations-junit-jupiter-springjunitwebconfig>> +* <<integration-testing-annotations-testconstructor>> +* <<integration-testing-annotations-nestedtestconfiguration>> +* <<integration-testing-annotations-junit-jupiter-enabledif>> +* <<integration-testing-annotations-junit-jupiter-disabledif>> + +[[integration-testing-annotations-junit-jupiter-springjunitconfig]] +== `@SpringJUnitConfig` + +`@SpringJUnitConfig` is a composed annotation that combines +`@ExtendWith(SpringExtension.class)` from JUnit Jupiter with `@ContextConfiguration` from +the Spring TestContext Framework. It can be used at the class level as a drop-in +replacement for `@ContextConfiguration`. With regard to configuration options, the only +difference between `@ContextConfiguration` and `@SpringJUnitConfig` is that component +classes may be declared with the `value` attribute in `@SpringJUnitConfig`. + +The following example shows how to use the `@SpringJUnitConfig` annotation to specify a +configuration class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestConfig.class) // <1> + class ConfigurationClassJUnitJupiterSpringTests { + // class body... + } +---- +<1> Specify the configuration class. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestConfig::class) // <1> + class ConfigurationClassJUnitJupiterSpringTests { + // class body... + } +---- +<1> Specify the configuration class. + + +The following example shows how to use the `@SpringJUnitConfig` annotation to specify the +location of a configuration file: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(locations = "/test-config.xml") // <1> + class XmlJUnitJupiterSpringTests { + // class body... + } +---- +<1> Specify the location of a configuration file. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(locations = ["/test-config.xml"]) // <1> + class XmlJUnitJupiterSpringTests { + // class body... + } +---- +<1> Specify the location of a configuration file. + + +See <<testcontext-ctx-management>> as well as the javadoc for +{api-spring-framework}/test/context/junit/jupiter/SpringJUnitConfig.html[`@SpringJUnitConfig`] +and `@ContextConfiguration` for further details. + +[[integration-testing-annotations-junit-jupiter-springjunitwebconfig]] +== `@SpringJUnitWebConfig` + +`@SpringJUnitWebConfig` is a composed annotation that combines +`@ExtendWith(SpringExtension.class)` from JUnit Jupiter with `@ContextConfiguration` and +`@WebAppConfiguration` from the Spring TestContext Framework. You can use it at the class +level as a drop-in replacement for `@ContextConfiguration` and `@WebAppConfiguration`. +With regard to configuration options, the only difference between `@ContextConfiguration` +and `@SpringJUnitWebConfig` is that you can declare component classes by using the +`value` attribute in `@SpringJUnitWebConfig`. In addition, you can override the `value` +attribute from `@WebAppConfiguration` only by using the `resourcePath` attribute in +`@SpringJUnitWebConfig`. + +The following example shows how to use the `@SpringJUnitWebConfig` annotation to specify +a configuration class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitWebConfig(TestConfig.class) // <1> + class ConfigurationClassJUnitJupiterSpringWebTests { + // class body... + } +---- +<1> Specify the configuration class. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitWebConfig(TestConfig::class) // <1> + class ConfigurationClassJUnitJupiterSpringWebTests { + // class body... + } +---- +<1> Specify the configuration class. + + +The following example shows how to use the `@SpringJUnitWebConfig` annotation to specify the +location of a configuration file: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitWebConfig(locations = "/test-config.xml") // <1> + class XmlJUnitJupiterSpringWebTests { + // class body... + } +---- +<1> Specify the location of a configuration file. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitWebConfig(locations = ["/test-config.xml"]) // <1> + class XmlJUnitJupiterSpringWebTests { + // class body... + } +---- +<1> Specify the location of a configuration file. + + +See <<testcontext-ctx-management>> as well as the javadoc for +{api-spring-framework}/test/context/junit/jupiter/web/SpringJUnitWebConfig.html[`@SpringJUnitWebConfig`], +{api-spring-framework}/test/context/ContextConfiguration.html[`@ContextConfiguration`], and +{api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`] +for further details. + +[[integration-testing-annotations-testconstructor]] +== `@TestConstructor` + +`@TestConstructor` is a type-level annotation that is used to configure how the parameters +of a test class constructor are autowired from components in the test's +`ApplicationContext`. + +If `@TestConstructor` is not present or meta-present on a test class, the default _test +constructor autowire mode_ will be used. See the tip below for details on how to change +the default mode. Note, however, that a local declaration of `@Autowired` on a +constructor takes precedence over both `@TestConstructor` and the default mode. + +.Changing the default test constructor autowire mode +[TIP] +===== +The default _test constructor autowire mode_ can be changed by setting the +`spring.test.constructor.autowire.mode` JVM system property to `all`. Alternatively, the +default mode may be set via the +<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism. + +As of Spring Framework 5.3, the default mode may also be configured as a +https://junit.org/junit5/docs/current/user-guide/#running-tests-config-params[JUnit Platform configuration parameter]. + +If the `spring.test.constructor.autowire.mode` property is not set, test class +constructors will not be automatically autowired. +===== + +NOTE: As of Spring Framework 5.2, `@TestConstructor` is only supported in conjunction +with the `SpringExtension` for use with JUnit Jupiter. Note that the `SpringExtension` is +often automatically registered for you – for example, when using annotations such as +`@SpringJUnitConfig` and `@SpringJUnitWebConfig` or various test-related annotations from +Spring Boot Test. + +[[integration-testing-annotations-nestedtestconfiguration]] +== `@NestedTestConfiguration` + +`@NestedTestConfiguration` is a type-level annotation that is used to configure how +Spring test configuration annotations are processed within enclosing class hierarchies +for inner test classes. + +If `@NestedTestConfiguration` is not present or meta-present on a test class, in its +supertype hierarchy, or in its enclosing class hierarchy, the default _enclosing +configuration inheritance mode_ will be used. See the tip below for details on how to +change the default mode. + +.Changing the default enclosing configuration inheritance mode +[TIP] +===== +The default _enclosing configuration inheritance mode_ is `INHERIT`, but it can be +changed by setting the `spring.test.enclosing.configuration` JVM system property to +`OVERRIDE`. Alternatively, the default mode may be set via the +<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism. +===== + +The <<testcontext-framework>> honors `@NestedTestConfiguration` semantics for the +following annotations. + +* <<spring-testing-annotation-bootstrapwith>> +* <<spring-testing-annotation-contextconfiguration>> +* <<spring-testing-annotation-webappconfiguration>> +* <<spring-testing-annotation-contexthierarchy>> +* <<spring-testing-annotation-activeprofiles>> +* <<spring-testing-annotation-testpropertysource>> +* <<spring-testing-annotation-dynamicpropertysource>> +* <<spring-testing-annotation-dirtiescontext>> +* <<spring-testing-annotation-testexecutionlisteners>> +* <<spring-testing-annotation-recordapplicationevents>> +* <<testcontext-tx,`@Transactional`>> +* <<spring-testing-annotation-commit>> +* <<spring-testing-annotation-rollback>> +* <<spring-testing-annotation-sql>> +* <<spring-testing-annotation-sqlconfig>> +* <<spring-testing-annotation-sqlmergemode>> +* <<integration-testing-annotations-testconstructor>> + +NOTE: The use of `@NestedTestConfiguration` typically only makes sense in conjunction +with `@Nested` test classes in JUnit Jupiter; however, there may be other testing +frameworks with support for Spring and nested test classes that make use of this +annotation. + +See <<testcontext-junit-jupiter-nested-test-configuration>> for an example and further +details. + +[[integration-testing-annotations-junit-jupiter-enabledif]] +== `@EnabledIf` + +`@EnabledIf` is used to signal that the annotated JUnit Jupiter test class or test method +is enabled and should be run if the supplied `expression` evaluates to `true`. +Specifically, if the expression evaluates to `Boolean.TRUE` or a `String` equal to `true` +(ignoring case), the test is enabled. When applied at the class level, all test methods +within that class are automatically enabled by default as well. + +Expressions can be any of the following: + +* <<core.adoc#expressions, Spring Expression Language>> (SpEL) expression. For example: + `@EnabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")` +* Placeholder for a property available in the Spring <<core.adoc#beans-environment, `Environment`>>. + For example: `@EnabledIf("${smoke.tests.enabled}")` +* Text literal. For example: `@EnabledIf("true")` + +Note, however, that a text literal that is not the result of dynamic resolution of a +property placeholder is of zero practical value, since `@EnabledIf("false")` is +equivalent to `@Disabled` and `@EnabledIf("true")` is logically meaningless. + +You can use `@EnabledIf` as a meta-annotation to create custom composed annotations. For +example, you can create a custom `@EnabledOnMac` annotation as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target({ElementType.TYPE, ElementType.METHOD}) + @Retention(RetentionPolicy.RUNTIME) + @EnabledIf( + expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}", + reason = "Enabled on Mac OS" + ) + public @interface EnabledOnMac {} +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION) + @Retention(AnnotationRetention.RUNTIME) + @EnabledIf( + expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}", + reason = "Enabled on Mac OS" + ) + annotation class EnabledOnMac {} +---- + +[NOTE] +==== +`@EnabledOnMac` is meant only as an example of what is possible. If you have that exact +use case, please use the built-in `@EnabledOnOs(MAC)` support in JUnit Jupiter. +==== + +[WARNING] +==== +Since JUnit 5.7, JUnit Jupiter also has a condition annotation named `@EnabledIf`. Thus, +if you wish to use Spring's `@EnabledIf` support make sure you import the annotation type +from the correct package. +==== + +[[integration-testing-annotations-junit-jupiter-disabledif]] +== `@DisabledIf` + +`@DisabledIf` is used to signal that the annotated JUnit Jupiter test class or test +method is disabled and should not be run if the supplied `expression` evaluates to +`true`. Specifically, if the expression evaluates to `Boolean.TRUE` or a `String` equal +to `true` (ignoring case), the test is disabled. When applied at the class level, all +test methods within that class are automatically disabled as well. + +Expressions can be any of the following: + +* <<core.adoc#expressions, Spring Expression Language>> (SpEL) expression. For example: + `@DisabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")` +* Placeholder for a property available in the Spring <<core.adoc#beans-environment, `Environment`>>. + For example: `@DisabledIf("${smoke.tests.disabled}")` +* Text literal. For example: `@DisabledIf("true")` + +Note, however, that a text literal that is not the result of dynamic resolution of a +property placeholder is of zero practical value, since `@DisabledIf("true")` is +equivalent to `@Disabled` and `@DisabledIf("false")` is logically meaningless. + +You can use `@DisabledIf` as a meta-annotation to create custom composed annotations. For +example, you can create a custom `@DisabledOnMac` annotation as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target({ElementType.TYPE, ElementType.METHOD}) + @Retention(RetentionPolicy.RUNTIME) + @DisabledIf( + expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}", + reason = "Disabled on Mac OS" + ) + public @interface DisabledOnMac {} +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION) + @Retention(AnnotationRetention.RUNTIME) + @DisabledIf( + expression = "#{systemProperties['os.name'].toLowerCase().contains('mac')}", + reason = "Disabled on Mac OS" + ) + annotation class DisabledOnMac {} +---- + +[NOTE] +==== +`@DisabledOnMac` is meant only as an example of what is possible. If you have that exact +use case, please use the built-in `@DisabledOnOs(MAC)` support in JUnit Jupiter. +==== + +[WARNING] +==== +Since JUnit 5.7, JUnit Jupiter also has a condition annotation named `@DisabledIf`. Thus, +if you wish to use Spring's `@DisabledIf` support make sure you import the annotation type +from the correct package. +==== + + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc new file mode 100644 index 000000000000..077c53dbf06b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc @@ -0,0 +1,184 @@ +[[integration-testing-annotations-junit4]] += Spring JUnit 4 Testing Annotations + +The following annotations are supported only when used in conjunction with the +<<testcontext-junit4-runner, SpringRunner>>, <<testcontext-junit4-rules, Spring's JUnit 4 +rules>>, or <<testcontext-support-classes-junit4, Spring's JUnit 4 support classes>>: + +* <<integration-testing-annotations-junit4-ifprofilevalue>> +* <<integration-testing-annotations-junit4-profilevaluesourceconfiguration>> +* <<integration-testing-annotations-junit4-timed>> +* <<integration-testing-annotations-junit4-repeat>> + +[[integration-testing-annotations-junit4-ifprofilevalue]] +== `@IfProfileValue` + +`@IfProfileValue` indicates that the annotated test is enabled for a specific testing +environment. If the configured `ProfileValueSource` returns a matching `value` for the +provided `name`, the test is enabled. Otherwise, the test is disabled and, effectively, +ignored. + +You can apply `@IfProfileValue` at the class level, the method level, or both. +Class-level usage of `@IfProfileValue` takes precedence over method-level usage for any +methods within that class or its subclasses. Specifically, a test is enabled if it is +enabled both at the class level and at the method level. The absence of `@IfProfileValue` +means the test is implicitly enabled. This is analogous to the semantics of JUnit 4's +`@Ignore` annotation, except that the presence of `@Ignore` always disables a test. + +The following example shows a test that has an `@IfProfileValue` annotation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @IfProfileValue(name="java.vendor", value="Oracle Corporation") // <1> + @Test + public void testProcessWhichRunsOnlyOnOracleJvm() { + // some logic that should run only on Java VMs from Oracle Corporation + } +---- +<1> Run this test only when the Java vendor is "Oracle Corporation". + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @IfProfileValue(name="java.vendor", value="Oracle Corporation") // <1> + @Test + fun testProcessWhichRunsOnlyOnOracleJvm() { + // some logic that should run only on Java VMs from Oracle Corporation + } +---- +<1> Run this test only when the Java vendor is "Oracle Corporation". + + +Alternatively, you can configure `@IfProfileValue` with a list of `values` (with `OR` +semantics) to achieve TestNG-like support for test groups in a JUnit 4 environment. +Consider the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @IfProfileValue(name="test-groups", values={"unit-tests", "integration-tests"}) // <1> + @Test + public void testProcessWhichRunsForUnitOrIntegrationTestGroups() { + // some logic that should run only for unit and integration test groups + } +---- +<1> Run this test for unit tests and integration tests. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @IfProfileValue(name="test-groups", values=["unit-tests", "integration-tests"]) // <1> + @Test + fun testProcessWhichRunsForUnitOrIntegrationTestGroups() { + // some logic that should run only for unit and integration test groups + } +---- +<1> Run this test for unit tests and integration tests. + + +[[integration-testing-annotations-junit4-profilevaluesourceconfiguration]] +== `@ProfileValueSourceConfiguration` + +`@ProfileValueSourceConfiguration` is a class-level annotation that specifies what type +of `ProfileValueSource` to use when retrieving profile values configured through the +`@IfProfileValue` annotation. If `@ProfileValueSourceConfiguration` is not declared for a +test, `SystemProfileValueSource` is used by default. The following example shows how to +use `@ProfileValueSourceConfiguration`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ProfileValueSourceConfiguration(CustomProfileValueSource.class) // <1> + public class CustomProfileValueSourceTests { + // class body... + } +---- +<1> Use a custom profile value source. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ProfileValueSourceConfiguration(CustomProfileValueSource::class) // <1> + class CustomProfileValueSourceTests { + // class body... + } +---- +<1> Use a custom profile value source. + + +[[integration-testing-annotations-junit4-timed]] +== `@Timed` + +`@Timed` indicates that the annotated test method must finish execution in a specified +time period (in milliseconds). If the text execution time exceeds the specified time +period, the test fails. + +The time period includes running the test method itself, any repetitions of the test (see +`@Repeat`), as well as any setting up or tearing down of the test fixture. The following +example shows how to use it: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Timed(millis = 1000) // <1> + public void testProcessWithOneSecondTimeout() { + // some logic that should not take longer than 1 second to run + } +---- +<1> Set the time period for the test to one second. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Timed(millis = 1000) // <1> + fun testProcessWithOneSecondTimeout() { + // some logic that should not take longer than 1 second to run + } +---- +<1> Set the time period for the test to one second. + + +Spring's `@Timed` annotation has different semantics than JUnit 4's `@Test(timeout=...)` +support. Specifically, due to the manner in which JUnit 4 handles test execution timeouts +(that is, by executing the test method in a separate `Thread`), `@Test(timeout=...)` +preemptively fails the test if the test takes too long. Spring's `@Timed`, on the other +hand, does not preemptively fail the test but rather waits for the test to complete +before failing. + +[[integration-testing-annotations-junit4-repeat]] +== `@Repeat` + +`@Repeat` indicates that the annotated test method must be run repeatedly. The number of +times that the test method is to be run is specified in the annotation. + +The scope of execution to be repeated includes execution of the test method itself as +well as any setting up or tearing down of the test fixture. When used with the +<<testcontext-junit4-rules, `SpringMethodRule`>>, the scope additionally includes +preparation of the test instance by `TestExecutionListener` implementations. The +following example shows how to use the `@Repeat` annotation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Repeat(10) // <1> + @Test + public void testProcessRepeatedly() { + // ... + } +---- +<1> Repeat this test ten times. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Repeat(10) // <1> + @Test + fun testProcessRepeatedly() { + // ... + } +---- +<1> Repeat this test ten times. + + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc new file mode 100644 index 000000000000..8cb176ac1bb7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc @@ -0,0 +1,264 @@ +[[integration-testing-annotations-meta]] += Meta-Annotation Support for Testing + +You can use most test-related annotations as +<<core.adoc#beans-meta-annotations, meta-annotations>> to create custom composed +annotations and reduce configuration duplication across a test suite. + +You can use each of the following as a meta-annotation in conjunction with the +<<testcontext-framework, TestContext framework>>. + +* `@BootstrapWith` +* `@ContextConfiguration` +* `@ContextHierarchy` +* `@ActiveProfiles` +* `@TestPropertySource` +* `@DirtiesContext` +* `@WebAppConfiguration` +* `@TestExecutionListeners` +* `@Transactional` +* `@BeforeTransaction` +* `@AfterTransaction` +* `@Commit` +* `@Rollback` +* `@Sql` +* `@SqlConfig` +* `@SqlMergeMode` +* `@SqlGroup` +* `@Repeat` _(only supported on JUnit 4)_ +* `@Timed` _(only supported on JUnit 4)_ +* `@IfProfileValue` _(only supported on JUnit 4)_ +* `@ProfileValueSourceConfiguration` _(only supported on JUnit 4)_ +* `@SpringJUnitConfig` _(only supported on JUnit Jupiter)_ +* `@SpringJUnitWebConfig` _(only supported on JUnit Jupiter)_ +* `@TestConstructor` _(only supported on JUnit Jupiter)_ +* `@NestedTestConfiguration` _(only supported on JUnit Jupiter)_ +* `@EnabledIf` _(only supported on JUnit Jupiter)_ +* `@DisabledIf` _(only supported on JUnit Jupiter)_ + +Consider the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RunWith(SpringRunner.class) + @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) + @ActiveProfiles("dev") + @Transactional + public class OrderRepositoryTests { } + + @RunWith(SpringRunner.class) + @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) + @ActiveProfiles("dev") + @Transactional + public class UserRepositoryTests { } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RunWith(SpringRunner::class) + @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") + @ActiveProfiles("dev") + @Transactional + class OrderRepositoryTests { } + + @RunWith(SpringRunner::class) + @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") + @ActiveProfiles("dev") + @Transactional + class UserRepositoryTests { } +---- + +If we discover that we are repeating the preceding configuration across our JUnit 4-based +test suite, we can reduce the duplication by introducing a custom composed annotation +that centralizes the common test configuration for Spring, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target(ElementType.TYPE) + @Retention(RetentionPolicy.RUNTIME) + @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) + @ActiveProfiles("dev") + @Transactional + public @interface TransactionalDevTestConfig { } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.TYPE) + @Retention(AnnotationRetention.RUNTIME) + @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") + @ActiveProfiles("dev") + @Transactional + annotation class TransactionalDevTestConfig { } +---- + +Then we can use our custom `@TransactionalDevTestConfig` annotation to simplify the +configuration of individual JUnit 4 based test classes, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RunWith(SpringRunner.class) + @TransactionalDevTestConfig + public class OrderRepositoryTests { } + + @RunWith(SpringRunner.class) + @TransactionalDevTestConfig + public class UserRepositoryTests { } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RunWith(SpringRunner::class) + @TransactionalDevTestConfig + class OrderRepositoryTests + + @RunWith(SpringRunner::class) + @TransactionalDevTestConfig + class UserRepositoryTests +---- + +If we write tests that use JUnit Jupiter, we can reduce code duplication even further, +since annotations in JUnit 5 can also be used as meta-annotations. Consider the following +example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) + @ActiveProfiles("dev") + @Transactional + class OrderRepositoryTests { } + + @ExtendWith(SpringExtension.class) + @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) + @ActiveProfiles("dev") + @Transactional + class UserRepositoryTests { } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") + @ActiveProfiles("dev") + @Transactional + class OrderRepositoryTests { } + + @ExtendWith(SpringExtension::class) + @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") + @ActiveProfiles("dev") + @Transactional + class UserRepositoryTests { } +---- + +If we discover that we are repeating the preceding configuration across our JUnit +Jupiter-based test suite, we can reduce the duplication by introducing a custom composed +annotation that centralizes the common test configuration for Spring and JUnit Jupiter, +as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target(ElementType.TYPE) + @Retention(RetentionPolicy.RUNTIME) + @ExtendWith(SpringExtension.class) + @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) + @ActiveProfiles("dev") + @Transactional + public @interface TransactionalDevTestConfig { } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.TYPE) + @Retention(AnnotationRetention.RUNTIME) + @ExtendWith(SpringExtension::class) + @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") + @ActiveProfiles("dev") + @Transactional + annotation class TransactionalDevTestConfig { } +---- + +Then we can use our custom `@TransactionalDevTestConfig` annotation to simplify the +configuration of individual JUnit Jupiter based test classes, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @TransactionalDevTestConfig + class OrderRepositoryTests { } + + @TransactionalDevTestConfig + class UserRepositoryTests { } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @TransactionalDevTestConfig + class OrderRepositoryTests { } + + @TransactionalDevTestConfig + class UserRepositoryTests { } +---- + +Since JUnit Jupiter supports the use of `@Test`, `@RepeatedTest`, `ParameterizedTest`, +and others as meta-annotations, you can also create custom composed annotations at the +test method level. For example, if we wish to create a composed annotation that combines +the `@Test` and `@Tag` annotations from JUnit Jupiter with the `@Transactional` +annotation from Spring, we could create an `@TransactionalIntegrationTest` annotation, as +follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target(ElementType.METHOD) + @Retention(RetentionPolicy.RUNTIME) + @Transactional + @Tag("integration-test") // org.junit.jupiter.api.Tag + @Test // org.junit.jupiter.api.Test + public @interface TransactionalIntegrationTest { } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.TYPE) + @Retention(AnnotationRetention.RUNTIME) + @Transactional + @Tag("integration-test") // org.junit.jupiter.api.Tag + @Test // org.junit.jupiter.api.Test + annotation class TransactionalIntegrationTest { } +---- + +Then we can use our custom `@TransactionalIntegrationTest` annotation to simplify the +configuration of individual JUnit Jupiter based test methods, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @TransactionalIntegrationTest + void saveOrder() { } + + @TransactionalIntegrationTest + void deleteOrder() { } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @TransactionalIntegrationTest + fun saveOrder() { } + + @TransactionalIntegrationTest + fun deleteOrder() { } +---- + +For further details, see the +https://github.com/spring-projects/spring-framework/wiki/Spring-Annotation-Programming-Model[Spring Annotation Programming Model] +wiki page. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc new file mode 100644 index 000000000000..8bfde481a8cc --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc @@ -0,0 +1,29 @@ +[[integration-testing-annotations-spring]] += Spring Testing Annotations + +The Spring Framework provides the following set of Spring-specific annotations that you +can use in your unit and integration tests in conjunction with the TestContext framework. +See the corresponding javadoc for further information, including default attribute +values, attribute aliases, and other details. + +Spring's testing annotations include the following: + +* <<spring-testing-annotation-bootstrapwith>> +* <<spring-testing-annotation-contextconfiguration>> +* <<spring-testing-annotation-webappconfiguration>> +* <<spring-testing-annotation-contexthierarchy>> +* <<spring-testing-annotation-activeprofiles>> +* <<spring-testing-annotation-testpropertysource>> +* <<spring-testing-annotation-dynamicpropertysource>> +* <<spring-testing-annotation-dirtiescontext>> +* <<spring-testing-annotation-testexecutionlisteners>> +* <<spring-testing-annotation-recordapplicationevents>> +* <<spring-testing-annotation-commit>> +* <<spring-testing-annotation-rollback>> +* <<spring-testing-annotation-beforetransaction>> +* <<spring-testing-annotation-aftertransaction>> +* <<spring-testing-annotation-sql>> +* <<spring-testing-annotation-sqlconfig>> +* <<spring-testing-annotation-sqlmergemode>> +* <<spring-testing-annotation-sqlgroup>> + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc new file mode 100644 index 000000000000..42a1284f6d34 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc @@ -0,0 +1,69 @@ +[[spring-testing-annotation-activeprofiles]] += `@ActiveProfiles` + +`@ActiveProfiles` is a class-level annotation that is used to declare which bean +definition profiles should be active when loading an `ApplicationContext` for an +integration test. + +The following example indicates that the `dev` profile should be active: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @ActiveProfiles("dev") // <1> + class DeveloperTests { + // class body... + } +---- +<1> Indicate that the `dev` profile should be active. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @ActiveProfiles("dev") // <1> + class DeveloperTests { + // class body... + } +---- +<1> Indicate that the `dev` profile should be active. + + +The following example indicates that both the `dev` and the `integration` profiles should +be active: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @ActiveProfiles({"dev", "integration"}) // <1> + class DeveloperIntegrationTests { + // class body... + } +---- +<1> Indicate that the `dev` and `integration` profiles should be active. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @ActiveProfiles(["dev", "integration"]) // <1> + class DeveloperIntegrationTests { + // class body... + } +---- +<1> Indicate that the `dev` and `integration` profiles should be active. + + +NOTE: `@ActiveProfiles` provides support for inheriting active bean definition profiles +declared by superclasses and enclosing classes by default. You can also resolve active +bean definition profiles programmatically by implementing a custom +<<testcontext-ctx-management-env-profiles-ActiveProfilesResolver, `ActiveProfilesResolver`>> +and registering it by using the `resolver` attribute of `@ActiveProfiles`. + +See <<testcontext-ctx-management-env-profiles>>, +<<testcontext-junit-jupiter-nested-test-configuration>>, and the +{api-spring-framework}/test/context/ActiveProfiles.html[`@ActiveProfiles`] javadoc for +examples and further details. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-aftertransaction.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-aftertransaction.adoc new file mode 100644 index 000000000000..d54a7343fe2f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-aftertransaction.adoc @@ -0,0 +1,30 @@ +[[spring-testing-annotation-aftertransaction]] += `@AfterTransaction` + +`@AfterTransaction` indicates that the annotated `void` method should be run after a +transaction is ended, for test methods that have been configured to run within a +transaction by using Spring's `@Transactional` annotation. `@AfterTransaction` methods +are not required to be `public` and may be declared on Java 8-based interface default +methods. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @AfterTransaction // <1> + void afterTransaction() { + // logic to be run after a transaction has ended + } +---- +<1> Run this method after a transaction. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @AfterTransaction // <1> + fun afterTransaction() { + // logic to be run after a transaction has ended + } +---- +<1> Run this method after a transaction. + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-beforetransaction.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-beforetransaction.adoc new file mode 100644 index 000000000000..943451ef2a82 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-beforetransaction.adoc @@ -0,0 +1,32 @@ +[[spring-testing-annotation-beforetransaction]] += `@BeforeTransaction` + +`@BeforeTransaction` indicates that the annotated `void` method should be run before a +transaction is started, for test methods that have been configured to run within a +transaction by using Spring's `@Transactional` annotation. `@BeforeTransaction` methods +are not required to be `public` and may be declared on Java 8-based interface default +methods. + +The following example shows how to use the `@BeforeTransaction` annotation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @BeforeTransaction // <1> + void beforeTransaction() { + // logic to be run before a transaction is started + } +---- +<1> Run this method before a transaction. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @BeforeTransaction // <1> + fun beforeTransaction() { + // logic to be run before a transaction is started + } +---- +<1> Run this method before a transaction. + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc new file mode 100644 index 000000000000..6646495d547c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc @@ -0,0 +1,8 @@ +[[spring-testing-annotation-bootstrapwith]] += `@BootstrapWith` + +`@BootstrapWith` is a class-level annotation that you can use to configure how the Spring +TestContext Framework is bootstrapped. Specifically, you can use `@BootstrapWith` to +specify a custom `TestContextBootstrapper`. See the section on +<<testcontext-bootstrapping, bootstrapping the TestContext framework>> for further details. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-commit.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-commit.adoc new file mode 100644 index 000000000000..7702fcfa78b4 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-commit.adoc @@ -0,0 +1,34 @@ +[[spring-testing-annotation-commit]] += `@Commit` + +`@Commit` indicates that the transaction for a transactional test method should be +committed after the test method has completed. You can use `@Commit` as a direct +replacement for `@Rollback(false)` to more explicitly convey the intent of the code. +Analogous to `@Rollback`, `@Commit` can also be declared as a class-level or method-level +annotation. + +The following example shows how to use the `@Commit` annotation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Commit // <1> + @Test + void testProcessWithoutRollback() { + // ... + } +---- +<1> Commit the result of the test to the database. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Commit // <1> + @Test + fun testProcessWithoutRollback() { + // ... + } +---- +<1> Commit the result of the test to the database. + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc new file mode 100644 index 000000000000..e39524afd925 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc @@ -0,0 +1,122 @@ +[[spring-testing-annotation-contextconfiguration]] += `@ContextConfiguration` + +`@ContextConfiguration` defines class-level metadata that is used to determine how to +load and configure an `ApplicationContext` for integration tests. Specifically, +`@ContextConfiguration` declares the application context resource `locations` or the +component `classes` used to load the context. + +Resource locations are typically XML configuration files or Groovy scripts located in the +classpath, while component classes are typically `@Configuration` classes. However, +resource locations can also refer to files and scripts in the file system, and component +classes can be `@Component` classes, `@Service` classes, and so on. See +<<testcontext-ctx-management-javaconfig-component-classes>> for further details. + +The following example shows a `@ContextConfiguration` annotation that refers to an XML +file: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration("/test-config.xml") // <1> + class XmlApplicationContextTests { + // class body... + } +---- +<1> Referring to an XML file. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration("/test-config.xml") // <1> + class XmlApplicationContextTests { + // class body... + } +---- +<1> Referring to an XML file. + + +The following example shows a `@ContextConfiguration` annotation that refers to a class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration(classes = TestConfig.class) // <1> + class ConfigClassApplicationContextTests { + // class body... + } +---- +<1> Referring to a class. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration(classes = [TestConfig::class]) // <1> + class ConfigClassApplicationContextTests { + // class body... + } +---- +<1> Referring to a class. + + +As an alternative or in addition to declaring resource locations or component classes, +you can use `@ContextConfiguration` to declare `ApplicationContextInitializer` classes. +The following example shows such a case: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration(initializers = CustomContextInitializer.class) // <1> + class ContextInitializerTests { + // class body... + } +---- +<1> Declaring an initializer class. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration(initializers = [CustomContextInitializer::class]) // <1> + class ContextInitializerTests { + // class body... + } +---- +<1> Declaring an initializer class. + + +You can optionally use `@ContextConfiguration` to declare the `ContextLoader` strategy as +well. Note, however, that you typically do not need to explicitly configure the loader, +since the default loader supports `initializers` and either resource `locations` or +component `classes`. + +The following example uses both a location and a loader: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration(locations = "/test-context.xml", loader = CustomContextLoader.class) // <1> + class CustomLoaderXmlApplicationContextTests { + // class body... + } +---- +<1> Configuring both a location and a custom loader. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration("/test-context.xml", loader = CustomContextLoader::class) // <1> + class CustomLoaderXmlApplicationContextTests { + // class body... + } +---- +<1> Configuring both a location and a custom loader. + + +NOTE: `@ContextConfiguration` provides support for inheriting resource locations or +configuration classes as well as context initializers that are declared by superclasses +or enclosing classes. + +See <<testcontext-ctx-management>>, +<<testcontext-junit-jupiter-nested-test-configuration>>, and the `@ContextConfiguration` +javadocs for further details. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc new file mode 100644 index 000000000000..e0f0c48b54a5 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc @@ -0,0 +1,63 @@ +[[spring-testing-annotation-contexthierarchy]] += `@ContextHierarchy` + +`@ContextHierarchy` is a class-level annotation that is used to define a hierarchy of +`ApplicationContext` instances for integration tests. `@ContextHierarchy` should be +declared with a list of one or more `@ContextConfiguration` instances, each of which +defines a level in the context hierarchy. The following examples demonstrate the use of +`@ContextHierarchy` within a single test class (`@ContextHierarchy` can also be used +within a test class hierarchy): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextHierarchy({ + @ContextConfiguration("/parent-config.xml"), + @ContextConfiguration("/child-config.xml") + }) + class ContextHierarchyTests { + // class body... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextHierarchy( + ContextConfiguration("/parent-config.xml"), + ContextConfiguration("/child-config.xml")) + class ContextHierarchyTests { + // class body... + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @WebAppConfiguration + @ContextHierarchy({ + @ContextConfiguration(classes = AppConfig.class), + @ContextConfiguration(classes = WebConfig.class) + }) + class WebIntegrationTests { + // class body... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @WebAppConfiguration + @ContextHierarchy( + ContextConfiguration(classes = [AppConfig::class]), + ContextConfiguration(classes = [WebConfig::class])) + class WebIntegrationTests { + // class body... + } +---- + +If you need to merge or override the configuration for a given level of the context +hierarchy within a test class hierarchy, you must explicitly name that level by supplying +the same value to the `name` attribute in `@ContextConfiguration` at each corresponding +level in the class hierarchy. See <<testcontext-ctx-management-ctx-hierarchies>> and the +{api-spring-framework}/test/context/ContextHierarchy.html[`@ContextHierarchy`] javadoc +for further examples. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dirtiescontext.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dirtiescontext.adoc new file mode 100644 index 000000000000..9f6103a1c60a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dirtiescontext.adoc @@ -0,0 +1,223 @@ +[[spring-testing-annotation-dirtiescontext]] += `@DirtiesContext` + +`@DirtiesContext` indicates that the underlying Spring `ApplicationContext` has been +dirtied during the execution of a test (that is, the test modified or corrupted it in +some manner -- for example, by changing the state of a singleton bean) and should be +closed. When an application context is marked as dirty, it is removed from the testing +framework's cache and closed. As a consequence, the underlying Spring container is +rebuilt for any subsequent test that requires a context with the same configuration +metadata. + +You can use `@DirtiesContext` as both a class-level and a method-level annotation within +the same class or class hierarchy. In such scenarios, the `ApplicationContext` is marked +as dirty before or after any such annotated method as well as before or after the current +test class, depending on the configured `methodMode` and `classMode`. + +The following examples explain when the context would be dirtied for various +configuration scenarios: + +* Before the current test class, when declared on a class with class mode set to +`BEFORE_CLASS`. ++ +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @DirtiesContext(classMode = BEFORE_CLASS) // <1> + class FreshContextTests { + // some tests that require a new Spring container + } +---- +<1> Dirty the context before the current test class. ++ +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @DirtiesContext(classMode = BEFORE_CLASS) // <1> + class FreshContextTests { + // some tests that require a new Spring container + } +---- +<1> Dirty the context before the current test class. + +* After the current test class, when declared on a class with class mode set to +`AFTER_CLASS` (i.e., the default class mode). ++ +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @DirtiesContext // <1> + class ContextDirtyingTests { + // some tests that result in the Spring container being dirtied + } +---- +<1> Dirty the context after the current test class. ++ +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @DirtiesContext // <1> + class ContextDirtyingTests { + // some tests that result in the Spring container being dirtied + } +---- +<1> Dirty the context after the current test class. + + +* Before each test method in the current test class, when declared on a class with class +mode set to `BEFORE_EACH_TEST_METHOD.` ++ +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @DirtiesContext(classMode = BEFORE_EACH_TEST_METHOD) // <1> + class FreshContextTests { + // some tests that require a new Spring container + } +---- +<1> Dirty the context before each test method. ++ +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @DirtiesContext(classMode = BEFORE_EACH_TEST_METHOD) // <1> + class FreshContextTests { + // some tests that require a new Spring container + } +---- +<1> Dirty the context before each test method. + + +* After each test method in the current test class, when declared on a class with class +mode set to `AFTER_EACH_TEST_METHOD.` ++ +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @DirtiesContext(classMode = AFTER_EACH_TEST_METHOD) // <1> + class ContextDirtyingTests { + // some tests that result in the Spring container being dirtied + } +---- +<1> Dirty the context after each test method. ++ +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @DirtiesContext(classMode = AFTER_EACH_TEST_METHOD) // <1> + class ContextDirtyingTests { + // some tests that result in the Spring container being dirtied + } +---- +<1> Dirty the context after each test method. + + +* Before the current test, when declared on a method with the method mode set to +`BEFORE_METHOD`. ++ +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @DirtiesContext(methodMode = BEFORE_METHOD) // <1> + @Test + void testProcessWhichRequiresFreshAppCtx() { + // some logic that requires a new Spring container + } +---- +<1> Dirty the context before the current test method. ++ +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @DirtiesContext(methodMode = BEFORE_METHOD) // <1> + @Test + fun testProcessWhichRequiresFreshAppCtx() { + // some logic that requires a new Spring container + } +---- +<1> Dirty the context before the current test method. + +* After the current test, when declared on a method with the method mode set to +`AFTER_METHOD` (i.e., the default method mode). ++ +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @DirtiesContext // <1> + @Test + void testProcessWhichDirtiesAppCtx() { + // some logic that results in the Spring container being dirtied + } +---- +<1> Dirty the context after the current test method. ++ +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @DirtiesContext // <1> + @Test + fun testProcessWhichDirtiesAppCtx() { + // some logic that results in the Spring container being dirtied + } +---- +<1> Dirty the context after the current test method. + + +If you use `@DirtiesContext` in a test whose context is configured as part of a context +hierarchy with `@ContextHierarchy`, you can use the `hierarchyMode` flag to control how +the context cache is cleared. By default, an exhaustive algorithm is used to clear the +context cache, including not only the current level but also all other context +hierarchies that share an ancestor context common to the current test. All +`ApplicationContext` instances that reside in a sub-hierarchy of the common ancestor +context are removed from the context cache and closed. If the exhaustive algorithm is +overkill for a particular use case, you can specify the simpler current level algorithm, +as the following example shows. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextHierarchy({ + @ContextConfiguration("/parent-config.xml"), + @ContextConfiguration("/child-config.xml") + }) + class BaseTests { + // class body... + } + + class ExtendedTests extends BaseTests { + + @Test + @DirtiesContext(hierarchyMode = CURRENT_LEVEL) // <1> + void test() { + // some logic that results in the child context being dirtied + } + } +---- +<1> Use the current-level algorithm. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextHierarchy( + ContextConfiguration("/parent-config.xml"), + ContextConfiguration("/child-config.xml")) + open class BaseTests { + // class body... + } + + class ExtendedTests : BaseTests() { + + @Test + @DirtiesContext(hierarchyMode = CURRENT_LEVEL) // <1> + fun test() { + // some logic that results in the child context being dirtied + } + } +---- +<1> Use the current-level algorithm. + + +For further details regarding the `EXHAUSTIVE` and `CURRENT_LEVEL` algorithms, see the +{api-spring-framework}/test/annotation/DirtiesContext.HierarchyMode.html[`DirtiesContext.HierarchyMode`] +javadoc. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc new file mode 100644 index 000000000000..70bb526e0de0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc @@ -0,0 +1,59 @@ +[[spring-testing-annotation-dynamicpropertysource]] += `@DynamicPropertySource` + +`@DynamicPropertySource` is a method-level annotation that you can use to register +_dynamic_ properties to be added to the set of `PropertySources` in the `Environment` for +an `ApplicationContext` loaded for an integration test. Dynamic properties are useful +when you do not know the value of the properties upfront – for example, if the properties +are managed by an external resource such as for a container managed by the +https://www.testcontainers.org/[Testcontainers] project. + +The following example demonstrates how to register a dynamic property: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + class MyIntegrationTests { + + static MyExternalServer server = // ... + + @DynamicPropertySource // <1> + static void dynamicProperties(DynamicPropertyRegistry registry) { // <2> + registry.add("server.port", server::getPort); // <3> + } + + // tests ... + } +---- +<1> Annotate a `static` method with `@DynamicPropertySource`. +<2> Accept a `DynamicPropertyRegistry` as an argument. +<3> Register a dynamic `server.port` property to be retrieved lazily from the server. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + class MyIntegrationTests { + + companion object { + + @JvmStatic + val server: MyExternalServer = // ... + + @DynamicPropertySource // <1> + @JvmStatic + fun dynamicProperties(registry: DynamicPropertyRegistry) { // <2> + registry.add("server.port", server::getPort) // <3> + } + } + + // tests ... + } +---- +<1> Annotate a `static` method with `@DynamicPropertySource`. +<2> Accept a `DynamicPropertyRegistry` as an argument. +<3> Register a dynamic `server.port` property to be retrieved lazily from the server. + +See <<testcontext-ctx-management-dynamic-property-sources>> for further details. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc new file mode 100644 index 000000000000..dcb9a2df441f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc @@ -0,0 +1,13 @@ +[[spring-testing-annotation-recordapplicationevents]] += `@RecordApplicationEvents` + +`@RecordApplicationEvents` is a class-level annotation that is used to instruct the +_Spring TestContext Framework_ to record all application events that are published in the +`ApplicationContext` during the execution of a single test. + +The recorded events can be accessed via the `ApplicationEvents` API within tests. + +See <<testcontext-application-events>> and the +{api-spring-framework}/test/context/event/RecordApplicationEvents.html[`@RecordApplicationEvents` +javadoc] for an example and further details. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc new file mode 100644 index 000000000000..2d4c7ace099a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc @@ -0,0 +1,40 @@ +[[spring-testing-annotation-rollback]] += `@Rollback` + +`@Rollback` indicates whether the transaction for a transactional test method should be +rolled back after the test method has completed. If `true`, the transaction is rolled +back. Otherwise, the transaction is committed (see also +<<spring-testing-annotation-commit>>). Rollback for integration tests in the Spring +TestContext Framework defaults to `true` even if `@Rollback` is not explicitly declared. + +When declared as a class-level annotation, `@Rollback` defines the default rollback +semantics for all test methods within the test class hierarchy. When declared as a +method-level annotation, `@Rollback` defines rollback semantics for the specific test +method, potentially overriding class-level `@Rollback` or `@Commit` semantics. + +The following example causes a test method's result to not be rolled back (that is, the +result is committed to the database): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Rollback(false) // <1> + @Test + void testProcessWithoutRollback() { + // ... + } +---- +<1> Do not roll back the result. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Rollback(false) // <1> + @Test + fun testProcessWithoutRollback() { + // ... + } +---- +<1> Do not roll back the result. + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc new file mode 100644 index 000000000000..32dd573437df --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc @@ -0,0 +1,32 @@ +[[spring-testing-annotation-sql]] += `@Sql` + +`@Sql` is used to annotate a test class or test method to configure SQL scripts to be run +against a given database during integration tests. The following example shows how to use +it: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Test + @Sql({"/test-schema.sql", "/test-user-data.sql"}) // <1> + void userTest() { + // run code that relies on the test schema and test data + } +---- +<1> Run two scripts for this test. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Test + @Sql("/test-schema.sql", "/test-user-data.sql") // <1> + fun userTest() { + // run code that relies on the test schema and test data + } +---- +<1> Run two scripts for this test. + +See <<testcontext-executing-sql-declaratively>> for further details. + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlconfig.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlconfig.adoc new file mode 100644 index 000000000000..98c961544efc --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlconfig.adoc @@ -0,0 +1,31 @@ +[[spring-testing-annotation-sqlconfig]] += `@SqlConfig` + +`@SqlConfig` defines metadata that is used to determine how to parse and run SQL scripts +configured with the `@Sql` annotation. The following example shows how to use it: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Test + @Sql( + scripts = "/test-user-data.sql", + config = @SqlConfig(commentPrefix = "`", separator = "@@") // <1> + ) + void userTest() { + // run code that relies on the test data + } +---- +<1> Set the comment prefix and the separator in SQL scripts. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Test + @Sql("/test-user-data.sql", config = SqlConfig(commentPrefix = "`", separator = "@@")) // <1> + fun userTest() { + // run code that relies on the test data + } +---- +<1> Set the comment prefix and the separator in SQL scripts. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlgroup.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlgroup.adoc new file mode 100644 index 000000000000..e75050853598 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlgroup.adoc @@ -0,0 +1,38 @@ +[[spring-testing-annotation-sqlgroup]] += `@SqlGroup` + +`@SqlGroup` is a container annotation that aggregates several `@Sql` annotations. You can +use `@SqlGroup` natively to declare several nested `@Sql` annotations, or you can use it +in conjunction with Java 8's support for repeatable annotations, where `@Sql` can be +declared several times on the same class or method, implicitly generating this container +annotation. The following example shows how to declare an SQL group: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Test + @SqlGroup({ // <1> + @Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")), + @Sql("/test-user-data.sql") + }) + void userTest() { + // run code that uses the test schema and test data + } +---- +<1> Declare a group of SQL scripts. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Test + @SqlGroup( // <1> + Sql("/test-schema.sql", config = SqlConfig(commentPrefix = "`")), + Sql("/test-user-data.sql")) + fun userTest() { + // run code that uses the test schema and test data + } +---- +<1> Declare a group of SQL scripts. + + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlmergemode.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlmergemode.adoc new file mode 100644 index 000000000000..cd594989144c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlmergemode.adoc @@ -0,0 +1,84 @@ +[[spring-testing-annotation-sqlmergemode]] += `@SqlMergeMode` + +`@SqlMergeMode` is used to annotate a test class or test method to configure whether +method-level `@Sql` declarations are merged with class-level `@Sql` declarations. If +`@SqlMergeMode` is not declared on a test class or test method, the `OVERRIDE` merge mode +will be used by default. With the `OVERRIDE` mode, method-level `@Sql` declarations will +effectively override class-level `@Sql` declarations. + +Note that a method-level `@SqlMergeMode` declaration overrides a class-level declaration. + +The following example shows how to use `@SqlMergeMode` at the class level. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestConfig.class) + @Sql("/test-schema.sql") + @SqlMergeMode(MERGE) // <1> + class UserTests { + + @Test + @Sql("/user-test-data-001.sql") + void standardUserProfile() { + // run code that relies on test data set 001 + } + } +---- +<1> Set the `@Sql` merge mode to `MERGE` for all test methods in the class. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestConfig::class) + @Sql("/test-schema.sql") + @SqlMergeMode(MERGE) // <1> + class UserTests { + + @Test + @Sql("/user-test-data-001.sql") + fun standardUserProfile() { + // run code that relies on test data set 001 + } + } +---- +<1> Set the `@Sql` merge mode to `MERGE` for all test methods in the class. + +The following example shows how to use `@SqlMergeMode` at the method level. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestConfig.class) + @Sql("/test-schema.sql") + class UserTests { + + @Test + @Sql("/user-test-data-001.sql") + @SqlMergeMode(MERGE) // <1> + void standardUserProfile() { + // run code that relies on test data set 001 + } + } +---- +<1> Set the `@Sql` merge mode to `MERGE` for a specific test method. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestConfig::class) + @Sql("/test-schema.sql") + class UserTests { + + @Test + @Sql("/user-test-data-001.sql") + @SqlMergeMode(MERGE) // <1> + fun standardUserProfile() { + // run code that relies on test data set 001 + } + } +---- +<1> Set the `@Sql` merge mode to `MERGE` for a specific test method. + + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc new file mode 100644 index 000000000000..38548fc41505 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc @@ -0,0 +1,41 @@ +[[spring-testing-annotation-testexecutionlisteners]] += `@TestExecutionListeners` + +`@TestExecutionListeners` is used to register listeners for a particular test class, its +subclasses, and its nested classes. If you wish to register a listener globally, you +should register it via the automatic discovery mechanism described in +<<testcontext-tel-config>>. + +The following example shows how to register two `TestExecutionListener` implementations: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @TestExecutionListeners({CustomTestExecutionListener.class, AnotherTestExecutionListener.class}) // <1> + class CustomTestExecutionListenerTests { + // class body... + } +---- +<1> Register two `TestExecutionListener` implementations. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @TestExecutionListeners(CustomTestExecutionListener::class, AnotherTestExecutionListener::class) // <1> + class CustomTestExecutionListenerTests { + // class body... + } +---- +<1> Register two `TestExecutionListener` implementations. + + +By default, `@TestExecutionListeners` provides support for inheriting listeners from +superclasses or enclosing classes. See +<<testcontext-junit-jupiter-nested-test-configuration>> and the +{api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners` +javadoc] for an example and further details. If you discover that you need to switch +back to using the default `TestExecutionListener` implementations, see the note +in <<testcontext-tel-config-registering-tels>>. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc new file mode 100644 index 000000000000..c793c4b057e5 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc @@ -0,0 +1,59 @@ +[[spring-testing-annotation-testpropertysource]] += `@TestPropertySource` + +`@TestPropertySource` is a class-level annotation that you can use to configure the +locations of properties files and inlined properties to be added to the set of +`PropertySources` in the `Environment` for an `ApplicationContext` loaded for an +integration test. + +The following example demonstrates how to declare a properties file from the classpath: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @TestPropertySource("/test.properties") // <1> + class MyIntegrationTests { + // class body... + } +---- +<1> Get properties from `test.properties` in the root of the classpath. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @TestPropertySource("/test.properties") // <1> + class MyIntegrationTests { + // class body... + } +---- +<1> Get properties from `test.properties` in the root of the classpath. + + +The following example demonstrates how to declare inlined properties: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @TestPropertySource(properties = { "timezone = GMT", "port: 4242" }) // <1> + class MyIntegrationTests { + // class body... + } +---- +<1> Declare `timezone` and `port` properties. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @TestPropertySource(properties = ["timezone = GMT", "port: 4242"]) // <1> + class MyIntegrationTests { + // class body... + } +---- +<1> Declare `timezone` and `port` properties. + +See <<testcontext-ctx-management-property-sources>> for examples and further details. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-webappconfiguration.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-webappconfiguration.adoc new file mode 100644 index 000000000000..d81df81904df --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-webappconfiguration.adoc @@ -0,0 +1,75 @@ +[[spring-testing-annotation-webappconfiguration]] += `@WebAppConfiguration` + +`@WebAppConfiguration` is a class-level annotation that you can use to declare that the +`ApplicationContext` loaded for an integration test should be a `WebApplicationContext`. +The mere presence of `@WebAppConfiguration` on a test class ensures that a +`WebApplicationContext` is loaded for the test, using the default value of +`"file:src/main/webapp"` for the path to the root of the web application (that is, the +resource base path). The resource base path is used behind the scenes to create a +`MockServletContext`, which serves as the `ServletContext` for the test's +`WebApplicationContext`. + +The following example shows how to use the `@WebAppConfiguration` annotation: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @WebAppConfiguration // <1> + class WebAppTests { + // class body... + } +---- +<1> The `@WebAppConfiguration` annotation. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @WebAppConfiguration // <1> + class WebAppTests { + // class body... + } +---- +<1> The `@WebAppConfiguration` annotation. +-- + + +To override the default, you can specify a different base resource path by using the +implicit `value` attribute. Both `classpath:` and `file:` resource prefixes are +supported. If no resource prefix is supplied, the path is assumed to be a file system +resource. The following example shows how to specify a classpath resource: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @WebAppConfiguration("classpath:test-web-resources") // <1> + class WebAppTests { + // class body... + } +---- +<1> Specifying a classpath resource. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @WebAppConfiguration("classpath:test-web-resources") // <1> + class WebAppTests { + // class body... + } +---- +<1> Specifying a classpath resource. +-- + + +Note that `@WebAppConfiguration` must be used in conjunction with +`@ContextConfiguration`, either within a single test class or within a test class +hierarchy. See the +{api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`] +javadoc for further details. + diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc new file mode 100644 index 000000000000..c18d763e571f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc @@ -0,0 +1,37 @@ +[[integration-testing-annotations-standard]] += Standard Annotation Support + +The following annotations are supported with standard semantics for all configurations of +the Spring TestContext Framework. Note that these annotations are not specific to tests +and can be used anywhere in the Spring Framework. + +* `@Autowired` +* `@Qualifier` +* `@Value` +* `@Resource` (jakarta.annotation) if JSR-250 is present +* `@ManagedBean` (jakarta.annotation) if JSR-250 is present +* `@Inject` (jakarta.inject) if JSR-330 is present +* `@Named` (jakarta.inject) if JSR-330 is present +* `@PersistenceContext` (jakarta.persistence) if JPA is present +* `@PersistenceUnit` (jakarta.persistence) if JPA is present +* `@Transactional` (org.springframework.transaction.annotation) + _with <<testcontext-tx-attribute-support, limited attribute support>>_ + +.JSR-250 Lifecycle Annotations +[NOTE] +==== +In the Spring TestContext Framework, you can use `@PostConstruct` and `@PreDestroy` with +standard semantics on any application components configured in the `ApplicationContext`. +However, these lifecycle annotations have limited usage within an actual test class. + +If a method within a test class is annotated with `@PostConstruct`, that method runs +before any before methods of the underlying test framework (for example, methods +annotated with JUnit Jupiter's `@BeforeEach`), and that applies for every test method in +the test class. On the other hand, if a method within a test class is annotated with +`@PreDestroy`, that method never runs. Therefore, within a test class, we recommend that +you use test lifecycle callbacks from the underlying test framework instead of +`@PostConstruct` and `@PreDestroy`. +==== + + + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc index 10f21afe6113..20e842203e41 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc @@ -12,1863 +12,3 @@ objects instead of raw data as well as the ability to switch to full, end-to-end tests against a live server and use the same test API. -[[spring-mvc-test-server]] -== Overview - -You can write plain unit tests for Spring MVC by instantiating a controller, injecting it -with dependencies, and calling its methods. However such tests do not verify request -mappings, data binding, message conversion, type conversion, validation, and nor -do they involve any of the supporting `@InitBinder`, `@ModelAttribute`, or -`@ExceptionHandler` methods. - -The Spring MVC Test framework, also known as `MockMvc`, aims to provide more complete -testing for Spring MVC controllers without a running server. It does that by invoking -the `DispatcherServlet` and passing -<<mock-objects-servlet, "`mock`" implementations of the Servlet API>> from the -`spring-test` module which replicates the full Spring MVC request handling without -a running server. - -MockMvc is a server side test framework that lets you verify most of the functionality -of a Spring MVC application using lightweight and targeted tests. You can use it on -its own to perform requests and to verify responses, or you can also use it through -the <<webtestclient>> API with MockMvc plugged in as the server to handle requests -with. - - -[[spring-mvc-test-server-static-imports]] -== Static Imports - -When using MockMvc directly to perform requests, you'll need static imports for: - -- `MockMvcBuilders.{asterisk}` -- `MockMvcRequestBuilders.{asterisk}` -- `MockMvcResultMatchers.{asterisk}` -- `MockMvcResultHandlers.{asterisk}` - -An easy way to remember that is search for `MockMvc*`. If using Eclipse be sure to also -add the above as "`favorite static members`" in the Eclipse preferences. - -When using MockMvc through the <<webtestclient>> you do not need static imports. -The `WebTestClient` provides a fluent API without static imports. - - -[[spring-mvc-test-server-setup-options]] -== Setup Choices - -MockMvc can be setup in one of two ways. One is to point directly to the controllers you -want to test and programmatically configure Spring MVC infrastructure. The second is to -point to Spring configuration with Spring MVC and controller infrastructure in it. - -To set up MockMvc for testing a specific controller, use the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - class MyWebTests { - - MockMvc mockMvc; - - @BeforeEach - void setup() { - this.mockMvc = MockMvcBuilders.standaloneSetup(new AccountController()).build(); - } - - // ... - - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyWebTests { - - lateinit var mockMvc : MockMvc - - @BeforeEach - fun setup() { - mockMvc = MockMvcBuilders.standaloneSetup(AccountController()).build() - } - - // ... - - } ----- - -Or you can also use this setup when testing through the -<<webtestclient-controller-config, WebTestClient>> which delegates to the same builder -as shown above. - -To set up MockMvc through Spring configuration, use the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitWebConfig(locations = "my-servlet-context.xml") - class MyWebTests { - - MockMvc mockMvc; - - @BeforeEach - void setup(WebApplicationContext wac) { - this.mockMvc = MockMvcBuilders.webAppContextSetup(wac).build(); - } - - // ... - - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitWebConfig(locations = ["my-servlet-context.xml"]) - class MyWebTests { - - lateinit var mockMvc: MockMvc - - @BeforeEach - fun setup(wac: WebApplicationContext) { - mockMvc = MockMvcBuilders.webAppContextSetup(wac).build() - } - - // ... - - } ----- - -Or you can also use this setup when testing through the -<<webtestclient-context-config, WebTestClient>> which delegates to the same builder -as shown above. - - - -Which setup option should you use? - -The `webAppContextSetup` loads your actual Spring MVC configuration, resulting in a more -complete integration test. Since the TestContext framework caches the loaded Spring -configuration, it helps keep tests running fast, even as you introduce more tests in your -test suite. Furthermore, you can inject mock services into controllers through Spring -configuration to remain focused on testing the web layer. The following example declares -a mock service with Mockito: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="accountService" class="org.mockito.Mockito" factory-method="mock"> - <constructor-arg value="org.example.AccountService"/> - </bean> ----- - -You can then inject the mock service into the test to set up and verify your -expectations, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitWebConfig(locations = "test-servlet-context.xml") - class AccountTests { - - @Autowired - AccountService accountService; - - MockMvc mockMvc; - - @BeforeEach - void setup(WebApplicationContext wac) { - this.mockMvc = MockMvcBuilders.webAppContextSetup(wac).build(); - } - - // ... - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitWebConfig(locations = ["test-servlet-context.xml"]) - class AccountTests { - - @Autowired - lateinit var accountService: AccountService - - lateinit mockMvc: MockMvc - - @BeforeEach - fun setup(wac: WebApplicationContext) { - mockMvc = MockMvcBuilders.webAppContextSetup(wac).build() - } - - // ... - - } ----- - -The `standaloneSetup`, on the other hand, is a little closer to a unit test. It tests one -controller at a time. You can manually inject the controller with mock dependencies, and -it does not involve loading Spring configuration. Such tests are more focused on style -and make it easier to see which controller is being tested, whether any specific Spring -MVC configuration is required to work, and so on. The `standaloneSetup` is also a very -convenient way to write ad-hoc tests to verify specific behavior or to debug an issue. - -As with most "`integration versus unit testing`" debates, there is no right or wrong -answer. However, using the `standaloneSetup` does imply the need for additional -`webAppContextSetup` tests in order to verify your Spring MVC configuration. -Alternatively, you can write all your tests with `webAppContextSetup`, in order to always -test against your actual Spring MVC configuration. - -[[spring-mvc-test-server-setup-steps]] -== Setup Features - -No matter which MockMvc builder you use, all `MockMvcBuilder` implementations provide -some common and very useful features. For example, you can declare an `Accept` header for -all requests and expect a status of 200 as well as a `Content-Type` header in all -responses, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // static import of MockMvcBuilders.standaloneSetup - - MockMvc mockMvc = standaloneSetup(new MusicController()) - .defaultRequest(get("/").accept(MediaType.APPLICATION_JSON)) - .alwaysExpect(status().isOk()) - .alwaysExpect(content().contentType("application/json;charset=UTF-8")) - .build(); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ----- - -In addition, third-party frameworks (and applications) can pre-package setup -instructions, such as those in a `MockMvcConfigurer`. The Spring Framework has one such -built-in implementation that helps to save and re-use the HTTP session across requests. -You can use it as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // static import of SharedHttpSessionConfigurer.sharedHttpSession - - MockMvc mockMvc = MockMvcBuilders.standaloneSetup(new TestController()) - .apply(sharedHttpSession()) - .build(); - - // Use mockMvc to perform requests... ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ----- - -See the javadoc for -{api-spring-framework}/test/web/servlet/setup/ConfigurableMockMvcBuilder.html[`ConfigurableMockMvcBuilder`] -for a list of all MockMvc builder features or use the IDE to explore the available options. - -[[spring-mvc-test-server-performing-requests]] -== Performing Requests - -This section shows how to use MockMvc on its own to perform requests and verify responses. -If using MockMvc through the `WebTestClient` please see the corresponding section on -<<webtestclient-tests>> instead. - -To perform requests that use any HTTP method, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // static import of MockMvcRequestBuilders.* - - mockMvc.perform(post("/hotels/{id}", 42).accept(MediaType.APPLICATION_JSON)); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.test.web.servlet.post - - mockMvc.post("/hotels/{id}", 42) { - accept = MediaType.APPLICATION_JSON - } ----- - -You can also perform file upload requests that internally use -`MockMultipartHttpServletRequest` so that there is no actual parsing of a multipart -request. Rather, you have to set it up to be similar to the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - mockMvc.perform(multipart("/doc").file("a1", "ABC".getBytes("UTF-8"))); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.test.web.servlet.multipart - - mockMvc.multipart("/doc") { - file("a1", "ABC".toByteArray(charset("UTF8"))) - } ----- - -You can specify query parameters in URI template style, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - mockMvc.perform(get("/hotels?thing={thing}", "somewhere")); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - mockMvc.get("/hotels?thing={thing}", "somewhere") ----- - -You can also add Servlet request parameters that represent either query or form -parameters, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - mockMvc.perform(get("/hotels").param("thing", "somewhere")); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.test.web.servlet.get - - mockMvc.get("/hotels") { - param("thing", "somewhere") - } ----- - -If application code relies on Servlet request parameters and does not check the query -string explicitly (as is most often the case), it does not matter which option you use. -Keep in mind, however, that query parameters provided with the URI template are decoded -while request parameters provided through the `param(...)` method are expected to already -be decoded. - -In most cases, it is preferable to leave the context path and the Servlet path out of the -request URI. If you must test with the full request URI, be sure to set the `contextPath` -and `servletPath` accordingly so that request mappings work, as the following example -shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - mockMvc.perform(get("/app/main/hotels/{id}").contextPath("/app").servletPath("/main")) ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.test.web.servlet.get - - mockMvc.get("/app/main/hotels/{id}") { - contextPath = "/app" - servletPath = "/main" - } ----- - -In the preceding example, it would be cumbersome to set the `contextPath` and -`servletPath` with every performed request. Instead, you can set up default request -properties, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - class MyWebTests { - - MockMvc mockMvc; - - @BeforeEach - void setup() { - mockMvc = standaloneSetup(new AccountController()) - .defaultRequest(get("/") - .contextPath("/app").servletPath("/main") - .accept(MediaType.APPLICATION_JSON)).build(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ----- - -The preceding properties affect every request performed through the `MockMvc` instance. -If the same property is also specified on a given request, it overrides the default -value. That is why the HTTP method and URI in the default request do not matter, since -they must be specified on every request. - -[[spring-mvc-test-server-defining-expectations]] -== Defining Expectations - -You can define expectations by appending one or more `andExpect(..)` calls after -performing a request, as the following example shows. As soon as one expectation fails, -no other expectations will be asserted. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // static import of MockMvcRequestBuilders.* and MockMvcResultMatchers.* - - mockMvc.perform(get("/accounts/1")).andExpect(status().isOk()); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.test.web.servlet.get - - mockMvc.get("/accounts/1").andExpect { - status { isOk() } - } ----- - -You can define multiple expectations by appending `andExpectAll(..)` after performing a -request, as the following example shows. In contrast to `andExpect(..)`, -`andExpectAll(..)` guarantees that all supplied expectations will be asserted and that -all failures will be tracked and reported. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // static import of MockMvcRequestBuilders.* and MockMvcResultMatchers.* - - mockMvc.perform(get("/accounts/1")).andExpectAll( - status().isOk(), - content().contentType("application/json;charset=UTF-8")); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.test.web.servlet.get - - mockMvc.get("/accounts/1").andExpectAll { - status { isOk() } - content { contentType(APPLICATION_JSON) } - } ----- - -`MockMvcResultMatchers.*` provides a number of expectations, some of which are further -nested with more detailed expectations. - -Expectations fall in two general categories. The first category of assertions verifies -properties of the response (for example, the response status, headers, and content). -These are the most important results to assert. - -The second category of assertions goes beyond the response. These assertions let you -inspect Spring MVC specific aspects, such as which controller method processed the -request, whether an exception was raised and handled, what the content of the model is, -what view was selected, what flash attributes were added, and so on. They also let you -inspect Servlet specific aspects, such as request and session attributes. - -The following test asserts that binding or validation failed: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - mockMvc.perform(post("/persons")) - .andExpect(status().isOk()) - .andExpect(model().attributeHasErrors("person")); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.test.web.servlet.post - - mockMvc.post("/persons").andExpect { - status { isOk() } - model { - attributeHasErrors("person") - } - } ----- - -Many times, when writing tests, it is useful to dump the results of the performed -request. You can do so as follows, where `print()` is a static import from -`MockMvcResultHandlers`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - mockMvc.perform(post("/persons")) - .andDo(print()) - .andExpect(status().isOk()) - .andExpect(model().attributeHasErrors("person")); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.test.web.servlet.post - - mockMvc.post("/persons").andDo { - print() - }.andExpect { - status { isOk() } - model { - attributeHasErrors("person") - } - } ----- - -As long as request processing does not cause an unhandled exception, the `print()` method -prints all the available result data to `System.out`. There is also a `log()` method and -two additional variants of the `print()` method, one that accepts an `OutputStream` and -one that accepts a `Writer`. For example, invoking `print(System.err)` prints the result -data to `System.err`, while invoking `print(myWriter)` prints the result data to a custom -writer. If you want to have the result data logged instead of printed, you can invoke the -`log()` method, which logs the result data as a single `DEBUG` message under the -`org.springframework.test.web.servlet.result` logging category. - -In some cases, you may want to get direct access to the result and verify something that -cannot be verified otherwise. This can be achieved by appending `.andReturn()` after all -other expectations, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - MvcResult mvcResult = mockMvc.perform(post("/persons")).andExpect(status().isOk()).andReturn(); - // ... ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - var mvcResult = mockMvc.post("/persons").andExpect { status { isOk() } }.andReturn() - // ... ----- - -If all tests repeat the same expectations, you can set up common expectations once when -building the `MockMvc` instance, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - standaloneSetup(new SimpleController()) - .alwaysExpect(status().isOk()) - .alwaysExpect(content().contentType("application/json;charset=UTF-8")) - .build() ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ----- - -Note that common expectations are always applied and cannot be overridden without -creating a separate `MockMvc` instance. - -When a JSON response content contains hypermedia links created with -https://github.com/spring-projects/spring-hateoas[Spring HATEOAS], you can verify the -resulting links by using JsonPath expressions, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - mockMvc.perform(get("/people").accept(MediaType.APPLICATION_JSON)) - .andExpect(jsonPath("$.links[?(@.rel == 'self')].href").value("http://localhost:8080/people")); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - mockMvc.get("/people") { - accept(MediaType.APPLICATION_JSON) - }.andExpect { - jsonPath("$.links[?(@.rel == 'self')].href") { - value("http://localhost:8080/people") - } - } ----- - -When XML response content contains hypermedia links created with -https://github.com/spring-projects/spring-hateoas[Spring HATEOAS], you can verify the -resulting links by using XPath expressions: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Map<String, String> ns = Collections.singletonMap("ns", "http://www.w3.org/2005/Atom"); - mockMvc.perform(get("/handle").accept(MediaType.APPLICATION_XML)) - .andExpect(xpath("/person/ns:link[@rel='self']/@href", ns).string("http://localhost:8080/people")); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val ns = mapOf("ns" to "http://www.w3.org/2005/Atom") - mockMvc.get("/handle") { - accept(MediaType.APPLICATION_XML) - }.andExpect { - xpath("/person/ns:link[@rel='self']/@href", ns) { - string("http://localhost:8080/people") - } - } ----- - -[[spring-mvc-test-async-requests]] -== Async Requests - -This section shows how to use MockMvc on its own to test asynchronous request handling. -If using MockMvc through the <<webtestclient>>, there is nothing special to do to make -asynchronous requests work as the `WebTestClient` automatically does what is described -in this section. - -Servlet asynchronous requests, <<web.adoc#mvc-ann-async,supported in Spring MVC>>, -work by exiting the Servlet container thread and allowing the application to compute -the response asynchronously, after which an async dispatch is made to complete -processing on a Servlet container thread. - -In Spring MVC Test, async requests can be tested by asserting the produced async value -first, then manually performing the async dispatch, and finally verifying the response. -Below is an example test for controller methods that return `DeferredResult`, `Callable`, -or reactive type such as Reactor `Mono`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // static import of MockMvcRequestBuilders.* and MockMvcResultMatchers.* - - @Test - void test() throws Exception { - MvcResult mvcResult = this.mockMvc.perform(get("/path")) - .andExpect(status().isOk()) <1> - .andExpect(request().asyncStarted()) <2> - .andExpect(request().asyncResult("body")) <3> - .andReturn(); - - this.mockMvc.perform(asyncDispatch(mvcResult)) <4> - .andExpect(status().isOk()) <5> - .andExpect(content().string("body")); - } ----- -<1> Check response status is still unchanged -<2> Async processing must have started -<3> Wait and assert the async result -<4> Manually perform an ASYNC dispatch (as there is no running container) -<5> Verify the final response - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Test - fun test() { - var mvcResult = mockMvc.get("/path").andExpect { - status { isOk() } // <1> - request { asyncStarted() } // <2> - // TODO Remove unused generic parameter - request { asyncResult<Nothing>("body") } // <3> - }.andReturn() - - - mockMvc.perform(asyncDispatch(mvcResult)) // <4> - .andExpect { - status { isOk() } // <5> - content().string("body") - } - } ----- -<1> Check response status is still unchanged -<2> Async processing must have started -<3> Wait and assert the async result -<4> Manually perform an ASYNC dispatch (as there is no running container) -<5> Verify the final response - - -[[spring-mvc-test-vs-streaming-response]] -== Streaming Responses - -The best way to test streaming responses such as Server-Sent Events is through the -<<WebTestClient>> which can be used as a test client to connect to a `MockMvc` instance -to perform tests on Spring MVC controllers without a running server. For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebTestClient client = MockMvcWebTestClient.bindToController(new SseController()).build(); - - FluxExchangeResult<Person> exchangeResult = client.get() - .uri("/persons") - .exchange() - .expectStatus().isOk() - .expectHeader().contentType("text/event-stream") - .returnResult(Person.class); - - // Use StepVerifier from Project Reactor to test the streaming response - - StepVerifier.create(exchangeResult.getResponseBody()) - .expectNext(new Person("N0"), new Person("N1"), new Person("N2")) - .expectNextCount(4) - .consumeNextWith(person -> assertThat(person.getName()).endsWith("7")) - .thenCancel() - .verify(); ----- - -`WebTestClient` can also connect to a live server and perform full end-to-end integration -tests. This is also supported in Spring Boot where you can -{docs-spring-boot}/html/spring-boot-features.html#boot-features-testing-spring-boot-applications-testing-with-running-server[test a running server]. - - -[[spring-mvc-test-server-filters]] -== Filter Registrations - -When setting up a `MockMvc` instance, you can register one or more Servlet `Filter` -instances, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - mockMvc = standaloneSetup(new PersonController()).addFilters(new CharacterEncodingFilter()).build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ----- - -Registered filters are invoked through the `MockFilterChain` from `spring-test`, and the -last filter delegates to the `DispatcherServlet`. - - -[[spring-mvc-test-vs-end-to-end-integration-tests]] -== MockMvc vs End-to-End Tests - -MockMVc is built on Servlet API mock implementations from the -`spring-test` module and does not rely on a running container. Therefore, there are -some differences when compared to full end-to-end integration tests with an actual -client and a live server running. - -The easiest way to think about this is by starting with a blank `MockHttpServletRequest`. -Whatever you add to it is what the request becomes. Things that may catch you by surprise -are that there is no context path by default; no `jsessionid` cookie; no forwarding, -error, or async dispatches; and, therefore, no actual JSP rendering. Instead, -"`forwarded`" and "`redirected`" URLs are saved in the `MockHttpServletResponse` and can -be asserted with expectations. - -This means that, if you use JSPs, you can verify the JSP page to which the request was -forwarded, but no HTML is rendered. In other words, the JSP is not invoked. Note, -however, that all other rendering technologies that do not rely on forwarding, such as -Thymeleaf and Freemarker, render HTML to the response body as expected. The same is true -for rendering JSON, XML, and other formats through `@ResponseBody` methods. - -Alternatively, you may consider the full end-to-end integration testing support from -Spring Boot with `@SpringBootTest`. See the -{docs-spring-boot}/html/spring-boot-features.html#boot-features-testing[Spring Boot Reference Guide]. - -There are pros and cons for each approach. The options provided in Spring MVC Test are -different stops on the scale from classic unit testing to full integration testing. To be -certain, none of the options in Spring MVC Test fall under the category of classic unit -testing, but they are a little closer to it. For example, you can isolate the web layer -by injecting mocked services into controllers, in which case you are testing the web -layer only through the `DispatcherServlet` but with actual Spring configuration, as you -might test the data access layer in isolation from the layers above it. Also, you can use -the stand-alone setup, focusing on one controller at a time and manually providing the -configuration required to make it work. - -Another important distinction when using Spring MVC Test is that, conceptually, such -tests are the server-side, so you can check what handler was used, if an exception was -handled with a HandlerExceptionResolver, what the content of the model is, what binding -errors there were, and other details. That means that it is easier to write expectations, -since the server is not an opaque box, as it is when testing it through an actual HTTP -client. This is generally an advantage of classic unit testing: It is easier to write, -reason about, and debug but does not replace the need for full integration tests. At the -same time, it is important not to lose sight of the fact that the response is the most -important thing to check. In short, there is room here for multiple styles and strategies -of testing even within the same project. - -[[spring-mvc-test-server-resources]] -== Further Examples - -The framework's own tests include -{spring-framework-main-code}/spring-test/src/test/java/org/springframework/test/web/servlet/samples[ -many sample tests] intended to show how to use MockMvc on its own or through the -{spring-framework-main-code}/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client[ -WebTestClient]. Browse these examples for further ideas. - - -[[spring-mvc-test-server-htmlunit]] -== HtmlUnit Integration - -Spring provides integration between <<spring-mvc-test-server, MockMvc>> and -https://htmlunit.sourceforge.io/[HtmlUnit]. This simplifies performing end-to-end testing -when using HTML-based views. This integration lets you: - -* Easily test HTML pages by using tools such as - https://htmlunit.sourceforge.io/[HtmlUnit], - https://www.seleniumhq.org[WebDriver], and - https://www.gebish.org/manual/current/#spock-junit-testng[Geb] without the need to - deploy to a Servlet container. -* Test JavaScript within pages. -* Optionally, test using mock services to speed up testing. -* Share logic between in-container end-to-end tests and out-of-container integration tests. - -NOTE: MockMvc works with templating technologies that do not rely on a Servlet Container -(for example, Thymeleaf, FreeMarker, and others), but it does not work with JSPs, since -they rely on the Servlet container. - -[[spring-mvc-test-server-htmlunit-why]] -=== Why HtmlUnit Integration? - -The most obvious question that comes to mind is "`Why do I need this?`" The answer is -best found by exploring a very basic sample application. Assume you have a Spring MVC web -application that supports CRUD operations on a `Message` object. The application also -supports paging through all messages. How would you go about testing it? - -With Spring MVC Test, we can easily test if we are able to create a `Message`, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - MockHttpServletRequestBuilder createMessage = post("/messages/") - .param("summary", "Spring Rocks") - .param("text", "In case you didn't know, Spring Rocks!"); - - mockMvc.perform(createMessage) - .andExpect(status().is3xxRedirection()) - .andExpect(redirectedUrl("/messages/123")); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Test - fun test() { - mockMvc.post("/messages/") { - param("summary", "Spring Rocks") - param("text", "In case you didn't know, Spring Rocks!") - }.andExpect { - status().is3xxRedirection() - redirectedUrl("/messages/123") - } - } ----- - -What if we want to test the form view that lets us create the message? For example, -assume our form looks like the following snippet: - -[source,xml,indent=0] ----- - <form id="messageForm" action="/messages/" method="post"> - <div class="pull-right"><a href="/messages/">Messages</a></div> - - <label for="summary">Summary</label> - <input type="text" class="required" id="summary" name="summary" value="" /> - - <label for="text">Message</label> - <textarea id="text" name="text"></textarea> - - <div class="form-actions"> - <input type="submit" value="Create" /> - </div> - </form> ----- - -How do we ensure that our form produce the correct request to create a new message? A -naive attempt might resemble the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - mockMvc.perform(get("/messages/form")) - .andExpect(xpath("//input[@name='summary']").exists()) - .andExpect(xpath("//textarea[@name='text']").exists()); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - mockMvc.get("/messages/form").andExpect { - xpath("//input[@name='summary']") { exists() } - xpath("//textarea[@name='text']") { exists() } - } ----- - -This test has some obvious drawbacks. If we update our controller to use the parameter -`message` instead of `text`, our form test continues to pass, even though the HTML form -is out of synch with the controller. To resolve this we can combine our two tests, as -follows: - -[[spring-mvc-test-server-htmlunit-mock-mvc-test]] -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - String summaryParamName = "summary"; - String textParamName = "text"; - mockMvc.perform(get("/messages/form")) - .andExpect(xpath("//input[@name='" + summaryParamName + "']").exists()) - .andExpect(xpath("//textarea[@name='" + textParamName + "']").exists()); - - MockHttpServletRequestBuilder createMessage = post("/messages/") - .param(summaryParamName, "Spring Rocks") - .param(textParamName, "In case you didn't know, Spring Rocks!"); - - mockMvc.perform(createMessage) - .andExpect(status().is3xxRedirection()) - .andExpect(redirectedUrl("/messages/123")); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val summaryParamName = "summary"; - val textParamName = "text"; - mockMvc.get("/messages/form").andExpect { - xpath("//input[@name='$summaryParamName']") { exists() } - xpath("//textarea[@name='$textParamName']") { exists() } - } - mockMvc.post("/messages/") { - param(summaryParamName, "Spring Rocks") - param(textParamName, "In case you didn't know, Spring Rocks!") - }.andExpect { - status().is3xxRedirection() - redirectedUrl("/messages/123") - } ----- - -This would reduce the risk of our test incorrectly passing, but there are still some -problems: - -* What if we have multiple forms on our page? Admittedly, we could update our XPath - expressions, but they get more complicated as we take more factors into account: Are - the fields the correct type? Are the fields enabled? And so on. -* Another issue is that we are doing double the work we would expect. We must first - verify the view, and then we submit the view with the same parameters we just verified. - Ideally, this could be done all at once. -* Finally, we still cannot account for some things. For example, what if the form has - JavaScript validation that we wish to test as well? - -The overall problem is that testing a web page does not involve a single interaction. -Instead, it is a combination of how the user interacts with a web page and how that web -page interacts with other resources. For example, the result of a form view is used as -the input to a user for creating a message. In addition, our form view can potentially -use additional resources that impact the behavior of the page, such as JavaScript -validation. - -[[spring-mvc-test-server-htmlunit-why-integration]] -==== Integration Testing to the Rescue? - -To resolve the issues mentioned earlier, we could perform end-to-end integration testing, -but this has some drawbacks. Consider testing the view that lets us page through the -messages. We might need the following tests: - -* Does our page display a notification to the user to indicate that no results are - available when the messages are empty? -* Does our page properly display a single message? -* Does our page properly support paging? - -To set up these tests, we need to ensure our database contains the proper messages. This -leads to a number of additional challenges: - -* Ensuring the proper messages are in the database can be tedious. (Consider foreign key - constraints.) -* Testing can become slow, since each test would need to ensure that the database is in - the correct state. -* Since our database needs to be in a specific state, we cannot run tests in parallel. -* Performing assertions on such items as auto-generated IDs, timestamps, and others can - be difficult. - -These challenges do not mean that we should abandon end-to-end integration testing -altogether. Instead, we can reduce the number of end-to-end integration tests by -refactoring our detailed tests to use mock services that run much faster, more reliably, -and without side effects. We can then implement a small number of true end-to-end -integration tests that validate simple workflows to ensure that everything works together -properly. - -[[spring-mvc-test-server-htmlunit-why-mockmvc]] -==== Enter HtmlUnit Integration - -So how can we achieve a balance between testing the interactions of our pages and still -retain good performance within our test suite? The answer is: "`By integrating MockMvc -with HtmlUnit.`" - -[[spring-mvc-test-server-htmlunit-options]] -==== HtmlUnit Integration Options - -You have a number of options when you want to integrate MockMvc with HtmlUnit: - -* <<spring-mvc-test-server-htmlunit-mah,MockMvc and HtmlUnit>>: Use this option if you - want to use the raw HtmlUnit libraries. -* <<spring-mvc-test-server-htmlunit-webdriver,MockMvc and WebDriver>>: Use this option to - ease development and reuse code between integration and end-to-end testing. -* <<spring-mvc-test-server-htmlunit-geb,MockMvc and Geb>>: Use this option if you want to - use Groovy for testing, ease development, and reuse code between integration and - end-to-end testing. - -[[spring-mvc-test-server-htmlunit-mah]] -=== MockMvc and HtmlUnit - -This section describes how to integrate MockMvc and HtmlUnit. Use this option if you want -to use the raw HtmlUnit libraries. - -[[spring-mvc-test-server-htmlunit-mah-setup]] -==== MockMvc and HtmlUnit Setup - -First, make sure that you have included a test dependency on -`net.sourceforge.htmlunit:htmlunit`. In order to use HtmlUnit with Apache HttpComponents -4.5+, you need to use HtmlUnit 2.18 or higher. - -We can easily create an HtmlUnit `WebClient` that integrates with MockMvc by using the -`MockMvcWebClientBuilder`, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient webClient; - - @BeforeEach - void setup(WebApplicationContext context) { - webClient = MockMvcWebClientBuilder - .webAppContextSetup(context) - .build(); - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - lateinit var webClient: WebClient - - @BeforeEach - fun setup(context: WebApplicationContext) { - webClient = MockMvcWebClientBuilder - .webAppContextSetup(context) - .build() - } ----- - -NOTE: This is a simple example of using `MockMvcWebClientBuilder`. For advanced usage, -see <<spring-mvc-test-server-htmlunit-mah-advanced-builder>>. - -This ensures that any URL that references `localhost` as the server is directed to our -`MockMvc` instance without the need for a real HTTP connection. Any other URL is -requested by using a network connection, as normal. This lets us easily test the use of -CDNs. - -[[spring-mvc-test-server-htmlunit-mah-usage]] -==== MockMvc and HtmlUnit Usage - -Now we can use HtmlUnit as we normally would but without the need to deploy our -application to a Servlet container. For example, we can request the view to create a -message with the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HtmlPage createMsgFormPage = webClient.getPage("http://localhost/messages/form"); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val createMsgFormPage = webClient.getPage("http://localhost/messages/form") ----- - -NOTE: The default context path is `""`. Alternatively, we can specify the context path, -as described in <<spring-mvc-test-server-htmlunit-mah-advanced-builder>>. - -Once we have a reference to the `HtmlPage`, we can then fill out the form and submit it -to create a message, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HtmlForm form = createMsgFormPage.getHtmlElementById("messageForm"); - HtmlTextInput summaryInput = createMsgFormPage.getHtmlElementById("summary"); - summaryInput.setValueAttribute("Spring Rocks"); - HtmlTextArea textInput = createMsgFormPage.getHtmlElementById("text"); - textInput.setText("In case you didn't know, Spring Rocks!"); - HtmlSubmitInput submit = form.getOneHtmlElementByAttribute("input", "type", "submit"); - HtmlPage newMessagePage = submit.click(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val form = createMsgFormPage.getHtmlElementById("messageForm") - val summaryInput = createMsgFormPage.getHtmlElementById("summary") - summaryInput.setValueAttribute("Spring Rocks") - val textInput = createMsgFormPage.getHtmlElementById("text") - textInput.setText("In case you didn't know, Spring Rocks!") - val submit = form.getOneHtmlElementByAttribute("input", "type", "submit") - val newMessagePage = submit.click() ----- - -Finally, we can verify that a new message was created successfully. The following -assertions use the https://assertj.github.io/doc/[AssertJ] library: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - assertThat(newMessagePage.getUrl().toString()).endsWith("/messages/123"); - String id = newMessagePage.getHtmlElementById("id").getTextContent(); - assertThat(id).isEqualTo("123"); - String summary = newMessagePage.getHtmlElementById("summary").getTextContent(); - assertThat(summary).isEqualTo("Spring Rocks"); - String text = newMessagePage.getHtmlElementById("text").getTextContent(); - assertThat(text).isEqualTo("In case you didn't know, Spring Rocks!"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - assertThat(newMessagePage.getUrl().toString()).endsWith("/messages/123") - val id = newMessagePage.getHtmlElementById("id").getTextContent() - assertThat(id).isEqualTo("123") - val summary = newMessagePage.getHtmlElementById("summary").getTextContent() - assertThat(summary).isEqualTo("Spring Rocks") - val text = newMessagePage.getHtmlElementById("text").getTextContent() - assertThat(text).isEqualTo("In case you didn't know, Spring Rocks!") ----- - -The preceding code improves on our -<<spring-mvc-test-server-htmlunit-mock-mvc-test, MockMvc test>> in a number of ways. -First, we no longer have to explicitly verify our form and then create a request that -looks like the form. Instead, we request the form, fill it out, and submit it, thereby -significantly reducing the overhead. - -Another important factor is that https://htmlunit.sourceforge.io/javascript.html[HtmlUnit -uses the Mozilla Rhino engine] to evaluate JavaScript. This means that we can also test -the behavior of JavaScript within our pages. - -See the https://htmlunit.sourceforge.io/gettingStarted.html[HtmlUnit documentation] for -additional information about using HtmlUnit. - -[[spring-mvc-test-server-htmlunit-mah-advanced-builder]] -==== Advanced `MockMvcWebClientBuilder` - -In the examples so far, we have used `MockMvcWebClientBuilder` in the simplest way -possible, by building a `WebClient` based on the `WebApplicationContext` loaded for us by -the Spring TestContext Framework. This approach is repeated in the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient webClient; - - @BeforeEach - void setup(WebApplicationContext context) { - webClient = MockMvcWebClientBuilder - .webAppContextSetup(context) - .build(); - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - lateinit var webClient: WebClient - - @BeforeEach - fun setup(context: WebApplicationContext) { - webClient = MockMvcWebClientBuilder - .webAppContextSetup(context) - .build() - } ----- - -We can also specify additional configuration options, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient webClient; - - @BeforeEach - void setup() { - webClient = MockMvcWebClientBuilder - // demonstrates applying a MockMvcConfigurer (Spring Security) - .webAppContextSetup(context, springSecurity()) - // for illustration only - defaults to "" - .contextPath("") - // By default MockMvc is used for localhost only; - // the following will use MockMvc for example.com and example.org as well - .useMockMvcForHosts("example.com","example.org") - .build(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - lateinit var webClient: WebClient - - @BeforeEach - fun setup() { - webClient = MockMvcWebClientBuilder - // demonstrates applying a MockMvcConfigurer (Spring Security) - .webAppContextSetup(context, springSecurity()) - // for illustration only - defaults to "" - .contextPath("") - // By default MockMvc is used for localhost only; - // the following will use MockMvc for example.com and example.org as well - .useMockMvcForHosts("example.com","example.org") - .build() - } ----- - -As an alternative, we can perform the exact same setup by configuring the `MockMvc` -instance separately and supplying it to the `MockMvcWebClientBuilder`, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - MockMvc mockMvc = MockMvcBuilders - .webAppContextSetup(context) - .apply(springSecurity()) - .build(); - - webClient = MockMvcWebClientBuilder - .mockMvcSetup(mockMvc) - // for illustration only - defaults to "" - .contextPath("") - // By default MockMvc is used for localhost only; - // the following will use MockMvc for example.com and example.org as well - .useMockMvcForHosts("example.com","example.org") - .build(); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ----- - -This is more verbose, but, by building the `WebClient` with a `MockMvc` instance, we have -the full power of MockMvc at our fingertips. - -TIP: For additional information on creating a `MockMvc` instance, see -<<spring-mvc-test-server-setup-options>>. - -[[spring-mvc-test-server-htmlunit-webdriver]] -=== MockMvc and WebDriver - -In the previous sections, we have seen how to use MockMvc in conjunction with the raw -HtmlUnit APIs. In this section, we use additional abstractions within the Selenium -https://docs.seleniumhq.org/projects/webdriver/[WebDriver] to make things even easier. - -[[spring-mvc-test-server-htmlunit-webdriver-why]] -==== Why WebDriver and MockMvc? - -We can already use HtmlUnit and MockMvc, so why would we want to use WebDriver? The -Selenium WebDriver provides a very elegant API that lets us easily organize our code. To -better show how it works, we explore an example in this section. - -NOTE: Despite being a part of https://docs.seleniumhq.org/[Selenium], WebDriver does not -require a Selenium Server to run your tests. - -Suppose we need to ensure that a message is created properly. The tests involve finding -the HTML form input elements, filling them out, and making various assertions. - -This approach results in numerous separate tests because we want to test error conditions -as well. For example, we want to ensure that we get an error if we fill out only part of -the form. If we fill out the entire form, the newly created message should be displayed -afterwards. - -If one of the fields were named "`summary`", we might have something that resembles the -following repeated in multiple places within our tests: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HtmlTextInput summaryInput = currentPage.getHtmlElementById("summary"); - summaryInput.setValueAttribute(summary); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val summaryInput = currentPage.getHtmlElementById("summary") - summaryInput.setValueAttribute(summary) ----- - -So what happens if we change the `id` to `smmry`? Doing so would force us to update all -of our tests to incorporate this change. This violates the DRY principle, so we should -ideally extract this code into its own method, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public HtmlPage createMessage(HtmlPage currentPage, String summary, String text) { - setSummary(currentPage, summary); - // ... - } - - public void setSummary(HtmlPage currentPage, String summary) { - HtmlTextInput summaryInput = currentPage.getHtmlElementById("summary"); - summaryInput.setValueAttribute(summary); - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun createMessage(currentPage: HtmlPage, summary:String, text:String) :HtmlPage{ - setSummary(currentPage, summary); - // ... - } - - fun setSummary(currentPage:HtmlPage , summary: String) { - val summaryInput = currentPage.getHtmlElementById("summary") - summaryInput.setValueAttribute(summary) - } ----- - -Doing so ensures that we do not have to update all of our tests if we change the UI. - -We might even take this a step further and place this logic within an `Object` that -represents the `HtmlPage` we are currently on, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class CreateMessagePage { - - final HtmlPage currentPage; - - final HtmlTextInput summaryInput; - - final HtmlSubmitInput submit; - - public CreateMessagePage(HtmlPage currentPage) { - this.currentPage = currentPage; - this.summaryInput = currentPage.getHtmlElementById("summary"); - this.submit = currentPage.getHtmlElementById("submit"); - } - - public <T> T createMessage(String summary, String text) throws Exception { - setSummary(summary); - - HtmlPage result = submit.click(); - boolean error = CreateMessagePage.at(result); - - return (T) (error ? new CreateMessagePage(result) : new ViewMessagePage(result)); - } - - public void setSummary(String summary) throws Exception { - summaryInput.setValueAttribute(summary); - } - - public static boolean at(HtmlPage page) { - return "Create Message".equals(page.getTitleText()); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class CreateMessagePage(private val currentPage: HtmlPage) { - - val summaryInput: HtmlTextInput = currentPage.getHtmlElementById("summary") - - val submit: HtmlSubmitInput = currentPage.getHtmlElementById("submit") - - fun <T> createMessage(summary: String, text: String): T { - setSummary(summary) - - val result = submit.click() - val error = at(result) - - return (if (error) CreateMessagePage(result) else ViewMessagePage(result)) as T - } - - fun setSummary(summary: String) { - summaryInput.setValueAttribute(summary) - } - - fun at(page: HtmlPage): Boolean { - return "Create Message" == page.getTitleText() - } - } -} ----- - -Formerly, this pattern was known as the -https://github.com/SeleniumHQ/selenium/wiki/PageObjects[Page Object Pattern]. While we -can certainly do this with HtmlUnit, WebDriver provides some tools that we explore in the -following sections to make this pattern much easier to implement. - -[[spring-mvc-test-server-htmlunit-webdriver-setup]] -==== MockMvc and WebDriver Setup - -To use Selenium WebDriver with the Spring MVC Test framework, make sure that your project -includes a test dependency on `org.seleniumhq.selenium:selenium-htmlunit-driver`. - -We can easily create a Selenium WebDriver that integrates with MockMvc by using the -`MockMvcHtmlUnitDriverBuilder` as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebDriver driver; - - @BeforeEach - void setup(WebApplicationContext context) { - driver = MockMvcHtmlUnitDriverBuilder - .webAppContextSetup(context) - .build(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - lateinit var driver: WebDriver - - @BeforeEach - fun setup(context: WebApplicationContext) { - driver = MockMvcHtmlUnitDriverBuilder - .webAppContextSetup(context) - .build() - } ----- - -NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced -usage, see <<spring-mvc-test-server-htmlunit-webdriver-advanced-builder>>. - -The preceding example ensures that any URL that references `localhost` as the server is -directed to our `MockMvc` instance without the need for a real HTTP connection. Any other -URL is requested by using a network connection, as normal. This lets us easily test the -use of CDNs. - -[[spring-mvc-test-server-htmlunit-webdriver-usage]] -==== MockMvc and WebDriver Usage - -Now we can use WebDriver as we normally would but without the need to deploy our -application to a Servlet container. For example, we can request the view to create a -message with the following: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - CreateMessagePage page = CreateMessagePage.to(driver); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val page = CreateMessagePage.to(driver) ----- --- - -We can then fill out the form and submit it to create a message, as follows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ViewMessagePage viewMessagePage = - page.createMessage(ViewMessagePage.class, expectedSummary, expectedText); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val viewMessagePage = - page.createMessage(ViewMessagePage::class, expectedSummary, expectedText) ----- --- - -This improves on the design of our <<spring-mvc-test-server-htmlunit-mah-usage, HtmlUnit test>> -by leveraging the Page Object Pattern. As we mentioned in -<<spring-mvc-test-server-htmlunit-webdriver-why>>, we can use the Page Object Pattern -with HtmlUnit, but it is much easier with WebDriver. Consider the following -`CreateMessagePage` implementation: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class CreateMessagePage extends AbstractPage { // <1> - - // <2> - private WebElement summary; - private WebElement text; - - @FindBy(css = "input[type=submit]") // <3> - private WebElement submit; - - public CreateMessagePage(WebDriver driver) { - super(driver); - } - - public <T> T createMessage(Class<T> resultPage, String summary, String details) { - this.summary.sendKeys(summary); - this.text.sendKeys(details); - this.submit.click(); - return PageFactory.initElements(driver, resultPage); - } - - public static CreateMessagePage to(WebDriver driver) { - driver.get("http://localhost:9990/mail/messages/form"); - return PageFactory.initElements(driver, CreateMessagePage.class); - } - } ----- -<1> `CreateMessagePage` extends the `AbstractPage`. We do not go over the details of -`AbstractPage`, but, in summary, it contains common functionality for all of our pages. -For example, if our application has a navigational bar, global error messages, and other -features, we can place this logic in a shared location. -<2> We have a member variable for each of the parts of the HTML page in which we are -interested. These are of type `WebElement`. WebDriver's -https://github.com/SeleniumHQ/selenium/wiki/PageFactory[`PageFactory`] lets us remove a -lot of code from the HtmlUnit version of `CreateMessagePage` by automatically resolving -each `WebElement`. The -https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/support/PageFactory.html#initElements-org.openqa.selenium.WebDriver-java.lang.Class-[`PageFactory#initElements(WebDriver,Class<T>)`] -method automatically resolves each `WebElement` by using the field name and looking it up -by the `id` or `name` of the element within the HTML page. -<3> We can use the -https://github.com/SeleniumHQ/selenium/wiki/PageFactory#making-the-example-work-using-annotations[`@FindBy` annotation] -to override the default lookup behavior. Our example shows how to use the `@FindBy` -annotation to look up our submit button with a `css` selector (`input[type=submit]`). - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class CreateMessagePage(private val driver: WebDriver) : AbstractPage(driver) { // <1> - - // <2> - private lateinit var summary: WebElement - private lateinit var text: WebElement - - @FindBy(css = "input[type=submit]") // <3> - private lateinit var submit: WebElement - - fun <T> createMessage(resultPage: Class<T>, summary: String, details: String): T { - this.summary.sendKeys(summary) - text.sendKeys(details) - submit.click() - return PageFactory.initElements(driver, resultPage) - } - companion object { - fun to(driver: WebDriver): CreateMessagePage { - driver.get("http://localhost:9990/mail/messages/form") - return PageFactory.initElements(driver, CreateMessagePage::class.java) - } - } - } ----- -<1> `CreateMessagePage` extends the `AbstractPage`. We do not go over the details of -`AbstractPage`, but, in summary, it contains common functionality for all of our pages. -For example, if our application has a navigational bar, global error messages, and other -features, we can place this logic in a shared location. -<2> We have a member variable for each of the parts of the HTML page in which we are -interested. These are of type `WebElement`. WebDriver's -https://github.com/SeleniumHQ/selenium/wiki/PageFactory[`PageFactory`] lets us remove a -lot of code from the HtmlUnit version of `CreateMessagePage` by automatically resolving -each `WebElement`. The -https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/support/PageFactory.html#initElements-org.openqa.selenium.WebDriver-java.lang.Class-[`PageFactory#initElements(WebDriver,Class<T>)`] -method automatically resolves each `WebElement` by using the field name and looking it up -by the `id` or `name` of the element within the HTML page. -<3> We can use the -https://github.com/SeleniumHQ/selenium/wiki/PageFactory#making-the-example-work-using-annotations[`@FindBy` annotation] -to override the default lookup behavior. Our example shows how to use the `@FindBy` -annotation to look up our submit button with a `css` selector (*input[type=submit]*). --- - -Finally, we can verify that a new message was created successfully. The following -assertions use the https://assertj.github.io/doc/[AssertJ] assertion library: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - assertThat(viewMessagePage.getMessage()).isEqualTo(expectedMessage); - assertThat(viewMessagePage.getSuccess()).isEqualTo("Successfully created a new message"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - assertThat(viewMessagePage.message).isEqualTo(expectedMessage) - assertThat(viewMessagePage.success).isEqualTo("Successfully created a new message") ----- --- - -We can see that our `ViewMessagePage` lets us interact with our custom domain model. For -example, it exposes a method that returns a `Message` object: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public Message getMessage() throws ParseException { - Message message = new Message(); - message.setId(getId()); - message.setCreated(getCreated()); - message.setSummary(getSummary()); - message.setText(getText()); - return message; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun getMessage() = Message(getId(), getCreated(), getSummary(), getText()) ----- --- - -We can then use the rich domain objects in our assertions. - -Lastly, we must not forget to close the `WebDriver` instance when the test is complete, -as follows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @AfterEach - void destroy() { - if (driver != null) { - driver.close(); - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @AfterEach - fun destroy() { - if (driver != null) { - driver.close() - } - } ----- --- - -For additional information on using WebDriver, see the Selenium -https://github.com/SeleniumHQ/selenium/wiki/Getting-Started[WebDriver documentation]. - -[[spring-mvc-test-server-htmlunit-webdriver-advanced-builder]] -==== Advanced `MockMvcHtmlUnitDriverBuilder` - -In the examples so far, we have used `MockMvcHtmlUnitDriverBuilder` in the simplest way -possible, by building a `WebDriver` based on the `WebApplicationContext` loaded for us by -the Spring TestContext Framework. This approach is repeated here, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebDriver driver; - - @BeforeEach - void setup(WebApplicationContext context) { - driver = MockMvcHtmlUnitDriverBuilder - .webAppContextSetup(context) - .build(); - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - lateinit var driver: WebDriver - - @BeforeEach - fun setup(context: WebApplicationContext) { - driver = MockMvcHtmlUnitDriverBuilder - .webAppContextSetup(context) - .build() - } ----- - -We can also specify additional configuration options, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebDriver driver; - - @BeforeEach - void setup() { - driver = MockMvcHtmlUnitDriverBuilder - // demonstrates applying a MockMvcConfigurer (Spring Security) - .webAppContextSetup(context, springSecurity()) - // for illustration only - defaults to "" - .contextPath("") - // By default MockMvc is used for localhost only; - // the following will use MockMvc for example.com and example.org as well - .useMockMvcForHosts("example.com","example.org") - .build(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - lateinit var driver: WebDriver - - @BeforeEach - fun setup() { - driver = MockMvcHtmlUnitDriverBuilder - // demonstrates applying a MockMvcConfigurer (Spring Security) - .webAppContextSetup(context, springSecurity()) - // for illustration only - defaults to "" - .contextPath("") - // By default MockMvc is used for localhost only; - // the following will use MockMvc for example.com and example.org as well - .useMockMvcForHosts("example.com","example.org") - .build() - } ----- - -As an alternative, we can perform the exact same setup by configuring the `MockMvc` -instance separately and supplying it to the `MockMvcHtmlUnitDriverBuilder`, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - MockMvc mockMvc = MockMvcBuilders - .webAppContextSetup(context) - .apply(springSecurity()) - .build(); - - driver = MockMvcHtmlUnitDriverBuilder - .mockMvcSetup(mockMvc) - // for illustration only - defaults to "" - .contextPath("") - // By default MockMvc is used for localhost only; - // the following will use MockMvc for example.com and example.org as well - .useMockMvcForHosts("example.com","example.org") - .build(); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ----- - -This is more verbose, but, by building the `WebDriver` with a `MockMvc` instance, we have -the full power of MockMvc at our fingertips. - -TIP: For additional information on creating a `MockMvc` instance, see -<<spring-mvc-test-server-setup-options>>. - -[[spring-mvc-test-server-htmlunit-geb]] -=== MockMvc and Geb - -In the previous section, we saw how to use MockMvc with WebDriver. In this section, we -use https://www.gebish.org/[Geb] to make our tests even Groovy-er. - -[[spring-mvc-test-server-htmlunit-geb-why]] -==== Why Geb and MockMvc? - -Geb is backed by WebDriver, so it offers many of the -<<spring-mvc-test-server-htmlunit-webdriver-why, same benefits>> that we get from -WebDriver. However, Geb makes things even easier by taking care of some of the -boilerplate code for us. - -[[spring-mvc-test-server-htmlunit-geb-setup]] -==== MockMvc and Geb Setup - -We can easily initialize a Geb `Browser` with a Selenium WebDriver that uses MockMvc, as -follows: - -[source,groovy] ----- -def setup() { - browser.driver = MockMvcHtmlUnitDriverBuilder - .webAppContextSetup(context) - .build() -} ----- - -NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced -usage, see <<spring-mvc-test-server-htmlunit-webdriver-advanced-builder>>. - -This ensures that any URL referencing `localhost` as the server is directed to our -`MockMvc` instance without the need for a real HTTP connection. Any other URL is -requested by using a network connection as normal. This lets us easily test the use of -CDNs. - -[[spring-mvc-test-server-htmlunit-geb-usage]] -==== MockMvc and Geb Usage - -Now we can use Geb as we normally would but without the need to deploy our application to -a Servlet container. For example, we can request the view to create a message with the -following: - -[source,groovy] ----- -to CreateMessagePage ----- - -We can then fill out the form and submit it to create a message, as follows: - -[source,groovy] ----- -when: -form.summary = expectedSummary -form.text = expectedMessage -submit.click(ViewMessagePage) ----- - -Any unrecognized method calls or property accesses or references that are not found are -forwarded to the current page object. This removes a lot of the boilerplate code we -needed when using WebDriver directly. - -As with direct WebDriver usage, this improves on the design of our -<<spring-mvc-test-server-htmlunit-mah-usage, HtmlUnit test>> by using the Page Object -Pattern. As mentioned previously, we can use the Page Object Pattern with HtmlUnit and -WebDriver, but it is even easier with Geb. Consider our new Groovy-based -`CreateMessagePage` implementation: - -[source,groovy] ----- -class CreateMessagePage extends Page { - static url = 'messages/form' - static at = { assert title == 'Messages : Create'; true } - static content = { - submit { $('input[type=submit]') } - form { $('form') } - errors(required:false) { $('label.error, .alert-error')?.text() } - } -} ----- - -Our `CreateMessagePage` extends `Page`. We do not go over the details of `Page`, but, in -summary, it contains common functionality for all of our pages. We define a URL in which -this page can be found. This lets us navigate to the page, as follows: - -[source,groovy] ----- -to CreateMessagePage ----- - -We also have an `at` closure that determines if we are at the specified page. It should -return `true` if we are on the correct page. This is why we can assert that we are on the -correct page, as follows: - -[source,groovy] ----- -then: -at CreateMessagePage -errors.contains('This field is required.') ----- - -NOTE: We use an assertion in the closure so that we can determine where things went wrong -if we were at the wrong page. - -Next, we create a `content` closure that specifies all the areas of interest within the -page. We can use a -https://www.gebish.org/manual/current/#the-jquery-ish-navigator-api[jQuery-ish Navigator -API] to select the content in which we are interested. - -Finally, we can verify that a new message was created successfully, as follows: - -[source,groovy] ----- -then: -at ViewMessagePage -success == 'Successfully created a new message' -id -date -summary == expectedSummary -message == expectedMessage ----- - -For further details on how to get the most out of Geb, see -https://www.gebish.org/manual/current/[The Book of Geb] user's manual. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc new file mode 100644 index 000000000000..b6b4f06ff1b1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc @@ -0,0 +1,69 @@ +[[spring-mvc-test-async-requests]] += Async Requests + +This section shows how to use MockMvc on its own to test asynchronous request handling. +If using MockMvc through the <<webtestclient>>, there is nothing special to do to make +asynchronous requests work as the `WebTestClient` automatically does what is described +in this section. + +Servlet asynchronous requests, <<web.adoc#mvc-ann-async,supported in Spring MVC>>, +work by exiting the Servlet container thread and allowing the application to compute +the response asynchronously, after which an async dispatch is made to complete +processing on a Servlet container thread. + +In Spring MVC Test, async requests can be tested by asserting the produced async value +first, then manually performing the async dispatch, and finally verifying the response. +Below is an example test for controller methods that return `DeferredResult`, `Callable`, +or reactive type such as Reactor `Mono`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // static import of MockMvcRequestBuilders.* and MockMvcResultMatchers.* + + @Test + void test() throws Exception { + MvcResult mvcResult = this.mockMvc.perform(get("/path")) + .andExpect(status().isOk()) <1> + .andExpect(request().asyncStarted()) <2> + .andExpect(request().asyncResult("body")) <3> + .andReturn(); + + this.mockMvc.perform(asyncDispatch(mvcResult)) <4> + .andExpect(status().isOk()) <5> + .andExpect(content().string("body")); + } +---- +<1> Check response status is still unchanged +<2> Async processing must have started +<3> Wait and assert the async result +<4> Manually perform an ASYNC dispatch (as there is no running container) +<5> Verify the final response + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Test + fun test() { + var mvcResult = mockMvc.get("/path").andExpect { + status { isOk() } // <1> + request { asyncStarted() } // <2> + // TODO Remove unused generic parameter + request { asyncResult<Nothing>("body") } // <3> + }.andReturn() + + + mockMvc.perform(asyncDispatch(mvcResult)) // <4> + .andExpect { + status { isOk() } // <5> + content().string("body") + } + } +---- +<1> Check response status is still unchanged +<2> Async processing must have started +<3> Wait and assert the async result +<4> Manually perform an ASYNC dispatch (as there is no running container) +<5> Verify the final response + + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-defining-expectations.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-defining-expectations.adoc new file mode 100644 index 000000000000..a558611599d9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-defining-expectations.adoc @@ -0,0 +1,210 @@ +[[spring-mvc-test-server-defining-expectations]] += Defining Expectations + +You can define expectations by appending one or more `andExpect(..)` calls after +performing a request, as the following example shows. As soon as one expectation fails, +no other expectations will be asserted. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // static import of MockMvcRequestBuilders.* and MockMvcResultMatchers.* + + mockMvc.perform(get("/accounts/1")).andExpect(status().isOk()); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.test.web.servlet.get + + mockMvc.get("/accounts/1").andExpect { + status { isOk() } + } +---- + +You can define multiple expectations by appending `andExpectAll(..)` after performing a +request, as the following example shows. In contrast to `andExpect(..)`, +`andExpectAll(..)` guarantees that all supplied expectations will be asserted and that +all failures will be tracked and reported. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // static import of MockMvcRequestBuilders.* and MockMvcResultMatchers.* + + mockMvc.perform(get("/accounts/1")).andExpectAll( + status().isOk(), + content().contentType("application/json;charset=UTF-8")); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.test.web.servlet.get + + mockMvc.get("/accounts/1").andExpectAll { + status { isOk() } + content { contentType(APPLICATION_JSON) } + } +---- + +`MockMvcResultMatchers.*` provides a number of expectations, some of which are further +nested with more detailed expectations. + +Expectations fall in two general categories. The first category of assertions verifies +properties of the response (for example, the response status, headers, and content). +These are the most important results to assert. + +The second category of assertions goes beyond the response. These assertions let you +inspect Spring MVC specific aspects, such as which controller method processed the +request, whether an exception was raised and handled, what the content of the model is, +what view was selected, what flash attributes were added, and so on. They also let you +inspect Servlet specific aspects, such as request and session attributes. + +The following test asserts that binding or validation failed: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + mockMvc.perform(post("/persons")) + .andExpect(status().isOk()) + .andExpect(model().attributeHasErrors("person")); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.test.web.servlet.post + + mockMvc.post("/persons").andExpect { + status { isOk() } + model { + attributeHasErrors("person") + } + } +---- + +Many times, when writing tests, it is useful to dump the results of the performed +request. You can do so as follows, where `print()` is a static import from +`MockMvcResultHandlers`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + mockMvc.perform(post("/persons")) + .andDo(print()) + .andExpect(status().isOk()) + .andExpect(model().attributeHasErrors("person")); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.test.web.servlet.post + + mockMvc.post("/persons").andDo { + print() + }.andExpect { + status { isOk() } + model { + attributeHasErrors("person") + } + } +---- + +As long as request processing does not cause an unhandled exception, the `print()` method +prints all the available result data to `System.out`. There is also a `log()` method and +two additional variants of the `print()` method, one that accepts an `OutputStream` and +one that accepts a `Writer`. For example, invoking `print(System.err)` prints the result +data to `System.err`, while invoking `print(myWriter)` prints the result data to a custom +writer. If you want to have the result data logged instead of printed, you can invoke the +`log()` method, which logs the result data as a single `DEBUG` message under the +`org.springframework.test.web.servlet.result` logging category. + +In some cases, you may want to get direct access to the result and verify something that +cannot be verified otherwise. This can be achieved by appending `.andReturn()` after all +other expectations, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + MvcResult mvcResult = mockMvc.perform(post("/persons")).andExpect(status().isOk()).andReturn(); + // ... +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + var mvcResult = mockMvc.post("/persons").andExpect { status { isOk() } }.andReturn() + // ... +---- + +If all tests repeat the same expectations, you can set up common expectations once when +building the `MockMvc` instance, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + standaloneSetup(new SimpleController()) + .alwaysExpect(status().isOk()) + .alwaysExpect(content().contentType("application/json;charset=UTF-8")) + .build() +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed +---- + +Note that common expectations are always applied and cannot be overridden without +creating a separate `MockMvc` instance. + +When a JSON response content contains hypermedia links created with +https://github.com/spring-projects/spring-hateoas[Spring HATEOAS], you can verify the +resulting links by using JsonPath expressions, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + mockMvc.perform(get("/people").accept(MediaType.APPLICATION_JSON)) + .andExpect(jsonPath("$.links[?(@.rel == 'self')].href").value("http://localhost:8080/people")); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + mockMvc.get("/people") { + accept(MediaType.APPLICATION_JSON) + }.andExpect { + jsonPath("$.links[?(@.rel == 'self')].href") { + value("http://localhost:8080/people") + } + } +---- + +When XML response content contains hypermedia links created with +https://github.com/spring-projects/spring-hateoas[Spring HATEOAS], you can verify the +resulting links by using XPath expressions: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Map<String, String> ns = Collections.singletonMap("ns", "http://www.w3.org/2005/Atom"); + mockMvc.perform(get("/handle").accept(MediaType.APPLICATION_XML)) + .andExpect(xpath("/person/ns:link[@rel='self']/@href", ns).string("http://localhost:8080/people")); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val ns = mapOf("ns" to "http://www.w3.org/2005/Atom") + mockMvc.get("/handle") { + accept(MediaType.APPLICATION_XML) + }.andExpect { + xpath("/person/ns:link[@rel='self']/@href", ns) { + string("http://localhost:8080/people") + } + } +---- + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc new file mode 100644 index 000000000000..4dd5c1abd347 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc @@ -0,0 +1,21 @@ +[[spring-mvc-test-server-filters]] += Filter Registrations + +When setting up a `MockMvc` instance, you can register one or more Servlet `Filter` +instances, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + mockMvc = standaloneSetup(new PersonController()).addFilters(new CharacterEncodingFilter()).build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed +---- + +Registered filters are invoked through the `MockFilterChain` from `spring-test`, and the +last filter delegates to the `DispatcherServlet`. + + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc new file mode 100644 index 000000000000..579c3e5e97fa --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc @@ -0,0 +1,20 @@ +[[spring-mvc-test-server-htmlunit]] += HtmlUnit Integration + +Spring provides integration between <<spring-mvc-test-server, MockMvc>> and +https://htmlunit.sourceforge.io/[HtmlUnit]. This simplifies performing end-to-end testing +when using HTML-based views. This integration lets you: + +* Easily test HTML pages by using tools such as + https://htmlunit.sourceforge.io/[HtmlUnit], + https://www.seleniumhq.org[WebDriver], and + https://www.gebish.org/manual/current/#spock-junit-testng[Geb] without the need to + deploy to a Servlet container. +* Test JavaScript within pages. +* Optionally, test using mock services to speed up testing. +* Share logic between in-container end-to-end tests and out-of-container integration tests. + +NOTE: MockMvc works with templating technologies that do not rely on a Servlet Container +(for example, Thymeleaf, FreeMarker, and others), but it does not work with JSPs, since +they rely on the Servlet container. + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc new file mode 100644 index 000000000000..39d603320172 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc @@ -0,0 +1,125 @@ +[[spring-mvc-test-server-htmlunit-geb]] += MockMvc and Geb + +In the previous section, we saw how to use MockMvc with WebDriver. In this section, we +use https://www.gebish.org/[Geb] to make our tests even Groovy-er. + +[[spring-mvc-test-server-htmlunit-geb-why]] +== Why Geb and MockMvc? + +Geb is backed by WebDriver, so it offers many of the +<<spring-mvc-test-server-htmlunit-webdriver-why, same benefits>> that we get from +WebDriver. However, Geb makes things even easier by taking care of some of the +boilerplate code for us. + +[[spring-mvc-test-server-htmlunit-geb-setup]] +== MockMvc and Geb Setup + +We can easily initialize a Geb `Browser` with a Selenium WebDriver that uses MockMvc, as +follows: + +[source,groovy] +---- +def setup() { + browser.driver = MockMvcHtmlUnitDriverBuilder + .webAppContextSetup(context) + .build() +} +---- + +NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced +usage, see <<spring-mvc-test-server-htmlunit-webdriver-advanced-builder>>. + +This ensures that any URL referencing `localhost` as the server is directed to our +`MockMvc` instance without the need for a real HTTP connection. Any other URL is +requested by using a network connection as normal. This lets us easily test the use of +CDNs. + +[[spring-mvc-test-server-htmlunit-geb-usage]] +== MockMvc and Geb Usage + +Now we can use Geb as we normally would but without the need to deploy our application to +a Servlet container. For example, we can request the view to create a message with the +following: + +[source,groovy] +---- +to CreateMessagePage +---- + +We can then fill out the form and submit it to create a message, as follows: + +[source,groovy] +---- +when: +form.summary = expectedSummary +form.text = expectedMessage +submit.click(ViewMessagePage) +---- + +Any unrecognized method calls or property accesses or references that are not found are +forwarded to the current page object. This removes a lot of the boilerplate code we +needed when using WebDriver directly. + +As with direct WebDriver usage, this improves on the design of our +<<spring-mvc-test-server-htmlunit-mah-usage, HtmlUnit test>> by using the Page Object +Pattern. As mentioned previously, we can use the Page Object Pattern with HtmlUnit and +WebDriver, but it is even easier with Geb. Consider our new Groovy-based +`CreateMessagePage` implementation: + +[source,groovy] +---- +class CreateMessagePage extends Page { + static url = 'messages/form' + static at = { assert title == 'Messages : Create'; true } + static content = { + submit { $('input[type=submit]') } + form { $('form') } + errors(required:false) { $('label.error, .alert-error')?.text() } + } +} +---- + +Our `CreateMessagePage` extends `Page`. We do not go over the details of `Page`, but, in +summary, it contains common functionality for all of our pages. We define a URL in which +this page can be found. This lets us navigate to the page, as follows: + +[source,groovy] +---- +to CreateMessagePage +---- + +We also have an `at` closure that determines if we are at the specified page. It should +return `true` if we are on the correct page. This is why we can assert that we are on the +correct page, as follows: + +[source,groovy] +---- +then: +at CreateMessagePage +errors.contains('This field is required.') +---- + +NOTE: We use an assertion in the closure so that we can determine where things went wrong +if we were at the wrong page. + +Next, we create a `content` closure that specifies all the areas of interest within the +page. We can use a +https://www.gebish.org/manual/current/#the-jquery-ish-navigator-api[jQuery-ish Navigator +API] to select the content in which we are interested. + +Finally, we can verify that a new message was created successfully, as follows: + +[source,groovy] +---- +then: +at ViewMessagePage +success == 'Successfully created a new message' +id +date +summary == expectedSummary +message == expectedMessage +---- + +For further details on how to get the most out of Geb, see +https://www.gebish.org/manual/current/[The Book of Geb] user's manual. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc new file mode 100644 index 000000000000..c34323787234 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc @@ -0,0 +1,242 @@ +[[spring-mvc-test-server-htmlunit-mah]] += MockMvc and HtmlUnit + +This section describes how to integrate MockMvc and HtmlUnit. Use this option if you want +to use the raw HtmlUnit libraries. + +[[spring-mvc-test-server-htmlunit-mah-setup]] +== MockMvc and HtmlUnit Setup + +First, make sure that you have included a test dependency on +`net.sourceforge.htmlunit:htmlunit`. In order to use HtmlUnit with Apache HttpComponents +4.5+, you need to use HtmlUnit 2.18 or higher. + +We can easily create an HtmlUnit `WebClient` that integrates with MockMvc by using the +`MockMvcWebClientBuilder`, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient webClient; + + @BeforeEach + void setup(WebApplicationContext context) { + webClient = MockMvcWebClientBuilder + .webAppContextSetup(context) + .build(); + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + lateinit var webClient: WebClient + + @BeforeEach + fun setup(context: WebApplicationContext) { + webClient = MockMvcWebClientBuilder + .webAppContextSetup(context) + .build() + } +---- + +NOTE: This is a simple example of using `MockMvcWebClientBuilder`. For advanced usage, +see <<spring-mvc-test-server-htmlunit-mah-advanced-builder>>. + +This ensures that any URL that references `localhost` as the server is directed to our +`MockMvc` instance without the need for a real HTTP connection. Any other URL is +requested by using a network connection, as normal. This lets us easily test the use of +CDNs. + +[[spring-mvc-test-server-htmlunit-mah-usage]] +== MockMvc and HtmlUnit Usage + +Now we can use HtmlUnit as we normally would but without the need to deploy our +application to a Servlet container. For example, we can request the view to create a +message with the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HtmlPage createMsgFormPage = webClient.getPage("http://localhost/messages/form"); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val createMsgFormPage = webClient.getPage("http://localhost/messages/form") +---- + +NOTE: The default context path is `""`. Alternatively, we can specify the context path, +as described in <<spring-mvc-test-server-htmlunit-mah-advanced-builder>>. + +Once we have a reference to the `HtmlPage`, we can then fill out the form and submit it +to create a message, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HtmlForm form = createMsgFormPage.getHtmlElementById("messageForm"); + HtmlTextInput summaryInput = createMsgFormPage.getHtmlElementById("summary"); + summaryInput.setValueAttribute("Spring Rocks"); + HtmlTextArea textInput = createMsgFormPage.getHtmlElementById("text"); + textInput.setText("In case you didn't know, Spring Rocks!"); + HtmlSubmitInput submit = form.getOneHtmlElementByAttribute("input", "type", "submit"); + HtmlPage newMessagePage = submit.click(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val form = createMsgFormPage.getHtmlElementById("messageForm") + val summaryInput = createMsgFormPage.getHtmlElementById("summary") + summaryInput.setValueAttribute("Spring Rocks") + val textInput = createMsgFormPage.getHtmlElementById("text") + textInput.setText("In case you didn't know, Spring Rocks!") + val submit = form.getOneHtmlElementByAttribute("input", "type", "submit") + val newMessagePage = submit.click() +---- + +Finally, we can verify that a new message was created successfully. The following +assertions use the https://assertj.github.io/doc/[AssertJ] library: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + assertThat(newMessagePage.getUrl().toString()).endsWith("/messages/123"); + String id = newMessagePage.getHtmlElementById("id").getTextContent(); + assertThat(id).isEqualTo("123"); + String summary = newMessagePage.getHtmlElementById("summary").getTextContent(); + assertThat(summary).isEqualTo("Spring Rocks"); + String text = newMessagePage.getHtmlElementById("text").getTextContent(); + assertThat(text).isEqualTo("In case you didn't know, Spring Rocks!"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + assertThat(newMessagePage.getUrl().toString()).endsWith("/messages/123") + val id = newMessagePage.getHtmlElementById("id").getTextContent() + assertThat(id).isEqualTo("123") + val summary = newMessagePage.getHtmlElementById("summary").getTextContent() + assertThat(summary).isEqualTo("Spring Rocks") + val text = newMessagePage.getHtmlElementById("text").getTextContent() + assertThat(text).isEqualTo("In case you didn't know, Spring Rocks!") +---- + +The preceding code improves on our +<<spring-mvc-test-server-htmlunit-mock-mvc-test, MockMvc test>> in a number of ways. +First, we no longer have to explicitly verify our form and then create a request that +looks like the form. Instead, we request the form, fill it out, and submit it, thereby +significantly reducing the overhead. + +Another important factor is that https://htmlunit.sourceforge.io/javascript.html[HtmlUnit +uses the Mozilla Rhino engine] to evaluate JavaScript. This means that we can also test +the behavior of JavaScript within our pages. + +See the https://htmlunit.sourceforge.io/gettingStarted.html[HtmlUnit documentation] for +additional information about using HtmlUnit. + +[[spring-mvc-test-server-htmlunit-mah-advanced-builder]] +== Advanced `MockMvcWebClientBuilder` + +In the examples so far, we have used `MockMvcWebClientBuilder` in the simplest way +possible, by building a `WebClient` based on the `WebApplicationContext` loaded for us by +the Spring TestContext Framework. This approach is repeated in the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient webClient; + + @BeforeEach + void setup(WebApplicationContext context) { + webClient = MockMvcWebClientBuilder + .webAppContextSetup(context) + .build(); + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + lateinit var webClient: WebClient + + @BeforeEach + fun setup(context: WebApplicationContext) { + webClient = MockMvcWebClientBuilder + .webAppContextSetup(context) + .build() + } +---- + +We can also specify additional configuration options, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient webClient; + + @BeforeEach + void setup() { + webClient = MockMvcWebClientBuilder + // demonstrates applying a MockMvcConfigurer (Spring Security) + .webAppContextSetup(context, springSecurity()) + // for illustration only - defaults to "" + .contextPath("") + // By default MockMvc is used for localhost only; + // the following will use MockMvc for example.com and example.org as well + .useMockMvcForHosts("example.com","example.org") + .build(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + lateinit var webClient: WebClient + + @BeforeEach + fun setup() { + webClient = MockMvcWebClientBuilder + // demonstrates applying a MockMvcConfigurer (Spring Security) + .webAppContextSetup(context, springSecurity()) + // for illustration only - defaults to "" + .contextPath("") + // By default MockMvc is used for localhost only; + // the following will use MockMvc for example.com and example.org as well + .useMockMvcForHosts("example.com","example.org") + .build() + } +---- + +As an alternative, we can perform the exact same setup by configuring the `MockMvc` +instance separately and supplying it to the `MockMvcWebClientBuilder`, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + MockMvc mockMvc = MockMvcBuilders + .webAppContextSetup(context) + .apply(springSecurity()) + .build(); + + webClient = MockMvcWebClientBuilder + .mockMvcSetup(mockMvc) + // for illustration only - defaults to "" + .contextPath("") + // By default MockMvc is used for localhost only; + // the following will use MockMvc for example.com and example.org as well + .useMockMvcForHosts("example.com","example.org") + .build(); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed +---- + +This is more verbose, but, by building the `WebClient` with a `MockMvc` instance, we have +the full power of MockMvc at our fingertips. + +TIP: For additional information on creating a `MockMvc` instance, see +<<spring-mvc-test-server-setup-options>>. + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc new file mode 100644 index 000000000000..57a91b65951e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc @@ -0,0 +1,503 @@ +[[spring-mvc-test-server-htmlunit-webdriver]] += MockMvc and WebDriver + +In the previous sections, we have seen how to use MockMvc in conjunction with the raw +HtmlUnit APIs. In this section, we use additional abstractions within the Selenium +https://docs.seleniumhq.org/projects/webdriver/[WebDriver] to make things even easier. + +[[spring-mvc-test-server-htmlunit-webdriver-why]] +== Why WebDriver and MockMvc? + +We can already use HtmlUnit and MockMvc, so why would we want to use WebDriver? The +Selenium WebDriver provides a very elegant API that lets us easily organize our code. To +better show how it works, we explore an example in this section. + +NOTE: Despite being a part of https://docs.seleniumhq.org/[Selenium], WebDriver does not +require a Selenium Server to run your tests. + +Suppose we need to ensure that a message is created properly. The tests involve finding +the HTML form input elements, filling them out, and making various assertions. + +This approach results in numerous separate tests because we want to test error conditions +as well. For example, we want to ensure that we get an error if we fill out only part of +the form. If we fill out the entire form, the newly created message should be displayed +afterwards. + +If one of the fields were named "`summary`", we might have something that resembles the +following repeated in multiple places within our tests: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HtmlTextInput summaryInput = currentPage.getHtmlElementById("summary"); + summaryInput.setValueAttribute(summary); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val summaryInput = currentPage.getHtmlElementById("summary") + summaryInput.setValueAttribute(summary) +---- + +So what happens if we change the `id` to `smmry`? Doing so would force us to update all +of our tests to incorporate this change. This violates the DRY principle, so we should +ideally extract this code into its own method, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public HtmlPage createMessage(HtmlPage currentPage, String summary, String text) { + setSummary(currentPage, summary); + // ... + } + + public void setSummary(HtmlPage currentPage, String summary) { + HtmlTextInput summaryInput = currentPage.getHtmlElementById("summary"); + summaryInput.setValueAttribute(summary); + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun createMessage(currentPage: HtmlPage, summary:String, text:String) :HtmlPage{ + setSummary(currentPage, summary); + // ... + } + + fun setSummary(currentPage:HtmlPage , summary: String) { + val summaryInput = currentPage.getHtmlElementById("summary") + summaryInput.setValueAttribute(summary) + } +---- + +Doing so ensures that we do not have to update all of our tests if we change the UI. + +We might even take this a step further and place this logic within an `Object` that +represents the `HtmlPage` we are currently on, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class CreateMessagePage { + + final HtmlPage currentPage; + + final HtmlTextInput summaryInput; + + final HtmlSubmitInput submit; + + public CreateMessagePage(HtmlPage currentPage) { + this.currentPage = currentPage; + this.summaryInput = currentPage.getHtmlElementById("summary"); + this.submit = currentPage.getHtmlElementById("submit"); + } + + public <T> T createMessage(String summary, String text) throws Exception { + setSummary(summary); + + HtmlPage result = submit.click(); + boolean error = CreateMessagePage.at(result); + + return (T) (error ? new CreateMessagePage(result) : new ViewMessagePage(result)); + } + + public void setSummary(String summary) throws Exception { + summaryInput.setValueAttribute(summary); + } + + public static boolean at(HtmlPage page) { + return "Create Message".equals(page.getTitleText()); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class CreateMessagePage(private val currentPage: HtmlPage) { + + val summaryInput: HtmlTextInput = currentPage.getHtmlElementById("summary") + + val submit: HtmlSubmitInput = currentPage.getHtmlElementById("submit") + + fun <T> createMessage(summary: String, text: String): T { + setSummary(summary) + + val result = submit.click() + val error = at(result) + + return (if (error) CreateMessagePage(result) else ViewMessagePage(result)) as T + } + + fun setSummary(summary: String) { + summaryInput.setValueAttribute(summary) + } + + fun at(page: HtmlPage): Boolean { + return "Create Message" == page.getTitleText() + } + } +} +---- + +Formerly, this pattern was known as the +https://github.com/SeleniumHQ/selenium/wiki/PageObjects[Page Object Pattern]. While we +can certainly do this with HtmlUnit, WebDriver provides some tools that we explore in the +following sections to make this pattern much easier to implement. + +[[spring-mvc-test-server-htmlunit-webdriver-setup]] +== MockMvc and WebDriver Setup + +To use Selenium WebDriver with the Spring MVC Test framework, make sure that your project +includes a test dependency on `org.seleniumhq.selenium:selenium-htmlunit-driver`. + +We can easily create a Selenium WebDriver that integrates with MockMvc by using the +`MockMvcHtmlUnitDriverBuilder` as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebDriver driver; + + @BeforeEach + void setup(WebApplicationContext context) { + driver = MockMvcHtmlUnitDriverBuilder + .webAppContextSetup(context) + .build(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + lateinit var driver: WebDriver + + @BeforeEach + fun setup(context: WebApplicationContext) { + driver = MockMvcHtmlUnitDriverBuilder + .webAppContextSetup(context) + .build() + } +---- + +NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced +usage, see <<spring-mvc-test-server-htmlunit-webdriver-advanced-builder>>. + +The preceding example ensures that any URL that references `localhost` as the server is +directed to our `MockMvc` instance without the need for a real HTTP connection. Any other +URL is requested by using a network connection, as normal. This lets us easily test the +use of CDNs. + +[[spring-mvc-test-server-htmlunit-webdriver-usage]] +== MockMvc and WebDriver Usage + +Now we can use WebDriver as we normally would but without the need to deploy our +application to a Servlet container. For example, we can request the view to create a +message with the following: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + CreateMessagePage page = CreateMessagePage.to(driver); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val page = CreateMessagePage.to(driver) +---- +-- + +We can then fill out the form and submit it to create a message, as follows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ViewMessagePage viewMessagePage = + page.createMessage(ViewMessagePage.class, expectedSummary, expectedText); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val viewMessagePage = + page.createMessage(ViewMessagePage::class, expectedSummary, expectedText) +---- +-- + +This improves on the design of our <<spring-mvc-test-server-htmlunit-mah-usage, HtmlUnit test>> +by leveraging the Page Object Pattern. As we mentioned in +<<spring-mvc-test-server-htmlunit-webdriver-why>>, we can use the Page Object Pattern +with HtmlUnit, but it is much easier with WebDriver. Consider the following +`CreateMessagePage` implementation: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class CreateMessagePage extends AbstractPage { // <1> + + // <2> + private WebElement summary; + private WebElement text; + + @FindBy(css = "input[type=submit]") // <3> + private WebElement submit; + + public CreateMessagePage(WebDriver driver) { + super(driver); + } + + public <T> T createMessage(Class<T> resultPage, String summary, String details) { + this.summary.sendKeys(summary); + this.text.sendKeys(details); + this.submit.click(); + return PageFactory.initElements(driver, resultPage); + } + + public static CreateMessagePage to(WebDriver driver) { + driver.get("http://localhost:9990/mail/messages/form"); + return PageFactory.initElements(driver, CreateMessagePage.class); + } + } +---- +<1> `CreateMessagePage` extends the `AbstractPage`. We do not go over the details of +`AbstractPage`, but, in summary, it contains common functionality for all of our pages. +For example, if our application has a navigational bar, global error messages, and other +features, we can place this logic in a shared location. +<2> We have a member variable for each of the parts of the HTML page in which we are +interested. These are of type `WebElement`. WebDriver's +https://github.com/SeleniumHQ/selenium/wiki/PageFactory[`PageFactory`] lets us remove a +lot of code from the HtmlUnit version of `CreateMessagePage` by automatically resolving +each `WebElement`. The +https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/support/PageFactory.html#initElements-org.openqa.selenium.WebDriver-java.lang.Class-[`PageFactory#initElements(WebDriver,Class<T>)`] +method automatically resolves each `WebElement` by using the field name and looking it up +by the `id` or `name` of the element within the HTML page. +<3> We can use the +https://github.com/SeleniumHQ/selenium/wiki/PageFactory#making-the-example-work-using-annotations[`@FindBy` annotation] +to override the default lookup behavior. Our example shows how to use the `@FindBy` +annotation to look up our submit button with a `css` selector (`input[type=submit]`). + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class CreateMessagePage(private val driver: WebDriver) : AbstractPage(driver) { // <1> + + // <2> + private lateinit var summary: WebElement + private lateinit var text: WebElement + + @FindBy(css = "input[type=submit]") // <3> + private lateinit var submit: WebElement + + fun <T> createMessage(resultPage: Class<T>, summary: String, details: String): T { + this.summary.sendKeys(summary) + text.sendKeys(details) + submit.click() + return PageFactory.initElements(driver, resultPage) + } + companion object { + fun to(driver: WebDriver): CreateMessagePage { + driver.get("http://localhost:9990/mail/messages/form") + return PageFactory.initElements(driver, CreateMessagePage::class.java) + } + } + } +---- +<1> `CreateMessagePage` extends the `AbstractPage`. We do not go over the details of +`AbstractPage`, but, in summary, it contains common functionality for all of our pages. +For example, if our application has a navigational bar, global error messages, and other +features, we can place this logic in a shared location. +<2> We have a member variable for each of the parts of the HTML page in which we are +interested. These are of type `WebElement`. WebDriver's +https://github.com/SeleniumHQ/selenium/wiki/PageFactory[`PageFactory`] lets us remove a +lot of code from the HtmlUnit version of `CreateMessagePage` by automatically resolving +each `WebElement`. The +https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/support/PageFactory.html#initElements-org.openqa.selenium.WebDriver-java.lang.Class-[`PageFactory#initElements(WebDriver,Class<T>)`] +method automatically resolves each `WebElement` by using the field name and looking it up +by the `id` or `name` of the element within the HTML page. +<3> We can use the +https://github.com/SeleniumHQ/selenium/wiki/PageFactory#making-the-example-work-using-annotations[`@FindBy` annotation] +to override the default lookup behavior. Our example shows how to use the `@FindBy` +annotation to look up our submit button with a `css` selector (*input[type=submit]*). +-- + +Finally, we can verify that a new message was created successfully. The following +assertions use the https://assertj.github.io/doc/[AssertJ] assertion library: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + assertThat(viewMessagePage.getMessage()).isEqualTo(expectedMessage); + assertThat(viewMessagePage.getSuccess()).isEqualTo("Successfully created a new message"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + assertThat(viewMessagePage.message).isEqualTo(expectedMessage) + assertThat(viewMessagePage.success).isEqualTo("Successfully created a new message") +---- +-- + +We can see that our `ViewMessagePage` lets us interact with our custom domain model. For +example, it exposes a method that returns a `Message` object: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public Message getMessage() throws ParseException { + Message message = new Message(); + message.setId(getId()); + message.setCreated(getCreated()); + message.setSummary(getSummary()); + message.setText(getText()); + return message; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun getMessage() = Message(getId(), getCreated(), getSummary(), getText()) +---- +-- + +We can then use the rich domain objects in our assertions. + +Lastly, we must not forget to close the `WebDriver` instance when the test is complete, +as follows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @AfterEach + void destroy() { + if (driver != null) { + driver.close(); + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @AfterEach + fun destroy() { + if (driver != null) { + driver.close() + } + } +---- +-- + +For additional information on using WebDriver, see the Selenium +https://github.com/SeleniumHQ/selenium/wiki/Getting-Started[WebDriver documentation]. + +[[spring-mvc-test-server-htmlunit-webdriver-advanced-builder]] +== Advanced `MockMvcHtmlUnitDriverBuilder` + +In the examples so far, we have used `MockMvcHtmlUnitDriverBuilder` in the simplest way +possible, by building a `WebDriver` based on the `WebApplicationContext` loaded for us by +the Spring TestContext Framework. This approach is repeated here, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebDriver driver; + + @BeforeEach + void setup(WebApplicationContext context) { + driver = MockMvcHtmlUnitDriverBuilder + .webAppContextSetup(context) + .build(); + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + lateinit var driver: WebDriver + + @BeforeEach + fun setup(context: WebApplicationContext) { + driver = MockMvcHtmlUnitDriverBuilder + .webAppContextSetup(context) + .build() + } +---- + +We can also specify additional configuration options, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebDriver driver; + + @BeforeEach + void setup() { + driver = MockMvcHtmlUnitDriverBuilder + // demonstrates applying a MockMvcConfigurer (Spring Security) + .webAppContextSetup(context, springSecurity()) + // for illustration only - defaults to "" + .contextPath("") + // By default MockMvc is used for localhost only; + // the following will use MockMvc for example.com and example.org as well + .useMockMvcForHosts("example.com","example.org") + .build(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + lateinit var driver: WebDriver + + @BeforeEach + fun setup() { + driver = MockMvcHtmlUnitDriverBuilder + // demonstrates applying a MockMvcConfigurer (Spring Security) + .webAppContextSetup(context, springSecurity()) + // for illustration only - defaults to "" + .contextPath("") + // By default MockMvc is used for localhost only; + // the following will use MockMvc for example.com and example.org as well + .useMockMvcForHosts("example.com","example.org") + .build() + } +---- + +As an alternative, we can perform the exact same setup by configuring the `MockMvc` +instance separately and supplying it to the `MockMvcHtmlUnitDriverBuilder`, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + MockMvc mockMvc = MockMvcBuilders + .webAppContextSetup(context) + .apply(springSecurity()) + .build(); + + driver = MockMvcHtmlUnitDriverBuilder + .mockMvcSetup(mockMvc) + // for illustration only - defaults to "" + .contextPath("") + // By default MockMvc is used for localhost only; + // the following will use MockMvc for example.com and example.org as well + .useMockMvcForHosts("example.com","example.org") + .build(); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed +---- + +This is more verbose, but, by building the `WebDriver` with a `MockMvc` instance, we have +the full power of MockMvc at our fingertips. + +TIP: For additional information on creating a `MockMvc` instance, see +<<spring-mvc-test-server-setup-options>>. + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc new file mode 100644 index 000000000000..55b478e20d8c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc @@ -0,0 +1,187 @@ +[[spring-mvc-test-server-htmlunit-why]] += Why HtmlUnit Integration? + +The most obvious question that comes to mind is "`Why do I need this?`" The answer is +best found by exploring a very basic sample application. Assume you have a Spring MVC web +application that supports CRUD operations on a `Message` object. The application also +supports paging through all messages. How would you go about testing it? + +With Spring MVC Test, we can easily test if we are able to create a `Message`, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + MockHttpServletRequestBuilder createMessage = post("/messages/") + .param("summary", "Spring Rocks") + .param("text", "In case you didn't know, Spring Rocks!"); + + mockMvc.perform(createMessage) + .andExpect(status().is3xxRedirection()) + .andExpect(redirectedUrl("/messages/123")); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Test + fun test() { + mockMvc.post("/messages/") { + param("summary", "Spring Rocks") + param("text", "In case you didn't know, Spring Rocks!") + }.andExpect { + status().is3xxRedirection() + redirectedUrl("/messages/123") + } + } +---- + +What if we want to test the form view that lets us create the message? For example, +assume our form looks like the following snippet: + +[source,xml,indent=0] +---- + <form id="messageForm" action="/messages/" method="post"> + <div class="pull-right"><a href="/messages/">Messages</a></div> + + <label for="summary">Summary</label> + <input type="text" class="required" id="summary" name="summary" value="" /> + + <label for="text">Message</label> + <textarea id="text" name="text"></textarea> + + <div class="form-actions"> + <input type="submit" value="Create" /> + </div> + </form> +---- + +How do we ensure that our form produce the correct request to create a new message? A +naive attempt might resemble the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + mockMvc.perform(get("/messages/form")) + .andExpect(xpath("//input[@name='summary']").exists()) + .andExpect(xpath("//textarea[@name='text']").exists()); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + mockMvc.get("/messages/form").andExpect { + xpath("//input[@name='summary']") { exists() } + xpath("//textarea[@name='text']") { exists() } + } +---- + +This test has some obvious drawbacks. If we update our controller to use the parameter +`message` instead of `text`, our form test continues to pass, even though the HTML form +is out of synch with the controller. To resolve this we can combine our two tests, as +follows: + +[[spring-mvc-test-server-htmlunit-mock-mvc-test]] +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + String summaryParamName = "summary"; + String textParamName = "text"; + mockMvc.perform(get("/messages/form")) + .andExpect(xpath("//input[@name='" + summaryParamName + "']").exists()) + .andExpect(xpath("//textarea[@name='" + textParamName + "']").exists()); + + MockHttpServletRequestBuilder createMessage = post("/messages/") + .param(summaryParamName, "Spring Rocks") + .param(textParamName, "In case you didn't know, Spring Rocks!"); + + mockMvc.perform(createMessage) + .andExpect(status().is3xxRedirection()) + .andExpect(redirectedUrl("/messages/123")); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val summaryParamName = "summary"; + val textParamName = "text"; + mockMvc.get("/messages/form").andExpect { + xpath("//input[@name='$summaryParamName']") { exists() } + xpath("//textarea[@name='$textParamName']") { exists() } + } + mockMvc.post("/messages/") { + param(summaryParamName, "Spring Rocks") + param(textParamName, "In case you didn't know, Spring Rocks!") + }.andExpect { + status().is3xxRedirection() + redirectedUrl("/messages/123") + } +---- + +This would reduce the risk of our test incorrectly passing, but there are still some +problems: + +* What if we have multiple forms on our page? Admittedly, we could update our XPath + expressions, but they get more complicated as we take more factors into account: Are + the fields the correct type? Are the fields enabled? And so on. +* Another issue is that we are doing double the work we would expect. We must first + verify the view, and then we submit the view with the same parameters we just verified. + Ideally, this could be done all at once. +* Finally, we still cannot account for some things. For example, what if the form has + JavaScript validation that we wish to test as well? + +The overall problem is that testing a web page does not involve a single interaction. +Instead, it is a combination of how the user interacts with a web page and how that web +page interacts with other resources. For example, the result of a form view is used as +the input to a user for creating a message. In addition, our form view can potentially +use additional resources that impact the behavior of the page, such as JavaScript +validation. + +[[spring-mvc-test-server-htmlunit-why-integration]] +== Integration Testing to the Rescue? + +To resolve the issues mentioned earlier, we could perform end-to-end integration testing, +but this has some drawbacks. Consider testing the view that lets us page through the +messages. We might need the following tests: + +* Does our page display a notification to the user to indicate that no results are + available when the messages are empty? +* Does our page properly display a single message? +* Does our page properly support paging? + +To set up these tests, we need to ensure our database contains the proper messages. This +leads to a number of additional challenges: + +* Ensuring the proper messages are in the database can be tedious. (Consider foreign key + constraints.) +* Testing can become slow, since each test would need to ensure that the database is in + the correct state. +* Since our database needs to be in a specific state, we cannot run tests in parallel. +* Performing assertions on such items as auto-generated IDs, timestamps, and others can + be difficult. + +These challenges do not mean that we should abandon end-to-end integration testing +altogether. Instead, we can reduce the number of end-to-end integration tests by +refactoring our detailed tests to use mock services that run much faster, more reliably, +and without side effects. We can then implement a small number of true end-to-end +integration tests that validate simple workflows to ensure that everything works together +properly. + +[[spring-mvc-test-server-htmlunit-why-mockmvc]] +== Enter HtmlUnit Integration + +So how can we achieve a balance between testing the interactions of our pages and still +retain good performance within our test suite? The answer is: "`By integrating MockMvc +with HtmlUnit.`" + +[[spring-mvc-test-server-htmlunit-options]] +== HtmlUnit Integration Options + +You have a number of options when you want to integrate MockMvc with HtmlUnit: + +* <<spring-mvc-test-server-htmlunit-mah,MockMvc and HtmlUnit>>: Use this option if you + want to use the raw HtmlUnit libraries. +* <<spring-mvc-test-server-htmlunit-webdriver,MockMvc and WebDriver>>: Use this option to + ease development and reuse code between integration and end-to-end testing. +* <<spring-mvc-test-server-htmlunit-geb,MockMvc and Geb>>: Use this option if you want to + use Groovy for testing, ease development, and reuse code between integration and + end-to-end testing. + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc new file mode 100644 index 000000000000..adc596e5497a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc @@ -0,0 +1,136 @@ +[[spring-mvc-test-server-performing-requests]] += Performing Requests + +This section shows how to use MockMvc on its own to perform requests and verify responses. +If using MockMvc through the `WebTestClient` please see the corresponding section on +<<webtestclient-tests>> instead. + +To perform requests that use any HTTP method, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // static import of MockMvcRequestBuilders.* + + mockMvc.perform(post("/hotels/{id}", 42).accept(MediaType.APPLICATION_JSON)); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.test.web.servlet.post + + mockMvc.post("/hotels/{id}", 42) { + accept = MediaType.APPLICATION_JSON + } +---- + +You can also perform file upload requests that internally use +`MockMultipartHttpServletRequest` so that there is no actual parsing of a multipart +request. Rather, you have to set it up to be similar to the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + mockMvc.perform(multipart("/doc").file("a1", "ABC".getBytes("UTF-8"))); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.test.web.servlet.multipart + + mockMvc.multipart("/doc") { + file("a1", "ABC".toByteArray(charset("UTF8"))) + } +---- + +You can specify query parameters in URI template style, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + mockMvc.perform(get("/hotels?thing={thing}", "somewhere")); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + mockMvc.get("/hotels?thing={thing}", "somewhere") +---- + +You can also add Servlet request parameters that represent either query or form +parameters, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + mockMvc.perform(get("/hotels").param("thing", "somewhere")); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.test.web.servlet.get + + mockMvc.get("/hotels") { + param("thing", "somewhere") + } +---- + +If application code relies on Servlet request parameters and does not check the query +string explicitly (as is most often the case), it does not matter which option you use. +Keep in mind, however, that query parameters provided with the URI template are decoded +while request parameters provided through the `param(...)` method are expected to already +be decoded. + +In most cases, it is preferable to leave the context path and the Servlet path out of the +request URI. If you must test with the full request URI, be sure to set the `contextPath` +and `servletPath` accordingly so that request mappings work, as the following example +shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + mockMvc.perform(get("/app/main/hotels/{id}").contextPath("/app").servletPath("/main")) +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.test.web.servlet.get + + mockMvc.get("/app/main/hotels/{id}") { + contextPath = "/app" + servletPath = "/main" + } +---- + +In the preceding example, it would be cumbersome to set the `contextPath` and +`servletPath` with every performed request. Instead, you can set up default request +properties, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + class MyWebTests { + + MockMvc mockMvc; + + @BeforeEach + void setup() { + mockMvc = standaloneSetup(new AccountController()) + .defaultRequest(get("/") + .contextPath("/app").servletPath("/main") + .accept(MediaType.APPLICATION_JSON)).build(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed +---- + +The preceding properties affect every request performed through the `MockMvc` instance. +If the same property is also specified on a given request, it overrides the default +value. That is why the HTTP method and URI in the default request do not matter, since +they must be specified on every request. + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-resources.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-resources.adoc new file mode 100644 index 000000000000..21a6592973e9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-resources.adoc @@ -0,0 +1,10 @@ +[[spring-mvc-test-server-resources]] += Further Examples + +The framework's own tests include +{spring-framework-main-code}/spring-test/src/test/java/org/springframework/test/web/servlet/samples[ +many sample tests] intended to show how to use MockMvc on its own or through the +{spring-framework-main-code}/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client[ +WebTestClient]. Browse these examples for further ideas. + + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc new file mode 100644 index 000000000000..26e34e16411d --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc @@ -0,0 +1,164 @@ +[[spring-mvc-test-server-setup-options]] += Setup Choices + +MockMvc can be setup in one of two ways. One is to point directly to the controllers you +want to test and programmatically configure Spring MVC infrastructure. The second is to +point to Spring configuration with Spring MVC and controller infrastructure in it. + +To set up MockMvc for testing a specific controller, use the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + class MyWebTests { + + MockMvc mockMvc; + + @BeforeEach + void setup() { + this.mockMvc = MockMvcBuilders.standaloneSetup(new AccountController()).build(); + } + + // ... + + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyWebTests { + + lateinit var mockMvc : MockMvc + + @BeforeEach + fun setup() { + mockMvc = MockMvcBuilders.standaloneSetup(AccountController()).build() + } + + // ... + + } +---- + +Or you can also use this setup when testing through the +<<webtestclient-controller-config, WebTestClient>> which delegates to the same builder +as shown above. + +To set up MockMvc through Spring configuration, use the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitWebConfig(locations = "my-servlet-context.xml") + class MyWebTests { + + MockMvc mockMvc; + + @BeforeEach + void setup(WebApplicationContext wac) { + this.mockMvc = MockMvcBuilders.webAppContextSetup(wac).build(); + } + + // ... + + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitWebConfig(locations = ["my-servlet-context.xml"]) + class MyWebTests { + + lateinit var mockMvc: MockMvc + + @BeforeEach + fun setup(wac: WebApplicationContext) { + mockMvc = MockMvcBuilders.webAppContextSetup(wac).build() + } + + // ... + + } +---- + +Or you can also use this setup when testing through the +<<webtestclient-context-config, WebTestClient>> which delegates to the same builder +as shown above. + + + +Which setup option should you use? + +The `webAppContextSetup` loads your actual Spring MVC configuration, resulting in a more +complete integration test. Since the TestContext framework caches the loaded Spring +configuration, it helps keep tests running fast, even as you introduce more tests in your +test suite. Furthermore, you can inject mock services into controllers through Spring +configuration to remain focused on testing the web layer. The following example declares +a mock service with Mockito: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <bean id="accountService" class="org.mockito.Mockito" factory-method="mock"> + <constructor-arg value="org.example.AccountService"/> + </bean> +---- + +You can then inject the mock service into the test to set up and verify your +expectations, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitWebConfig(locations = "test-servlet-context.xml") + class AccountTests { + + @Autowired + AccountService accountService; + + MockMvc mockMvc; + + @BeforeEach + void setup(WebApplicationContext wac) { + this.mockMvc = MockMvcBuilders.webAppContextSetup(wac).build(); + } + + // ... + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitWebConfig(locations = ["test-servlet-context.xml"]) + class AccountTests { + + @Autowired + lateinit var accountService: AccountService + + lateinit mockMvc: MockMvc + + @BeforeEach + fun setup(wac: WebApplicationContext) { + mockMvc = MockMvcBuilders.webAppContextSetup(wac).build() + } + + // ... + + } +---- + +The `standaloneSetup`, on the other hand, is a little closer to a unit test. It tests one +controller at a time. You can manually inject the controller with mock dependencies, and +it does not involve loading Spring configuration. Such tests are more focused on style +and make it easier to see which controller is being tested, whether any specific Spring +MVC configuration is required to work, and so on. The `standaloneSetup` is also a very +convenient way to write ad-hoc tests to verify specific behavior or to debug an issue. + +As with most "`integration versus unit testing`" debates, there is no right or wrong +answer. However, using the `standaloneSetup` does imply the need for additional +`webAppContextSetup` tests in order to verify your Spring MVC configuration. +Alternatively, you can write all your tests with `webAppContextSetup`, in order to always +test against your actual Spring MVC configuration. + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-steps.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-steps.adoc new file mode 100644 index 000000000000..3ebd6a8a00c7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-steps.adoc @@ -0,0 +1,53 @@ +[[spring-mvc-test-server-setup-steps]] += Setup Features + +No matter which MockMvc builder you use, all `MockMvcBuilder` implementations provide +some common and very useful features. For example, you can declare an `Accept` header for +all requests and expect a status of 200 as well as a `Content-Type` header in all +responses, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // static import of MockMvcBuilders.standaloneSetup + + MockMvc mockMvc = standaloneSetup(new MusicController()) + .defaultRequest(get("/").accept(MediaType.APPLICATION_JSON)) + .alwaysExpect(status().isOk()) + .alwaysExpect(content().contentType("application/json;charset=UTF-8")) + .build(); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed +---- + +In addition, third-party frameworks (and applications) can pre-package setup +instructions, such as those in a `MockMvcConfigurer`. The Spring Framework has one such +built-in implementation that helps to save and re-use the HTTP session across requests. +You can use it as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // static import of SharedHttpSessionConfigurer.sharedHttpSession + + MockMvc mockMvc = MockMvcBuilders.standaloneSetup(new TestController()) + .apply(sharedHttpSession()) + .build(); + + // Use mockMvc to perform requests... +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed +---- + +See the javadoc for +{api-spring-framework}/test/web/servlet/setup/ConfigurableMockMvcBuilder.html[`ConfigurableMockMvcBuilder`] +for a list of all MockMvc builder features or use the IDE to explore the available options. + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc new file mode 100644 index 000000000000..834ee8d26b4f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc @@ -0,0 +1,17 @@ +[[spring-mvc-test-server-static-imports]] += Static Imports + +When using MockMvc directly to perform requests, you'll need static imports for: + +- `MockMvcBuilders.{asterisk}` +- `MockMvcRequestBuilders.{asterisk}` +- `MockMvcResultMatchers.{asterisk}` +- `MockMvcResultHandlers.{asterisk}` + +An easy way to remember that is search for `MockMvc*`. If using Eclipse be sure to also +add the above as "`favorite static members`" in the Eclipse preferences. + +When using MockMvc through the <<webtestclient>> you do not need static imports. +The `WebTestClient` provides a fluent API without static imports. + + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc new file mode 100644 index 000000000000..929faaf13b41 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc @@ -0,0 +1,23 @@ +[[spring-mvc-test-server]] += Overview + +You can write plain unit tests for Spring MVC by instantiating a controller, injecting it +with dependencies, and calling its methods. However such tests do not verify request +mappings, data binding, message conversion, type conversion, validation, and nor +do they involve any of the supporting `@InitBinder`, `@ModelAttribute`, or +`@ExceptionHandler` methods. + +The Spring MVC Test framework, also known as `MockMvc`, aims to provide more complete +testing for Spring MVC controllers without a running server. It does that by invoking +the `DispatcherServlet` and passing +<<mock-objects-servlet, "`mock`" implementations of the Servlet API>> from the +`spring-test` module which replicates the full Spring MVC request handling without +a running server. + +MockMvc is a server side test framework that lets you verify most of the functionality +of a Spring MVC application using lightweight and targeted tests. You can use it on +its own to perform requests and to verify responses, or you can also use it through +the <<webtestclient>> API with MockMvc plugged in as the server to handle requests +with. + + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-end-to-end-integration-tests.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-end-to-end-integration-tests.adoc new file mode 100644 index 000000000000..9b26c80f2370 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-end-to-end-integration-tests.adoc @@ -0,0 +1,46 @@ +[[spring-mvc-test-vs-end-to-end-integration-tests]] += MockMvc vs End-to-End Tests + +MockMVc is built on Servlet API mock implementations from the +`spring-test` module and does not rely on a running container. Therefore, there are +some differences when compared to full end-to-end integration tests with an actual +client and a live server running. + +The easiest way to think about this is by starting with a blank `MockHttpServletRequest`. +Whatever you add to it is what the request becomes. Things that may catch you by surprise +are that there is no context path by default; no `jsessionid` cookie; no forwarding, +error, or async dispatches; and, therefore, no actual JSP rendering. Instead, +"`forwarded`" and "`redirected`" URLs are saved in the `MockHttpServletResponse` and can +be asserted with expectations. + +This means that, if you use JSPs, you can verify the JSP page to which the request was +forwarded, but no HTML is rendered. In other words, the JSP is not invoked. Note, +however, that all other rendering technologies that do not rely on forwarding, such as +Thymeleaf and Freemarker, render HTML to the response body as expected. The same is true +for rendering JSON, XML, and other formats through `@ResponseBody` methods. + +Alternatively, you may consider the full end-to-end integration testing support from +Spring Boot with `@SpringBootTest`. See the +{docs-spring-boot}/html/spring-boot-features.html#boot-features-testing[Spring Boot Reference Guide]. + +There are pros and cons for each approach. The options provided in Spring MVC Test are +different stops on the scale from classic unit testing to full integration testing. To be +certain, none of the options in Spring MVC Test fall under the category of classic unit +testing, but they are a little closer to it. For example, you can isolate the web layer +by injecting mocked services into controllers, in which case you are testing the web +layer only through the `DispatcherServlet` but with actual Spring configuration, as you +might test the data access layer in isolation from the layers above it. Also, you can use +the stand-alone setup, focusing on one controller at a time and manually providing the +configuration required to make it work. + +Another important distinction when using Spring MVC Test is that, conceptually, such +tests are the server-side, so you can check what handler was used, if an exception was +handled with a HandlerExceptionResolver, what the content of the model is, what binding +errors there were, and other details. That means that it is easier to write expectations, +since the server is not an opaque box, as it is when testing it through an actual HTTP +client. This is generally an advantage of classic unit testing: It is easier to write, +reason about, and debug but does not replace the need for full integration tests. At the +same time, it is important not to lose sight of the fact that the response is the most +important thing to check. In short, there is room here for multiple styles and strategies +of testing even within the same project. + diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-streaming-response.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-streaming-response.adoc new file mode 100644 index 000000000000..f1004ec9c16f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-streaming-response.adoc @@ -0,0 +1,34 @@ +[[spring-mvc-test-vs-streaming-response]] += Streaming Responses + +The best way to test streaming responses such as Server-Sent Events is through the +<<WebTestClient>> which can be used as a test client to connect to a `MockMvc` instance +to perform tests on Spring MVC controllers without a running server. For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebTestClient client = MockMvcWebTestClient.bindToController(new SseController()).build(); + + FluxExchangeResult<Person> exchangeResult = client.get() + .uri("/persons") + .exchange() + .expectStatus().isOk() + .expectHeader().contentType("text/event-stream") + .returnResult(Person.class); + + // Use StepVerifier from Project Reactor to test the streaming response + + StepVerifier.create(exchangeResult.getResponseBody()) + .expectNext(new Person("N0"), new Person("N1"), new Person("N2")) + .expectNextCount(4) + .consumeNextWith(person -> assertThat(person.getName()).endsWith("7")) + .thenCancel() + .verify(); +---- + +`WebTestClient` can also connect to a live server and perform full end-to-end integration +tests. This is also supported in Spring Boot where you can +{docs-spring-boot}/html/spring-boot-features.html#boot-features-testing-spring-boot-applications-testing-with-running-server[test a running server]. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc index b1d41eda4fb8..fe336ea7d5a0 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc @@ -23,4712 +23,3 @@ management>>), <<testcontext-support-classes, support classes>>, and <<integration-testing-annotations, annotation support>> sections. -[[testcontext-key-abstractions]] -== Key Abstractions - -The core of the framework consists of the `TestContextManager` class and the -`TestContext`, `TestExecutionListener`, and `SmartContextLoader` interfaces. A -`TestContextManager` is created for each test class (for example, for the execution of -all test methods within a single test class in JUnit Jupiter). The `TestContextManager`, -in turn, manages a `TestContext` that holds the context of the current test. The -`TestContextManager` also updates the state of the `TestContext` as the test progresses -and delegates to `TestExecutionListener` implementations, which instrument the actual -test execution by providing dependency injection, managing transactions, and so on. A -`SmartContextLoader` is responsible for loading an `ApplicationContext` for a given test -class. See the {api-spring-framework}/test/context/package-summary.html[javadoc] and the -Spring test suite for further information and examples of various implementations. - -[[testcontext]] -=== `TestContext` - -`TestContext` encapsulates the context in which a test is run (agnostic of the -actual testing framework in use) and provides context management and caching support for -the test instance for which it is responsible. The `TestContext` also delegates to a -`SmartContextLoader` to load an `ApplicationContext` if requested. - -[[testcontextmanager]] -=== `TestContextManager` - -`TestContextManager` is the main entry point into the Spring TestContext Framework and is -responsible for managing a single `TestContext` and signaling events to each registered -`TestExecutionListener` at well-defined test execution points: - -* Prior to any "`before class`" or "`before all`" methods of a particular testing framework. -* Test instance post-processing. -* Prior to any "`before`" or "`before each`" methods of a particular testing framework. -* Immediately before execution of the test method but after test setup. -* Immediately after execution of the test method but before test tear down. -* After any "`after`" or "`after each`" methods of a particular testing framework. -* After any "`after class`" or "`after all`" methods of a particular testing framework. - -[[testexecutionlistener]] -=== `TestExecutionListener` - -`TestExecutionListener` defines the API for reacting to test-execution events published by -the `TestContextManager` with which the listener is registered. See <<testcontext-tel-config>>. - -[[context-loaders]] -=== Context Loaders - -`ContextLoader` is a strategy interface for loading an `ApplicationContext` for an -integration test managed by the Spring TestContext Framework. You should implement -`SmartContextLoader` instead of this interface to provide support for component classes, -active bean definition profiles, test property sources, context hierarchies, and -`WebApplicationContext` support. - -`SmartContextLoader` is an extension of the `ContextLoader` interface that supersedes the -original minimal `ContextLoader` SPI. Specifically, a `SmartContextLoader` can choose to -process resource locations, component classes, or context initializers. Furthermore, a -`SmartContextLoader` can set active bean definition profiles and test property sources in -the context that it loads. - -Spring provides the following implementations: - -* `DelegatingSmartContextLoader`: One of two default loaders, it delegates internally to - an `AnnotationConfigContextLoader`, a `GenericXmlContextLoader`, or a - `GenericGroovyXmlContextLoader`, depending either on the configuration declared for the - test class or on the presence of default locations or default configuration classes. - Groovy support is enabled only if Groovy is on the classpath. -* `WebDelegatingSmartContextLoader`: One of two default loaders, it delegates internally - to an `AnnotationConfigWebContextLoader`, a `GenericXmlWebContextLoader`, or a - `GenericGroovyXmlWebContextLoader`, depending either on the configuration declared for - the test class or on the presence of default locations or default configuration - classes. A web `ContextLoader` is used only if `@WebAppConfiguration` is present on the - test class. Groovy support is enabled only if Groovy is on the classpath. -* `AnnotationConfigContextLoader`: Loads a standard `ApplicationContext` from component - classes. -* `AnnotationConfigWebContextLoader`: Loads a `WebApplicationContext` from component - classes. -* `GenericGroovyXmlContextLoader`: Loads a standard `ApplicationContext` from resource - locations that are either Groovy scripts or XML configuration files. -* `GenericGroovyXmlWebContextLoader`: Loads a `WebApplicationContext` from resource - locations that are either Groovy scripts or XML configuration files. -* `GenericXmlContextLoader`: Loads a standard `ApplicationContext` from XML resource - locations. -* `GenericXmlWebContextLoader`: Loads a `WebApplicationContext` from XML resource - locations. - - -[[testcontext-bootstrapping]] -== Bootstrapping the TestContext Framework - -The default configuration for the internals of the Spring TestContext Framework is -sufficient for all common use cases. However, there are times when a development team or -third party framework would like to change the default `ContextLoader`, implement a -custom `TestContext` or `ContextCache`, augment the default sets of -`ContextCustomizerFactory` and `TestExecutionListener` implementations, and so on. For -such low-level control over how the TestContext framework operates, Spring provides a -bootstrapping strategy. - -`TestContextBootstrapper` defines the SPI for bootstrapping the TestContext framework. A -`TestContextBootstrapper` is used by the `TestContextManager` to load the -`TestExecutionListener` implementations for the current test and to build the -`TestContext` that it manages. You can configure a custom bootstrapping strategy for a -test class (or test class hierarchy) by using `@BootstrapWith`, either directly or as a -meta-annotation. If a bootstrapper is not explicitly configured by using -`@BootstrapWith`, either the `DefaultTestContextBootstrapper` or the -`WebTestContextBootstrapper` is used, depending on the presence of `@WebAppConfiguration`. - -Since the `TestContextBootstrapper` SPI is likely to change in the future (to accommodate -new requirements), we strongly encourage implementers not to implement this interface -directly but rather to extend `AbstractTestContextBootstrapper` or one of its concrete -subclasses instead. - - -[[testcontext-tel-config]] -== `TestExecutionListener` Configuration - -Spring provides the following `TestExecutionListener` implementations that are registered -by default, exactly in the following order: - -* `ServletTestExecutionListener`: Configures Servlet API mocks for a - `WebApplicationContext`. -* `DirtiesContextBeforeModesTestExecutionListener`: Handles the `@DirtiesContext` - annotation for "`before`" modes. -* `ApplicationEventsTestExecutionListener`: Provides support for - <<testcontext-application-events, `ApplicationEvents`>>. -* `DependencyInjectionTestExecutionListener`: Provides dependency injection for the test - instance. -* `DirtiesContextTestExecutionListener`: Handles the `@DirtiesContext` annotation for - "`after`" modes. -* `TransactionalTestExecutionListener`: Provides transactional test execution with - default rollback semantics. -* `SqlScriptsTestExecutionListener`: Runs SQL scripts configured by using the `@Sql` - annotation. -* `EventPublishingTestExecutionListener`: Publishes test execution events to the test's - `ApplicationContext` (see <<testcontext-test-execution-events>>). - -[[testcontext-tel-config-registering-tels]] -=== Registering `TestExecutionListener` Implementations - -You can register `TestExecutionListener` implementations explicitly for a test class, its -subclasses, and its nested classes by using the `@TestExecutionListeners` annotation. See -<<integration-testing-annotations, annotation support>> and the javadoc for -{api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners`] -for details and examples. - -.Switching to default `TestExecutionListener` implementations -[NOTE] -==== -If you extend a class that is annotated with `@TestExecutionListeners` and you need to -switch to using the default set of listeners, you can annotate your class with the -following. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Switch to default listeners - @TestExecutionListeners( - listeners = {}, - inheritListeners = false, - mergeMode = MERGE_WITH_DEFAULTS) - class MyTest extends BaseTest { - // class body... - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Switch to default listeners - @TestExecutionListeners( - listeners = [], - inheritListeners = false, - mergeMode = MERGE_WITH_DEFAULTS) - class MyTest : BaseTest { - // class body... - } ----- -==== - -[[testcontext-tel-config-automatic-discovery]] -=== Automatic Discovery of Default `TestExecutionListener` Implementations - -Registering `TestExecutionListener` implementations by using `@TestExecutionListeners` is -suitable for custom listeners that are used in limited testing scenarios. However, it can -become cumbersome if a custom listener needs to be used across an entire test suite. This -issue is addressed through support for automatic discovery of default -`TestExecutionListener` implementations through the `SpringFactoriesLoader` mechanism. - -Specifically, the `spring-test` module declares all core default `TestExecutionListener` -implementations under the `org.springframework.test.context.TestExecutionListener` key in -its `META-INF/spring.factories` properties file. Third-party frameworks and developers -can contribute their own `TestExecutionListener` implementations to the list of default -listeners in the same manner through their own `META-INF/spring.factories` properties -file. - -[[testcontext-tel-config-ordering]] -=== Ordering `TestExecutionListener` Implementations - -When the TestContext framework discovers default `TestExecutionListener` implementations -through the <<testcontext-tel-config-automatic-discovery, aforementioned>> -`SpringFactoriesLoader` mechanism, the instantiated listeners are sorted by using -Spring's `AnnotationAwareOrderComparator`, which honors Spring's `Ordered` interface and -`@Order` annotation for ordering. `AbstractTestExecutionListener` and all default -`TestExecutionListener` implementations provided by Spring implement `Ordered` with -appropriate values. Third-party frameworks and developers should therefore make sure that -their default `TestExecutionListener` implementations are registered in the proper order -by implementing `Ordered` or declaring `@Order`. See the javadoc for the `getOrder()` -methods of the core default `TestExecutionListener` implementations for details on what -values are assigned to each core listener. - -[[testcontext-tel-config-merging]] -=== Merging `TestExecutionListener` Implementations - -If a custom `TestExecutionListener` is registered via `@TestExecutionListeners`, the -default listeners are not registered. In most common testing scenarios, this effectively -forces the developer to manually declare all default listeners in addition to any custom -listeners. The following listing demonstrates this style of configuration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @TestExecutionListeners({ - MyCustomTestExecutionListener.class, - ServletTestExecutionListener.class, - DirtiesContextBeforeModesTestExecutionListener.class, - DependencyInjectionTestExecutionListener.class, - DirtiesContextTestExecutionListener.class, - TransactionalTestExecutionListener.class, - SqlScriptsTestExecutionListener.class - }) - class MyTest { - // class body... - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @TestExecutionListeners( - MyCustomTestExecutionListener::class, - ServletTestExecutionListener::class, - DirtiesContextBeforeModesTestExecutionListener::class, - DependencyInjectionTestExecutionListener::class, - DirtiesContextTestExecutionListener::class, - TransactionalTestExecutionListener::class, - SqlScriptsTestExecutionListener::class - ) - class MyTest { - // class body... - } ----- - -The challenge with this approach is that it requires that the developer know exactly -which listeners are registered by default. Moreover, the set of default listeners can -change from release to release -- for example, `SqlScriptsTestExecutionListener` was -introduced in Spring Framework 4.1, and `DirtiesContextBeforeModesTestExecutionListener` -was introduced in Spring Framework 4.2. Furthermore, third-party frameworks like Spring -Boot and Spring Security register their own default `TestExecutionListener` -implementations by using the aforementioned <<testcontext-tel-config-automatic-discovery, -automatic discovery mechanism>>. - -To avoid having to be aware of and re-declare all default listeners, you can set the -`mergeMode` attribute of `@TestExecutionListeners` to `MergeMode.MERGE_WITH_DEFAULTS`. -`MERGE_WITH_DEFAULTS` indicates that locally declared listeners should be merged with the -default listeners. The merging algorithm ensures that duplicates are removed from the -list and that the resulting set of merged listeners is sorted according to the semantics -of `AnnotationAwareOrderComparator`, as described in <<testcontext-tel-config-ordering>>. -If a listener implements `Ordered` or is annotated with `@Order`, it can influence the -position in which it is merged with the defaults. Otherwise, locally declared listeners -are appended to the list of default listeners when merged. - -For example, if the `MyCustomTestExecutionListener` class in the previous example -configures its `order` value (for example, `500`) to be less than the order of the -`ServletTestExecutionListener` (which happens to be `1000`), the -`MyCustomTestExecutionListener` can then be automatically merged with the list of -defaults in front of the `ServletTestExecutionListener`, and the previous example could -be replaced with the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @TestExecutionListeners( - listeners = MyCustomTestExecutionListener.class, - mergeMode = MERGE_WITH_DEFAULTS - ) - class MyTest { - // class body... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @TestExecutionListeners( - listeners = [MyCustomTestExecutionListener::class], - mergeMode = MERGE_WITH_DEFAULTS - ) - class MyTest { - // class body... - } ----- - -[[testcontext-application-events]] -== Application Events - -Since Spring Framework 5.3.3, the TestContext framework provides support for recording -<<core.adoc#context-functionality-events, application events>> published in the -`ApplicationContext` so that assertions can be performed against those events within -tests. All events published during the execution of a single test are made available via -the `ApplicationEvents` API which allows you to process the events as a -`java.util.Stream`. - -To use `ApplicationEvents` in your tests, do the following. - -* Ensure that your test class is annotated or meta-annotated with - <<spring-testing-annotation-recordapplicationevents>>. -* Ensure that the `ApplicationEventsTestExecutionListener` is registered. Note, however, - that `ApplicationEventsTestExecutionListener` is registered by default and only needs - to be manually registered if you have custom configuration via - `@TestExecutionListeners` that does not include the default listeners. -* Annotate a field of type `ApplicationEvents` with `@Autowired` and use that instance of - `ApplicationEvents` in your test and lifecycle methods (such as `@BeforeEach` and - `@AfterEach` methods in JUnit Jupiter). -** When using the <<testcontext-junit-jupiter-extension>>, you may declare a method - parameter of type `ApplicationEvents` in a test or lifecycle method as an alternative - to an `@Autowired` field in the test class. - -The following test class uses the `SpringExtension` for JUnit Jupiter and -https://assertj.github.io/doc/[AssertJ] to assert the types of application events -published while invoking a method in a Spring-managed component: - -// Don't use "quotes" in the "subs" section because of the asterisks in /* ... */ -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @SpringJUnitConfig(/* ... */) - @RecordApplicationEvents // <1> - class OrderServiceTests { - - @Autowired - OrderService orderService; - - @Autowired - ApplicationEvents events; // <2> - - @Test - void submitOrder() { - // Invoke method in OrderService that publishes an event - orderService.submitOrder(new Order(/* ... */)); - // Verify that an OrderSubmitted event was published - long numEvents = events.stream(OrderSubmitted.class).count(); // <3> - assertThat(numEvents).isEqualTo(1); - } - } ----- -<1> Annotate the test class with `@RecordApplicationEvents`. -<2> Inject the `ApplicationEvents` instance for the current test. -<3> Use the `ApplicationEvents` API to count how many `OrderSubmitted` events were published. - -// Don't use "quotes" in the "subs" section because of the asterisks in /* ... */ -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(/* ... */) - @RecordApplicationEvents // <1> - class OrderServiceTests { - - @Autowired - lateinit var orderService: OrderService - - @Autowired - lateinit var events: ApplicationEvents // <2> - - @Test - fun submitOrder() { - // Invoke method in OrderService that publishes an event - orderService.submitOrder(Order(/* ... */)) - // Verify that an OrderSubmitted event was published - val numEvents = events.stream(OrderSubmitted::class).count() // <3> - assertThat(numEvents).isEqualTo(1) - } - } ----- -<1> Annotate the test class with `@RecordApplicationEvents`. -<2> Inject the `ApplicationEvents` instance for the current test. -<3> Use the `ApplicationEvents` API to count how many `OrderSubmitted` events were published. - -See the -{api-spring-framework}/test/context/event/ApplicationEvents.html[`ApplicationEvents` -javadoc] for further details regarding the `ApplicationEvents` API. - -[[testcontext-test-execution-events]] -== Test Execution Events - -The `EventPublishingTestExecutionListener` introduced in Spring Framework 5.2 offers an -alternative approach to implementing a custom `TestExecutionListener`. Components in the -test's `ApplicationContext` can listen to the following events published by the -`EventPublishingTestExecutionListener`, each of which corresponds to a method in the -`TestExecutionListener` API. - -* `BeforeTestClassEvent` -* `PrepareTestInstanceEvent` -* `BeforeTestMethodEvent` -* `BeforeTestExecutionEvent` -* `AfterTestExecutionEvent` -* `AfterTestMethodEvent` -* `AfterTestClassEvent` - -These events may be consumed for various reasons, such as resetting mock beans or tracing -test execution. One advantage of consuming test execution events rather than implementing -a custom `TestExecutionListener` is that test execution events may be consumed by any -Spring bean registered in the test `ApplicationContext`, and such beans may benefit -directly from dependency injection and other features of the `ApplicationContext`. In -contrast, a `TestExecutionListener` is not a bean in the `ApplicationContext`. - -[NOTE] -==== -The `EventPublishingTestExecutionListener` is registered by default; however, it only -publishes events if the `ApplicationContext` has _already been loaded_. This prevents the -`ApplicationContext` from being loaded unnecessarily or too early. - -Consequently, a `BeforeTestClassEvent` will not be published until after the -`ApplicationContext` has been loaded by another `TestExecutionListener`. For example, with -the default set of `TestExecutionListener` implementations registered, a -`BeforeTestClassEvent` will not be published for the first test class that uses a -particular test `ApplicationContext`, but a `BeforeTestClassEvent` _will_ be published for -any subsequent test class in the same test suite that uses the same test -`ApplicationContext` since the context will already have been loaded when subsequent test -classes run (as long as the context has not been removed from the `ContextCache` via -`@DirtiesContext` or the max-size eviction policy). - -If you wish to ensure that a `BeforeTestClassEvent` is always published for every test -class, you need to register a `TestExecutionListener` that loads the `ApplicationContext` -in the `beforeTestClass` callback, and that `TestExecutionListener` must be registered -_before_ the `EventPublishingTestExecutionListener`. - -Similarly, if `@DirtiesContext` is used to remove the `ApplicationContext` from the -context cache after the last test method in a given test class, the `AfterTestClassEvent` -will not be published for that test class. -==== - -In order to listen to test execution events, a Spring bean may choose to implement the -`org.springframework.context.ApplicationListener` interface. Alternatively, listener -methods can be annotated with `@EventListener` and configured to listen to one of the -particular event types listed above (see -<<core.adoc#context-functionality-events-annotation, Annotation-based Event Listeners>>). -Due to the popularity of this approach, Spring provides the following dedicated -`@EventListener` annotations to simplify registration of test execution event listeners. -These annotations reside in the `org.springframework.test.context.event.annotation` -package. - -* `@BeforeTestClass` -* `@PrepareTestInstance` -* `@BeforeTestMethod` -* `@BeforeTestExecution` -* `@AfterTestExecution` -* `@AfterTestMethod` -* `@AfterTestClass` - -[[testcontext-test-execution-events-exception-handling]] -=== Exception Handling - -By default, if a test execution event listener throws an exception while consuming an -event, that exception will propagate to the underlying testing framework in use (such as -JUnit or TestNG). For example, if the consumption of a `BeforeTestMethodEvent` results in -an exception, the corresponding test method will fail as a result of the exception. In -contrast, if an asynchronous test execution event listener throws an exception, the -exception will not propagate to the underlying testing framework. For further details on -asynchronous exception handling, consult the class-level javadoc for `@EventListener`. - -[[testcontext-test-execution-events-async]] -=== Asynchronous Listeners - -If you want a particular test execution event listener to process events asynchronously, -you can use Spring's <<integration.adoc#scheduling-annotation-support-async,regular -`@Async` support>>. For further details, consult the class-level javadoc for -`@EventListener`. - - -[[testcontext-ctx-management]] -== Context Management - -Each `TestContext` provides context management and caching support for the test instance -for which it is responsible. Test instances do not automatically receive access to the -configured `ApplicationContext`. However, if a test class implements the -`ApplicationContextAware` interface, a reference to the `ApplicationContext` is supplied -to the test instance. Note that `AbstractJUnit4SpringContextTests` and -`AbstractTestNGSpringContextTests` implement `ApplicationContextAware` and, therefore, -provide access to the `ApplicationContext` automatically. - -.@Autowired ApplicationContext -[TIP] -===== -As an alternative to implementing the `ApplicationContextAware` interface, you can inject -the application context for your test class through the `@Autowired` annotation on either -a field or setter method, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig - class MyTest { - - @Autowired // <1> - ApplicationContext applicationContext; - - // class body... - } ----- -<1> Injecting the `ApplicationContext`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig - class MyTest { - - @Autowired // <1> - lateinit var applicationContext: ApplicationContext - - // class body... - } ----- -<1> Injecting the `ApplicationContext`. - - -Similarly, if your test is configured to load a `WebApplicationContext`, you can inject -the web application context into your test, as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitWebConfig // <1> - class MyWebAppTest { - - @Autowired // <2> - WebApplicationContext wac; - - // class body... - } ----- -<1> Configuring the `WebApplicationContext`. -<2> Injecting the `WebApplicationContext`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitWebConfig // <1> - class MyWebAppTest { - - @Autowired // <2> - lateinit var wac: WebApplicationContext - // class body... - } ----- -<1> Configuring the `WebApplicationContext`. -<2> Injecting the `WebApplicationContext`. - - -Dependency injection by using `@Autowired` is provided by the -`DependencyInjectionTestExecutionListener`, which is configured by default -(see <<testcontext-fixture-di>>). -===== - -Test classes that use the TestContext framework do not need to extend any particular -class or implement a specific interface to configure their application context. Instead, -configuration is achieved by declaring the `@ContextConfiguration` annotation at the -class level. If your test class does not explicitly declare application context resource -locations or component classes, the configured `ContextLoader` determines how to load a -context from a default location or default configuration classes. In addition to context -resource locations and component classes, an application context can also be configured -through application context initializers. - -The following sections explain how to use Spring's `@ContextConfiguration` annotation to -configure a test `ApplicationContext` by using XML configuration files, Groovy scripts, -component classes (typically `@Configuration` classes), or context initializers. -Alternatively, you can implement and configure your own custom `SmartContextLoader` for -advanced use cases. - -* <<testcontext-ctx-management-xml>> -* <<testcontext-ctx-management-groovy>> -* <<testcontext-ctx-management-javaconfig>> -* <<testcontext-ctx-management-mixed-config>> -* <<testcontext-ctx-management-initializers>> -* <<testcontext-ctx-management-inheritance>> -* <<testcontext-ctx-management-env-profiles>> -* <<testcontext-ctx-management-property-sources>> -* <<testcontext-ctx-management-dynamic-property-sources>> -* <<testcontext-ctx-management-web>> -* <<testcontext-ctx-management-caching>> -* <<testcontext-ctx-management-ctx-hierarchies>> - -[[testcontext-ctx-management-xml]] -=== Context Configuration with XML resources - -To load an `ApplicationContext` for your tests by using XML configuration files, annotate -your test class with `@ContextConfiguration` and configure the `locations` attribute with -an array that contains the resource locations of XML configuration metadata. A plain or -relative path (for example, `context.xml`) is treated as a classpath resource that is -relative to the package in which the test class is defined. A path starting with a slash -is treated as an absolute classpath location (for example, `/org/example/config.xml`). A -path that represents a resource URL (i.e., a path prefixed with `classpath:`, `file:`, -`http:`, etc.) is used _as is_. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be loaded from "/app-config.xml" and - // "/test-config.xml" in the root of the classpath - @ContextConfiguration(locations = {"/app-config.xml", "/test-config.xml"}) // <1> - class MyTest { - // class body... - } ----- -<1> Setting the locations attribute to a list of XML files. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be loaded from "/app-config.xml" and - // "/test-config.xml" in the root of the classpath - @ContextConfiguration(locations = ["/app-config.xml", "/test-config.xml"]) // <1> - class MyTest { - // class body... - } ----- -<1> Setting the locations attribute to a list of XML files. - - -`@ContextConfiguration` supports an alias for the `locations` attribute through the -standard Java `value` attribute. Thus, if you do not need to declare additional -attributes in `@ContextConfiguration`, you can omit the declaration of the `locations` -attribute name and declare the resource locations by using the shorthand format -demonstrated in the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - @ContextConfiguration({"/app-config.xml", "/test-config.xml"}) <1> - class MyTest { - // class body... - } ----- -<1> Specifying XML files without using the `locations` attribute. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - @ContextConfiguration("/app-config.xml", "/test-config.xml") // <1> - class MyTest { - // class body... - } ----- -<1> Specifying XML files without using the `locations` attribute. - - -If you omit both the `locations` and the `value` attributes from the -`@ContextConfiguration` annotation, the TestContext framework tries to detect a default -XML resource location. Specifically, `GenericXmlContextLoader` and -`GenericXmlWebContextLoader` detect a default location based on the name of the test -class. If your class is named `com.example.MyTest`, `GenericXmlContextLoader` loads your -application context from `"classpath:com/example/MyTest-context.xml"`. The following -example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be loaded from - // "classpath:com/example/MyTest-context.xml" - @ContextConfiguration // <1> - class MyTest { - // class body... - } ----- -<1> Loading configuration from the default location. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be loaded from - // "classpath:com/example/MyTest-context.xml" - @ContextConfiguration // <1> - class MyTest { - // class body... - } ----- -<1> Loading configuration from the default location. - - -[[testcontext-ctx-management-groovy]] -=== Context Configuration with Groovy Scripts - -To load an `ApplicationContext` for your tests by using Groovy scripts that use the -<<core.adoc#groovy-bean-definition-dsl, Groovy Bean Definition DSL>>, you can annotate -your test class with `@ContextConfiguration` and configure the `locations` or `value` -attribute with an array that contains the resource locations of Groovy scripts. Resource -lookup semantics for Groovy scripts are the same as those described for -<<testcontext-ctx-management-xml, XML configuration files>>. - -.Enabling Groovy script support -TIP: Support for using Groovy scripts to load an `ApplicationContext` in the Spring -TestContext Framework is enabled automatically if Groovy is on the classpath. - -The following example shows how to specify Groovy configuration files: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be loaded from "/AppConfig.groovy" and - // "/TestConfig.groovy" in the root of the classpath - @ContextConfiguration({"/AppConfig.groovy", "/TestConfig.Groovy"}) <1> - class MyTest { - // class body... - } ----- -<1> Specifying the location of Groovy configuration files. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be loaded from "/AppConfig.groovy" and - // "/TestConfig.groovy" in the root of the classpath - @ContextConfiguration("/AppConfig.groovy", "/TestConfig.Groovy") // <1> - class MyTest { - // class body... - } ----- -<1> Specifying the location of Groovy configuration files. - - -If you omit both the `locations` and `value` attributes from the `@ContextConfiguration` -annotation, the TestContext framework tries to detect a default Groovy script. -Specifically, `GenericGroovyXmlContextLoader` and `GenericGroovyXmlWebContextLoader` -detect a default location based on the name of the test class. If your class is named -`com.example.MyTest`, the Groovy context loader loads your application context from -`"classpath:com/example/MyTestContext.groovy"`. The following example shows how to use -the default: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be loaded from - // "classpath:com/example/MyTestContext.groovy" - @ContextConfiguration // <1> - class MyTest { - // class body... - } ----- -<1> Loading configuration from the default location. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be loaded from - // "classpath:com/example/MyTestContext.groovy" - @ContextConfiguration // <1> - class MyTest { - // class body... - } ----- -<1> Loading configuration from the default location. - - -.Declaring XML configuration and Groovy scripts simultaneously -[TIP] -===== -You can declare both XML configuration files and Groovy scripts simultaneously by using -the `locations` or `value` attribute of `@ContextConfiguration`. If the path to a -configured resource location ends with `.xml`, it is loaded by using an -`XmlBeanDefinitionReader`. Otherwise, it is loaded by using a -`GroovyBeanDefinitionReader`. - -The following listing shows how to combine both in an integration test: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be loaded from - // "/app-config.xml" and "/TestConfig.groovy" - @ContextConfiguration({ "/app-config.xml", "/TestConfig.groovy" }) - class MyTest { - // class body... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be loaded from - // "/app-config.xml" and "/TestConfig.groovy" - @ContextConfiguration("/app-config.xml", "/TestConfig.groovy") - class MyTest { - // class body... - } ----- -===== - -[[testcontext-ctx-management-javaconfig]] -=== Context Configuration with Component Classes - -To load an `ApplicationContext` for your tests by using component classes (see -<<core.adoc#beans-java, Java-based container configuration>>), you can annotate your test -class with `@ContextConfiguration` and configure the `classes` attribute with an array -that contains references to component classes. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be loaded from AppConfig and TestConfig - @ContextConfiguration(classes = {AppConfig.class, TestConfig.class}) // <1> - class MyTest { - // class body... - } ----- -<1> Specifying component classes. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be loaded from AppConfig and TestConfig - @ContextConfiguration(classes = [AppConfig::class, TestConfig::class]) // <1> - class MyTest { - // class body... - } ----- -<1> Specifying component classes. - - -[[testcontext-ctx-management-javaconfig-component-classes]] -.Component Classes -[TIP] -==== -The term "`component class`" can refer to any of the following: - -* A class annotated with `@Configuration`. -* A component (that is, a class annotated with `@Component`, `@Service`, `@Repository`, or other stereotype annotations). -* A JSR-330 compliant class that is annotated with `jakarta.inject` annotations. -* Any class that contains `@Bean`-methods. -* Any other class that is intended to be registered as a Spring component (i.e., a Spring - bean in the `ApplicationContext`), potentially taking advantage of automatic autowiring - of a single constructor without the use of Spring annotations. - -See the javadoc of -{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] and -{api-spring-framework}/context/annotation/Bean.html[`@Bean`] for further information -regarding the configuration and semantics of component classes, paying special attention -to the discussion of `@Bean` Lite Mode. -==== - -If you omit the `classes` attribute from the `@ContextConfiguration` annotation, the -TestContext framework tries to detect the presence of default configuration classes. -Specifically, `AnnotationConfigContextLoader` and `AnnotationConfigWebContextLoader` -detect all `static` nested classes of the test class that meet the requirements for -configuration class implementations, as specified in the -{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] javadoc. -Note that the name of the configuration class is arbitrary. In addition, a test class can -contain more than one `static` nested configuration class if desired. In the following -example, the `OrderServiceTest` class declares a `static` nested configuration class -named `Config` that is automatically used to load the `ApplicationContext` for the test -class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig <1> - // ApplicationContext will be loaded from the static nested Config class - class OrderServiceTest { - - @Configuration - static class Config { - - // this bean will be injected into the OrderServiceTest class - @Bean - OrderService orderService() { - OrderService orderService = new OrderServiceImpl(); - // set properties, etc. - return orderService; - } - } - - @Autowired - OrderService orderService; - - @Test - void testOrderService() { - // test the orderService - } - - } ----- -<1> Loading configuration information from the nested `Config` class. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig <1> - // ApplicationContext will be loaded from the nested Config class - class OrderServiceTest { - - @Autowired - lateinit var orderService: OrderService - - @Configuration - class Config { - - // this bean will be injected into the OrderServiceTest class - @Bean - fun orderService(): OrderService { - // set properties, etc. - return OrderServiceImpl() - } - } - - @Test - fun testOrderService() { - // test the orderService - } - } ----- -<1> Loading configuration information from the nested `Config` class. - - -[[testcontext-ctx-management-mixed-config]] -=== Mixing XML, Groovy Scripts, and Component Classes - -It may sometimes be desirable to mix XML configuration files, Groovy scripts, and -component classes (typically `@Configuration` classes) to configure an -`ApplicationContext` for your tests. For example, if you use XML configuration in -production, you may decide that you want to use `@Configuration` classes to configure -specific Spring-managed components for your tests, or vice versa. - -Furthermore, some third-party frameworks (such as Spring Boot) provide first-class -support for loading an `ApplicationContext` from different types of resources -simultaneously (for example, XML configuration files, Groovy scripts, and -`@Configuration` classes). The Spring Framework, historically, has not supported this for -standard deployments. Consequently, most of the `SmartContextLoader` implementations that -the Spring Framework delivers in the `spring-test` module support only one resource type -for each test context. However, this does not mean that you cannot use both. One -exception to the general rule is that the `GenericGroovyXmlContextLoader` and -`GenericGroovyXmlWebContextLoader` support both XML configuration files and Groovy -scripts simultaneously. Furthermore, third-party frameworks may choose to support the -declaration of both `locations` and `classes` through `@ContextConfiguration`, and, with -the standard testing support in the TestContext framework, you have the following options. - -If you want to use resource locations (for example, XML or Groovy) and `@Configuration` -classes to configure your tests, you must pick one as the entry point, and that one must -include or import the other. For example, in XML or Groovy scripts, you can include -`@Configuration` classes by using component scanning or defining them as normal Spring -beans, whereas, in a `@Configuration` class, you can use `@ImportResource` to import XML -configuration files or Groovy scripts. Note that this behavior is semantically equivalent -to how you configure your application in production: In production configuration, you -define either a set of XML or Groovy resource locations or a set of `@Configuration` -classes from which your production `ApplicationContext` is loaded, but you still have the -freedom to include or import the other type of configuration. - -[[testcontext-ctx-management-initializers]] -=== Context Configuration with Context Initializers - -To configure an `ApplicationContext` for your tests by using context initializers, -annotate your test class with `@ContextConfiguration` and configure the `initializers` -attribute with an array that contains references to classes that implement -`ApplicationContextInitializer`. The declared context initializers are then used to -initialize the `ConfigurableApplicationContext` that is loaded for your tests. Note that -the concrete `ConfigurableApplicationContext` type supported by each declared initializer -must be compatible with the type of `ApplicationContext` created by the -`SmartContextLoader` in use (typically a `GenericApplicationContext`). Furthermore, the -order in which the initializers are invoked depends on whether they implement Spring's -`Ordered` interface or are annotated with Spring's `@Order` annotation or the standard -`@Priority` annotation. The following example shows how to use initializers: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be loaded from TestConfig - // and initialized by TestAppCtxInitializer - @ContextConfiguration( - classes = TestConfig.class, - initializers = TestAppCtxInitializer.class) // <1> - class MyTest { - // class body... - } ----- -<1> Specifying configuration by using a configuration class and an initializer. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be loaded from TestConfig - // and initialized by TestAppCtxInitializer - @ContextConfiguration( - classes = [TestConfig::class], - initializers = [TestAppCtxInitializer::class]) // <1> - class MyTest { - // class body... - } ----- -<1> Specifying configuration by using a configuration class and an initializer. - - -You can also omit the declaration of XML configuration files, Groovy scripts, or -component classes in `@ContextConfiguration` entirely and instead declare only -`ApplicationContextInitializer` classes, which are then responsible for registering beans -in the context -- for example, by programmatically loading bean definitions from XML -files or configuration classes. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be initialized by EntireAppInitializer - // which presumably registers beans in the context - @ContextConfiguration(initializers = EntireAppInitializer.class) <1> - class MyTest { - // class body... - } ----- -<1> Specifying configuration by using only an initializer. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be initialized by EntireAppInitializer - // which presumably registers beans in the context - @ContextConfiguration(initializers = [EntireAppInitializer::class]) // <1> - class MyTest { - // class body... - } ----- -<1> Specifying configuration by using only an initializer. - - -[[testcontext-ctx-management-inheritance]] -=== Context Configuration Inheritance - -`@ContextConfiguration` supports boolean `inheritLocations` and `inheritInitializers` -attributes that denote whether resource locations or component classes and context -initializers declared by superclasses should be inherited. The default value for both -flags is `true`. This means that a test class inherits the resource locations or -component classes as well as the context initializers declared by any superclasses. -Specifically, the resource locations or component classes for a test class are appended -to the list of resource locations or annotated classes declared by superclasses. -Similarly, the initializers for a given test class are added to the set of initializers -defined by test superclasses. Thus, subclasses have the option of extending the resource -locations, component classes, or context initializers. - -If the `inheritLocations` or `inheritInitializers` attribute in `@ContextConfiguration` -is set to `false`, the resource locations or component classes and the context -initializers, respectively, for the test class shadow and effectively replace the -configuration defined by superclasses. - -NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing -classes. See <<testcontext-junit-jupiter-nested-test-configuration>> for details. - -In the next example, which uses XML resource locations, the `ApplicationContext` for -`ExtendedTest` is loaded from `base-config.xml` and `extended-config.xml`, in that order. -Beans defined in `extended-config.xml` can, therefore, override (that is, replace) those -defined in `base-config.xml`. The following example shows how one class can extend -another and use both its own configuration file and the superclass's configuration file: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be loaded from "/base-config.xml" - // in the root of the classpath - @ContextConfiguration("/base-config.xml") <1> - class BaseTest { - // class body... - } - - // ApplicationContext will be loaded from "/base-config.xml" and - // "/extended-config.xml" in the root of the classpath - @ContextConfiguration("/extended-config.xml") <2> - class ExtendedTest extends BaseTest { - // class body... - } ----- -<1> Configuration file defined in the superclass. -<2> Configuration file defined in the subclass. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be loaded from "/base-config.xml" - // in the root of the classpath - @ContextConfiguration("/base-config.xml") // <1> - open class BaseTest { - // class body... - } - - // ApplicationContext will be loaded from "/base-config.xml" and - // "/extended-config.xml" in the root of the classpath - @ContextConfiguration("/extended-config.xml") // <2> - class ExtendedTest : BaseTest() { - // class body... - } ----- -<1> Configuration file defined in the superclass. -<2> Configuration file defined in the subclass. - - -Similarly, in the next example, which uses component classes, the `ApplicationContext` -for `ExtendedTest` is loaded from the `BaseConfig` and `ExtendedConfig` classes, in that -order. Beans defined in `ExtendedConfig` can, therefore, override (that is, replace) -those defined in `BaseConfig`. The following example shows how one class can extend -another and use both its own configuration class and the superclass's configuration class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // ApplicationContext will be loaded from BaseConfig - @SpringJUnitConfig(BaseConfig.class) // <1> - class BaseTest { - // class body... - } - - // ApplicationContext will be loaded from BaseConfig and ExtendedConfig - @SpringJUnitConfig(ExtendedConfig.class) // <2> - class ExtendedTest extends BaseTest { - // class body... - } ----- -<1> Configuration class defined in the superclass. -<2> Configuration class defined in the subclass. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // ApplicationContext will be loaded from BaseConfig - @SpringJUnitConfig(BaseConfig::class) // <1> - open class BaseTest { - // class body... - } - - // ApplicationContext will be loaded from BaseConfig and ExtendedConfig - @SpringJUnitConfig(ExtendedConfig::class) // <2> - class ExtendedTest : BaseTest() { - // class body... - } ----- -<1> Configuration class defined in the superclass. -<2> Configuration class defined in the subclass. - - -In the next example, which uses context initializers, the `ApplicationContext` for -`ExtendedTest` is initialized by using `BaseInitializer` and `ExtendedInitializer`. Note, -however, that the order in which the initializers are invoked depends on whether they -implement Spring's `Ordered` interface or are annotated with Spring's `@Order` annotation -or the standard `@Priority` annotation. The following example shows how one class can -extend another and use both its own initializer and the superclass's initializer: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // ApplicationContext will be initialized by BaseInitializer - @SpringJUnitConfig(initializers = BaseInitializer.class) // <1> - class BaseTest { - // class body... - } - - // ApplicationContext will be initialized by BaseInitializer - // and ExtendedInitializer - @SpringJUnitConfig(initializers = ExtendedInitializer.class) // <2> - class ExtendedTest extends BaseTest { - // class body... - } ----- -<1> Initializer defined in the superclass. -<2> Initializer defined in the subclass. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // ApplicationContext will be initialized by BaseInitializer - @SpringJUnitConfig(initializers = [BaseInitializer::class]) // <1> - open class BaseTest { - // class body... - } - - // ApplicationContext will be initialized by BaseInitializer - // and ExtendedInitializer - @SpringJUnitConfig(initializers = [ExtendedInitializer::class]) // <2> - class ExtendedTest : BaseTest() { - // class body... - } ----- -<1> Initializer defined in the superclass. -<2> Initializer defined in the subclass. - - -[[testcontext-ctx-management-env-profiles]] -=== Context Configuration with Environment Profiles - -The Spring Framework has first-class support for the notion of environments and profiles -(AKA "bean definition profiles"), and integration tests can be configured to activate -particular bean definition profiles for various testing scenarios. This is achieved by -annotating a test class with the `@ActiveProfiles` annotation and supplying a list of -profiles that should be activated when loading the `ApplicationContext` for the test. - -NOTE: You can use `@ActiveProfiles` with any implementation of the `SmartContextLoader` -SPI, but `@ActiveProfiles` is not supported with implementations of the older -`ContextLoader` SPI. - -Consider two examples with XML configuration and `@Configuration` classes: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <!-- app-config.xml --> - <beans xmlns="http://www.springframework.org/schema/beans" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xmlns:jdbc="http://www.springframework.org/schema/jdbc" - xmlns:jee="http://www.springframework.org/schema/jee" - xsi:schemaLocation="..."> - - <bean id="transferService" - class="com.bank.service.internal.DefaultTransferService"> - <constructor-arg ref="accountRepository"/> - <constructor-arg ref="feePolicy"/> - </bean> - - <bean id="accountRepository" - class="com.bank.repository.internal.JdbcAccountRepository"> - <constructor-arg ref="dataSource"/> - </bean> - - <bean id="feePolicy" - class="com.bank.service.internal.ZeroFeePolicy"/> - - <beans profile="dev"> - <jdbc:embedded-database id="dataSource"> - <jdbc:script - location="classpath:com/bank/config/sql/schema.sql"/> - <jdbc:script - location="classpath:com/bank/config/sql/test-data.sql"/> - </jdbc:embedded-database> - </beans> - - <beans profile="production"> - <jee:jndi-lookup id="dataSource" jndi-name="java:comp/env/jdbc/datasource"/> - </beans> - - <beans profile="default"> - <jdbc:embedded-database id="dataSource"> - <jdbc:script - location="classpath:com/bank/config/sql/schema.sql"/> - </jdbc:embedded-database> - </beans> - - </beans> ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // ApplicationContext will be loaded from "classpath:/app-config.xml" - @ContextConfiguration("/app-config.xml") - @ActiveProfiles("dev") - class TransferServiceTest { - - @Autowired - TransferService transferService; - - @Test - void testTransferService() { - // test the transferService - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // ApplicationContext will be loaded from "classpath:/app-config.xml" - @ContextConfiguration("/app-config.xml") - @ActiveProfiles("dev") - class TransferServiceTest { - - @Autowired - lateinit var transferService: TransferService - - @Test - fun testTransferService() { - // test the transferService - } - } ----- - -When `TransferServiceTest` is run, its `ApplicationContext` is loaded from the -`app-config.xml` configuration file in the root of the classpath. If you inspect -`app-config.xml`, you can see that the `accountRepository` bean has a dependency on a -`dataSource` bean. However, `dataSource` is not defined as a top-level bean. Instead, -`dataSource` is defined three times: in the `production` profile, in the `dev` profile, -and in the `default` profile. - -By annotating `TransferServiceTest` with `@ActiveProfiles("dev")`, we instruct the Spring -TestContext Framework to load the `ApplicationContext` with the active profiles set to -`{"dev"}`. As a result, an embedded database is created and populated with test data, and -the `accountRepository` bean is wired with a reference to the development `DataSource`. -That is likely what we want in an integration test. - -It is sometimes useful to assign beans to a `default` profile. Beans within the default -profile are included only when no other profile is specifically activated. You can use -this to define "`fallback`" beans to be used in the application's default state. For -example, you may explicitly provide a data source for `dev` and `production` profiles, -but define an in-memory data source as a default when neither of these is active. - -The following code listings demonstrate how to implement the same configuration and -integration test with `@Configuration` classes instead of XML: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @Profile("dev") - public class StandaloneDataConfig { - - @Bean - public DataSource dataSource() { - return new EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .addScript("classpath:com/bank/config/sql/test-data.sql") - .build(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @Profile("dev") - class StandaloneDataConfig { - - @Bean - fun dataSource(): DataSource { - return EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .addScript("classpath:com/bank/config/sql/test-data.sql") - .build() - } - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @Profile("production") - public class JndiDataConfig { - - @Bean(destroyMethod="") - public DataSource dataSource() throws Exception { - Context ctx = new InitialContext(); - return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource"); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @Profile("production") - class JndiDataConfig { - - @Bean(destroyMethod = "") - fun dataSource(): DataSource { - val ctx = InitialContext() - return ctx.lookup("java:comp/env/jdbc/datasource") as DataSource - } - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @Profile("default") - public class DefaultDataConfig { - - @Bean - public DataSource dataSource() { - return new EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .build(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @Profile("default") - class DefaultDataConfig { - - @Bean - fun dataSource(): DataSource { - return EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .build() - } - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class TransferServiceConfig { - - @Autowired DataSource dataSource; - - @Bean - public TransferService transferService() { - return new DefaultTransferService(accountRepository(), feePolicy()); - } - - @Bean - public AccountRepository accountRepository() { - return new JdbcAccountRepository(dataSource); - } - - @Bean - public FeePolicy feePolicy() { - return new ZeroFeePolicy(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class TransferServiceConfig { - - @Autowired - lateinit var dataSource: DataSource - - @Bean - fun transferService(): TransferService { - return DefaultTransferService(accountRepository(), feePolicy()) - } - - @Bean - fun accountRepository(): AccountRepository { - return JdbcAccountRepository(dataSource) - } - - @Bean - fun feePolicy(): FeePolicy { - return ZeroFeePolicy() - } - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig({ - TransferServiceConfig.class, - StandaloneDataConfig.class, - JndiDataConfig.class, - DefaultDataConfig.class}) - @ActiveProfiles("dev") - class TransferServiceTest { - - @Autowired - TransferService transferService; - - @Test - void testTransferService() { - // test the transferService - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig( - TransferServiceConfig::class, - StandaloneDataConfig::class, - JndiDataConfig::class, - DefaultDataConfig::class) - @ActiveProfiles("dev") - class TransferServiceTest { - - @Autowired - lateinit var transferService: TransferService - - @Test - fun testTransferService() { - // test the transferService - } - } ----- - -In this variation, we have split the XML configuration into four independent -`@Configuration` classes: - -* `TransferServiceConfig`: Acquires a `dataSource` through dependency injection by using - `@Autowired`. -* `StandaloneDataConfig`: Defines a `dataSource` for an embedded database suitable for - developer tests. -* `JndiDataConfig`: Defines a `dataSource` that is retrieved from JNDI in a production - environment. -* `DefaultDataConfig`: Defines a `dataSource` for a default embedded database, in case no - profile is active. - -As with the XML-based configuration example, we still annotate `TransferServiceTest` with -`@ActiveProfiles("dev")`, but this time we specify all four configuration classes by -using the `@ContextConfiguration` annotation. The body of the test class itself remains -completely unchanged. - -It is often the case that a single set of profiles is used across multiple test classes -within a given project. Thus, to avoid duplicate declarations of the `@ActiveProfiles` -annotation, you can declare `@ActiveProfiles` once on a base class, and subclasses -automatically inherit the `@ActiveProfiles` configuration from the base class. In the -following example, the declaration of `@ActiveProfiles` (as well as other annotations) -has been moved to an abstract superclass, `AbstractIntegrationTest`: - -NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing -classes. See <<testcontext-junit-jupiter-nested-test-configuration>> for details. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig({ - TransferServiceConfig.class, - StandaloneDataConfig.class, - JndiDataConfig.class, - DefaultDataConfig.class}) - @ActiveProfiles("dev") - abstract class AbstractIntegrationTest { - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig( - TransferServiceConfig::class, - StandaloneDataConfig::class, - JndiDataConfig::class, - DefaultDataConfig::class) - @ActiveProfiles("dev") - abstract class AbstractIntegrationTest { - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // "dev" profile inherited from superclass - class TransferServiceTest extends AbstractIntegrationTest { - - @Autowired - TransferService transferService; - - @Test - void testTransferService() { - // test the transferService - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // "dev" profile inherited from superclass - class TransferServiceTest : AbstractIntegrationTest() { - - @Autowired - lateinit var transferService: TransferService - - @Test - fun testTransferService() { - // test the transferService - } - } ----- - -`@ActiveProfiles` also supports an `inheritProfiles` attribute that can be used to -disable the inheritance of active profiles, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // "dev" profile overridden with "production" - @ActiveProfiles(profiles = "production", inheritProfiles = false) - class ProductionTransferServiceTest extends AbstractIntegrationTest { - // test body - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // "dev" profile overridden with "production" - @ActiveProfiles("production", inheritProfiles = false) - class ProductionTransferServiceTest : AbstractIntegrationTest() { - // test body - } ----- - -[[testcontext-ctx-management-env-profiles-ActiveProfilesResolver]] -Furthermore, it is sometimes necessary to resolve active profiles for tests -programmatically instead of declaratively -- for example, based on: - -* The current operating system. -* Whether tests are being run on a continuous integration build server. -* The presence of certain environment variables. -* The presence of custom class-level annotations. -* Other concerns. - -To resolve active bean definition profiles programmatically, you can implement -a custom `ActiveProfilesResolver` and register it by using the `resolver` -attribute of `@ActiveProfiles`. For further information, see the corresponding -{api-spring-framework}/test/context/ActiveProfilesResolver.html[javadoc]. -The following example demonstrates how to implement and register a custom -`OperatingSystemActiveProfilesResolver`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // "dev" profile overridden programmatically via a custom resolver - @ActiveProfiles( - resolver = OperatingSystemActiveProfilesResolver.class, - inheritProfiles = false) - class TransferServiceTest extends AbstractIntegrationTest { - // test body - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // "dev" profile overridden programmatically via a custom resolver - @ActiveProfiles( - resolver = OperatingSystemActiveProfilesResolver::class, - inheritProfiles = false) - class TransferServiceTest : AbstractIntegrationTest() { - // test body - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class OperatingSystemActiveProfilesResolver implements ActiveProfilesResolver { - - @Override - public String[] resolve(Class<?> testClass) { - String profile = ...; - // determine the value of profile based on the operating system - return new String[] {profile}; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class OperatingSystemActiveProfilesResolver : ActiveProfilesResolver { - - override fun resolve(testClass: Class<*>): Array<String> { - val profile: String = ... - // determine the value of profile based on the operating system - return arrayOf(profile) - } - } ----- - -[[testcontext-ctx-management-property-sources]] -=== Context Configuration with Test Property Sources - -The Spring Framework has first-class support for the notion of an environment with a -hierarchy of property sources, and you can configure integration tests with test-specific -property sources. In contrast to the `@PropertySource` annotation used on -`@Configuration` classes, you can declare the `@TestPropertySource` annotation on a test -class to declare resource locations for test properties files or inlined properties. -These test property sources are added to the set of `PropertySources` in the -`Environment` for the `ApplicationContext` loaded for the annotated integration test. - -[NOTE] -==== -You can use `@TestPropertySource` with any implementation of the `SmartContextLoader` -SPI, but `@TestPropertySource` is not supported with implementations of the older -`ContextLoader` SPI. - -Implementations of `SmartContextLoader` gain access to merged test property source values -through the `getPropertySourceLocations()` and `getPropertySourceProperties()` methods in -`MergedContextConfiguration`. -==== - -[[declaring-test-property-sources]] -==== Declaring Test Property Sources - -You can configure test properties files by using the `locations` or `value` attribute of -`@TestPropertySource`. - -Both traditional and XML-based properties file formats are supported -- for example, -`"classpath:/com/example/test.properties"` or `"file:///path/to/file.xml"`. - -Each path is interpreted as a Spring `Resource`. A plain path (for example, -`"test.properties"`) is treated as a classpath resource that is relative to the package -in which the test class is defined. A path starting with a slash is treated as an -absolute classpath resource (for example: `"/org/example/test.xml"`). A path that -references a URL (for example, a path prefixed with `classpath:`, `file:`, or `http:`) is -loaded by using the specified resource protocol. Resource location wildcards (such as -`**/*.properties`) are not permitted: Each location must evaluate to exactly one -`.properties` or `.xml` resource. - -The following example uses a test properties file: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @TestPropertySource("/test.properties") // <1> - class MyIntegrationTests { - // class body... - } ----- -<1> Specifying a properties file with an absolute path. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @TestPropertySource("/test.properties") // <1> - class MyIntegrationTests { - // class body... - } ----- -<1> Specifying a properties file with an absolute path. - - -You can configure inlined properties in the form of key-value pairs by using the -`properties` attribute of `@TestPropertySource`, as shown in the next example. All -key-value pairs are added to the enclosing `Environment` as a single test -`PropertySource` with the highest precedence. - -The supported syntax for key-value pairs is the same as the syntax defined for entries in -a Java properties file: - -* `key=value` -* `key:value` -* `key value` - -The following example sets two inlined properties: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @TestPropertySource(properties = {"timezone = GMT", "port: 4242"}) // <1> - class MyIntegrationTests { - // class body... - } ----- -<1> Setting two properties by using two variations of the key-value syntax. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @TestPropertySource(properties = ["timezone = GMT", "port: 4242"]) // <1> - class MyIntegrationTests { - // class body... - } ----- -<1> Setting two properties by using two variations of the key-value syntax. - -[NOTE] -==== -As of Spring Framework 5.2, `@TestPropertySource` can be used as _repeatable annotation_. -That means that you can have multiple declarations of `@TestPropertySource` on a single -test class, with the `locations` and `properties` from later `@TestPropertySource` -annotations overriding those from previous `@TestPropertySource` annotations. - -In addition, you may declare multiple composed annotations on a test class that are each -meta-annotated with `@TestPropertySource`, and all of those `@TestPropertySource` -declarations will contribute to your test property sources. - -Directly present `@TestPropertySource` annotations always take precedence over -meta-present `@TestPropertySource` annotations. In other words, `locations` and -`properties` from a directly present `@TestPropertySource` annotation will override the -`locations` and `properties` from a `@TestPropertySource` annotation used as a -meta-annotation. -==== - - -[[default-properties-file-detection]] -==== Default Properties File Detection - -If `@TestPropertySource` is declared as an empty annotation (that is, without explicit -values for the `locations` or `properties` attributes), an attempt is made to detect a -default properties file relative to the class that declared the annotation. For example, -if the annotated test class is `com.example.MyTest`, the corresponding default properties -file is `classpath:com/example/MyTest.properties`. If the default cannot be detected, an -`IllegalStateException` is thrown. - -[[precedence]] -==== Precedence - -Test properties have higher precedence than those defined in the operating system's -environment, Java system properties, or property sources added by the application -declaratively by using `@PropertySource` or programmatically. Thus, test properties can -be used to selectively override properties loaded from system and application property -sources. Furthermore, inlined properties have higher precedence than properties loaded -from resource locations. Note, however, that properties registered via -<<testcontext-ctx-management-dynamic-property-sources, `@DynamicPropertySource`>> have -higher precedence than those loaded via `@TestPropertySource`. - -In the next example, the `timezone` and `port` properties and any properties defined in -`"/test.properties"` override any properties of the same name that are defined in system -and application property sources. Furthermore, if the `"/test.properties"` file defines -entries for the `timezone` and `port` properties those are overridden by the inlined -properties declared by using the `properties` attribute. The following example shows how -to specify properties both in a file and inline: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration - @TestPropertySource( - locations = "/test.properties", - properties = {"timezone = GMT", "port: 4242"} - ) - class MyIntegrationTests { - // class body... - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration - @TestPropertySource("/test.properties", - properties = ["timezone = GMT", "port: 4242"] - ) - class MyIntegrationTests { - // class body... - } ----- - -[[inheriting-and-overriding-test-property-sources]] -==== Inheriting and Overriding Test Property Sources - -`@TestPropertySource` supports boolean `inheritLocations` and `inheritProperties` -attributes that denote whether resource locations for properties files and inlined -properties declared by superclasses should be inherited. The default value for both flags -is `true`. This means that a test class inherits the locations and inlined properties -declared by any superclasses. Specifically, the locations and inlined properties for a -test class are appended to the locations and inlined properties declared by superclasses. -Thus, subclasses have the option of extending the locations and inlined properties. Note -that properties that appear later shadow (that is, override) properties of the same name -that appear earlier. In addition, the aforementioned precedence rules apply for inherited -test property sources as well. - -If the `inheritLocations` or `inheritProperties` attribute in `@TestPropertySource` is -set to `false`, the locations or inlined properties, respectively, for the test class -shadow and effectively replace the configuration defined by superclasses. - -NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing -classes. See <<testcontext-junit-jupiter-nested-test-configuration>> for details. - -In the next example, the `ApplicationContext` for `BaseTest` is loaded by using only the -`base.properties` file as a test property source. In contrast, the `ApplicationContext` -for `ExtendedTest` is loaded by using the `base.properties` and `extended.properties` -files as test property source locations. The following example shows how to define -properties in both a subclass and its superclass by using `properties` files: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @TestPropertySource("base.properties") - @ContextConfiguration - class BaseTest { - // ... - } - - @TestPropertySource("extended.properties") - @ContextConfiguration - class ExtendedTest extends BaseTest { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @TestPropertySource("base.properties") - @ContextConfiguration - open class BaseTest { - // ... - } - - @TestPropertySource("extended.properties") - @ContextConfiguration - class ExtendedTest : BaseTest() { - // ... - } ----- - -In the next example, the `ApplicationContext` for `BaseTest` is loaded by using only the -inlined `key1` property. In contrast, the `ApplicationContext` for `ExtendedTest` is -loaded by using the inlined `key1` and `key2` properties. The following example shows how -to define properties in both a subclass and its superclass by using inline properties: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @TestPropertySource(properties = "key1 = value1") - @ContextConfiguration - class BaseTest { - // ... - } - - @TestPropertySource(properties = "key2 = value2") - @ContextConfiguration - class ExtendedTest extends BaseTest { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @TestPropertySource(properties = ["key1 = value1"]) - @ContextConfiguration - open class BaseTest { - // ... - } - - @TestPropertySource(properties = ["key2 = value2"]) - @ContextConfiguration - class ExtendedTest : BaseTest() { - // ... - } ----- - -[[testcontext-ctx-management-dynamic-property-sources]] -=== Context Configuration with Dynamic Property Sources - -As of Spring Framework 5.2.5, the TestContext framework provides support for _dynamic_ -properties via the `@DynamicPropertySource` annotation. This annotation can be used in -integration tests that need to add properties with dynamic values to the set of -`PropertySources` in the `Environment` for the `ApplicationContext` loaded for the -integration test. - -[NOTE] -==== -The `@DynamicPropertySource` annotation and its supporting infrastructure were -originally designed to allow properties from -https://www.testcontainers.org/[Testcontainers] based tests to be exposed easily to -Spring integration tests. However, this feature may also be used with any form of -external resource whose lifecycle is maintained outside the test's `ApplicationContext`. -==== - -In contrast to the <<testcontext-ctx-management-property-sources,`@TestPropertySource`>> -annotation that is applied at the class level, `@DynamicPropertySource` must be applied -to a `static` method that accepts a single `DynamicPropertyRegistry` argument which is -used to add _name-value_ pairs to the `Environment`. Values are dynamic and provided via -a `Supplier` which is only invoked when the property is resolved. Typically, method -references are used to supply values, as can be seen in the following example which uses -the Testcontainers project to manage a Redis container outside of the Spring -`ApplicationContext`. The IP address and port of the managed Redis container are made -available to components within the test's `ApplicationContext` via the `redis.host` and -`redis.port` properties. These properties can be accessed via Spring's `Environment` -abstraction or injected directly into Spring-managed components – for example, via -`@Value("${redis.host}")` and `@Value("${redis.port}")`, respectively. - -[TIP] -==== -If you use `@DynamicPropertySource` in a base class and discover that tests in subclasses -fail because the dynamic properties change between subclasses, you may need to annotate -your base class with <<spring-testing-annotation-dirtiescontext, `@DirtiesContext`>> to -ensure that each subclass gets its own `ApplicationContext` with the correct dynamic -properties. -==== - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(/* ... */) - @Testcontainers - class ExampleIntegrationTests { - - @Container - static GenericContainer redis = - new GenericContainer("redis:5.0.3-alpine").withExposedPorts(6379); - - @DynamicPropertySource - static void redisProperties(DynamicPropertyRegistry registry) { - registry.add("redis.host", redis::getHost); - registry.add("redis.port", redis::getFirstMappedPort); - } - - // tests ... - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(/* ... */) - @Testcontainers - class ExampleIntegrationTests { - - companion object { - - @Container - @JvmStatic - val redis: GenericContainer = - GenericContainer("redis:5.0.3-alpine").withExposedPorts(6379) - - @DynamicPropertySource - @JvmStatic - fun redisProperties(registry: DynamicPropertyRegistry) { - registry.add("redis.host", redis::getHost) - registry.add("redis.port", redis::getFirstMappedPort) - } - } - - // tests ... - - } ----- - -[[precedence]] -==== Precedence - -Dynamic properties have higher precedence than those loaded from `@TestPropertySource`, -the operating system's environment, Java system properties, or property sources added by -the application declaratively by using `@PropertySource` or programmatically. Thus, -dynamic properties can be used to selectively override properties loaded via -`@TestPropertySource`, system property sources, and application property sources. - -[[testcontext-ctx-management-web]] -=== Loading a `WebApplicationContext` - -To instruct the TestContext framework to load a `WebApplicationContext` instead of a -standard `ApplicationContext`, you can annotate the respective test class with -`@WebAppConfiguration`. - -The presence of `@WebAppConfiguration` on your test class instructs the TestContext -framework (TCF) that a `WebApplicationContext` (WAC) should be loaded for your -integration tests. In the background, the TCF makes sure that a `MockServletContext` is -created and supplied to your test's WAC. By default, the base resource path for your -`MockServletContext` is set to `src/main/webapp`. This is interpreted as a path relative -to the root of your JVM (normally the path to your project). If you are familiar with the -directory structure of a web application in a Maven project, you know that -`src/main/webapp` is the default location for the root of your WAR. If you need to -override this default, you can provide an alternate path to the `@WebAppConfiguration` -annotation (for example, `@WebAppConfiguration("src/test/webapp")`). If you wish to -reference a base resource path from the classpath instead of the file system, you can use -Spring's `classpath:` prefix. - -Note that Spring's testing support for `WebApplicationContext` implementations is on par -with its support for standard `ApplicationContext` implementations. When testing with a -`WebApplicationContext`, you are free to declare XML configuration files, Groovy scripts, -or `@Configuration` classes by using `@ContextConfiguration`. You are also free to use -any other test annotations, such as `@ActiveProfiles`, `@TestExecutionListeners`, `@Sql`, -`@Rollback`, and others. - -The remaining examples in this section show some of the various configuration options for -loading a `WebApplicationContext`. The following example shows the TestContext -framework's support for convention over configuration: - -.Conventions -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - - // defaults to "file:src/main/webapp" - @WebAppConfiguration - - // detects "WacTests-context.xml" in the same package - // or static nested @Configuration classes - @ContextConfiguration - class WacTests { - //... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - - // defaults to "file:src/main/webapp" - @WebAppConfiguration - - // detects "WacTests-context.xml" in the same package - // or static nested @Configuration classes - @ContextConfiguration - class WacTests { - //... - } ----- - -If you annotate a test class with `@WebAppConfiguration` without specifying a resource -base path, the resource path effectively defaults to `file:src/main/webapp`. Similarly, -if you declare `@ContextConfiguration` without specifying resource `locations`, component -`classes`, or context `initializers`, Spring tries to detect the presence of your -configuration by using conventions (that is, `WacTests-context.xml` in the same package -as the `WacTests` class or static nested `@Configuration` classes). - -The following example shows how to explicitly declare a resource base path with -`@WebAppConfiguration` and an XML resource location with `@ContextConfiguration`: - -.Default resource semantics -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - - // file system resource - @WebAppConfiguration("webapp") - - // classpath resource - @ContextConfiguration("/spring/test-servlet-config.xml") - class WacTests { - //... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - - // file system resource - @WebAppConfiguration("webapp") - - // classpath resource - @ContextConfiguration("/spring/test-servlet-config.xml") - class WacTests { - //... - } ----- - -The important thing to note here is the different semantics for paths with these two -annotations. By default, `@WebAppConfiguration` resource paths are file system based, -whereas `@ContextConfiguration` resource locations are classpath based. - -The following example shows that we can override the default resource semantics for both -annotations by specifying a Spring resource prefix: - -.Explicit resource semantics -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - - // classpath resource - @WebAppConfiguration("classpath:test-web-resources") - - // file system resource - @ContextConfiguration("file:src/main/webapp/WEB-INF/servlet-config.xml") - class WacTests { - //... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - - // classpath resource - @WebAppConfiguration("classpath:test-web-resources") - - // file system resource - @ContextConfiguration("file:src/main/webapp/WEB-INF/servlet-config.xml") - class WacTests { - //... - } ----- - -Contrast the comments in this example with the previous example. - -[[testcontext-ctx-management-web-mocks]] -=== Working with Web Mocks - -To provide comprehensive web testing support, the TestContext framework has a -`ServletTestExecutionListener` that is enabled by default. When testing against a -`WebApplicationContext`, this <<testcontext-key-abstractions, `TestExecutionListener`>> -sets up default thread-local state by using Spring Web's `RequestContextHolder` before -each test method and creates a `MockHttpServletRequest`, a `MockHttpServletResponse`, and -a `ServletWebRequest` based on the base resource path configured with -`@WebAppConfiguration`. `ServletTestExecutionListener` also ensures that the -`MockHttpServletResponse` and `ServletWebRequest` can be injected into the test instance, -and, once the test is complete, it cleans up thread-local state. - -Once you have a `WebApplicationContext` loaded for your test, you might find that you -need to interact with the web mocks -- for example, to set up your test fixture or to -perform assertions after invoking your web component. The following example shows which -mocks can be autowired into your test instance. Note that the `WebApplicationContext` and -`MockServletContext` are both cached across the test suite, whereas the other mocks are -managed per test method by the `ServletTestExecutionListener`. - -.Injecting mocks -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitWebConfig - class WacTests { - - @Autowired - WebApplicationContext wac; // cached - - @Autowired - MockServletContext servletContext; // cached - - @Autowired - MockHttpSession session; - - @Autowired - MockHttpServletRequest request; - - @Autowired - MockHttpServletResponse response; - - @Autowired - ServletWebRequest webRequest; - - //... - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitWebConfig - class WacTests { - - @Autowired - lateinit var wac: WebApplicationContext // cached - - @Autowired - lateinit var servletContext: MockServletContext // cached - - @Autowired - lateinit var session: MockHttpSession - - @Autowired - lateinit var request: MockHttpServletRequest - - @Autowired - lateinit var response: MockHttpServletResponse - - @Autowired - lateinit var webRequest: ServletWebRequest - - //... - } ----- - -[[testcontext-ctx-management-caching]] -=== Context Caching - -Once the TestContext framework loads an `ApplicationContext` (or `WebApplicationContext`) -for a test, that context is cached and reused for all subsequent tests that declare the -same unique context configuration within the same test suite. To understand how caching -works, it is important to understand what is meant by "`unique`" and "`test suite.`" - -An `ApplicationContext` can be uniquely identified by the combination of configuration -parameters that is used to load it. Consequently, the unique combination of configuration -parameters is used to generate a key under which the context is cached. The TestContext -framework uses the following configuration parameters to build the context cache key: - -* `locations` (from `@ContextConfiguration`) -* `classes` (from `@ContextConfiguration`) -* `contextInitializerClasses` (from `@ContextConfiguration`) -* `contextCustomizers` (from `ContextCustomizerFactory`) – this includes - `@DynamicPropertySource` methods as well as various features from Spring Boot's - testing support such as `@MockBean` and `@SpyBean`. -* `contextLoader` (from `@ContextConfiguration`) -* `parent` (from `@ContextHierarchy`) -* `activeProfiles` (from `@ActiveProfiles`) -* `propertySourceLocations` (from `@TestPropertySource`) -* `propertySourceProperties` (from `@TestPropertySource`) -* `resourceBasePath` (from `@WebAppConfiguration`) - -For example, if `TestClassA` specifies `{"app-config.xml", "test-config.xml"}` for the -`locations` (or `value`) attribute of `@ContextConfiguration`, the TestContext framework -loads the corresponding `ApplicationContext` and stores it in a `static` context cache -under a key that is based solely on those locations. So, if `TestClassB` also defines -`{"app-config.xml", "test-config.xml"}` for its locations (either explicitly or -implicitly through inheritance) but does not define `@WebAppConfiguration`, a different -`ContextLoader`, different active profiles, different context initializers, different -test property sources, or a different parent context, then the same `ApplicationContext` -is shared by both test classes. This means that the setup cost for loading an application -context is incurred only once (per test suite), and subsequent test execution is much -faster. - -.Test suites and forked processes -[NOTE] -==== -The Spring TestContext framework stores application contexts in a static cache. This -means that the context is literally stored in a `static` variable. In other words, if -tests run in separate processes, the static cache is cleared between each test -execution, which effectively disables the caching mechanism. - -To benefit from the caching mechanism, all tests must run within the same process or test -suite. This can be achieved by executing all tests as a group within an IDE. Similarly, -when executing tests with a build framework such as Ant, Maven, or Gradle, it is -important to make sure that the build framework does not fork between tests. For example, -if the -https://maven.apache.org/plugins/maven-surefire-plugin/test-mojo.html#forkMode[`forkMode`] -for the Maven Surefire plug-in is set to `always` or `pertest`, the TestContext framework -cannot cache application contexts between test classes, and the build process runs -significantly more slowly as a result. -==== - -The size of the context cache is bounded with a default maximum size of 32. Whenever the -maximum size is reached, a least recently used (LRU) eviction policy is used to evict and -close stale contexts. You can configure the maximum size from the command line or a build -script by setting a JVM system property named `spring.test.context.cache.maxSize`. As an -alternative, you can set the same property via the -<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism. - -Since having a large number of application contexts loaded within a given test suite can -cause the suite to take an unnecessarily long time to run, it is often beneficial to -know exactly how many contexts have been loaded and cached. To view the statistics for -the underlying context cache, you can set the log level for the -`org.springframework.test.context.cache` logging category to `DEBUG`. - -In the unlikely case that a test corrupts the application context and requires reloading -(for example, by modifying a bean definition or the state of an application object), you -can annotate your test class or test method with `@DirtiesContext` (see the discussion of -`@DirtiesContext` in <<spring-testing-annotation-dirtiescontext, Spring Testing -Annotations>>). This instructs Spring to remove the context from the cache and rebuild -the application context before running the next test that requires the same application -context. Note that support for the `@DirtiesContext` annotation is provided by the -`DirtiesContextBeforeModesTestExecutionListener` and the -`DirtiesContextTestExecutionListener`, which are enabled by default. - -.ApplicationContext lifecycle and console logging -[NOTE] -==== -When you need to debug a test executed with the Spring TestContext Framework, it can be -useful to analyze the console output (that is, output to the `SYSOUT` and `SYSERR` -streams). Some build tools and IDEs are able to associate console output with a given -test; however, some console output cannot be easily associated with a given test. - -With regard to console logging triggered by the Spring Framework itself or by components -registered in the `ApplicationContext`, it is important to understand the lifecycle of an -`ApplicationContext` that has been loaded by the Spring TestContext Framework within a -test suite. - -The `ApplicationContext` for a test is typically loaded when an instance of the test -class is being prepared -- for example, to perform dependency injection into `@Autowired` -fields of the test instance. This means that any console logging triggered during the -initialization of the `ApplicationContext` typically cannot be associated with an -individual test method. However, if the context is closed immediately before the -execution of a test method according to <<spring-testing-annotation-dirtiescontext>> -semantics, a new instance of the context will be loaded just prior to execution of the -test method. In the latter scenario, an IDE or build tool may potentially associate -console logging with the individual test method. - -The `ApplicationContext` for a test can be closed via one of the following scenarios. - -* The context is closed according to `@DirtiesContext` semantics. -* The context is closed because it has been automatically evicted from the cache - according to the LRU eviction policy. -* The context is closed via a JVM shutdown hook when the JVM for the test suite - terminates. - -If the context is closed according to `@DirtiesContext` semantics after a particular test -method, an IDE or build tool may potentially associate console logging with the -individual test method. If the context is closed according to `@DirtiesContext` semantics -after a test class, any console logging triggered during the shutdown of the -`ApplicationContext` cannot be associated with an individual test method. Similarly, any -console logging triggered during the shutdown phase via a JVM shutdown hook cannot be -associated with an individual test method. - -When a Spring `ApplicationContext` is closed via a JVM shutdown hook, callbacks executed -during the shutdown phase are executed on a thread named `SpringContextShutdownHook`. So, -if you wish to disable console logging triggered when the `ApplicationContext` is closed -via a JVM shutdown hook, you may be able to register a custom filter with your logging -framework that allows you to ignore any logging initiated by that thread. -==== - -[[testcontext-ctx-management-ctx-hierarchies]] -=== Context Hierarchies - -When writing integration tests that rely on a loaded Spring `ApplicationContext`, it is -often sufficient to test against a single context. However, there are times when it is -beneficial or even necessary to test against a hierarchy of `ApplicationContext` -instances. For example, if you are developing a Spring MVC web application, you typically -have a root `WebApplicationContext` loaded by Spring's `ContextLoaderListener` and a -child `WebApplicationContext` loaded by Spring's `DispatcherServlet`. This results in a -parent-child context hierarchy where shared components and infrastructure configuration -are declared in the root context and consumed in the child context by web-specific -components. Another use case can be found in Spring Batch applications, where you often -have a parent context that provides configuration for shared batch infrastructure and a -child context for the configuration of a specific batch job. - -You can write integration tests that use context hierarchies by declaring context -configuration with the `@ContextHierarchy` annotation, either on an individual test class -or within a test class hierarchy. If a context hierarchy is declared on multiple classes -within a test class hierarchy, you can also merge or override the context configuration -for a specific, named level in the context hierarchy. When merging configuration for a -given level in the hierarchy, the configuration resource type (that is, XML configuration -files or component classes) must be consistent. Otherwise, it is perfectly acceptable to -have different levels in a context hierarchy configured using different resource types. - -The remaining JUnit Jupiter based examples in this section show common configuration -scenarios for integration tests that require the use of context hierarchies. - -**Single test class with context hierarchy** --- -`ControllerIntegrationTests` represents a typical integration testing scenario for a -Spring MVC web application by declaring a context hierarchy that consists of two levels, -one for the root `WebApplicationContext` (loaded by using the `TestAppConfig` -`@Configuration` class) and one for the dispatcher servlet `WebApplicationContext` -(loaded by using the `WebConfig` `@Configuration` class). The `WebApplicationContext` -that is autowired into the test instance is the one for the child context (that is, the -lowest context in the hierarchy). The following listing shows this configuration scenario: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - @WebAppConfiguration - @ContextHierarchy({ - @ContextConfiguration(classes = TestAppConfig.class), - @ContextConfiguration(classes = WebConfig.class) - }) - class ControllerIntegrationTests { - - @Autowired - WebApplicationContext wac; - - // ... - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - @WebAppConfiguration - @ContextHierarchy( - ContextConfiguration(classes = [TestAppConfig::class]), - ContextConfiguration(classes = [WebConfig::class])) - class ControllerIntegrationTests { - - @Autowired - lateinit var wac: WebApplicationContext - - // ... - } ----- --- - -**Class hierarchy with implicit parent context** --- -The test classes in this example define a context hierarchy within a test class -hierarchy. `AbstractWebTests` declares the configuration for a root -`WebApplicationContext` in a Spring-powered web application. Note, however, that -`AbstractWebTests` does not declare `@ContextHierarchy`. Consequently, subclasses of -`AbstractWebTests` can optionally participate in a context hierarchy or follow the -standard semantics for `@ContextConfiguration`. `SoapWebServiceTests` and -`RestWebServiceTests` both extend `AbstractWebTests` and define a context hierarchy by -using `@ContextHierarchy`. The result is that three application contexts are loaded (one -for each declaration of `@ContextConfiguration`), and the application context loaded -based on the configuration in `AbstractWebTests` is set as the parent context for each of -the contexts loaded for the concrete subclasses. The following listing shows this -configuration scenario: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - @WebAppConfiguration - @ContextConfiguration("file:src/main/webapp/WEB-INF/applicationContext.xml") - public abstract class AbstractWebTests {} - - @ContextHierarchy(@ContextConfiguration("/spring/soap-ws-config.xml")) - public class SoapWebServiceTests extends AbstractWebTests {} - - @ContextHierarchy(@ContextConfiguration("/spring/rest-ws-config.xml")) - public class RestWebServiceTests extends AbstractWebTests {} ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - @WebAppConfiguration - @ContextConfiguration("file:src/main/webapp/WEB-INF/applicationContext.xml") - abstract class AbstractWebTests - - @ContextHierarchy(ContextConfiguration("/spring/soap-ws-config.xml")) - class SoapWebServiceTests : AbstractWebTests() - - @ContextHierarchy(ContextConfiguration("/spring/rest-ws-config.xml")) - class RestWebServiceTests : AbstractWebTests() - ----- --- - -**Class hierarchy with merged context hierarchy configuration** --- -The classes in this example show the use of named hierarchy levels in order to merge the -configuration for specific levels in a context hierarchy. `BaseTests` defines two levels -in the hierarchy, `parent` and `child`. `ExtendedTests` extends `BaseTests` and instructs -the Spring TestContext Framework to merge the context configuration for the `child` -hierarchy level, by ensuring that the names declared in the `name` attribute in -`@ContextConfiguration` are both `child`. The result is that three application contexts -are loaded: one for `/app-config.xml`, one for `/user-config.xml`, and one for -`{"/user-config.xml", "/order-config.xml"}`. As with the previous example, the -application context loaded from `/app-config.xml` is set as the parent context for the -contexts loaded from `/user-config.xml` and `{"/user-config.xml", "/order-config.xml"}`. -The following listing shows this configuration scenario: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - @ContextHierarchy({ - @ContextConfiguration(name = "parent", locations = "/app-config.xml"), - @ContextConfiguration(name = "child", locations = "/user-config.xml") - }) - class BaseTests {} - - @ContextHierarchy( - @ContextConfiguration(name = "child", locations = "/order-config.xml") - ) - class ExtendedTests extends BaseTests {} ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - @ContextHierarchy( - ContextConfiguration(name = "parent", locations = ["/app-config.xml"]), - ContextConfiguration(name = "child", locations = ["/user-config.xml"])) - open class BaseTests {} - - @ContextHierarchy( - ContextConfiguration(name = "child", locations = ["/order-config.xml"]) - ) - class ExtendedTests : BaseTests() {} ----- --- - -**Class hierarchy with overridden context hierarchy configuration** --- -In contrast to the previous example, this example demonstrates how to override the -configuration for a given named level in a context hierarchy by setting the -`inheritLocations` flag in `@ContextConfiguration` to `false`. Consequently, the -application context for `ExtendedTests` is loaded only from `/test-user-config.xml` and -has its parent set to the context loaded from `/app-config.xml`. The following listing -shows this configuration scenario: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - @ContextHierarchy({ - @ContextConfiguration(name = "parent", locations = "/app-config.xml"), - @ContextConfiguration(name = "child", locations = "/user-config.xml") - }) - class BaseTests {} - - @ContextHierarchy( - @ContextConfiguration( - name = "child", - locations = "/test-user-config.xml", - inheritLocations = false - )) - class ExtendedTests extends BaseTests {} ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - @ContextHierarchy( - ContextConfiguration(name = "parent", locations = ["/app-config.xml"]), - ContextConfiguration(name = "child", locations = ["/user-config.xml"])) - open class BaseTests {} - - @ContextHierarchy( - ContextConfiguration( - name = "child", - locations = ["/test-user-config.xml"], - inheritLocations = false - )) - class ExtendedTests : BaseTests() {} ----- - -.Dirtying a context within a context hierarchy -NOTE: If you use `@DirtiesContext` in a test whose context is configured as part of a -context hierarchy, you can use the `hierarchyMode` flag to control how the context cache -is cleared. For further details, see the discussion of `@DirtiesContext` in -<<spring-testing-annotation-dirtiescontext, Spring Testing Annotations>> and the -{api-spring-framework}/test/annotation/DirtiesContext.html[`@DirtiesContext`] javadoc. --- - -[[testcontext-fixture-di]] -== Dependency Injection of Test Fixtures - -When you use the `DependencyInjectionTestExecutionListener` (which is configured by -default), the dependencies of your test instances are injected from beans in the -application context that you configured with `@ContextConfiguration` or related -annotations. You may use setter injection, field injection, or both, depending on -which annotations you choose and whether you place them on setter methods or fields. -If you are using JUnit Jupiter you may also optionally use constructor injection -(see <<testcontext-junit-jupiter-di>>). For consistency with Spring's annotation-based -injection support, you may also use Spring's `@Autowired` annotation or the `@Inject` -annotation from JSR-330 for field and setter injection. - -TIP: For testing frameworks other than JUnit Jupiter, the TestContext framework does not -participate in instantiation of the test class. Thus, the use of `@Autowired` or -`@Inject` for constructors has no effect for test classes. - -NOTE: Although field injection is discouraged in production code, field injection is -actually quite natural in test code. The rationale for the difference is that you will -never instantiate your test class directly. Consequently, there is no need to be able to -invoke a `public` constructor or setter method on your test class. - -Because `@Autowired` is used to perform <<core.adoc#beans-factory-autowire, autowiring by -type>>, if you have multiple bean definitions of the same type, you cannot rely on this -approach for those particular beans. In that case, you can use `@Autowired` in -conjunction with `@Qualifier`. You can also choose to use `@Inject` in conjunction with -`@Named`. Alternatively, if your test class has access to its `ApplicationContext`, you -can perform an explicit lookup by using (for example) a call to -`applicationContext.getBean("titleRepository", TitleRepository.class)`. - -If you do not want dependency injection applied to your test instances, do not annotate -fields or setter methods with `@Autowired` or `@Inject`. Alternatively, you can disable -dependency injection altogether by explicitly configuring your class with -`@TestExecutionListeners` and omitting `DependencyInjectionTestExecutionListener.class` -from the list of listeners. - -Consider the scenario of testing a `HibernateTitleRepository` class, as outlined in the -<<integration-testing-goals, Goals>> section. The next two code listings demonstrate the -use of `@Autowired` on fields and setter methods. The application context configuration -is presented after all sample code listings. - -[NOTE] -==== -The dependency injection behavior in the following code listings is not specific to JUnit -Jupiter. The same DI techniques can be used in conjunction with any supported testing -framework. - -The following examples make calls to static assertion methods, such as `assertNotNull()`, -but without prepending the call with `Assertions`. In such cases, assume that the method -was properly imported through an `import static` declaration that is not shown in the -example. -==== - -The first code listing shows a JUnit Jupiter based implementation of the test class that -uses `@Autowired` for field injection: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // specifies the Spring configuration to load for this test fixture - @ContextConfiguration("repository-config.xml") - class HibernateTitleRepositoryTests { - - // this instance will be dependency injected by type - @Autowired - HibernateTitleRepository titleRepository; - - @Test - void findById() { - Title title = titleRepository.findById(new Long(10)); - assertNotNull(title); - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // specifies the Spring configuration to load for this test fixture - @ContextConfiguration("repository-config.xml") - class HibernateTitleRepositoryTests { - - // this instance will be dependency injected by type - @Autowired - lateinit var titleRepository: HibernateTitleRepository - - @Test - fun findById() { - val title = titleRepository.findById(10) - assertNotNull(title) - } - } ----- - -Alternatively, you can configure the class to use `@Autowired` for setter injection, as -follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExtendWith(SpringExtension.class) - // specifies the Spring configuration to load for this test fixture - @ContextConfiguration("repository-config.xml") - class HibernateTitleRepositoryTests { - - // this instance will be dependency injected by type - HibernateTitleRepository titleRepository; - - @Autowired - void setTitleRepository(HibernateTitleRepository titleRepository) { - this.titleRepository = titleRepository; - } - - @Test - void findById() { - Title title = titleRepository.findById(new Long(10)); - assertNotNull(title); - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExtendWith(SpringExtension::class) - // specifies the Spring configuration to load for this test fixture - @ContextConfiguration("repository-config.xml") - class HibernateTitleRepositoryTests { - - // this instance will be dependency injected by type - lateinit var titleRepository: HibernateTitleRepository - - @Autowired - fun setTitleRepository(titleRepository: HibernateTitleRepository) { - this.titleRepository = titleRepository - } - - @Test - fun findById() { - val title = titleRepository.findById(10) - assertNotNull(title) - } - } ----- - -The preceding code listings use the same XML context file referenced by the -`@ContextConfiguration` annotation (that is, `repository-config.xml`). The following -shows this configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <?xml version="1.0" encoding="UTF-8"?> - <beans xmlns="http://www.springframework.org/schema/beans" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.springframework.org/schema/beans - https://www.springframework.org/schema/beans/spring-beans.xsd"> - - <!-- this bean will be injected into the HibernateTitleRepositoryTests class --> - <bean id="titleRepository" class="com.foo.repository.hibernate.HibernateTitleRepository"> - <property name="sessionFactory" ref="sessionFactory"/> - </bean> - - <bean id="sessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactoryBean"> - <!-- configuration elided for brevity --> - </bean> - - </beans> ----- - -[NOTE] -===== -If you are extending from a Spring-provided test base class that happens to use -`@Autowired` on one of its setter methods, you might have multiple beans of the affected -type defined in your application context (for example, multiple `DataSource` beans). In -such a case, you can override the setter method and use the `@Qualifier` annotation to -indicate a specific target bean, as follows (but make sure to delegate to the overridden -method in the superclass as well): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // ... - - @Autowired - @Override - public void setDataSource(@Qualifier("myDataSource") DataSource dataSource) { - super.setDataSource(dataSource); - } - - // ... ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // ... - - @Autowired - override fun setDataSource(@Qualifier("myDataSource") dataSource: DataSource) { - super.setDataSource(dataSource) - } - - // ... ----- - -The specified qualifier value indicates the specific `DataSource` bean to inject, -narrowing the set of type matches to a specific bean. Its value is matched against -`<qualifier>` declarations within the corresponding `<bean>` definitions. The bean name -is used as a fallback qualifier value, so you can effectively also point to a specific -bean by name there (as shown earlier, assuming that `myDataSource` is the bean `id`). -===== - - -[[testcontext-web-scoped-beans]] -== Testing Request- and Session-scoped Beans - -Spring has supported <<core#beans-factory-scopes-other, Request- and session-scoped -beans>> since the early years, and you can test your request-scoped and session-scoped -beans by following these steps: - -* Ensure that a `WebApplicationContext` is loaded for your test by annotating your test - class with `@WebAppConfiguration`. -* Inject the mock request or session into your test instance and prepare your test - fixture as appropriate. -* Invoke your web component that you retrieved from the configured - `WebApplicationContext` (with dependency injection). -* Perform assertions against the mocks. - -The next code snippet shows the XML configuration for a login use case. Note that the -`userService` bean has a dependency on a request-scoped `loginAction` bean. Also, the -`LoginAction` is instantiated by using <<core.adoc#expressions, SpEL expressions>> that -retrieve the username and password from the current HTTP request. In our test, we want to -configure these request parameters through the mock managed by the TestContext framework. -The following listing shows the configuration for this use case: - -.Request-scoped bean configuration -[source,xml,indent=0] ----- - <beans> - - <bean id="userService" class="com.example.SimpleUserService" - c:loginAction-ref="loginAction"/> - - <bean id="loginAction" class="com.example.LoginAction" - c:username="#{request.getParameter('user')}" - c:password="#{request.getParameter('pswd')}" - scope="request"> - <aop:scoped-proxy/> - </bean> - - </beans> ----- - -In `RequestScopedBeanTests`, we inject both the `UserService` (that is, the subject under -test) and the `MockHttpServletRequest` into our test instance. Within our -`requestScope()` test method, we set up our test fixture by setting request parameters in -the provided `MockHttpServletRequest`. When the `loginUser()` method is invoked on our -`userService`, we are assured that the user service has access to the request-scoped -`loginAction` for the current `MockHttpServletRequest` (that is, the one in which we just -set parameters). We can then perform assertions against the results based on the known -inputs for the username and password. The following listing shows how to do so: - -.Request-scoped bean test -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitWebConfig - class RequestScopedBeanTests { - - @Autowired UserService userService; - @Autowired MockHttpServletRequest request; - - @Test - void requestScope() { - request.setParameter("user", "enigma"); - request.setParameter("pswd", "$pr!ng"); - - LoginResults results = userService.loginUser(); - // assert results - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitWebConfig - class RequestScopedBeanTests { - - @Autowired lateinit var userService: UserService - @Autowired lateinit var request: MockHttpServletRequest - - @Test - fun requestScope() { - request.setParameter("user", "enigma") - request.setParameter("pswd", "\$pr!ng") - - val results = userService.loginUser() - // assert results - } - } ----- - -The following code snippet is similar to the one we saw earlier for a request-scoped -bean. However, this time, the `userService` bean has a dependency on a session-scoped -`userPreferences` bean. Note that the `UserPreferences` bean is instantiated by using a -SpEL expression that retrieves the theme from the current HTTP session. In our test, we -need to configure a theme in the mock session managed by the TestContext framework. The -following example shows how to do so: - -.Session-scoped bean configuration -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <beans> - - <bean id="userService" class="com.example.SimpleUserService" - c:userPreferences-ref="userPreferences" /> - - <bean id="userPreferences" class="com.example.UserPreferences" - c:theme="#{session.getAttribute('theme')}" - scope="session"> - <aop:scoped-proxy/> - </bean> - - </beans> ----- - -In `SessionScopedBeanTests`, we inject the `UserService` and the `MockHttpSession` into -our test instance. Within our `sessionScope()` test method, we set up our test fixture by -setting the expected `theme` attribute in the provided `MockHttpSession`. When the -`processUserPreferences()` method is invoked on our `userService`, we are assured that -the user service has access to the session-scoped `userPreferences` for the current -`MockHttpSession`, and we can perform assertions against the results based on the -configured theme. The following example shows how to do so: - -.Session-scoped bean test -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitWebConfig - class SessionScopedBeanTests { - - @Autowired UserService userService; - @Autowired MockHttpSession session; - - @Test - void sessionScope() throws Exception { - session.setAttribute("theme", "blue"); - - Results results = userService.processUserPreferences(); - // assert results - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitWebConfig - class SessionScopedBeanTests { - - @Autowired lateinit var userService: UserService - @Autowired lateinit var session: MockHttpSession - - @Test - fun sessionScope() { - session.setAttribute("theme", "blue") - - val results = userService.processUserPreferences() - // assert results - } - } ----- - -[[testcontext-tx]] -== Transaction Management - -In the TestContext framework, transactions are managed by the -`TransactionalTestExecutionListener`, which is configured by default, even if you do not -explicitly declare `@TestExecutionListeners` on your test class. To enable support for -transactions, however, you must configure a `PlatformTransactionManager` bean in the -`ApplicationContext` that is loaded with `@ContextConfiguration` semantics (further -details are provided later). In addition, you must declare Spring's `@Transactional` -annotation either at the class or the method level for your tests. - -[[testcontext-tx-test-managed-transactions]] -=== Test-managed Transactions - -Test-managed transactions are transactions that are managed declaratively by using the -`TransactionalTestExecutionListener` or programmatically by using `TestTransaction` -(described later). You should not confuse such transactions with Spring-managed -transactions (those managed directly by Spring within the `ApplicationContext` loaded for -tests) or application-managed transactions (those managed programmatically within -application code that is invoked by tests). Spring-managed and application-managed -transactions typically participate in test-managed transactions. However, you should use -caution if Spring-managed or application-managed transactions are configured with any -propagation type other than `REQUIRED` or `SUPPORTS` (see the discussion on -<<data-access.adoc#tx-propagation, transaction propagation>> for details). - -.Preemptive timeouts and test-managed transactions -[WARNING] -==== -Caution must be taken when using any form of preemptive timeouts from a testing framework -in conjunction with Spring's test-managed transactions. - -Specifically, Spring’s testing support binds transaction state to the current thread (via -a `java.lang.ThreadLocal` variable) _before_ the current test method is invoked. If a -testing framework invokes the current test method in a new thread in order to support a -preemptive timeout, any actions performed within the current test method will _not_ be -invoked within the test-managed transaction. Consequently, the result of any such actions -will not be rolled back with the test-managed transaction. On the contrary, such actions -will be committed to the persistent store -- for example, a relational database -- even -though the test-managed transaction is properly rolled back by Spring. - -Situations in which this can occur include but are not limited to the following. - -* JUnit 4's `@Test(timeout = ...)` support and `TimeOut` rule -* JUnit Jupiter's `assertTimeoutPreemptively(...)` methods in the - `org.junit.jupiter.api.Assertions` class -* TestNG's `@Test(timeOut = ...)` support -==== - -[[testcontext-tx-enabling-transactions]] -=== Enabling and Disabling Transactions - -Annotating a test method with `@Transactional` causes the test to be run within a -transaction that is, by default, automatically rolled back after completion of the test. -If a test class is annotated with `@Transactional`, each test method within that class -hierarchy runs within a transaction. Test methods that are not annotated with -`@Transactional` (at the class or method level) are not run within a transaction. Note -that `@Transactional` is not supported on test lifecycle methods — for example, methods -annotated with JUnit Jupiter's `@BeforeAll`, `@BeforeEach`, etc. Furthermore, tests that -are annotated with `@Transactional` but have the `propagation` attribute set to -`NOT_SUPPORTED` or `NEVER` are not run within a transaction. - -[[testcontext-tx-attribute-support]] -.`@Transactional` attribute support -|=== -|Attribute |Supported for test-managed transactions - -|`value` and `transactionManager` |yes - -|`propagation` |only `Propagation.NOT_SUPPORTED` and `Propagation.NEVER` are supported - -|`isolation` |no - -|`timeout` |no - -|`readOnly` |no - -|`rollbackFor` and `rollbackForClassName` |no: use `TestTransaction.flagForRollback()` instead - -|`noRollbackFor` and `noRollbackForClassName` |no: use `TestTransaction.flagForCommit()` instead -|=== - -[TIP] -==== -Method-level lifecycle methods — for example, methods annotated with JUnit Jupiter's -`@BeforeEach` or `@AfterEach` — are run within a test-managed transaction. On the other -hand, suite-level and class-level lifecycle methods — for example, methods annotated with -JUnit Jupiter's `@BeforeAll` or `@AfterAll` and methods annotated with TestNG's -`@BeforeSuite`, `@AfterSuite`, `@BeforeClass`, or `@AfterClass` — are _not_ run within a -test-managed transaction. - -If you need to run code in a suite-level or class-level lifecycle method within a -transaction, you may wish to inject a corresponding `PlatformTransactionManager` into -your test class and then use that with a `TransactionTemplate` for programmatic -transaction management. -==== - -Note that <<testcontext-support-classes-junit4, -`AbstractTransactionalJUnit4SpringContextTests`>> and -<<testcontext-support-classes-testng, `AbstractTransactionalTestNGSpringContextTests`>> -are preconfigured for transactional support at the class level. - -The following example demonstrates a common scenario for writing an integration test for -a Hibernate-based `UserRepository`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestConfig.class) - @Transactional - class HibernateUserRepositoryTests { - - @Autowired - HibernateUserRepository repository; - - @Autowired - SessionFactory sessionFactory; - - JdbcTemplate jdbcTemplate; - - @Autowired - void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - @Test - void createUser() { - // track initial state in test database: - final int count = countRowsInTable("user"); - - User user = new User(...); - repository.save(user); - - // Manual flush is required to avoid false positive in test - sessionFactory.getCurrentSession().flush(); - assertNumUsers(count + 1); - } - - private int countRowsInTable(String tableName) { - return JdbcTestUtils.countRowsInTable(this.jdbcTemplate, tableName); - } - - private void assertNumUsers(int expected) { - assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user")); - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestConfig::class) - @Transactional - class HibernateUserRepositoryTests { - - @Autowired - lateinit var repository: HibernateUserRepository - - @Autowired - lateinit var sessionFactory: SessionFactory - - lateinit var jdbcTemplate: JdbcTemplate - - @Autowired - fun setDataSource(dataSource: DataSource) { - this.jdbcTemplate = JdbcTemplate(dataSource) - } - - @Test - fun createUser() { - // track initial state in test database: - val count = countRowsInTable("user") - - val user = User() - repository.save(user) - - // Manual flush is required to avoid false positive in test - sessionFactory.getCurrentSession().flush() - assertNumUsers(count + 1) - } - - private fun countRowsInTable(tableName: String): Int { - return JdbcTestUtils.countRowsInTable(jdbcTemplate, tableName) - } - - private fun assertNumUsers(expected: Int) { - assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user")) - } - } ----- - -As explained in <<testcontext-tx-rollback-and-commit-behavior>>, there is no need to -clean up the database after the `createUser()` method runs, since any changes made to the -database are automatically rolled back by the `TransactionalTestExecutionListener`. - -[[testcontext-tx-rollback-and-commit-behavior]] -=== Transaction Rollback and Commit Behavior - -By default, test transactions will be automatically rolled back after completion of the -test; however, transactional commit and rollback behavior can be configured declaratively -via the `@Commit` and `@Rollback` annotations. See the corresponding entries in the -<<integration-testing-annotations, annotation support>> section for further details. - -[[testcontext-tx-programmatic-tx-mgt]] -=== Programmatic Transaction Management - -You can interact with test-managed transactions programmatically by using the static -methods in `TestTransaction`. For example, you can use `TestTransaction` within test -methods, before methods, and after methods to start or end the current test-managed -transaction or to configure the current test-managed transaction for rollback or commit. -Support for `TestTransaction` is automatically available whenever the -`TransactionalTestExecutionListener` is enabled. - -The following example demonstrates some of the features of `TestTransaction`. See the -javadoc for {api-spring-framework}/test/context/transaction/TestTransaction.html[`TestTransaction`] -for further details. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ContextConfiguration(classes = TestConfig.class) - public class ProgrammaticTransactionManagementTests extends - AbstractTransactionalJUnit4SpringContextTests { - - @Test - public void transactionalTest() { - // assert initial state in test database: - assertNumUsers(2); - - deleteFromTables("user"); - - // changes to the database will be committed! - TestTransaction.flagForCommit(); - TestTransaction.end(); - assertFalse(TestTransaction.isActive()); - assertNumUsers(0); - - TestTransaction.start(); - // perform other actions against the database that will - // be automatically rolled back after the test completes... - } - - protected void assertNumUsers(int expected) { - assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user")); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ContextConfiguration(classes = [TestConfig::class]) - class ProgrammaticTransactionManagementTests : AbstractTransactionalJUnit4SpringContextTests() { - - @Test - fun transactionalTest() { - // assert initial state in test database: - assertNumUsers(2) - - deleteFromTables("user") - - // changes to the database will be committed! - TestTransaction.flagForCommit() - TestTransaction.end() - assertFalse(TestTransaction.isActive()) - assertNumUsers(0) - - TestTransaction.start() - // perform other actions against the database that will - // be automatically rolled back after the test completes... - } - - protected fun assertNumUsers(expected: Int) { - assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user")) - } - } ----- - -[[testcontext-tx-before-and-after-tx]] -=== Running Code Outside of a Transaction - -Occasionally, you may need to run certain code before or after a transactional test -method but outside the transactional context -- for example, to verify the initial -database state prior to running your test or to verify expected transactional commit -behavior after your test runs (if the test was configured to commit the transaction). -`TransactionalTestExecutionListener` supports the `@BeforeTransaction` and -`@AfterTransaction` annotations for exactly such scenarios. You can annotate any `void` -method in a test class or any `void` default method in a test interface with one of these -annotations, and the `TransactionalTestExecutionListener` ensures that your before -transaction method or after transaction method runs at the appropriate time. - -TIP: Any before methods (such as methods annotated with JUnit Jupiter's `@BeforeEach`) -and any after methods (such as methods annotated with JUnit Jupiter's `@AfterEach`) are -run within a transaction. In addition, methods annotated with `@BeforeTransaction` or -`@AfterTransaction` are not run for test methods that are not configured to run within a -transaction. - -[[testcontext-tx-mgr-config]] -=== Configuring a Transaction Manager - -`TransactionalTestExecutionListener` expects a `PlatformTransactionManager` bean to be -defined in the Spring `ApplicationContext` for the test. If there are multiple instances -of `PlatformTransactionManager` within the test's `ApplicationContext`, you can declare a -qualifier by using `@Transactional("myTxMgr")` or `@Transactional(transactionManager = -"myTxMgr")`, or `TransactionManagementConfigurer` can be implemented by an -`@Configuration` class. Consult the -{api-spring-framework}/test/context/transaction/TestContextTransactionUtils.html#retrieveTransactionManager-org.springframework.test.context.TestContext-java.lang.String-[javadoc -for `TestContextTransactionUtils.retrieveTransactionManager()`] for details on the -algorithm used to look up a transaction manager in the test's `ApplicationContext`. - -[[testcontext-tx-annotation-demo]] -=== Demonstration of All Transaction-related Annotations - -The following JUnit Jupiter based example displays a fictitious integration testing -scenario that highlights all transaction-related annotations. The example is not intended -to demonstrate best practices but rather to demonstrate how these annotations can be -used. See the <<integration-testing-annotations, annotation support>> section for further -information and configuration examples. <<testcontext-executing-sql-declaratively-tx, -Transaction management for `@Sql`>> contains an additional example that uses `@Sql` for -declarative SQL script execution with default transaction rollback semantics. The -following example shows the relevant annotations: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig - @Transactional(transactionManager = "txMgr") - @Commit - class FictitiousTransactionalTest { - - @BeforeTransaction - void verifyInitialDatabaseState() { - // logic to verify the initial state before a transaction is started - } - - @BeforeEach - void setUpTestDataWithinTransaction() { - // set up test data within the transaction - } - - @Test - // overrides the class-level @Commit setting - @Rollback - void modifyDatabaseWithinTransaction() { - // logic which uses the test data and modifies database state - } - - @AfterEach - void tearDownWithinTransaction() { - // run "tear down" logic within the transaction - } - - @AfterTransaction - void verifyFinalDatabaseState() { - // logic to verify the final state after transaction has rolled back - } - - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig - @Transactional(transactionManager = "txMgr") - @Commit - class FictitiousTransactionalTest { - - @BeforeTransaction - fun verifyInitialDatabaseState() { - // logic to verify the initial state before a transaction is started - } - - @BeforeEach - fun setUpTestDataWithinTransaction() { - // set up test data within the transaction - } - - @Test - // overrides the class-level @Commit setting - @Rollback - fun modifyDatabaseWithinTransaction() { - // logic which uses the test data and modifies database state - } - - @AfterEach - fun tearDownWithinTransaction() { - // run "tear down" logic within the transaction - } - - @AfterTransaction - fun verifyFinalDatabaseState() { - // logic to verify the final state after transaction has rolled back - } - - } ----- - -[[testcontext-tx-false-positives]] -.Avoid false positives when testing ORM code -[NOTE] -===== -When you test application code that manipulates the state of a Hibernate session or JPA -persistence context, make sure to flush the underlying unit of work within test methods -that run that code. Failing to flush the underlying unit of work can produce false -positives: Your test passes, but the same code throws an exception in a live, production -environment. Note that this applies to any ORM framework that maintains an in-memory unit -of work. In the following Hibernate-based example test case, one method demonstrates a -false positive, and the other method correctly exposes the results of flushing the -session: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // ... - - @Autowired - SessionFactory sessionFactory; - - @Transactional - @Test // no expected exception! - public void falsePositive() { - updateEntityInHibernateSession(); - // False positive: an exception will be thrown once the Hibernate - // Session is finally flushed (i.e., in production code) - } - - @Transactional - @Test(expected = ...) - public void updateWithSessionFlush() { - updateEntityInHibernateSession(); - // Manual flush is required to avoid false positive in test - sessionFactory.getCurrentSession().flush(); - } - - // ... ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // ... - - @Autowired - lateinit var sessionFactory: SessionFactory - - @Transactional - @Test // no expected exception! - fun falsePositive() { - updateEntityInHibernateSession() - // False positive: an exception will be thrown once the Hibernate - // Session is finally flushed (i.e., in production code) - } - - @Transactional - @Test(expected = ...) - fun updateWithSessionFlush() { - updateEntityInHibernateSession() - // Manual flush is required to avoid false positive in test - sessionFactory.getCurrentSession().flush() - } - - // ... ----- - -The following example shows matching methods for JPA: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // ... - - @PersistenceContext - EntityManager entityManager; - - @Transactional - @Test // no expected exception! - public void falsePositive() { - updateEntityInJpaPersistenceContext(); - // False positive: an exception will be thrown once the JPA - // EntityManager is finally flushed (i.e., in production code) - } - - @Transactional - @Test(expected = ...) - public void updateWithEntityManagerFlush() { - updateEntityInJpaPersistenceContext(); - // Manual flush is required to avoid false positive in test - entityManager.flush(); - } - - // ... ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // ... - - @PersistenceContext - lateinit var entityManager:EntityManager - - @Transactional - @Test // no expected exception! - fun falsePositive() { - updateEntityInJpaPersistenceContext() - // False positive: an exception will be thrown once the JPA - // EntityManager is finally flushed (i.e., in production code) - } - - @Transactional - @Test(expected = ...) - void updateWithEntityManagerFlush() { - updateEntityInJpaPersistenceContext() - // Manual flush is required to avoid false positive in test - entityManager.flush() - } - - // ... ----- -===== - -[[testcontext-tx-orm-lifecycle-callbacks]] -.Testing ORM entity lifecycle callbacks -[NOTE] -===== -Similar to the note about avoiding <<testcontext-tx-false-positives, false positives>> -when testing ORM code, if your application makes use of entity lifecycle callbacks (also -known as entity listeners), make sure to flush the underlying unit of work within test -methods that run that code. Failing to _flush_ or _clear_ the underlying unit of work can -result in certain lifecycle callbacks not being invoked. - -For example, when using JPA, `@PostPersist`, `@PreUpdate`, and `@PostUpdate` callbacks -will not be called unless `entityManager.flush()` is invoked after an entity has been -saved or updated. Similarly, if an entity is already attached to the current unit of work -(associated with the current persistence context), an attempt to reload the entity will -not result in a `@PostLoad` callback unless `entityManager.clear()` is invoked before the -attempt to reload the entity. - -The following example shows how to flush the `EntityManager` to ensure that -`@PostPersist` callbacks are invoked when an entity is persisted. An entity listener with -a `@PostPersist` callback method has been registered for the `Person` entity used in the -example. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // ... - - @Autowired - JpaPersonRepository repo; - - @PersistenceContext - EntityManager entityManager; - - @Transactional - @Test - void savePerson() { - // EntityManager#persist(...) results in @PrePersist but not @PostPersist - repo.save(new Person("Jane")); - - // Manual flush is required for @PostPersist callback to be invoked - entityManager.flush(); - - // Test code that relies on the @PostPersist callback - // having been invoked... - } - - // ... ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // ... - - @Autowired - lateinit var repo: JpaPersonRepository - - @PersistenceContext - lateinit var entityManager: EntityManager - - @Transactional - @Test - fun savePerson() { - // EntityManager#persist(...) results in @PrePersist but not @PostPersist - repo.save(Person("Jane")) - - // Manual flush is required for @PostPersist callback to be invoked - entityManager.flush() - - // Test code that relies on the @PostPersist callback - // having been invoked... - } - - // ... ----- - -See -https://github.com/spring-projects/spring-framework/blob/main/spring-test/src/test/java/org/springframework/test/context/junit/jupiter/orm/JpaEntityListenerTests.java[JpaEntityListenerTests] -in the Spring Framework test suite for working examples using all JPA lifecycle callbacks. -===== - - -[[testcontext-executing-sql]] -== Executing SQL Scripts - -When writing integration tests against a relational database, it is often beneficial to -run SQL scripts to modify the database schema or insert test data into tables. The -`spring-jdbc` module provides support for _initializing_ an embedded or existing database -by executing SQL scripts when the Spring `ApplicationContext` is loaded. See -<<data-access.adoc#jdbc-embedded-database-support, Embedded database support>> and -<<data-access.adoc#jdbc-embedded-database-dao-testing, Testing data access logic with an -embedded database>> for details. - -Although it is very useful to initialize a database for testing _once_ when the -`ApplicationContext` is loaded, sometimes it is essential to be able to modify the -database _during_ integration tests. The following sections explain how to run SQL -scripts programmatically and declaratively during integration tests. - -[[testcontext-executing-sql-programmatically]] -=== Executing SQL scripts programmatically - -Spring provides the following options for executing SQL scripts programmatically within -integration test methods. - -* `org.springframework.jdbc.datasource.init.ScriptUtils` -* `org.springframework.jdbc.datasource.init.ResourceDatabasePopulator` -* `org.springframework.test.context.junit4.AbstractTransactionalJUnit4SpringContextTests` -* `org.springframework.test.context.testng.AbstractTransactionalTestNGSpringContextTests` - -`ScriptUtils` provides a collection of static utility methods for working with SQL -scripts and is mainly intended for internal use within the framework. However, if you -require full control over how SQL scripts are parsed and run, `ScriptUtils` may suit -your needs better than some of the other alternatives described later. See the -{api-spring-framework}/jdbc/datasource/init/ScriptUtils.html[javadoc] for individual -methods in `ScriptUtils` for further details. - -`ResourceDatabasePopulator` provides an object-based API for programmatically populating, -initializing, or cleaning up a database by using SQL scripts defined in external -resources. `ResourceDatabasePopulator` provides options for configuring the character -encoding, statement separator, comment delimiters, and error handling flags used when -parsing and running the scripts. Each of the configuration options has a reasonable -default value. See the -{api-spring-framework}/jdbc/datasource/init/ResourceDatabasePopulator.html[javadoc] for -details on default values. To run the scripts configured in a -`ResourceDatabasePopulator`, you can invoke either the `populate(Connection)` method to -run the populator against a `java.sql.Connection` or the `execute(DataSource)` method -to run the populator against a `javax.sql.DataSource`. The following example -specifies SQL scripts for a test schema and test data, sets the statement separator to -`@@`, and run the scripts against a `DataSource`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Test - void databaseTest() { - ResourceDatabasePopulator populator = new ResourceDatabasePopulator(); - populator.addScripts( - new ClassPathResource("test-schema.sql"), - new ClassPathResource("test-data.sql")); - populator.setSeparator("@@"); - populator.execute(this.dataSource); - // run code that uses the test schema and data - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Test - fun databaseTest() { - val populator = ResourceDatabasePopulator() - populator.addScripts( - ClassPathResource("test-schema.sql"), - ClassPathResource("test-data.sql")) - populator.setSeparator("@@") - populator.execute(dataSource) - // run code that uses the test schema and data - } ----- - -Note that `ResourceDatabasePopulator` internally delegates to `ScriptUtils` for parsing -and running SQL scripts. Similarly, the `executeSqlScript(..)` methods in -<<testcontext-support-classes-junit4, `AbstractTransactionalJUnit4SpringContextTests`>> -and <<testcontext-support-classes-testng, `AbstractTransactionalTestNGSpringContextTests`>> -internally use a `ResourceDatabasePopulator` to run SQL scripts. See the Javadoc for the -various `executeSqlScript(..)` methods for further details. - -[[testcontext-executing-sql-declaratively]] -=== Executing SQL scripts declaratively with @Sql - -In addition to the aforementioned mechanisms for running SQL scripts programmatically, -you can declaratively configure SQL scripts in the Spring TestContext Framework. -Specifically, you can declare the `@Sql` annotation on a test class or test method to -configure individual SQL statements or the resource paths to SQL scripts that should be -run against a given database before or after an integration test method. Support for -`@Sql` is provided by the `SqlScriptsTestExecutionListener`, which is enabled by default. - -NOTE: Method-level `@Sql` declarations override class-level declarations by default. As -of Spring Framework 5.2, however, this behavior may be configured per test class or per -test method via `@SqlMergeMode`. See -<<testcontext-executing-sql-declaratively-script-merging>> for further details. - -[[testcontext-executing-sql-declaratively-script-resources]] -==== Path Resource Semantics - -Each path is interpreted as a Spring `Resource`. A plain path (for example, -`"schema.sql"`) is treated as a classpath resource that is relative to the package in -which the test class is defined. A path starting with a slash is treated as an absolute -classpath resource (for example, `"/org/example/schema.sql"`). A path that references a -URL (for example, a path prefixed with `classpath:`, `file:`, `http:`) is loaded by using -the specified resource protocol. - -The following example shows how to use `@Sql` at the class level and at the method level -within a JUnit Jupiter based integration test class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig - @Sql("/test-schema.sql") - class DatabaseTests { - - @Test - void emptySchemaTest() { - // run code that uses the test schema without any test data - } - - @Test - @Sql({"/test-schema.sql", "/test-user-data.sql"}) - void userTest() { - // run code that uses the test schema and test data - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig - @Sql("/test-schema.sql") - class DatabaseTests { - - @Test - fun emptySchemaTest() { - // run code that uses the test schema without any test data - } - - @Test - @Sql("/test-schema.sql", "/test-user-data.sql") - fun userTest() { - // run code that uses the test schema and test data - } - } ----- - -[[testcontext-executing-sql-declaratively-script-detection]] -==== Default Script Detection - -If no SQL scripts or statements are specified, an attempt is made to detect a `default` -script, depending on where `@Sql` is declared. If a default cannot be detected, an -`IllegalStateException` is thrown. - -* Class-level declaration: If the annotated test class is `com.example.MyTest`, the - corresponding default script is `classpath:com/example/MyTest.sql`. -* Method-level declaration: If the annotated test method is named `testMethod()` and is - defined in the class `com.example.MyTest`, the corresponding default script is - `classpath:com/example/MyTest.testMethod.sql`. - -[[testcontext-executing-sql-declaratively-multiple-annotations]] -==== Declaring Multiple `@Sql` Sets - -If you need to configure multiple sets of SQL scripts for a given test class or test -method but with different syntax configuration, different error handling rules, or -different execution phases per set, you can declare multiple instances of `@Sql`. With -Java 8, you can use `@Sql` as a repeatable annotation. Otherwise, you can use the -`@SqlGroup` annotation as an explicit container for declaring multiple instances of -`@Sql`. - -The following example shows how to use `@Sql` as a repeatable annotation with Java 8: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Test - @Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")) - @Sql("/test-user-data.sql") - void userTest() { - // run code that uses the test schema and test data - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Repeatable annotations with non-SOURCE retention are not yet supported by Kotlin ----- - -In the scenario presented in the preceding example, the `test-schema.sql` script uses a -different syntax for single-line comments. - -The following example is identical to the preceding example, except that the `@Sql` -declarations are grouped together within `@SqlGroup`. With Java 8 and above, the use of -`@SqlGroup` is optional, but you may need to use `@SqlGroup` for compatibility with -other JVM languages such as Kotlin. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Test - @SqlGroup({ - @Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")), - @Sql("/test-user-data.sql") - )} - void userTest() { - // run code that uses the test schema and test data - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Test - @SqlGroup( - Sql("/test-schema.sql", config = SqlConfig(commentPrefix = "`")), - Sql("/test-user-data.sql")) - fun userTest() { - // Run code that uses the test schema and test data - } ----- - -[[testcontext-executing-sql-declaratively-script-execution-phases]] -==== Script Execution Phases - -By default, SQL scripts are run before the corresponding test method. However, if -you need to run a particular set of scripts after the test method (for example, to clean -up database state), you can use the `executionPhase` attribute in `@Sql`, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Test - @Sql( - scripts = "create-test-data.sql", - config = @SqlConfig(transactionMode = ISOLATED) - ) - @Sql( - scripts = "delete-test-data.sql", - config = @SqlConfig(transactionMode = ISOLATED), - executionPhase = AFTER_TEST_METHOD - ) - void userTest() { - // run code that needs the test data to be committed - // to the database outside of the test's transaction - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Test - @SqlGroup( - Sql("create-test-data.sql", - config = SqlConfig(transactionMode = ISOLATED)), - Sql("delete-test-data.sql", - config = SqlConfig(transactionMode = ISOLATED), - executionPhase = AFTER_TEST_METHOD)) - fun userTest() { - // run code that needs the test data to be committed - // to the database outside of the test's transaction - } ----- - -Note that `ISOLATED` and `AFTER_TEST_METHOD` are statically imported from -`Sql.TransactionMode` and `Sql.ExecutionPhase`, respectively. - -[[testcontext-executing-sql-declaratively-script-configuration]] -==== Script Configuration with `@SqlConfig` - -You can configure script parsing and error handling by using the `@SqlConfig` annotation. -When declared as a class-level annotation on an integration test class, `@SqlConfig` -serves as global configuration for all SQL scripts within the test class hierarchy. When -declared directly by using the `config` attribute of the `@Sql` annotation, `@SqlConfig` -serves as local configuration for the SQL scripts declared within the enclosing `@Sql` -annotation. Every attribute in `@SqlConfig` has an implicit default value, which is -documented in the javadoc of the corresponding attribute. Due to the rules defined for -annotation attributes in the Java Language Specification, it is, unfortunately, not -possible to assign a value of `null` to an annotation attribute. Thus, in order to -support overrides of inherited global configuration, `@SqlConfig` attributes have an -explicit default value of either `""` (for Strings), `{}` (for arrays), or `DEFAULT` (for -enumerations). This approach lets local declarations of `@SqlConfig` selectively override -individual attributes from global declarations of `@SqlConfig` by providing a value other -than `""`, `{}`, or `DEFAULT`. Global `@SqlConfig` attributes are inherited whenever -local `@SqlConfig` attributes do not supply an explicit value other than `""`, `{}`, or -`DEFAULT`. Explicit local configuration, therefore, overrides global configuration. - -The configuration options provided by `@Sql` and `@SqlConfig` are equivalent to those -supported by `ScriptUtils` and `ResourceDatabasePopulator` but are a superset of those -provided by the `<jdbc:initialize-database/>` XML namespace element. See the javadoc of -individual attributes in {api-spring-framework}/test/context/jdbc/Sql.html[`@Sql`] and -{api-spring-framework}/test/context/jdbc/SqlConfig.html[`@SqlConfig`] for details. - -[[testcontext-executing-sql-declaratively-tx]] -*Transaction management for `@Sql`* - -By default, the `SqlScriptsTestExecutionListener` infers the desired transaction -semantics for scripts configured by using `@Sql`. Specifically, SQL scripts are run -without a transaction, within an existing Spring-managed transaction (for example, a -transaction managed by the `TransactionalTestExecutionListener` for a test annotated with -`@Transactional`), or within an isolated transaction, depending on the configured value -of the `transactionMode` attribute in `@SqlConfig` and the presence of a -`PlatformTransactionManager` in the test's `ApplicationContext`. As a bare minimum, -however, a `javax.sql.DataSource` must be present in the test's `ApplicationContext`. - -If the algorithms used by `SqlScriptsTestExecutionListener` to detect a `DataSource` and -`PlatformTransactionManager` and infer the transaction semantics do not suit your needs, -you can specify explicit names by setting the `dataSource` and `transactionManager` -attributes of `@SqlConfig`. Furthermore, you can control the transaction propagation -behavior by setting the `transactionMode` attribute of `@SqlConfig` (for example, whether -scripts should be run in an isolated transaction). Although a thorough discussion of all -supported options for transaction management with `@Sql` is beyond the scope of this -reference manual, the javadoc for -{api-spring-framework}/test/context/jdbc/SqlConfig.html[`@SqlConfig`] and -{api-spring-framework}/test/context/jdbc/SqlScriptsTestExecutionListener.html[`SqlScriptsTestExecutionListener`] -provide detailed information, and the following example shows a typical testing scenario -that uses JUnit Jupiter and transactional tests with `@Sql`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestDatabaseConfig.class) - @Transactional - class TransactionalSqlScriptsTests { - - final JdbcTemplate jdbcTemplate; - - @Autowired - TransactionalSqlScriptsTests(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); - } - - @Test - @Sql("/test-data.sql") - void usersTest() { - // verify state in test database: - assertNumUsers(2); - // run code that uses the test data... - } - - int countRowsInTable(String tableName) { - return JdbcTestUtils.countRowsInTable(this.jdbcTemplate, tableName); - } - - void assertNumUsers(int expected) { - assertEquals(expected, countRowsInTable("user"), - "Number of rows in the [user] table."); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestDatabaseConfig::class) - @Transactional - class TransactionalSqlScriptsTests @Autowired constructor(dataSource: DataSource) { - - val jdbcTemplate: JdbcTemplate = JdbcTemplate(dataSource) - - @Test - @Sql("/test-data.sql") - fun usersTest() { - // verify state in test database: - assertNumUsers(2) - // run code that uses the test data... - } - - fun countRowsInTable(tableName: String): Int { - return JdbcTestUtils.countRowsInTable(jdbcTemplate, tableName) - } - - fun assertNumUsers(expected: Int) { - assertEquals(expected, countRowsInTable("user"), - "Number of rows in the [user] table.") - } - } ----- - -Note that there is no need to clean up the database after the `usersTest()` method is -run, since any changes made to the database (either within the test method or within the -`/test-data.sql` script) are automatically rolled back by the -`TransactionalTestExecutionListener` (see <<testcontext-tx,transaction management>> for -details). - -[[testcontext-executing-sql-declaratively-script-merging]] -==== Merging and Overriding Configuration with `@SqlMergeMode` - -As of Spring Framework 5.2, it is possible to merge method-level `@Sql` declarations with -class-level declarations. For example, this allows you to provide the configuration for a -database schema or some common test data once per test class and then provide additional, -use case specific test data per test method. To enable `@Sql` merging, annotate either -your test class or test method with `@SqlMergeMode(MERGE)`. To disable merging for a -specific test method (or specific test subclass), you can switch back to the default mode -via `@SqlMergeMode(OVERRIDE)`. Consult the <<spring-testing-annotation-sqlmergemode, -`@SqlMergeMode` annotation documentation section>> for examples and further details. - - -[[testcontext-parallel-test-execution]] -== Parallel Test Execution - -Spring Framework 5.0 introduced basic support for executing tests in parallel within a -single JVM when using the Spring TestContext Framework. In general, this means that most -test classes or test methods can be run in parallel without any changes to test code -or configuration. - -TIP: For details on how to set up parallel test execution, see the documentation for your -testing framework, build tool, or IDE. - -Keep in mind that the introduction of concurrency into your test suite can result in -unexpected side effects, strange runtime behavior, and tests that fail intermittently or -seemingly randomly. The Spring Team therefore provides the following general guidelines -for when not to run tests in parallel. - -Do not run tests in parallel if the tests: - -* Use Spring Framework's `@DirtiesContext` support. -* Use Spring Boot's `@MockBean` or `@SpyBean` support. -* Use JUnit 4's `@FixMethodOrder` support or any testing framework feature - that is designed to ensure that test methods run in a particular order. Note, - however, that this does not apply if entire test classes are run in parallel. -* Change the state of shared services or systems such as a database, message broker, - filesystem, and others. This applies to both embedded and external systems. - -[TIP] -==== -If parallel test execution fails with an exception stating that the `ApplicationContext` -for the current test is no longer active, this typically means that the -`ApplicationContext` was removed from the `ContextCache` in a different thread. - -This may be due to the use of `@DirtiesContext` or due to automatic eviction from the -`ContextCache`. If `@DirtiesContext` is the culprit, you either need to find a way to -avoid using `@DirtiesContext` or exclude such tests from parallel execution. If the -maximum size of the `ContextCache` has been exceeded, you can increase the maximum size -of the cache. See the discussion on <<testcontext-ctx-management-caching, context caching>> -for details. -==== - -WARNING: Parallel test execution in the Spring TestContext Framework is only possible if -the underlying `TestContext` implementation provides a copy constructor, as explained in -the javadoc for {api-spring-framework}/test/context/TestContext.html[`TestContext`]. The -`DefaultTestContext` used in Spring provides such a constructor. However, if you use a -third-party library that provides a custom `TestContext` implementation, you need to -verify that it is suitable for parallel test execution. - - -[[testcontext-support-classes]] -== TestContext Framework Support Classes - -This section describes the various classes that support the Spring TestContext Framework. - -[[testcontext-junit4-runner]] -=== Spring JUnit 4 Runner - -The Spring TestContext Framework offers full integration with JUnit 4 through a custom -runner (supported on JUnit 4.12 or higher). By annotating test classes with -`@RunWith(SpringJUnit4ClassRunner.class)` or the shorter `@RunWith(SpringRunner.class)` -variant, developers can implement standard JUnit 4-based unit and integration tests and -simultaneously reap the benefits of the TestContext framework, such as support for -loading application contexts, dependency injection of test instances, transactional test -method execution, and so on. If you want to use the Spring TestContext Framework with an -alternative runner (such as JUnit 4's `Parameterized` runner) or third-party runners -(such as the `MockitoJUnitRunner`), you can, optionally, use -<<testcontext-junit4-rules, Spring's support for JUnit rules>> instead. - -The following code listing shows the minimal requirements for configuring a test class to -run with the custom Spring `Runner`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RunWith(SpringRunner.class) - @TestExecutionListeners({}) - public class SimpleTest { - - @Test - public void testMethod() { - // test logic... - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RunWith(SpringRunner::class) - @TestExecutionListeners - class SimpleTest { - - @Test - fun testMethod() { - // test logic... - } - } ----- - -In the preceding example, `@TestExecutionListeners` is configured with an empty list, to -disable the default listeners, which otherwise would require an `ApplicationContext` to -be configured through `@ContextConfiguration`. - -[[testcontext-junit4-rules]] -=== Spring JUnit 4 Rules - -The `org.springframework.test.context.junit4.rules` package provides the following JUnit -4 rules (supported on JUnit 4.12 or higher): - -* `SpringClassRule` -* `SpringMethodRule` - -`SpringClassRule` is a JUnit `TestRule` that supports class-level features of the Spring -TestContext Framework, whereas `SpringMethodRule` is a JUnit `MethodRule` that supports -instance-level and method-level features of the Spring TestContext Framework. - -In contrast to the `SpringRunner`, Spring's rule-based JUnit support has the advantage of -being independent of any `org.junit.runner.Runner` implementation and can, therefore, be -combined with existing alternative runners (such as JUnit 4's `Parameterized`) or -third-party runners (such as the `MockitoJUnitRunner`). - -To support the full functionality of the TestContext framework, you must combine a -`SpringClassRule` with a `SpringMethodRule`. The following example shows the proper way -to declare these rules in an integration test: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Optionally specify a non-Spring Runner via @RunWith(...) - @ContextConfiguration - public class IntegrationTest { - - @ClassRule - public static final SpringClassRule springClassRule = new SpringClassRule(); - - @Rule - public final SpringMethodRule springMethodRule = new SpringMethodRule(); - - @Test - public void testMethod() { - // test logic... - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Optionally specify a non-Spring Runner via @RunWith(...) - @ContextConfiguration - class IntegrationTest { - - @Rule - val springMethodRule = SpringMethodRule() - - @Test - fun testMethod() { - // test logic... - } - - companion object { - @ClassRule - val springClassRule = SpringClassRule() - } - } ----- - -[[testcontext-support-classes-junit4]] -=== JUnit 4 Support Classes - -The `org.springframework.test.context.junit4` package provides the following support -classes for JUnit 4-based test cases (supported on JUnit 4.12 or higher): - -* `AbstractJUnit4SpringContextTests` -* `AbstractTransactionalJUnit4SpringContextTests` - -`AbstractJUnit4SpringContextTests` is an abstract base test class that integrates the -Spring TestContext Framework with explicit `ApplicationContext` testing support in a -JUnit 4 environment. When you extend `AbstractJUnit4SpringContextTests`, you can access a -`protected` `applicationContext` instance variable that you can use to perform explicit -bean lookups or to test the state of the context as a whole. - -`AbstractTransactionalJUnit4SpringContextTests` is an abstract transactional extension of -`AbstractJUnit4SpringContextTests` that adds some convenience functionality for JDBC -access. This class expects a `javax.sql.DataSource` bean and a -`PlatformTransactionManager` bean to be defined in the `ApplicationContext`. When you -extend `AbstractTransactionalJUnit4SpringContextTests`, you can access a `protected` -`jdbcTemplate` instance variable that you can use to run SQL statements to query the -database. You can use such queries to confirm database state both before and after -running database-related application code, and Spring ensures that such queries run in -the scope of the same transaction as the application code. When used in conjunction with -an ORM tool, be sure to avoid <<testcontext-tx-false-positives, false positives>>. -As mentioned in <<integration-testing-support-jdbc>>, -`AbstractTransactionalJUnit4SpringContextTests` also provides convenience methods that -delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`. -Furthermore, `AbstractTransactionalJUnit4SpringContextTests` provides an -`executeSqlScript(..)` method for running SQL scripts against the configured `DataSource`. - -TIP: These classes are a convenience for extension. If you do not want your test classes -to be tied to a Spring-specific class hierarchy, you can configure your own custom test -classes by using `@RunWith(SpringRunner.class)` or <<testcontext-junit4-rules, Spring's -JUnit rules>>. - -[[testcontext-junit-jupiter-extension]] -=== SpringExtension for JUnit Jupiter - -The Spring TestContext Framework offers full integration with the JUnit Jupiter testing -framework, introduced in JUnit 5. By annotating test classes with -`@ExtendWith(SpringExtension.class)`, you can implement standard JUnit Jupiter-based unit -and integration tests and simultaneously reap the benefits of the TestContext framework, -such as support for loading application contexts, dependency injection of test instances, -transactional test method execution, and so on. - -Furthermore, thanks to the rich extension API in JUnit Jupiter, Spring provides the -following features above and beyond the feature set that Spring supports for JUnit 4 and -TestNG: - -* Dependency injection for test constructors, test methods, and test lifecycle callback - methods. See <<testcontext-junit-jupiter-di>> for further details. -* Powerful support for link:https://junit.org/junit5/docs/current/user-guide/#extensions-conditions[conditional - test execution] based on SpEL expressions, environment variables, system properties, - and so on. See the documentation for `@EnabledIf` and `@DisabledIf` in - <<integration-testing-annotations-junit-jupiter>> for further details and examples. -* Custom composed annotations that combine annotations from Spring and JUnit Jupiter. See - the `@TransactionalDevTestConfig` and `@TransactionalIntegrationTest` examples in - <<integration-testing-annotations-meta>> for further details. - -The following code listing shows how to configure a test class to use the -`SpringExtension` in conjunction with `@ContextConfiguration`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Instructs JUnit Jupiter to extend the test with Spring support. - @ExtendWith(SpringExtension.class) - // Instructs Spring to load an ApplicationContext from TestConfig.class - @ContextConfiguration(classes = TestConfig.class) - class SimpleTests { - - @Test - void testMethod() { - // test logic... - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Instructs JUnit Jupiter to extend the test with Spring support. - @ExtendWith(SpringExtension::class) - // Instructs Spring to load an ApplicationContext from TestConfig::class - @ContextConfiguration(classes = [TestConfig::class]) - class SimpleTests { - - @Test - fun testMethod() { - // test logic... - } - } ----- - -Since you can also use annotations in JUnit 5 as meta-annotations, Spring provides the -`@SpringJUnitConfig` and `@SpringJUnitWebConfig` composed annotations to simplify the -configuration of the test `ApplicationContext` and JUnit Jupiter. - -The following example uses `@SpringJUnitConfig` to reduce the amount of configuration -used in the previous example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Instructs Spring to register the SpringExtension with JUnit - // Jupiter and load an ApplicationContext from TestConfig.class - @SpringJUnitConfig(TestConfig.class) - class SimpleTests { - - @Test - void testMethod() { - // test logic... - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Instructs Spring to register the SpringExtension with JUnit - // Jupiter and load an ApplicationContext from TestConfig.class - @SpringJUnitConfig(TestConfig::class) - class SimpleTests { - - @Test - fun testMethod() { - // test logic... - } - } ----- - -Similarly, the following example uses `@SpringJUnitWebConfig` to create a -`WebApplicationContext` for use with JUnit Jupiter: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Instructs Spring to register the SpringExtension with JUnit - // Jupiter and load a WebApplicationContext from TestWebConfig.class - @SpringJUnitWebConfig(TestWebConfig.class) - class SimpleWebTests { - - @Test - void testMethod() { - // test logic... - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Instructs Spring to register the SpringExtension with JUnit - // Jupiter and load a WebApplicationContext from TestWebConfig::class - @SpringJUnitWebConfig(TestWebConfig::class) - class SimpleWebTests { - - @Test - fun testMethod() { - // test logic... - } - } ----- - -See the documentation for `@SpringJUnitConfig` and `@SpringJUnitWebConfig` in -<<integration-testing-annotations-junit-jupiter>> for further details. - -[[testcontext-junit-jupiter-di]] -==== Dependency Injection with `SpringExtension` - -`SpringExtension` implements the -link:https://junit.org/junit5/docs/current/user-guide/#extensions-parameter-resolution[`ParameterResolver`] -extension API from JUnit Jupiter, which lets Spring provide dependency injection for test -constructors, test methods, and test lifecycle callback methods. - -Specifically, `SpringExtension` can inject dependencies from the test's -`ApplicationContext` into test constructors and methods that are annotated with -`@BeforeAll`, `@AfterAll`, `@BeforeEach`, `@AfterEach`, `@Test`, `@RepeatedTest`, -`@ParameterizedTest`, and others. - -[[testcontext-junit-jupiter-di-constructor]] -===== Constructor Injection - -If a specific parameter in a constructor for a JUnit Jupiter test class is of type -`ApplicationContext` (or a sub-type thereof) or is annotated or meta-annotated with -`@Autowired`, `@Qualifier`, or `@Value`, Spring injects the value for that specific -parameter with the corresponding bean or value from the test's `ApplicationContext`. - -Spring can also be configured to autowire all arguments for a test class constructor if -the constructor is considered to be _autowirable_. A constructor is considered to be -autowirable if one of the following conditions is met (in order of precedence). - -* The constructor is annotated with `@Autowired`. -* `@TestConstructor` is present or meta-present on the test class with the `autowireMode` - attribute set to `ALL`. -* The default _test constructor autowire mode_ has been changed to `ALL`. - -See <<integration-testing-annotations-testconstructor>> for details on the use of -`@TestConstructor` and how to change the global _test constructor autowire mode_. - -WARNING: If the constructor for a test class is considered to be _autowirable_, Spring -assumes the responsibility for resolving arguments for all parameters in the constructor. -Consequently, no other `ParameterResolver` registered with JUnit Jupiter can resolve -parameters for such a constructor. - -[WARNING] -==== -Constructor injection for test classes must not be used in conjunction with JUnit -Jupiter's `@TestInstance(PER_CLASS)` support if `@DirtiesContext` is used to close the -test's `ApplicationContext` before or after test methods. - -The reason is that `@TestInstance(PER_CLASS)` instructs JUnit Jupiter to cache the test -instance between test method invocations. Consequently, the test instance will retain -references to beans that were originally injected from an `ApplicationContext` that has -been subsequently closed. Since the constructor for the test class will only be invoked -once in such scenarios, dependency injection will not occur again, and subsequent tests -will interact with beans from the closed `ApplicationContext` which may result in errors. - -To use `@DirtiesContext` with "before test method" or "after test method" modes in -conjunction with `@TestInstance(PER_CLASS)`, one must configure dependencies from Spring -to be supplied via field or setter injection so that they can be re-injected between test -method invocations. -==== - -In the following example, Spring injects the `OrderService` bean from the -`ApplicationContext` loaded from `TestConfig.class` into the -`OrderServiceIntegrationTests` constructor. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestConfig.class) - class OrderServiceIntegrationTests { - - private final OrderService orderService; - - @Autowired - OrderServiceIntegrationTests(OrderService orderService) { - this.orderService = orderService; - } - - // tests that use the injected OrderService - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestConfig::class) - class OrderServiceIntegrationTests @Autowired constructor(private val orderService: OrderService){ - // tests that use the injected OrderService - } - ----- - -Note that this feature lets test dependencies be `final` and therefore immutable. - -If the `spring.test.constructor.autowire.mode` property is to `all` (see -<<integration-testing-annotations-testconstructor>>), we can omit the declaration of -`@Autowired` on the constructor in the previous example, resulting in the following. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestConfig.class) - class OrderServiceIntegrationTests { - - private final OrderService orderService; - - OrderServiceIntegrationTests(OrderService orderService) { - this.orderService = orderService; - } - - // tests that use the injected OrderService - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestConfig::class) - class OrderServiceIntegrationTests(val orderService:OrderService) { - // tests that use the injected OrderService - } ----- - -[[testcontext-junit-jupiter-di-method]] -===== Method Injection - -If a parameter in a JUnit Jupiter test method or test lifecycle callback method is of -type `ApplicationContext` (or a sub-type thereof) or is annotated or meta-annotated with -`@Autowired`, `@Qualifier`, or `@Value`, Spring injects the value for that specific -parameter with the corresponding bean from the test's `ApplicationContext`. - -In the following example, Spring injects the `OrderService` from the `ApplicationContext` -loaded from `TestConfig.class` into the `deleteOrder()` test method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestConfig.class) - class OrderServiceIntegrationTests { - - @Test - void deleteOrder(@Autowired OrderService orderService) { - // use orderService from the test's ApplicationContext - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestConfig::class) - class OrderServiceIntegrationTests { - - @Test - fun deleteOrder(@Autowired orderService: OrderService) { - // use orderService from the test's ApplicationContext - } - } ----- - -Due to the robustness of the `ParameterResolver` support in JUnit Jupiter, you can also -have multiple dependencies injected into a single method, not only from Spring but also -from JUnit Jupiter itself or other third-party extensions. - -The following example shows how to have both Spring and JUnit Jupiter inject dependencies -into the `placeOrderRepeatedly()` test method simultaneously. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestConfig.class) - class OrderServiceIntegrationTests { - - @RepeatedTest(10) - void placeOrderRepeatedly(RepetitionInfo repetitionInfo, - @Autowired OrderService orderService) { - - // use orderService from the test's ApplicationContext - // and repetitionInfo from JUnit Jupiter - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestConfig::class) - class OrderServiceIntegrationTests { - - @RepeatedTest(10) - fun placeOrderRepeatedly(repetitionInfo:RepetitionInfo, @Autowired orderService:OrderService) { - - // use orderService from the test's ApplicationContext - // and repetitionInfo from JUnit Jupiter - } - } ----- - -Note that the use of `@RepeatedTest` from JUnit Jupiter lets the test method gain access -to the `RepetitionInfo`. - -[[testcontext-junit-jupiter-nested-test-configuration]] -==== `@Nested` test class configuration - -The _Spring TestContext Framework_ has supported the use of test-related annotations on -`@Nested` test classes in JUnit Jupiter since Spring Framework 5.0; however, until Spring -Framework 5.3 class-level test configuration annotations were not _inherited_ from -enclosing classes like they are from superclasses. - -Spring Framework 5.3 introduces first-class support for inheriting test class -configuration from enclosing classes, and such configuration will be inherited by -default. To change from the default `INHERIT` mode to `OVERRIDE` mode, you may annotate -an individual `@Nested` test class with -`@NestedTestConfiguration(EnclosingConfiguration.OVERRIDE)`. An explicit -`@NestedTestConfiguration` declaration will apply to the annotated test class as well as -any of its subclasses and nested classes. Thus, you may annotate a top-level test class -with `@NestedTestConfiguration`, and that will apply to all of its nested test classes -recursively. - -In order to allow development teams to change the default to `OVERRIDE` – for example, -for compatibility with Spring Framework 5.0 through 5.2 – the default mode can be changed -globally via a JVM system property or a `spring.properties` file in the root of the -classpath. See the <<integration-testing-annotations-nestedtestconfiguration, "Changing -the default enclosing configuration inheritance mode">> note for details. - -Although the following "Hello World" example is very simplistic, it shows how to declare -common configuration on a top-level class that is inherited by its `@Nested` test -classes. In this particular example, only the `TestConfig` configuration class is -inherited. Each nested test class provides its own set of active profiles, resulting in a -distinct `ApplicationContext` for each nested test class (see -<<testcontext-ctx-management-caching>> for details). Consult the list of -<<integration-testing-annotations-nestedtestconfiguration, supported annotations>> to see -which annotations can be inherited in `@Nested` test classes. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @SpringJUnitConfig(TestConfig.class) - class GreetingServiceTests { - - @Nested - @ActiveProfiles("lang_en") - class EnglishGreetings { - - @Test - void hello(@Autowired GreetingService service) { - assertThat(service.greetWorld()).isEqualTo("Hello World"); - } - } - - @Nested - @ActiveProfiles("lang_de") - class GermanGreetings { - - @Test - void hello(@Autowired GreetingService service) { - assertThat(service.greetWorld()).isEqualTo("Hallo Welt"); - } - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @SpringJUnitConfig(TestConfig::class) - class GreetingServiceTests { - - @Nested - @ActiveProfiles("lang_en") - inner class EnglishGreetings { - - @Test - fun hello(@Autowired service:GreetingService) { - assertThat(service.greetWorld()).isEqualTo("Hello World") - } - } - - @Nested - @ActiveProfiles("lang_de") - inner class GermanGreetings { - - @Test - fun hello(@Autowired service:GreetingService) { - assertThat(service.greetWorld()).isEqualTo("Hallo Welt") - } - } - } ----- - -[[testcontext-support-classes-testng]] -=== TestNG Support Classes - -The `org.springframework.test.context.testng` package provides the following support -classes for TestNG based test cases: - -* `AbstractTestNGSpringContextTests` -* `AbstractTransactionalTestNGSpringContextTests` - -`AbstractTestNGSpringContextTests` is an abstract base test class that integrates the -Spring TestContext Framework with explicit `ApplicationContext` testing support in a -TestNG environment. When you extend `AbstractTestNGSpringContextTests`, you can access a -`protected` `applicationContext` instance variable that you can use to perform explicit -bean lookups or to test the state of the context as a whole. - -`AbstractTransactionalTestNGSpringContextTests` is an abstract transactional extension of -`AbstractTestNGSpringContextTests` that adds some convenience functionality for JDBC -access. This class expects a `javax.sql.DataSource` bean and a -`PlatformTransactionManager` bean to be defined in the `ApplicationContext`. When you -extend `AbstractTransactionalTestNGSpringContextTests`, you can access a `protected` -`jdbcTemplate` instance variable that you can use to run SQL statements to query the -database. You can use such queries to confirm database state both before and after -running database-related application code, and Spring ensures that such queries run in -the scope of the same transaction as the application code. When used in conjunction with -an ORM tool, be sure to avoid <<testcontext-tx-false-positives, false positives>>. -As mentioned in <<integration-testing-support-jdbc>>, -`AbstractTransactionalTestNGSpringContextTests` also provides convenience methods that -delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`. -Furthermore, `AbstractTransactionalTestNGSpringContextTests` provides an -`executeSqlScript(..)` method for running SQL scripts against the configured `DataSource`. - -TIP: These classes are a convenience for extension. If you do not want your test classes -to be tied to a Spring-specific class hierarchy, you can configure your own custom test -classes by using `@ContextConfiguration`, `@TestExecutionListeners`, and so on and by -manually instrumenting your test class with a `TestContextManager`. See the source code -of `AbstractTestNGSpringContextTests` for an example of how to instrument your test class. - -[[testcontext-aot]] -== Ahead of Time Support for Tests - -This chapter covers Spring's Ahead of Time (AOT) support for integration tests using the -Spring TestContext Framework. - -The testing support extends Spring's <<core.adoc#core.aot,core AOT support>> with the -following features. - -* Build-time detection of all integration tests in the current project that use the - TestContext framework to load an `ApplicationContext`. - - Provides explicit support for test classes based on JUnit Jupiter and JUnit 4 as well - as implicit support for TestNG and other testing frameworks that use Spring's core - testing annotations -- as long as the tests are run using a JUnit Platform - `TestEngine` that is registered for the current project. -* Build-time AOT processing: each unique test `ApplicationContext` in the current project - will be <<core.adoc#core.aot.refresh,refreshed for AOT processing>>. -* Runtime AOT support: when executing in AOT runtime mode, a Spring integration test will - use an AOT-optimized `ApplicationContext` that participates transparently with the - <<testcontext-ctx-management-caching, context cache>>. - -[WARNING] -==== -The `@ContextHierarchy` annotation is currently not supported in AOT mode. -==== - -To provide test-specific runtime hints for use within a GraalVM native image, you have -the following options. - -* Implement a custom - {api-spring-framework}/test/context/aot/TestRuntimeHintsRegistrar.html[`TestRuntimeHintsRegistrar`] - and register it globally via `META-INF/spring/aot.factories`. -* Implement a custom {api-spring-framework}/aot/hint/RuntimeHintsRegistrar.html[`RuntimeHintsRegistrar`] - and register it globally via `META-INF/spring/aot.factories` or locally on a test class - via {api-spring-framework}/context/annotation/ImportRuntimeHints.html[`@ImportRuntimeHints`]. -* Annotate a test class with {api-spring-framework}/aot/hint/annotation/Reflective.html[`@Reflective`] or - {api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`]. -* See <<core.adoc#core.aot.hints,Runtime Hints>> for details on Spring's core runtime hints - and annotation support. - -[TIP] -==== -The `TestRuntimeHintsRegistrar` API serves as a companion to the core -`RuntimeHintsRegistrar` API. If you need to register global hints for testing support -that are not specific to particular test classes, favor implementing -`RuntimeHintsRegistrar` over the test-specific API. -==== - -If you implement a custom `ContextLoader`, it must implement -{api-spring-framework}/test/context/aot/AotContextLoader.html[`AotContextLoader`] in -order to provide AOT build-time processing and AOT runtime execution support. Note, -however, that all context loader implementations provided by the Spring Framework and -Spring Boot already implement `AotContextLoader`. - -If you implement a custom `TestExecutionListener`, it must implement -{api-spring-framework}/test/context/aot/AotTestExecutionListener.html[`AotTestExecutionListener`] -in order to participate in AOT processing. See the `SqlScriptsTestExecutionListener` in -the `spring-test` module for an example. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc new file mode 100644 index 000000000000..d7a9e735c989 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc @@ -0,0 +1,58 @@ +[[testcontext-aot]] += Ahead of Time Support for Tests + +This chapter covers Spring's Ahead of Time (AOT) support for integration tests using the +Spring TestContext Framework. + +The testing support extends Spring's <<core.adoc#core.aot,core AOT support>> with the +following features. + +* Build-time detection of all integration tests in the current project that use the + TestContext framework to load an `ApplicationContext`. + - Provides explicit support for test classes based on JUnit Jupiter and JUnit 4 as well + as implicit support for TestNG and other testing frameworks that use Spring's core + testing annotations -- as long as the tests are run using a JUnit Platform + `TestEngine` that is registered for the current project. +* Build-time AOT processing: each unique test `ApplicationContext` in the current project + will be <<core.adoc#core.aot.refresh,refreshed for AOT processing>>. +* Runtime AOT support: when executing in AOT runtime mode, a Spring integration test will + use an AOT-optimized `ApplicationContext` that participates transparently with the + <<testcontext-ctx-management-caching, context cache>>. + +[WARNING] +==== +The `@ContextHierarchy` annotation is currently not supported in AOT mode. +==== + +To provide test-specific runtime hints for use within a GraalVM native image, you have +the following options. + +* Implement a custom + {api-spring-framework}/test/context/aot/TestRuntimeHintsRegistrar.html[`TestRuntimeHintsRegistrar`] + and register it globally via `META-INF/spring/aot.factories`. +* Implement a custom {api-spring-framework}/aot/hint/RuntimeHintsRegistrar.html[`RuntimeHintsRegistrar`] + and register it globally via `META-INF/spring/aot.factories` or locally on a test class + via {api-spring-framework}/context/annotation/ImportRuntimeHints.html[`@ImportRuntimeHints`]. +* Annotate a test class with {api-spring-framework}/aot/hint/annotation/Reflective.html[`@Reflective`] or + {api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`]. +* See <<core.adoc#core.aot.hints,Runtime Hints>> for details on Spring's core runtime hints + and annotation support. + +[TIP] +==== +The `TestRuntimeHintsRegistrar` API serves as a companion to the core +`RuntimeHintsRegistrar` API. If you need to register global hints for testing support +that are not specific to particular test classes, favor implementing +`RuntimeHintsRegistrar` over the test-specific API. +==== + +If you implement a custom `ContextLoader`, it must implement +{api-spring-framework}/test/context/aot/AotContextLoader.html[`AotContextLoader`] in +order to provide AOT build-time processing and AOT runtime execution support. Note, +however, that all context loader implementations provided by the Spring Framework and +Spring Boot already implement `AotContextLoader`. + +If you implement a custom `TestExecutionListener`, it must implement +{api-spring-framework}/test/context/aot/AotTestExecutionListener.html[`AotTestExecutionListener`] +in order to participate in AOT processing. See the `SqlScriptsTestExecutionListener` in +the `spring-test` module for an example. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc new file mode 100644 index 000000000000..516e5de64d2d --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc @@ -0,0 +1,89 @@ +[[testcontext-application-events]] += Application Events + +Since Spring Framework 5.3.3, the TestContext framework provides support for recording +<<core.adoc#context-functionality-events, application events>> published in the +`ApplicationContext` so that assertions can be performed against those events within +tests. All events published during the execution of a single test are made available via +the `ApplicationEvents` API which allows you to process the events as a +`java.util.Stream`. + +To use `ApplicationEvents` in your tests, do the following. + +* Ensure that your test class is annotated or meta-annotated with + <<spring-testing-annotation-recordapplicationevents>>. +* Ensure that the `ApplicationEventsTestExecutionListener` is registered. Note, however, + that `ApplicationEventsTestExecutionListener` is registered by default and only needs + to be manually registered if you have custom configuration via + `@TestExecutionListeners` that does not include the default listeners. +* Annotate a field of type `ApplicationEvents` with `@Autowired` and use that instance of + `ApplicationEvents` in your test and lifecycle methods (such as `@BeforeEach` and + `@AfterEach` methods in JUnit Jupiter). +** When using the <<testcontext-junit-jupiter-extension>>, you may declare a method + parameter of type `ApplicationEvents` in a test or lifecycle method as an alternative + to an `@Autowired` field in the test class. + +The following test class uses the `SpringExtension` for JUnit Jupiter and +https://assertj.github.io/doc/[AssertJ] to assert the types of application events +published while invoking a method in a Spring-managed component: + +// Don't use "quotes" in the "subs" section because of the asterisks in /* ... */ +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @SpringJUnitConfig(/* ... */) + @RecordApplicationEvents // <1> + class OrderServiceTests { + + @Autowired + OrderService orderService; + + @Autowired + ApplicationEvents events; // <2> + + @Test + void submitOrder() { + // Invoke method in OrderService that publishes an event + orderService.submitOrder(new Order(/* ... */)); + // Verify that an OrderSubmitted event was published + long numEvents = events.stream(OrderSubmitted.class).count(); // <3> + assertThat(numEvents).isEqualTo(1); + } + } +---- +<1> Annotate the test class with `@RecordApplicationEvents`. +<2> Inject the `ApplicationEvents` instance for the current test. +<3> Use the `ApplicationEvents` API to count how many `OrderSubmitted` events were published. + +// Don't use "quotes" in the "subs" section because of the asterisks in /* ... */ +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(/* ... */) + @RecordApplicationEvents // <1> + class OrderServiceTests { + + @Autowired + lateinit var orderService: OrderService + + @Autowired + lateinit var events: ApplicationEvents // <2> + + @Test + fun submitOrder() { + // Invoke method in OrderService that publishes an event + orderService.submitOrder(Order(/* ... */)) + // Verify that an OrderSubmitted event was published + val numEvents = events.stream(OrderSubmitted::class).count() // <3> + assertThat(numEvents).isEqualTo(1) + } + } +---- +<1> Annotate the test class with `@RecordApplicationEvents`. +<2> Inject the `ApplicationEvents` instance for the current test. +<3> Use the `ApplicationEvents` API to count how many `OrderSubmitted` events were published. + +See the +{api-spring-framework}/test/context/event/ApplicationEvents.html[`ApplicationEvents` +javadoc] for further details regarding the `ApplicationEvents` API. + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/bootstrapping.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/bootstrapping.adoc new file mode 100644 index 000000000000..bf3be0e663a6 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/bootstrapping.adoc @@ -0,0 +1,26 @@ +[[testcontext-bootstrapping]] += Bootstrapping the TestContext Framework + +The default configuration for the internals of the Spring TestContext Framework is +sufficient for all common use cases. However, there are times when a development team or +third party framework would like to change the default `ContextLoader`, implement a +custom `TestContext` or `ContextCache`, augment the default sets of +`ContextCustomizerFactory` and `TestExecutionListener` implementations, and so on. For +such low-level control over how the TestContext framework operates, Spring provides a +bootstrapping strategy. + +`TestContextBootstrapper` defines the SPI for bootstrapping the TestContext framework. A +`TestContextBootstrapper` is used by the `TestContextManager` to load the +`TestExecutionListener` implementations for the current test and to build the +`TestContext` that it manages. You can configure a custom bootstrapping strategy for a +test class (or test class hierarchy) by using `@BootstrapWith`, either directly or as a +meta-annotation. If a bootstrapper is not explicitly configured by using +`@BootstrapWith`, either the `DefaultTestContextBootstrapper` or the +`WebTestContextBootstrapper` is used, depending on the presence of `@WebAppConfiguration`. + +Since the `TestContextBootstrapper` SPI is likely to change in the future (to accommodate +new requirements), we strongly encourage implementers not to implement this interface +directly but rather to extend `AbstractTestContextBootstrapper` or one of its concrete +subclasses instead. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc new file mode 100644 index 000000000000..605aef0a4baf --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc @@ -0,0 +1,113 @@ +[[testcontext-ctx-management]] += Context Management + +Each `TestContext` provides context management and caching support for the test instance +for which it is responsible. Test instances do not automatically receive access to the +configured `ApplicationContext`. However, if a test class implements the +`ApplicationContextAware` interface, a reference to the `ApplicationContext` is supplied +to the test instance. Note that `AbstractJUnit4SpringContextTests` and +`AbstractTestNGSpringContextTests` implement `ApplicationContextAware` and, therefore, +provide access to the `ApplicationContext` automatically. + +.@Autowired ApplicationContext +[TIP] +===== +As an alternative to implementing the `ApplicationContextAware` interface, you can inject +the application context for your test class through the `@Autowired` annotation on either +a field or setter method, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig + class MyTest { + + @Autowired // <1> + ApplicationContext applicationContext; + + // class body... + } +---- +<1> Injecting the `ApplicationContext`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig + class MyTest { + + @Autowired // <1> + lateinit var applicationContext: ApplicationContext + + // class body... + } +---- +<1> Injecting the `ApplicationContext`. + + +Similarly, if your test is configured to load a `WebApplicationContext`, you can inject +the web application context into your test, as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitWebConfig // <1> + class MyWebAppTest { + + @Autowired // <2> + WebApplicationContext wac; + + // class body... + } +---- +<1> Configuring the `WebApplicationContext`. +<2> Injecting the `WebApplicationContext`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitWebConfig // <1> + class MyWebAppTest { + + @Autowired // <2> + lateinit var wac: WebApplicationContext + // class body... + } +---- +<1> Configuring the `WebApplicationContext`. +<2> Injecting the `WebApplicationContext`. + + +Dependency injection by using `@Autowired` is provided by the +`DependencyInjectionTestExecutionListener`, which is configured by default +(see <<testcontext-fixture-di>>). +===== + +Test classes that use the TestContext framework do not need to extend any particular +class or implement a specific interface to configure their application context. Instead, +configuration is achieved by declaring the `@ContextConfiguration` annotation at the +class level. If your test class does not explicitly declare application context resource +locations or component classes, the configured `ContextLoader` determines how to load a +context from a default location or default configuration classes. In addition to context +resource locations and component classes, an application context can also be configured +through application context initializers. + +The following sections explain how to use Spring's `@ContextConfiguration` annotation to +configure a test `ApplicationContext` by using XML configuration files, Groovy scripts, +component classes (typically `@Configuration` classes), or context initializers. +Alternatively, you can implement and configure your own custom `SmartContextLoader` for +advanced use cases. + +* <<testcontext-ctx-management-xml>> +* <<testcontext-ctx-management-groovy>> +* <<testcontext-ctx-management-javaconfig>> +* <<testcontext-ctx-management-mixed-config>> +* <<testcontext-ctx-management-initializers>> +* <<testcontext-ctx-management-inheritance>> +* <<testcontext-ctx-management-env-profiles>> +* <<testcontext-ctx-management-property-sources>> +* <<testcontext-ctx-management-dynamic-property-sources>> +* <<testcontext-ctx-management-web>> +* <<testcontext-ctx-management-caching>> +* <<testcontext-ctx-management-ctx-hierarchies>> + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc new file mode 100644 index 000000000000..fd6f51764aab --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc @@ -0,0 +1,126 @@ +[[testcontext-ctx-management-caching]] += Context Caching + +Once the TestContext framework loads an `ApplicationContext` (or `WebApplicationContext`) +for a test, that context is cached and reused for all subsequent tests that declare the +same unique context configuration within the same test suite. To understand how caching +works, it is important to understand what is meant by "`unique`" and "`test suite.`" + +An `ApplicationContext` can be uniquely identified by the combination of configuration +parameters that is used to load it. Consequently, the unique combination of configuration +parameters is used to generate a key under which the context is cached. The TestContext +framework uses the following configuration parameters to build the context cache key: + +* `locations` (from `@ContextConfiguration`) +* `classes` (from `@ContextConfiguration`) +* `contextInitializerClasses` (from `@ContextConfiguration`) +* `contextCustomizers` (from `ContextCustomizerFactory`) – this includes + `@DynamicPropertySource` methods as well as various features from Spring Boot's + testing support such as `@MockBean` and `@SpyBean`. +* `contextLoader` (from `@ContextConfiguration`) +* `parent` (from `@ContextHierarchy`) +* `activeProfiles` (from `@ActiveProfiles`) +* `propertySourceLocations` (from `@TestPropertySource`) +* `propertySourceProperties` (from `@TestPropertySource`) +* `resourceBasePath` (from `@WebAppConfiguration`) + +For example, if `TestClassA` specifies `{"app-config.xml", "test-config.xml"}` for the +`locations` (or `value`) attribute of `@ContextConfiguration`, the TestContext framework +loads the corresponding `ApplicationContext` and stores it in a `static` context cache +under a key that is based solely on those locations. So, if `TestClassB` also defines +`{"app-config.xml", "test-config.xml"}` for its locations (either explicitly or +implicitly through inheritance) but does not define `@WebAppConfiguration`, a different +`ContextLoader`, different active profiles, different context initializers, different +test property sources, or a different parent context, then the same `ApplicationContext` +is shared by both test classes. This means that the setup cost for loading an application +context is incurred only once (per test suite), and subsequent test execution is much +faster. + +.Test suites and forked processes +[NOTE] +==== +The Spring TestContext framework stores application contexts in a static cache. This +means that the context is literally stored in a `static` variable. In other words, if +tests run in separate processes, the static cache is cleared between each test +execution, which effectively disables the caching mechanism. + +To benefit from the caching mechanism, all tests must run within the same process or test +suite. This can be achieved by executing all tests as a group within an IDE. Similarly, +when executing tests with a build framework such as Ant, Maven, or Gradle, it is +important to make sure that the build framework does not fork between tests. For example, +if the +https://maven.apache.org/plugins/maven-surefire-plugin/test-mojo.html#forkMode[`forkMode`] +for the Maven Surefire plug-in is set to `always` or `pertest`, the TestContext framework +cannot cache application contexts between test classes, and the build process runs +significantly more slowly as a result. +==== + +The size of the context cache is bounded with a default maximum size of 32. Whenever the +maximum size is reached, a least recently used (LRU) eviction policy is used to evict and +close stale contexts. You can configure the maximum size from the command line or a build +script by setting a JVM system property named `spring.test.context.cache.maxSize`. As an +alternative, you can set the same property via the +<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism. + +Since having a large number of application contexts loaded within a given test suite can +cause the suite to take an unnecessarily long time to run, it is often beneficial to +know exactly how many contexts have been loaded and cached. To view the statistics for +the underlying context cache, you can set the log level for the +`org.springframework.test.context.cache` logging category to `DEBUG`. + +In the unlikely case that a test corrupts the application context and requires reloading +(for example, by modifying a bean definition or the state of an application object), you +can annotate your test class or test method with `@DirtiesContext` (see the discussion of +`@DirtiesContext` in <<spring-testing-annotation-dirtiescontext, Spring Testing +Annotations>>). This instructs Spring to remove the context from the cache and rebuild +the application context before running the next test that requires the same application +context. Note that support for the `@DirtiesContext` annotation is provided by the +`DirtiesContextBeforeModesTestExecutionListener` and the +`DirtiesContextTestExecutionListener`, which are enabled by default. + +.ApplicationContext lifecycle and console logging +[NOTE] +==== +When you need to debug a test executed with the Spring TestContext Framework, it can be +useful to analyze the console output (that is, output to the `SYSOUT` and `SYSERR` +streams). Some build tools and IDEs are able to associate console output with a given +test; however, some console output cannot be easily associated with a given test. + +With regard to console logging triggered by the Spring Framework itself or by components +registered in the `ApplicationContext`, it is important to understand the lifecycle of an +`ApplicationContext` that has been loaded by the Spring TestContext Framework within a +test suite. + +The `ApplicationContext` for a test is typically loaded when an instance of the test +class is being prepared -- for example, to perform dependency injection into `@Autowired` +fields of the test instance. This means that any console logging triggered during the +initialization of the `ApplicationContext` typically cannot be associated with an +individual test method. However, if the context is closed immediately before the +execution of a test method according to <<spring-testing-annotation-dirtiescontext>> +semantics, a new instance of the context will be loaded just prior to execution of the +test method. In the latter scenario, an IDE or build tool may potentially associate +console logging with the individual test method. + +The `ApplicationContext` for a test can be closed via one of the following scenarios. + +* The context is closed according to `@DirtiesContext` semantics. +* The context is closed because it has been automatically evicted from the cache + according to the LRU eviction policy. +* The context is closed via a JVM shutdown hook when the JVM for the test suite + terminates. + +If the context is closed according to `@DirtiesContext` semantics after a particular test +method, an IDE or build tool may potentially associate console logging with the +individual test method. If the context is closed according to `@DirtiesContext` semantics +after a test class, any console logging triggered during the shutdown of the +`ApplicationContext` cannot be associated with an individual test method. Similarly, any +console logging triggered during the shutdown phase via a JVM shutdown hook cannot be +associated with an individual test method. + +When a Spring `ApplicationContext` is closed via a JVM shutdown hook, callbacks executed +during the shutdown phase are executed on a thread named `SpringContextShutdownHook`. So, +if you wish to disable console logging triggered when the `ApplicationContext` is closed +via a JVM shutdown hook, you may be able to register a custom filter with your logging +framework that allows you to ignore any logging initiated by that thread. +==== + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc new file mode 100644 index 000000000000..d1935942e25a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc @@ -0,0 +1,97 @@ +[[testcontext-ctx-management-dynamic-property-sources]] += Context Configuration with Dynamic Property Sources + +As of Spring Framework 5.2.5, the TestContext framework provides support for _dynamic_ +properties via the `@DynamicPropertySource` annotation. This annotation can be used in +integration tests that need to add properties with dynamic values to the set of +`PropertySources` in the `Environment` for the `ApplicationContext` loaded for the +integration test. + +[NOTE] +==== +The `@DynamicPropertySource` annotation and its supporting infrastructure were +originally designed to allow properties from +https://www.testcontainers.org/[Testcontainers] based tests to be exposed easily to +Spring integration tests. However, this feature may also be used with any form of +external resource whose lifecycle is maintained outside the test's `ApplicationContext`. +==== + +In contrast to the <<testcontext-ctx-management-property-sources,`@TestPropertySource`>> +annotation that is applied at the class level, `@DynamicPropertySource` must be applied +to a `static` method that accepts a single `DynamicPropertyRegistry` argument which is +used to add _name-value_ pairs to the `Environment`. Values are dynamic and provided via +a `Supplier` which is only invoked when the property is resolved. Typically, method +references are used to supply values, as can be seen in the following example which uses +the Testcontainers project to manage a Redis container outside of the Spring +`ApplicationContext`. The IP address and port of the managed Redis container are made +available to components within the test's `ApplicationContext` via the `redis.host` and +`redis.port` properties. These properties can be accessed via Spring's `Environment` +abstraction or injected directly into Spring-managed components – for example, via +`@Value("${redis.host}")` and `@Value("${redis.port}")`, respectively. + +[TIP] +==== +If you use `@DynamicPropertySource` in a base class and discover that tests in subclasses +fail because the dynamic properties change between subclasses, you may need to annotate +your base class with <<spring-testing-annotation-dirtiescontext, `@DirtiesContext`>> to +ensure that each subclass gets its own `ApplicationContext` with the correct dynamic +properties. +==== + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(/* ... */) + @Testcontainers + class ExampleIntegrationTests { + + @Container + static GenericContainer redis = + new GenericContainer("redis:5.0.3-alpine").withExposedPorts(6379); + + @DynamicPropertySource + static void redisProperties(DynamicPropertyRegistry registry) { + registry.add("redis.host", redis::getHost); + registry.add("redis.port", redis::getFirstMappedPort); + } + + // tests ... + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(/* ... */) + @Testcontainers + class ExampleIntegrationTests { + + companion object { + + @Container + @JvmStatic + val redis: GenericContainer = + GenericContainer("redis:5.0.3-alpine").withExposedPorts(6379) + + @DynamicPropertySource + @JvmStatic + fun redisProperties(registry: DynamicPropertyRegistry) { + registry.add("redis.host", redis::getHost) + registry.add("redis.port", redis::getFirstMappedPort) + } + } + + // tests ... + + } +---- + +[[precedence]] +== Precedence + +Dynamic properties have higher precedence than those loaded from `@TestPropertySource`, +the operating system's environment, Java system properties, or property sources added by +the application declaratively by using `@PropertySource` or programmatically. Thus, +dynamic properties can be used to selectively override properties loaded via +`@TestPropertySource`, system property sources, and application property sources. + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc new file mode 100644 index 000000000000..2a96d0bd4207 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc @@ -0,0 +1,482 @@ +[[testcontext-ctx-management-env-profiles]] += Context Configuration with Environment Profiles + +The Spring Framework has first-class support for the notion of environments and profiles +(AKA "bean definition profiles"), and integration tests can be configured to activate +particular bean definition profiles for various testing scenarios. This is achieved by +annotating a test class with the `@ActiveProfiles` annotation and supplying a list of +profiles that should be activated when loading the `ApplicationContext` for the test. + +NOTE: You can use `@ActiveProfiles` with any implementation of the `SmartContextLoader` +SPI, but `@ActiveProfiles` is not supported with implementations of the older +`ContextLoader` SPI. + +Consider two examples with XML configuration and `@Configuration` classes: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <!-- app-config.xml --> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:jdbc="http://www.springframework.org/schema/jdbc" + xmlns:jee="http://www.springframework.org/schema/jee" + xsi:schemaLocation="..."> + + <bean id="transferService" + class="com.bank.service.internal.DefaultTransferService"> + <constructor-arg ref="accountRepository"/> + <constructor-arg ref="feePolicy"/> + </bean> + + <bean id="accountRepository" + class="com.bank.repository.internal.JdbcAccountRepository"> + <constructor-arg ref="dataSource"/> + </bean> + + <bean id="feePolicy" + class="com.bank.service.internal.ZeroFeePolicy"/> + + <beans profile="dev"> + <jdbc:embedded-database id="dataSource"> + <jdbc:script + location="classpath:com/bank/config/sql/schema.sql"/> + <jdbc:script + location="classpath:com/bank/config/sql/test-data.sql"/> + </jdbc:embedded-database> + </beans> + + <beans profile="production"> + <jee:jndi-lookup id="dataSource" jndi-name="java:comp/env/jdbc/datasource"/> + </beans> + + <beans profile="default"> + <jdbc:embedded-database id="dataSource"> + <jdbc:script + location="classpath:com/bank/config/sql/schema.sql"/> + </jdbc:embedded-database> + </beans> + + </beans> +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be loaded from "classpath:/app-config.xml" + @ContextConfiguration("/app-config.xml") + @ActiveProfiles("dev") + class TransferServiceTest { + + @Autowired + TransferService transferService; + + @Test + void testTransferService() { + // test the transferService + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be loaded from "classpath:/app-config.xml" + @ContextConfiguration("/app-config.xml") + @ActiveProfiles("dev") + class TransferServiceTest { + + @Autowired + lateinit var transferService: TransferService + + @Test + fun testTransferService() { + // test the transferService + } + } +---- + +When `TransferServiceTest` is run, its `ApplicationContext` is loaded from the +`app-config.xml` configuration file in the root of the classpath. If you inspect +`app-config.xml`, you can see that the `accountRepository` bean has a dependency on a +`dataSource` bean. However, `dataSource` is not defined as a top-level bean. Instead, +`dataSource` is defined three times: in the `production` profile, in the `dev` profile, +and in the `default` profile. + +By annotating `TransferServiceTest` with `@ActiveProfiles("dev")`, we instruct the Spring +TestContext Framework to load the `ApplicationContext` with the active profiles set to +`{"dev"}`. As a result, an embedded database is created and populated with test data, and +the `accountRepository` bean is wired with a reference to the development `DataSource`. +That is likely what we want in an integration test. + +It is sometimes useful to assign beans to a `default` profile. Beans within the default +profile are included only when no other profile is specifically activated. You can use +this to define "`fallback`" beans to be used in the application's default state. For +example, you may explicitly provide a data source for `dev` and `production` profiles, +but define an in-memory data source as a default when neither of these is active. + +The following code listings demonstrate how to implement the same configuration and +integration test with `@Configuration` classes instead of XML: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @Profile("dev") + public class StandaloneDataConfig { + + @Bean + public DataSource dataSource() { + return new EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .addScript("classpath:com/bank/config/sql/test-data.sql") + .build(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @Profile("dev") + class StandaloneDataConfig { + + @Bean + fun dataSource(): DataSource { + return EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .addScript("classpath:com/bank/config/sql/test-data.sql") + .build() + } + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @Profile("production") + public class JndiDataConfig { + + @Bean(destroyMethod="") + public DataSource dataSource() throws Exception { + Context ctx = new InitialContext(); + return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource"); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @Profile("production") + class JndiDataConfig { + + @Bean(destroyMethod = "") + fun dataSource(): DataSource { + val ctx = InitialContext() + return ctx.lookup("java:comp/env/jdbc/datasource") as DataSource + } + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @Profile("default") + public class DefaultDataConfig { + + @Bean + public DataSource dataSource() { + return new EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .build(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @Profile("default") + class DefaultDataConfig { + + @Bean + fun dataSource(): DataSource { + return EmbeddedDatabaseBuilder() + .setType(EmbeddedDatabaseType.HSQL) + .addScript("classpath:com/bank/config/sql/schema.sql") + .build() + } + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class TransferServiceConfig { + + @Autowired DataSource dataSource; + + @Bean + public TransferService transferService() { + return new DefaultTransferService(accountRepository(), feePolicy()); + } + + @Bean + public AccountRepository accountRepository() { + return new JdbcAccountRepository(dataSource); + } + + @Bean + public FeePolicy feePolicy() { + return new ZeroFeePolicy(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class TransferServiceConfig { + + @Autowired + lateinit var dataSource: DataSource + + @Bean + fun transferService(): TransferService { + return DefaultTransferService(accountRepository(), feePolicy()) + } + + @Bean + fun accountRepository(): AccountRepository { + return JdbcAccountRepository(dataSource) + } + + @Bean + fun feePolicy(): FeePolicy { + return ZeroFeePolicy() + } + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig({ + TransferServiceConfig.class, + StandaloneDataConfig.class, + JndiDataConfig.class, + DefaultDataConfig.class}) + @ActiveProfiles("dev") + class TransferServiceTest { + + @Autowired + TransferService transferService; + + @Test + void testTransferService() { + // test the transferService + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig( + TransferServiceConfig::class, + StandaloneDataConfig::class, + JndiDataConfig::class, + DefaultDataConfig::class) + @ActiveProfiles("dev") + class TransferServiceTest { + + @Autowired + lateinit var transferService: TransferService + + @Test + fun testTransferService() { + // test the transferService + } + } +---- + +In this variation, we have split the XML configuration into four independent +`@Configuration` classes: + +* `TransferServiceConfig`: Acquires a `dataSource` through dependency injection by using + `@Autowired`. +* `StandaloneDataConfig`: Defines a `dataSource` for an embedded database suitable for + developer tests. +* `JndiDataConfig`: Defines a `dataSource` that is retrieved from JNDI in a production + environment. +* `DefaultDataConfig`: Defines a `dataSource` for a default embedded database, in case no + profile is active. + +As with the XML-based configuration example, we still annotate `TransferServiceTest` with +`@ActiveProfiles("dev")`, but this time we specify all four configuration classes by +using the `@ContextConfiguration` annotation. The body of the test class itself remains +completely unchanged. + +It is often the case that a single set of profiles is used across multiple test classes +within a given project. Thus, to avoid duplicate declarations of the `@ActiveProfiles` +annotation, you can declare `@ActiveProfiles` once on a base class, and subclasses +automatically inherit the `@ActiveProfiles` configuration from the base class. In the +following example, the declaration of `@ActiveProfiles` (as well as other annotations) +has been moved to an abstract superclass, `AbstractIntegrationTest`: + +NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing +classes. See <<testcontext-junit-jupiter-nested-test-configuration>> for details. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig({ + TransferServiceConfig.class, + StandaloneDataConfig.class, + JndiDataConfig.class, + DefaultDataConfig.class}) + @ActiveProfiles("dev") + abstract class AbstractIntegrationTest { + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig( + TransferServiceConfig::class, + StandaloneDataConfig::class, + JndiDataConfig::class, + DefaultDataConfig::class) + @ActiveProfiles("dev") + abstract class AbstractIntegrationTest { + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // "dev" profile inherited from superclass + class TransferServiceTest extends AbstractIntegrationTest { + + @Autowired + TransferService transferService; + + @Test + void testTransferService() { + // test the transferService + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // "dev" profile inherited from superclass + class TransferServiceTest : AbstractIntegrationTest() { + + @Autowired + lateinit var transferService: TransferService + + @Test + fun testTransferService() { + // test the transferService + } + } +---- + +`@ActiveProfiles` also supports an `inheritProfiles` attribute that can be used to +disable the inheritance of active profiles, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // "dev" profile overridden with "production" + @ActiveProfiles(profiles = "production", inheritProfiles = false) + class ProductionTransferServiceTest extends AbstractIntegrationTest { + // test body + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // "dev" profile overridden with "production" + @ActiveProfiles("production", inheritProfiles = false) + class ProductionTransferServiceTest : AbstractIntegrationTest() { + // test body + } +---- + +[[testcontext-ctx-management-env-profiles-ActiveProfilesResolver]] +Furthermore, it is sometimes necessary to resolve active profiles for tests +programmatically instead of declaratively -- for example, based on: + +* The current operating system. +* Whether tests are being run on a continuous integration build server. +* The presence of certain environment variables. +* The presence of custom class-level annotations. +* Other concerns. + +To resolve active bean definition profiles programmatically, you can implement +a custom `ActiveProfilesResolver` and register it by using the `resolver` +attribute of `@ActiveProfiles`. For further information, see the corresponding +{api-spring-framework}/test/context/ActiveProfilesResolver.html[javadoc]. +The following example demonstrates how to implement and register a custom +`OperatingSystemActiveProfilesResolver`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // "dev" profile overridden programmatically via a custom resolver + @ActiveProfiles( + resolver = OperatingSystemActiveProfilesResolver.class, + inheritProfiles = false) + class TransferServiceTest extends AbstractIntegrationTest { + // test body + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // "dev" profile overridden programmatically via a custom resolver + @ActiveProfiles( + resolver = OperatingSystemActiveProfilesResolver::class, + inheritProfiles = false) + class TransferServiceTest : AbstractIntegrationTest() { + // test body + } +---- + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class OperatingSystemActiveProfilesResolver implements ActiveProfilesResolver { + + @Override + public String[] resolve(Class<?> testClass) { + String profile = ...; + // determine the value of profile based on the operating system + return new String[] {profile}; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class OperatingSystemActiveProfilesResolver : ActiveProfilesResolver { + + override fun resolve(testClass: Class<*>): Array<String> { + val profile: String = ... + // determine the value of profile based on the operating system + return arrayOf(profile) + } + } +---- + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc new file mode 100644 index 000000000000..fcd850e9d7ed --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc @@ -0,0 +1,113 @@ +[[testcontext-ctx-management-groovy]] += Context Configuration with Groovy Scripts + +To load an `ApplicationContext` for your tests by using Groovy scripts that use the +<<core.adoc#groovy-bean-definition-dsl, Groovy Bean Definition DSL>>, you can annotate +your test class with `@ContextConfiguration` and configure the `locations` or `value` +attribute with an array that contains the resource locations of Groovy scripts. Resource +lookup semantics for Groovy scripts are the same as those described for +<<testcontext-ctx-management-xml, XML configuration files>>. + +.Enabling Groovy script support +TIP: Support for using Groovy scripts to load an `ApplicationContext` in the Spring +TestContext Framework is enabled automatically if Groovy is on the classpath. + +The following example shows how to specify Groovy configuration files: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be loaded from "/AppConfig.groovy" and + // "/TestConfig.groovy" in the root of the classpath + @ContextConfiguration({"/AppConfig.groovy", "/TestConfig.Groovy"}) <1> + class MyTest { + // class body... + } +---- +<1> Specifying the location of Groovy configuration files. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be loaded from "/AppConfig.groovy" and + // "/TestConfig.groovy" in the root of the classpath + @ContextConfiguration("/AppConfig.groovy", "/TestConfig.Groovy") // <1> + class MyTest { + // class body... + } +---- +<1> Specifying the location of Groovy configuration files. + + +If you omit both the `locations` and `value` attributes from the `@ContextConfiguration` +annotation, the TestContext framework tries to detect a default Groovy script. +Specifically, `GenericGroovyXmlContextLoader` and `GenericGroovyXmlWebContextLoader` +detect a default location based on the name of the test class. If your class is named +`com.example.MyTest`, the Groovy context loader loads your application context from +`"classpath:com/example/MyTestContext.groovy"`. The following example shows how to use +the default: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be loaded from + // "classpath:com/example/MyTestContext.groovy" + @ContextConfiguration // <1> + class MyTest { + // class body... + } +---- +<1> Loading configuration from the default location. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be loaded from + // "classpath:com/example/MyTestContext.groovy" + @ContextConfiguration // <1> + class MyTest { + // class body... + } +---- +<1> Loading configuration from the default location. + + +.Declaring XML configuration and Groovy scripts simultaneously +[TIP] +===== +You can declare both XML configuration files and Groovy scripts simultaneously by using +the `locations` or `value` attribute of `@ContextConfiguration`. If the path to a +configured resource location ends with `.xml`, it is loaded by using an +`XmlBeanDefinitionReader`. Otherwise, it is loaded by using a +`GroovyBeanDefinitionReader`. + +The following listing shows how to combine both in an integration test: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be loaded from + // "/app-config.xml" and "/TestConfig.groovy" + @ContextConfiguration({ "/app-config.xml", "/TestConfig.groovy" }) + class MyTest { + // class body... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be loaded from + // "/app-config.xml" and "/TestConfig.groovy" + @ContextConfiguration("/app-config.xml", "/TestConfig.groovy") + class MyTest { + // class body... + } +---- +===== + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc new file mode 100644 index 000000000000..6cfd1b3a4eaf --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc @@ -0,0 +1,218 @@ +[[testcontext-ctx-management-ctx-hierarchies]] += Context Hierarchies + +When writing integration tests that rely on a loaded Spring `ApplicationContext`, it is +often sufficient to test against a single context. However, there are times when it is +beneficial or even necessary to test against a hierarchy of `ApplicationContext` +instances. For example, if you are developing a Spring MVC web application, you typically +have a root `WebApplicationContext` loaded by Spring's `ContextLoaderListener` and a +child `WebApplicationContext` loaded by Spring's `DispatcherServlet`. This results in a +parent-child context hierarchy where shared components and infrastructure configuration +are declared in the root context and consumed in the child context by web-specific +components. Another use case can be found in Spring Batch applications, where you often +have a parent context that provides configuration for shared batch infrastructure and a +child context for the configuration of a specific batch job. + +You can write integration tests that use context hierarchies by declaring context +configuration with the `@ContextHierarchy` annotation, either on an individual test class +or within a test class hierarchy. If a context hierarchy is declared on multiple classes +within a test class hierarchy, you can also merge or override the context configuration +for a specific, named level in the context hierarchy. When merging configuration for a +given level in the hierarchy, the configuration resource type (that is, XML configuration +files or component classes) must be consistent. Otherwise, it is perfectly acceptable to +have different levels in a context hierarchy configured using different resource types. + +The remaining JUnit Jupiter based examples in this section show common configuration +scenarios for integration tests that require the use of context hierarchies. + +**Single test class with context hierarchy** +-- +`ControllerIntegrationTests` represents a typical integration testing scenario for a +Spring MVC web application by declaring a context hierarchy that consists of two levels, +one for the root `WebApplicationContext` (loaded by using the `TestAppConfig` +`@Configuration` class) and one for the dispatcher servlet `WebApplicationContext` +(loaded by using the `WebConfig` `@Configuration` class). The `WebApplicationContext` +that is autowired into the test instance is the one for the child context (that is, the +lowest context in the hierarchy). The following listing shows this configuration scenario: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + @WebAppConfiguration + @ContextHierarchy({ + @ContextConfiguration(classes = TestAppConfig.class), + @ContextConfiguration(classes = WebConfig.class) + }) + class ControllerIntegrationTests { + + @Autowired + WebApplicationContext wac; + + // ... + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + @WebAppConfiguration + @ContextHierarchy( + ContextConfiguration(classes = [TestAppConfig::class]), + ContextConfiguration(classes = [WebConfig::class])) + class ControllerIntegrationTests { + + @Autowired + lateinit var wac: WebApplicationContext + + // ... + } +---- +-- + +**Class hierarchy with implicit parent context** +-- +The test classes in this example define a context hierarchy within a test class +hierarchy. `AbstractWebTests` declares the configuration for a root +`WebApplicationContext` in a Spring-powered web application. Note, however, that +`AbstractWebTests` does not declare `@ContextHierarchy`. Consequently, subclasses of +`AbstractWebTests` can optionally participate in a context hierarchy or follow the +standard semantics for `@ContextConfiguration`. `SoapWebServiceTests` and +`RestWebServiceTests` both extend `AbstractWebTests` and define a context hierarchy by +using `@ContextHierarchy`. The result is that three application contexts are loaded (one +for each declaration of `@ContextConfiguration`), and the application context loaded +based on the configuration in `AbstractWebTests` is set as the parent context for each of +the contexts loaded for the concrete subclasses. The following listing shows this +configuration scenario: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + @WebAppConfiguration + @ContextConfiguration("file:src/main/webapp/WEB-INF/applicationContext.xml") + public abstract class AbstractWebTests {} + + @ContextHierarchy(@ContextConfiguration("/spring/soap-ws-config.xml")) + public class SoapWebServiceTests extends AbstractWebTests {} + + @ContextHierarchy(@ContextConfiguration("/spring/rest-ws-config.xml")) + public class RestWebServiceTests extends AbstractWebTests {} +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + @WebAppConfiguration + @ContextConfiguration("file:src/main/webapp/WEB-INF/applicationContext.xml") + abstract class AbstractWebTests + + @ContextHierarchy(ContextConfiguration("/spring/soap-ws-config.xml")) + class SoapWebServiceTests : AbstractWebTests() + + @ContextHierarchy(ContextConfiguration("/spring/rest-ws-config.xml")) + class RestWebServiceTests : AbstractWebTests() + +---- +-- + +**Class hierarchy with merged context hierarchy configuration** +-- +The classes in this example show the use of named hierarchy levels in order to merge the +configuration for specific levels in a context hierarchy. `BaseTests` defines two levels +in the hierarchy, `parent` and `child`. `ExtendedTests` extends `BaseTests` and instructs +the Spring TestContext Framework to merge the context configuration for the `child` +hierarchy level, by ensuring that the names declared in the `name` attribute in +`@ContextConfiguration` are both `child`. The result is that three application contexts +are loaded: one for `/app-config.xml`, one for `/user-config.xml`, and one for +`{"/user-config.xml", "/order-config.xml"}`. As with the previous example, the +application context loaded from `/app-config.xml` is set as the parent context for the +contexts loaded from `/user-config.xml` and `{"/user-config.xml", "/order-config.xml"}`. +The following listing shows this configuration scenario: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + @ContextHierarchy({ + @ContextConfiguration(name = "parent", locations = "/app-config.xml"), + @ContextConfiguration(name = "child", locations = "/user-config.xml") + }) + class BaseTests {} + + @ContextHierarchy( + @ContextConfiguration(name = "child", locations = "/order-config.xml") + ) + class ExtendedTests extends BaseTests {} +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + @ContextHierarchy( + ContextConfiguration(name = "parent", locations = ["/app-config.xml"]), + ContextConfiguration(name = "child", locations = ["/user-config.xml"])) + open class BaseTests {} + + @ContextHierarchy( + ContextConfiguration(name = "child", locations = ["/order-config.xml"]) + ) + class ExtendedTests : BaseTests() {} +---- +-- + +**Class hierarchy with overridden context hierarchy configuration** +-- +In contrast to the previous example, this example demonstrates how to override the +configuration for a given named level in a context hierarchy by setting the +`inheritLocations` flag in `@ContextConfiguration` to `false`. Consequently, the +application context for `ExtendedTests` is loaded only from `/test-user-config.xml` and +has its parent set to the context loaded from `/app-config.xml`. The following listing +shows this configuration scenario: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + @ContextHierarchy({ + @ContextConfiguration(name = "parent", locations = "/app-config.xml"), + @ContextConfiguration(name = "child", locations = "/user-config.xml") + }) + class BaseTests {} + + @ContextHierarchy( + @ContextConfiguration( + name = "child", + locations = "/test-user-config.xml", + inheritLocations = false + )) + class ExtendedTests extends BaseTests {} +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + @ContextHierarchy( + ContextConfiguration(name = "parent", locations = ["/app-config.xml"]), + ContextConfiguration(name = "child", locations = ["/user-config.xml"])) + open class BaseTests {} + + @ContextHierarchy( + ContextConfiguration( + name = "child", + locations = ["/test-user-config.xml"], + inheritLocations = false + )) + class ExtendedTests : BaseTests() {} +---- + +.Dirtying a context within a context hierarchy +NOTE: If you use `@DirtiesContext` in a test whose context is configured as part of a +context hierarchy, you can use the `hierarchyMode` flag to control how the context cache +is cleared. For further details, see the discussion of `@DirtiesContext` in +<<spring-testing-annotation-dirtiescontext, Spring Testing Annotations>> and the +{api-spring-framework}/test/annotation/DirtiesContext.html[`@DirtiesContext`] javadoc. +-- + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc new file mode 100644 index 000000000000..8229e9c89a87 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc @@ -0,0 +1,160 @@ +[[testcontext-ctx-management-inheritance]] += Context Configuration Inheritance + +`@ContextConfiguration` supports boolean `inheritLocations` and `inheritInitializers` +attributes that denote whether resource locations or component classes and context +initializers declared by superclasses should be inherited. The default value for both +flags is `true`. This means that a test class inherits the resource locations or +component classes as well as the context initializers declared by any superclasses. +Specifically, the resource locations or component classes for a test class are appended +to the list of resource locations or annotated classes declared by superclasses. +Similarly, the initializers for a given test class are added to the set of initializers +defined by test superclasses. Thus, subclasses have the option of extending the resource +locations, component classes, or context initializers. + +If the `inheritLocations` or `inheritInitializers` attribute in `@ContextConfiguration` +is set to `false`, the resource locations or component classes and the context +initializers, respectively, for the test class shadow and effectively replace the +configuration defined by superclasses. + +NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing +classes. See <<testcontext-junit-jupiter-nested-test-configuration>> for details. + +In the next example, which uses XML resource locations, the `ApplicationContext` for +`ExtendedTest` is loaded from `base-config.xml` and `extended-config.xml`, in that order. +Beans defined in `extended-config.xml` can, therefore, override (that is, replace) those +defined in `base-config.xml`. The following example shows how one class can extend +another and use both its own configuration file and the superclass's configuration file: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be loaded from "/base-config.xml" + // in the root of the classpath + @ContextConfiguration("/base-config.xml") <1> + class BaseTest { + // class body... + } + + // ApplicationContext will be loaded from "/base-config.xml" and + // "/extended-config.xml" in the root of the classpath + @ContextConfiguration("/extended-config.xml") <2> + class ExtendedTest extends BaseTest { + // class body... + } +---- +<1> Configuration file defined in the superclass. +<2> Configuration file defined in the subclass. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be loaded from "/base-config.xml" + // in the root of the classpath + @ContextConfiguration("/base-config.xml") // <1> + open class BaseTest { + // class body... + } + + // ApplicationContext will be loaded from "/base-config.xml" and + // "/extended-config.xml" in the root of the classpath + @ContextConfiguration("/extended-config.xml") // <2> + class ExtendedTest : BaseTest() { + // class body... + } +---- +<1> Configuration file defined in the superclass. +<2> Configuration file defined in the subclass. + + +Similarly, in the next example, which uses component classes, the `ApplicationContext` +for `ExtendedTest` is loaded from the `BaseConfig` and `ExtendedConfig` classes, in that +order. Beans defined in `ExtendedConfig` can, therefore, override (that is, replace) +those defined in `BaseConfig`. The following example shows how one class can extend +another and use both its own configuration class and the superclass's configuration class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // ApplicationContext will be loaded from BaseConfig + @SpringJUnitConfig(BaseConfig.class) // <1> + class BaseTest { + // class body... + } + + // ApplicationContext will be loaded from BaseConfig and ExtendedConfig + @SpringJUnitConfig(ExtendedConfig.class) // <2> + class ExtendedTest extends BaseTest { + // class body... + } +---- +<1> Configuration class defined in the superclass. +<2> Configuration class defined in the subclass. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // ApplicationContext will be loaded from BaseConfig + @SpringJUnitConfig(BaseConfig::class) // <1> + open class BaseTest { + // class body... + } + + // ApplicationContext will be loaded from BaseConfig and ExtendedConfig + @SpringJUnitConfig(ExtendedConfig::class) // <2> + class ExtendedTest : BaseTest() { + // class body... + } +---- +<1> Configuration class defined in the superclass. +<2> Configuration class defined in the subclass. + + +In the next example, which uses context initializers, the `ApplicationContext` for +`ExtendedTest` is initialized by using `BaseInitializer` and `ExtendedInitializer`. Note, +however, that the order in which the initializers are invoked depends on whether they +implement Spring's `Ordered` interface or are annotated with Spring's `@Order` annotation +or the standard `@Priority` annotation. The following example shows how one class can +extend another and use both its own initializer and the superclass's initializer: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // ApplicationContext will be initialized by BaseInitializer + @SpringJUnitConfig(initializers = BaseInitializer.class) // <1> + class BaseTest { + // class body... + } + + // ApplicationContext will be initialized by BaseInitializer + // and ExtendedInitializer + @SpringJUnitConfig(initializers = ExtendedInitializer.class) // <2> + class ExtendedTest extends BaseTest { + // class body... + } +---- +<1> Initializer defined in the superclass. +<2> Initializer defined in the subclass. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // ApplicationContext will be initialized by BaseInitializer + @SpringJUnitConfig(initializers = [BaseInitializer::class]) // <1> + open class BaseTest { + // class body... + } + + // ApplicationContext will be initialized by BaseInitializer + // and ExtendedInitializer + @SpringJUnitConfig(initializers = [ExtendedInitializer::class]) // <2> + class ExtendedTest : BaseTest() { + // class body... + } +---- +<1> Initializer defined in the superclass. +<2> Initializer defined in the subclass. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/initializers.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/initializers.adoc new file mode 100644 index 000000000000..4263559232fc --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/initializers.adoc @@ -0,0 +1,79 @@ +[[testcontext-ctx-management-initializers]] += Context Configuration with Context Initializers + +To configure an `ApplicationContext` for your tests by using context initializers, +annotate your test class with `@ContextConfiguration` and configure the `initializers` +attribute with an array that contains references to classes that implement +`ApplicationContextInitializer`. The declared context initializers are then used to +initialize the `ConfigurableApplicationContext` that is loaded for your tests. Note that +the concrete `ConfigurableApplicationContext` type supported by each declared initializer +must be compatible with the type of `ApplicationContext` created by the +`SmartContextLoader` in use (typically a `GenericApplicationContext`). Furthermore, the +order in which the initializers are invoked depends on whether they implement Spring's +`Ordered` interface or are annotated with Spring's `@Order` annotation or the standard +`@Priority` annotation. The following example shows how to use initializers: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be loaded from TestConfig + // and initialized by TestAppCtxInitializer + @ContextConfiguration( + classes = TestConfig.class, + initializers = TestAppCtxInitializer.class) // <1> + class MyTest { + // class body... + } +---- +<1> Specifying configuration by using a configuration class and an initializer. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be loaded from TestConfig + // and initialized by TestAppCtxInitializer + @ContextConfiguration( + classes = [TestConfig::class], + initializers = [TestAppCtxInitializer::class]) // <1> + class MyTest { + // class body... + } +---- +<1> Specifying configuration by using a configuration class and an initializer. + + +You can also omit the declaration of XML configuration files, Groovy scripts, or +component classes in `@ContextConfiguration` entirely and instead declare only +`ApplicationContextInitializer` classes, which are then responsible for registering beans +in the context -- for example, by programmatically loading bean definitions from XML +files or configuration classes. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be initialized by EntireAppInitializer + // which presumably registers beans in the context + @ContextConfiguration(initializers = EntireAppInitializer.class) <1> + class MyTest { + // class body... + } +---- +<1> Specifying configuration by using only an initializer. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be initialized by EntireAppInitializer + // which presumably registers beans in the context + @ContextConfiguration(initializers = [EntireAppInitializer::class]) // <1> + class MyTest { + // class body... + } +---- +<1> Specifying configuration by using only an initializer. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc new file mode 100644 index 000000000000..fbc1b11114c5 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc @@ -0,0 +1,127 @@ +[[testcontext-ctx-management-javaconfig]] += Context Configuration with Component Classes + +To load an `ApplicationContext` for your tests by using component classes (see +<<core.adoc#beans-java, Java-based container configuration>>), you can annotate your test +class with `@ContextConfiguration` and configure the `classes` attribute with an array +that contains references to component classes. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be loaded from AppConfig and TestConfig + @ContextConfiguration(classes = {AppConfig.class, TestConfig.class}) // <1> + class MyTest { + // class body... + } +---- +<1> Specifying component classes. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be loaded from AppConfig and TestConfig + @ContextConfiguration(classes = [AppConfig::class, TestConfig::class]) // <1> + class MyTest { + // class body... + } +---- +<1> Specifying component classes. + + +[[testcontext-ctx-management-javaconfig-component-classes]] +.Component Classes +[TIP] +==== +The term "`component class`" can refer to any of the following: + +* A class annotated with `@Configuration`. +* A component (that is, a class annotated with `@Component`, `@Service`, `@Repository`, or other stereotype annotations). +* A JSR-330 compliant class that is annotated with `jakarta.inject` annotations. +* Any class that contains `@Bean`-methods. +* Any other class that is intended to be registered as a Spring component (i.e., a Spring + bean in the `ApplicationContext`), potentially taking advantage of automatic autowiring + of a single constructor without the use of Spring annotations. + +See the javadoc of +{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] and +{api-spring-framework}/context/annotation/Bean.html[`@Bean`] for further information +regarding the configuration and semantics of component classes, paying special attention +to the discussion of `@Bean` Lite Mode. +==== + +If you omit the `classes` attribute from the `@ContextConfiguration` annotation, the +TestContext framework tries to detect the presence of default configuration classes. +Specifically, `AnnotationConfigContextLoader` and `AnnotationConfigWebContextLoader` +detect all `static` nested classes of the test class that meet the requirements for +configuration class implementations, as specified in the +{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] javadoc. +Note that the name of the configuration class is arbitrary. In addition, a test class can +contain more than one `static` nested configuration class if desired. In the following +example, the `OrderServiceTest` class declares a `static` nested configuration class +named `Config` that is automatically used to load the `ApplicationContext` for the test +class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig <1> + // ApplicationContext will be loaded from the static nested Config class + class OrderServiceTest { + + @Configuration + static class Config { + + // this bean will be injected into the OrderServiceTest class + @Bean + OrderService orderService() { + OrderService orderService = new OrderServiceImpl(); + // set properties, etc. + return orderService; + } + } + + @Autowired + OrderService orderService; + + @Test + void testOrderService() { + // test the orderService + } + + } +---- +<1> Loading configuration information from the nested `Config` class. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig <1> + // ApplicationContext will be loaded from the nested Config class + class OrderServiceTest { + + @Autowired + lateinit var orderService: OrderService + + @Configuration + class Config { + + // this bean will be injected into the OrderServiceTest class + @Bean + fun orderService(): OrderService { + // set properties, etc. + return OrderServiceImpl() + } + } + + @Test + fun testOrderService() { + // test the orderService + } + } +---- +<1> Loading configuration information from the nested `Config` class. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/mixed-config.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/mixed-config.adoc new file mode 100644 index 000000000000..c1b97b4a7a2e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/mixed-config.adoc @@ -0,0 +1,33 @@ +[[testcontext-ctx-management-mixed-config]] += Mixing XML, Groovy Scripts, and Component Classes + +It may sometimes be desirable to mix XML configuration files, Groovy scripts, and +component classes (typically `@Configuration` classes) to configure an +`ApplicationContext` for your tests. For example, if you use XML configuration in +production, you may decide that you want to use `@Configuration` classes to configure +specific Spring-managed components for your tests, or vice versa. + +Furthermore, some third-party frameworks (such as Spring Boot) provide first-class +support for loading an `ApplicationContext` from different types of resources +simultaneously (for example, XML configuration files, Groovy scripts, and +`@Configuration` classes). The Spring Framework, historically, has not supported this for +standard deployments. Consequently, most of the `SmartContextLoader` implementations that +the Spring Framework delivers in the `spring-test` module support only one resource type +for each test context. However, this does not mean that you cannot use both. One +exception to the general rule is that the `GenericGroovyXmlContextLoader` and +`GenericGroovyXmlWebContextLoader` support both XML configuration files and Groovy +scripts simultaneously. Furthermore, third-party frameworks may choose to support the +declaration of both `locations` and `classes` through `@ContextConfiguration`, and, with +the standard testing support in the TestContext framework, you have the following options. + +If you want to use resource locations (for example, XML or Groovy) and `@Configuration` +classes to configure your tests, you must pick one as the entry point, and that one must +include or import the other. For example, in XML or Groovy scripts, you can include +`@Configuration` classes by using component scanning or defining them as normal Spring +beans, whereas, in a `@Configuration` class, you can use `@ImportResource` to import XML +configuration files or Groovy scripts. Note that this behavior is semantically equivalent +to how you configure your application in production: In production configuration, you +define either a set of XML or Groovy resource locations or a set of `@Configuration` +classes from which your production `ApplicationContext` is loaded, but you still have the +freedom to include or import the other type of configuration. + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc new file mode 100644 index 000000000000..7d59858e248c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc @@ -0,0 +1,268 @@ +[[testcontext-ctx-management-property-sources]] += Context Configuration with Test Property Sources + +The Spring Framework has first-class support for the notion of an environment with a +hierarchy of property sources, and you can configure integration tests with test-specific +property sources. In contrast to the `@PropertySource` annotation used on +`@Configuration` classes, you can declare the `@TestPropertySource` annotation on a test +class to declare resource locations for test properties files or inlined properties. +These test property sources are added to the set of `PropertySources` in the +`Environment` for the `ApplicationContext` loaded for the annotated integration test. + +[NOTE] +==== +You can use `@TestPropertySource` with any implementation of the `SmartContextLoader` +SPI, but `@TestPropertySource` is not supported with implementations of the older +`ContextLoader` SPI. + +Implementations of `SmartContextLoader` gain access to merged test property source values +through the `getPropertySourceLocations()` and `getPropertySourceProperties()` methods in +`MergedContextConfiguration`. +==== + +[[declaring-test-property-sources]] +== Declaring Test Property Sources + +You can configure test properties files by using the `locations` or `value` attribute of +`@TestPropertySource`. + +Both traditional and XML-based properties file formats are supported -- for example, +`"classpath:/com/example/test.properties"` or `"file:///path/to/file.xml"`. + +Each path is interpreted as a Spring `Resource`. A plain path (for example, +`"test.properties"`) is treated as a classpath resource that is relative to the package +in which the test class is defined. A path starting with a slash is treated as an +absolute classpath resource (for example: `"/org/example/test.xml"`). A path that +references a URL (for example, a path prefixed with `classpath:`, `file:`, or `http:`) is +loaded by using the specified resource protocol. Resource location wildcards (such as +`**/*.properties`) are not permitted: Each location must evaluate to exactly one +`.properties` or `.xml` resource. + +The following example uses a test properties file: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @TestPropertySource("/test.properties") // <1> + class MyIntegrationTests { + // class body... + } +---- +<1> Specifying a properties file with an absolute path. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @TestPropertySource("/test.properties") // <1> + class MyIntegrationTests { + // class body... + } +---- +<1> Specifying a properties file with an absolute path. + + +You can configure inlined properties in the form of key-value pairs by using the +`properties` attribute of `@TestPropertySource`, as shown in the next example. All +key-value pairs are added to the enclosing `Environment` as a single test +`PropertySource` with the highest precedence. + +The supported syntax for key-value pairs is the same as the syntax defined for entries in +a Java properties file: + +* `key=value` +* `key:value` +* `key value` + +The following example sets two inlined properties: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @TestPropertySource(properties = {"timezone = GMT", "port: 4242"}) // <1> + class MyIntegrationTests { + // class body... + } +---- +<1> Setting two properties by using two variations of the key-value syntax. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @TestPropertySource(properties = ["timezone = GMT", "port: 4242"]) // <1> + class MyIntegrationTests { + // class body... + } +---- +<1> Setting two properties by using two variations of the key-value syntax. + +[NOTE] +==== +As of Spring Framework 5.2, `@TestPropertySource` can be used as _repeatable annotation_. +That means that you can have multiple declarations of `@TestPropertySource` on a single +test class, with the `locations` and `properties` from later `@TestPropertySource` +annotations overriding those from previous `@TestPropertySource` annotations. + +In addition, you may declare multiple composed annotations on a test class that are each +meta-annotated with `@TestPropertySource`, and all of those `@TestPropertySource` +declarations will contribute to your test property sources. + +Directly present `@TestPropertySource` annotations always take precedence over +meta-present `@TestPropertySource` annotations. In other words, `locations` and +`properties` from a directly present `@TestPropertySource` annotation will override the +`locations` and `properties` from a `@TestPropertySource` annotation used as a +meta-annotation. +==== + + +[[default-properties-file-detection]] +== Default Properties File Detection + +If `@TestPropertySource` is declared as an empty annotation (that is, without explicit +values for the `locations` or `properties` attributes), an attempt is made to detect a +default properties file relative to the class that declared the annotation. For example, +if the annotated test class is `com.example.MyTest`, the corresponding default properties +file is `classpath:com/example/MyTest.properties`. If the default cannot be detected, an +`IllegalStateException` is thrown. + +[[precedence]] +== Precedence + +Test properties have higher precedence than those defined in the operating system's +environment, Java system properties, or property sources added by the application +declaratively by using `@PropertySource` or programmatically. Thus, test properties can +be used to selectively override properties loaded from system and application property +sources. Furthermore, inlined properties have higher precedence than properties loaded +from resource locations. Note, however, that properties registered via +<<testcontext-ctx-management-dynamic-property-sources, `@DynamicPropertySource`>> have +higher precedence than those loaded via `@TestPropertySource`. + +In the next example, the `timezone` and `port` properties and any properties defined in +`"/test.properties"` override any properties of the same name that are defined in system +and application property sources. Furthermore, if the `"/test.properties"` file defines +entries for the `timezone` and `port` properties those are overridden by the inlined +properties declared by using the `properties` attribute. The following example shows how +to specify properties both in a file and inline: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @TestPropertySource( + locations = "/test.properties", + properties = {"timezone = GMT", "port: 4242"} + ) + class MyIntegrationTests { + // class body... + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @TestPropertySource("/test.properties", + properties = ["timezone = GMT", "port: 4242"] + ) + class MyIntegrationTests { + // class body... + } +---- + +[[inheriting-and-overriding-test-property-sources]] +== Inheriting and Overriding Test Property Sources + +`@TestPropertySource` supports boolean `inheritLocations` and `inheritProperties` +attributes that denote whether resource locations for properties files and inlined +properties declared by superclasses should be inherited. The default value for both flags +is `true`. This means that a test class inherits the locations and inlined properties +declared by any superclasses. Specifically, the locations and inlined properties for a +test class are appended to the locations and inlined properties declared by superclasses. +Thus, subclasses have the option of extending the locations and inlined properties. Note +that properties that appear later shadow (that is, override) properties of the same name +that appear earlier. In addition, the aforementioned precedence rules apply for inherited +test property sources as well. + +If the `inheritLocations` or `inheritProperties` attribute in `@TestPropertySource` is +set to `false`, the locations or inlined properties, respectively, for the test class +shadow and effectively replace the configuration defined by superclasses. + +NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing +classes. See <<testcontext-junit-jupiter-nested-test-configuration>> for details. + +In the next example, the `ApplicationContext` for `BaseTest` is loaded by using only the +`base.properties` file as a test property source. In contrast, the `ApplicationContext` +for `ExtendedTest` is loaded by using the `base.properties` and `extended.properties` +files as test property source locations. The following example shows how to define +properties in both a subclass and its superclass by using `properties` files: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @TestPropertySource("base.properties") + @ContextConfiguration + class BaseTest { + // ... + } + + @TestPropertySource("extended.properties") + @ContextConfiguration + class ExtendedTest extends BaseTest { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @TestPropertySource("base.properties") + @ContextConfiguration + open class BaseTest { + // ... + } + + @TestPropertySource("extended.properties") + @ContextConfiguration + class ExtendedTest : BaseTest() { + // ... + } +---- + +In the next example, the `ApplicationContext` for `BaseTest` is loaded by using only the +inlined `key1` property. In contrast, the `ApplicationContext` for `ExtendedTest` is +loaded by using the inlined `key1` and `key2` properties. The following example shows how +to define properties in both a subclass and its superclass by using inline properties: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @TestPropertySource(properties = "key1 = value1") + @ContextConfiguration + class BaseTest { + // ... + } + + @TestPropertySource(properties = "key2 = value2") + @ContextConfiguration + class ExtendedTest extends BaseTest { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @TestPropertySource(properties = ["key1 = value1"]) + @ContextConfiguration + open class BaseTest { + // ... + } + + @TestPropertySource(properties = ["key2 = value2"]) + @ContextConfiguration + class ExtendedTest : BaseTest() { + // ... + } +---- + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc new file mode 100644 index 000000000000..bd5a31d226ae --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc @@ -0,0 +1,77 @@ +[[testcontext-ctx-management-web-mocks]] += Working with Web Mocks + +To provide comprehensive web testing support, the TestContext framework has a +`ServletTestExecutionListener` that is enabled by default. When testing against a +`WebApplicationContext`, this <<testcontext-key-abstractions, `TestExecutionListener`>> +sets up default thread-local state by using Spring Web's `RequestContextHolder` before +each test method and creates a `MockHttpServletRequest`, a `MockHttpServletResponse`, and +a `ServletWebRequest` based on the base resource path configured with +`@WebAppConfiguration`. `ServletTestExecutionListener` also ensures that the +`MockHttpServletResponse` and `ServletWebRequest` can be injected into the test instance, +and, once the test is complete, it cleans up thread-local state. + +Once you have a `WebApplicationContext` loaded for your test, you might find that you +need to interact with the web mocks -- for example, to set up your test fixture or to +perform assertions after invoking your web component. The following example shows which +mocks can be autowired into your test instance. Note that the `WebApplicationContext` and +`MockServletContext` are both cached across the test suite, whereas the other mocks are +managed per test method by the `ServletTestExecutionListener`. + +.Injecting mocks +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitWebConfig + class WacTests { + + @Autowired + WebApplicationContext wac; // cached + + @Autowired + MockServletContext servletContext; // cached + + @Autowired + MockHttpSession session; + + @Autowired + MockHttpServletRequest request; + + @Autowired + MockHttpServletResponse response; + + @Autowired + ServletWebRequest webRequest; + + //... + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitWebConfig + class WacTests { + + @Autowired + lateinit var wac: WebApplicationContext // cached + + @Autowired + lateinit var servletContext: MockServletContext // cached + + @Autowired + lateinit var session: MockHttpSession + + @Autowired + lateinit var request: MockHttpServletRequest + + @Autowired + lateinit var response: MockHttpServletResponse + + @Autowired + lateinit var webRequest: ServletWebRequest + + //... + } +---- + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web.adoc new file mode 100644 index 000000000000..163720fc87cb --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web.adoc @@ -0,0 +1,142 @@ +[[testcontext-ctx-management-web]] += Loading a `WebApplicationContext` + +To instruct the TestContext framework to load a `WebApplicationContext` instead of a +standard `ApplicationContext`, you can annotate the respective test class with +`@WebAppConfiguration`. + +The presence of `@WebAppConfiguration` on your test class instructs the TestContext +framework (TCF) that a `WebApplicationContext` (WAC) should be loaded for your +integration tests. In the background, the TCF makes sure that a `MockServletContext` is +created and supplied to your test's WAC. By default, the base resource path for your +`MockServletContext` is set to `src/main/webapp`. This is interpreted as a path relative +to the root of your JVM (normally the path to your project). If you are familiar with the +directory structure of a web application in a Maven project, you know that +`src/main/webapp` is the default location for the root of your WAR. If you need to +override this default, you can provide an alternate path to the `@WebAppConfiguration` +annotation (for example, `@WebAppConfiguration("src/test/webapp")`). If you wish to +reference a base resource path from the classpath instead of the file system, you can use +Spring's `classpath:` prefix. + +Note that Spring's testing support for `WebApplicationContext` implementations is on par +with its support for standard `ApplicationContext` implementations. When testing with a +`WebApplicationContext`, you are free to declare XML configuration files, Groovy scripts, +or `@Configuration` classes by using `@ContextConfiguration`. You are also free to use +any other test annotations, such as `@ActiveProfiles`, `@TestExecutionListeners`, `@Sql`, +`@Rollback`, and others. + +The remaining examples in this section show some of the various configuration options for +loading a `WebApplicationContext`. The following example shows the TestContext +framework's support for convention over configuration: + +.Conventions +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + + // defaults to "file:src/main/webapp" + @WebAppConfiguration + + // detects "WacTests-context.xml" in the same package + // or static nested @Configuration classes + @ContextConfiguration + class WacTests { + //... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + + // defaults to "file:src/main/webapp" + @WebAppConfiguration + + // detects "WacTests-context.xml" in the same package + // or static nested @Configuration classes + @ContextConfiguration + class WacTests { + //... + } +---- + +If you annotate a test class with `@WebAppConfiguration` without specifying a resource +base path, the resource path effectively defaults to `file:src/main/webapp`. Similarly, +if you declare `@ContextConfiguration` without specifying resource `locations`, component +`classes`, or context `initializers`, Spring tries to detect the presence of your +configuration by using conventions (that is, `WacTests-context.xml` in the same package +as the `WacTests` class or static nested `@Configuration` classes). + +The following example shows how to explicitly declare a resource base path with +`@WebAppConfiguration` and an XML resource location with `@ContextConfiguration`: + +.Default resource semantics +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + + // file system resource + @WebAppConfiguration("webapp") + + // classpath resource + @ContextConfiguration("/spring/test-servlet-config.xml") + class WacTests { + //... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + + // file system resource + @WebAppConfiguration("webapp") + + // classpath resource + @ContextConfiguration("/spring/test-servlet-config.xml") + class WacTests { + //... + } +---- + +The important thing to note here is the different semantics for paths with these two +annotations. By default, `@WebAppConfiguration` resource paths are file system based, +whereas `@ContextConfiguration` resource locations are classpath based. + +The following example shows that we can override the default resource semantics for both +annotations by specifying a Spring resource prefix: + +.Explicit resource semantics +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + + // classpath resource + @WebAppConfiguration("classpath:test-web-resources") + + // file system resource + @ContextConfiguration("file:src/main/webapp/WEB-INF/servlet-config.xml") + class WacTests { + //... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + + // classpath resource + @WebAppConfiguration("classpath:test-web-resources") + + // file system resource + @ContextConfiguration("file:src/main/webapp/WEB-INF/servlet-config.xml") + class WacTests { + //... + } +---- + +Contrast the comments in this example with the previous example. + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/xml.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/xml.adoc new file mode 100644 index 000000000000..b11a6c4be70b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/xml.adoc @@ -0,0 +1,103 @@ +[[testcontext-ctx-management-xml]] += Context Configuration with XML resources + +To load an `ApplicationContext` for your tests by using XML configuration files, annotate +your test class with `@ContextConfiguration` and configure the `locations` attribute with +an array that contains the resource locations of XML configuration metadata. A plain or +relative path (for example, `context.xml`) is treated as a classpath resource that is +relative to the package in which the test class is defined. A path starting with a slash +is treated as an absolute classpath location (for example, `/org/example/config.xml`). A +path that represents a resource URL (i.e., a path prefixed with `classpath:`, `file:`, +`http:`, etc.) is used _as is_. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be loaded from "/app-config.xml" and + // "/test-config.xml" in the root of the classpath + @ContextConfiguration(locations = {"/app-config.xml", "/test-config.xml"}) // <1> + class MyTest { + // class body... + } +---- +<1> Setting the locations attribute to a list of XML files. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be loaded from "/app-config.xml" and + // "/test-config.xml" in the root of the classpath + @ContextConfiguration(locations = ["/app-config.xml", "/test-config.xml"]) // <1> + class MyTest { + // class body... + } +---- +<1> Setting the locations attribute to a list of XML files. + + +`@ContextConfiguration` supports an alias for the `locations` attribute through the +standard Java `value` attribute. Thus, if you do not need to declare additional +attributes in `@ContextConfiguration`, you can omit the declaration of the `locations` +attribute name and declare the resource locations by using the shorthand format +demonstrated in the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + @ContextConfiguration({"/app-config.xml", "/test-config.xml"}) <1> + class MyTest { + // class body... + } +---- +<1> Specifying XML files without using the `locations` attribute. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + @ContextConfiguration("/app-config.xml", "/test-config.xml") // <1> + class MyTest { + // class body... + } +---- +<1> Specifying XML files without using the `locations` attribute. + + +If you omit both the `locations` and the `value` attributes from the +`@ContextConfiguration` annotation, the TestContext framework tries to detect a default +XML resource location. Specifically, `GenericXmlContextLoader` and +`GenericXmlWebContextLoader` detect a default location based on the name of the test +class. If your class is named `com.example.MyTest`, `GenericXmlContextLoader` loads your +application context from `"classpath:com/example/MyTest-context.xml"`. The following +example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // ApplicationContext will be loaded from + // "classpath:com/example/MyTest-context.xml" + @ContextConfiguration // <1> + class MyTest { + // class body... + } +---- +<1> Loading configuration from the default location. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // ApplicationContext will be loaded from + // "classpath:com/example/MyTest-context.xml" + @ContextConfiguration // <1> + class MyTest { + // class body... + } +---- +<1> Loading configuration from the default location. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc new file mode 100644 index 000000000000..c09002d9a652 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc @@ -0,0 +1,400 @@ +[[testcontext-executing-sql]] += Executing SQL Scripts + +When writing integration tests against a relational database, it is often beneficial to +run SQL scripts to modify the database schema or insert test data into tables. The +`spring-jdbc` module provides support for _initializing_ an embedded or existing database +by executing SQL scripts when the Spring `ApplicationContext` is loaded. See +<<data-access.adoc#jdbc-embedded-database-support, Embedded database support>> and +<<data-access.adoc#jdbc-embedded-database-dao-testing, Testing data access logic with an +embedded database>> for details. + +Although it is very useful to initialize a database for testing _once_ when the +`ApplicationContext` is loaded, sometimes it is essential to be able to modify the +database _during_ integration tests. The following sections explain how to run SQL +scripts programmatically and declaratively during integration tests. + +[[testcontext-executing-sql-programmatically]] +== Executing SQL scripts programmatically + +Spring provides the following options for executing SQL scripts programmatically within +integration test methods. + +* `org.springframework.jdbc.datasource.init.ScriptUtils` +* `org.springframework.jdbc.datasource.init.ResourceDatabasePopulator` +* `org.springframework.test.context.junit4.AbstractTransactionalJUnit4SpringContextTests` +* `org.springframework.test.context.testng.AbstractTransactionalTestNGSpringContextTests` + +`ScriptUtils` provides a collection of static utility methods for working with SQL +scripts and is mainly intended for internal use within the framework. However, if you +require full control over how SQL scripts are parsed and run, `ScriptUtils` may suit +your needs better than some of the other alternatives described later. See the +{api-spring-framework}/jdbc/datasource/init/ScriptUtils.html[javadoc] for individual +methods in `ScriptUtils` for further details. + +`ResourceDatabasePopulator` provides an object-based API for programmatically populating, +initializing, or cleaning up a database by using SQL scripts defined in external +resources. `ResourceDatabasePopulator` provides options for configuring the character +encoding, statement separator, comment delimiters, and error handling flags used when +parsing and running the scripts. Each of the configuration options has a reasonable +default value. See the +{api-spring-framework}/jdbc/datasource/init/ResourceDatabasePopulator.html[javadoc] for +details on default values. To run the scripts configured in a +`ResourceDatabasePopulator`, you can invoke either the `populate(Connection)` method to +run the populator against a `java.sql.Connection` or the `execute(DataSource)` method +to run the populator against a `javax.sql.DataSource`. The following example +specifies SQL scripts for a test schema and test data, sets the statement separator to +`@@`, and run the scripts against a `DataSource`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Test + void databaseTest() { + ResourceDatabasePopulator populator = new ResourceDatabasePopulator(); + populator.addScripts( + new ClassPathResource("test-schema.sql"), + new ClassPathResource("test-data.sql")); + populator.setSeparator("@@"); + populator.execute(this.dataSource); + // run code that uses the test schema and data + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Test + fun databaseTest() { + val populator = ResourceDatabasePopulator() + populator.addScripts( + ClassPathResource("test-schema.sql"), + ClassPathResource("test-data.sql")) + populator.setSeparator("@@") + populator.execute(dataSource) + // run code that uses the test schema and data + } +---- + +Note that `ResourceDatabasePopulator` internally delegates to `ScriptUtils` for parsing +and running SQL scripts. Similarly, the `executeSqlScript(..)` methods in +<<testcontext-support-classes-junit4, `AbstractTransactionalJUnit4SpringContextTests`>> +and <<testcontext-support-classes-testng, `AbstractTransactionalTestNGSpringContextTests`>> +internally use a `ResourceDatabasePopulator` to run SQL scripts. See the Javadoc for the +various `executeSqlScript(..)` methods for further details. + +[[testcontext-executing-sql-declaratively]] +== Executing SQL scripts declaratively with @Sql + +In addition to the aforementioned mechanisms for running SQL scripts programmatically, +you can declaratively configure SQL scripts in the Spring TestContext Framework. +Specifically, you can declare the `@Sql` annotation on a test class or test method to +configure individual SQL statements or the resource paths to SQL scripts that should be +run against a given database before or after an integration test method. Support for +`@Sql` is provided by the `SqlScriptsTestExecutionListener`, which is enabled by default. + +NOTE: Method-level `@Sql` declarations override class-level declarations by default. As +of Spring Framework 5.2, however, this behavior may be configured per test class or per +test method via `@SqlMergeMode`. See +<<testcontext-executing-sql-declaratively-script-merging>> for further details. + +[[testcontext-executing-sql-declaratively-script-resources]] +=== Path Resource Semantics + +Each path is interpreted as a Spring `Resource`. A plain path (for example, +`"schema.sql"`) is treated as a classpath resource that is relative to the package in +which the test class is defined. A path starting with a slash is treated as an absolute +classpath resource (for example, `"/org/example/schema.sql"`). A path that references a +URL (for example, a path prefixed with `classpath:`, `file:`, `http:`) is loaded by using +the specified resource protocol. + +The following example shows how to use `@Sql` at the class level and at the method level +within a JUnit Jupiter based integration test class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig + @Sql("/test-schema.sql") + class DatabaseTests { + + @Test + void emptySchemaTest() { + // run code that uses the test schema without any test data + } + + @Test + @Sql({"/test-schema.sql", "/test-user-data.sql"}) + void userTest() { + // run code that uses the test schema and test data + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig + @Sql("/test-schema.sql") + class DatabaseTests { + + @Test + fun emptySchemaTest() { + // run code that uses the test schema without any test data + } + + @Test + @Sql("/test-schema.sql", "/test-user-data.sql") + fun userTest() { + // run code that uses the test schema and test data + } + } +---- + +[[testcontext-executing-sql-declaratively-script-detection]] +=== Default Script Detection + +If no SQL scripts or statements are specified, an attempt is made to detect a `default` +script, depending on where `@Sql` is declared. If a default cannot be detected, an +`IllegalStateException` is thrown. + +* Class-level declaration: If the annotated test class is `com.example.MyTest`, the + corresponding default script is `classpath:com/example/MyTest.sql`. +* Method-level declaration: If the annotated test method is named `testMethod()` and is + defined in the class `com.example.MyTest`, the corresponding default script is + `classpath:com/example/MyTest.testMethod.sql`. + +[[testcontext-executing-sql-declaratively-multiple-annotations]] +=== Declaring Multiple `@Sql` Sets + +If you need to configure multiple sets of SQL scripts for a given test class or test +method but with different syntax configuration, different error handling rules, or +different execution phases per set, you can declare multiple instances of `@Sql`. With +Java 8, you can use `@Sql` as a repeatable annotation. Otherwise, you can use the +`@SqlGroup` annotation as an explicit container for declaring multiple instances of +`@Sql`. + +The following example shows how to use `@Sql` as a repeatable annotation with Java 8: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Test + @Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")) + @Sql("/test-user-data.sql") + void userTest() { + // run code that uses the test schema and test data + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Repeatable annotations with non-SOURCE retention are not yet supported by Kotlin +---- + +In the scenario presented in the preceding example, the `test-schema.sql` script uses a +different syntax for single-line comments. + +The following example is identical to the preceding example, except that the `@Sql` +declarations are grouped together within `@SqlGroup`. With Java 8 and above, the use of +`@SqlGroup` is optional, but you may need to use `@SqlGroup` for compatibility with +other JVM languages such as Kotlin. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Test + @SqlGroup({ + @Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")), + @Sql("/test-user-data.sql") + )} + void userTest() { + // run code that uses the test schema and test data + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Test + @SqlGroup( + Sql("/test-schema.sql", config = SqlConfig(commentPrefix = "`")), + Sql("/test-user-data.sql")) + fun userTest() { + // Run code that uses the test schema and test data + } +---- + +[[testcontext-executing-sql-declaratively-script-execution-phases]] +=== Script Execution Phases + +By default, SQL scripts are run before the corresponding test method. However, if +you need to run a particular set of scripts after the test method (for example, to clean +up database state), you can use the `executionPhase` attribute in `@Sql`, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Test + @Sql( + scripts = "create-test-data.sql", + config = @SqlConfig(transactionMode = ISOLATED) + ) + @Sql( + scripts = "delete-test-data.sql", + config = @SqlConfig(transactionMode = ISOLATED), + executionPhase = AFTER_TEST_METHOD + ) + void userTest() { + // run code that needs the test data to be committed + // to the database outside of the test's transaction + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Test + @SqlGroup( + Sql("create-test-data.sql", + config = SqlConfig(transactionMode = ISOLATED)), + Sql("delete-test-data.sql", + config = SqlConfig(transactionMode = ISOLATED), + executionPhase = AFTER_TEST_METHOD)) + fun userTest() { + // run code that needs the test data to be committed + // to the database outside of the test's transaction + } +---- + +Note that `ISOLATED` and `AFTER_TEST_METHOD` are statically imported from +`Sql.TransactionMode` and `Sql.ExecutionPhase`, respectively. + +[[testcontext-executing-sql-declaratively-script-configuration]] +=== Script Configuration with `@SqlConfig` + +You can configure script parsing and error handling by using the `@SqlConfig` annotation. +When declared as a class-level annotation on an integration test class, `@SqlConfig` +serves as global configuration for all SQL scripts within the test class hierarchy. When +declared directly by using the `config` attribute of the `@Sql` annotation, `@SqlConfig` +serves as local configuration for the SQL scripts declared within the enclosing `@Sql` +annotation. Every attribute in `@SqlConfig` has an implicit default value, which is +documented in the javadoc of the corresponding attribute. Due to the rules defined for +annotation attributes in the Java Language Specification, it is, unfortunately, not +possible to assign a value of `null` to an annotation attribute. Thus, in order to +support overrides of inherited global configuration, `@SqlConfig` attributes have an +explicit default value of either `""` (for Strings), `{}` (for arrays), or `DEFAULT` (for +enumerations). This approach lets local declarations of `@SqlConfig` selectively override +individual attributes from global declarations of `@SqlConfig` by providing a value other +than `""`, `{}`, or `DEFAULT`. Global `@SqlConfig` attributes are inherited whenever +local `@SqlConfig` attributes do not supply an explicit value other than `""`, `{}`, or +`DEFAULT`. Explicit local configuration, therefore, overrides global configuration. + +The configuration options provided by `@Sql` and `@SqlConfig` are equivalent to those +supported by `ScriptUtils` and `ResourceDatabasePopulator` but are a superset of those +provided by the `<jdbc:initialize-database/>` XML namespace element. See the javadoc of +individual attributes in {api-spring-framework}/test/context/jdbc/Sql.html[`@Sql`] and +{api-spring-framework}/test/context/jdbc/SqlConfig.html[`@SqlConfig`] for details. + +[[testcontext-executing-sql-declaratively-tx]] +*Transaction management for `@Sql`* + +By default, the `SqlScriptsTestExecutionListener` infers the desired transaction +semantics for scripts configured by using `@Sql`. Specifically, SQL scripts are run +without a transaction, within an existing Spring-managed transaction (for example, a +transaction managed by the `TransactionalTestExecutionListener` for a test annotated with +`@Transactional`), or within an isolated transaction, depending on the configured value +of the `transactionMode` attribute in `@SqlConfig` and the presence of a +`PlatformTransactionManager` in the test's `ApplicationContext`. As a bare minimum, +however, a `javax.sql.DataSource` must be present in the test's `ApplicationContext`. + +If the algorithms used by `SqlScriptsTestExecutionListener` to detect a `DataSource` and +`PlatformTransactionManager` and infer the transaction semantics do not suit your needs, +you can specify explicit names by setting the `dataSource` and `transactionManager` +attributes of `@SqlConfig`. Furthermore, you can control the transaction propagation +behavior by setting the `transactionMode` attribute of `@SqlConfig` (for example, whether +scripts should be run in an isolated transaction). Although a thorough discussion of all +supported options for transaction management with `@Sql` is beyond the scope of this +reference manual, the javadoc for +{api-spring-framework}/test/context/jdbc/SqlConfig.html[`@SqlConfig`] and +{api-spring-framework}/test/context/jdbc/SqlScriptsTestExecutionListener.html[`SqlScriptsTestExecutionListener`] +provide detailed information, and the following example shows a typical testing scenario +that uses JUnit Jupiter and transactional tests with `@Sql`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestDatabaseConfig.class) + @Transactional + class TransactionalSqlScriptsTests { + + final JdbcTemplate jdbcTemplate; + + @Autowired + TransactionalSqlScriptsTests(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + @Test + @Sql("/test-data.sql") + void usersTest() { + // verify state in test database: + assertNumUsers(2); + // run code that uses the test data... + } + + int countRowsInTable(String tableName) { + return JdbcTestUtils.countRowsInTable(this.jdbcTemplate, tableName); + } + + void assertNumUsers(int expected) { + assertEquals(expected, countRowsInTable("user"), + "Number of rows in the [user] table."); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestDatabaseConfig::class) + @Transactional + class TransactionalSqlScriptsTests @Autowired constructor(dataSource: DataSource) { + + val jdbcTemplate: JdbcTemplate = JdbcTemplate(dataSource) + + @Test + @Sql("/test-data.sql") + fun usersTest() { + // verify state in test database: + assertNumUsers(2) + // run code that uses the test data... + } + + fun countRowsInTable(tableName: String): Int { + return JdbcTestUtils.countRowsInTable(jdbcTemplate, tableName) + } + + fun assertNumUsers(expected: Int) { + assertEquals(expected, countRowsInTable("user"), + "Number of rows in the [user] table.") + } + } +---- + +Note that there is no need to clean up the database after the `usersTest()` method is +run, since any changes made to the database (either within the test method or within the +`/test-data.sql` script) are automatically rolled back by the +`TransactionalTestExecutionListener` (see <<testcontext-tx,transaction management>> for +details). + +[[testcontext-executing-sql-declaratively-script-merging]] +=== Merging and Overriding Configuration with `@SqlMergeMode` + +As of Spring Framework 5.2, it is possible to merge method-level `@Sql` declarations with +class-level declarations. For example, this allows you to provide the configuration for a +database schema or some common test data once per test class and then provide additional, +use case specific test data per test method. To enable `@Sql` merging, annotate either +your test class or test method with `@SqlMergeMode(MERGE)`. To disable merging for a +specific test method (or specific test subclass), you can switch back to the default mode +via `@SqlMergeMode(OVERRIDE)`. Consult the <<spring-testing-annotation-sqlmergemode, +`@SqlMergeMode` annotation documentation section>> for examples and further details. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc new file mode 100644 index 000000000000..e42242d68b79 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc @@ -0,0 +1,215 @@ +[[testcontext-fixture-di]] += Dependency Injection of Test Fixtures + +When you use the `DependencyInjectionTestExecutionListener` (which is configured by +default), the dependencies of your test instances are injected from beans in the +application context that you configured with `@ContextConfiguration` or related +annotations. You may use setter injection, field injection, or both, depending on +which annotations you choose and whether you place them on setter methods or fields. +If you are using JUnit Jupiter you may also optionally use constructor injection +(see <<testcontext-junit-jupiter-di>>). For consistency with Spring's annotation-based +injection support, you may also use Spring's `@Autowired` annotation or the `@Inject` +annotation from JSR-330 for field and setter injection. + +TIP: For testing frameworks other than JUnit Jupiter, the TestContext framework does not +participate in instantiation of the test class. Thus, the use of `@Autowired` or +`@Inject` for constructors has no effect for test classes. + +NOTE: Although field injection is discouraged in production code, field injection is +actually quite natural in test code. The rationale for the difference is that you will +never instantiate your test class directly. Consequently, there is no need to be able to +invoke a `public` constructor or setter method on your test class. + +Because `@Autowired` is used to perform <<core.adoc#beans-factory-autowire, autowiring by +type>>, if you have multiple bean definitions of the same type, you cannot rely on this +approach for those particular beans. In that case, you can use `@Autowired` in +conjunction with `@Qualifier`. You can also choose to use `@Inject` in conjunction with +`@Named`. Alternatively, if your test class has access to its `ApplicationContext`, you +can perform an explicit lookup by using (for example) a call to +`applicationContext.getBean("titleRepository", TitleRepository.class)`. + +If you do not want dependency injection applied to your test instances, do not annotate +fields or setter methods with `@Autowired` or `@Inject`. Alternatively, you can disable +dependency injection altogether by explicitly configuring your class with +`@TestExecutionListeners` and omitting `DependencyInjectionTestExecutionListener.class` +from the list of listeners. + +Consider the scenario of testing a `HibernateTitleRepository` class, as outlined in the +<<integration-testing-goals, Goals>> section. The next two code listings demonstrate the +use of `@Autowired` on fields and setter methods. The application context configuration +is presented after all sample code listings. + +[NOTE] +==== +The dependency injection behavior in the following code listings is not specific to JUnit +Jupiter. The same DI techniques can be used in conjunction with any supported testing +framework. + +The following examples make calls to static assertion methods, such as `assertNotNull()`, +but without prepending the call with `Assertions`. In such cases, assume that the method +was properly imported through an `import static` declaration that is not shown in the +example. +==== + +The first code listing shows a JUnit Jupiter based implementation of the test class that +uses `@Autowired` for field injection: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // specifies the Spring configuration to load for this test fixture + @ContextConfiguration("repository-config.xml") + class HibernateTitleRepositoryTests { + + // this instance will be dependency injected by type + @Autowired + HibernateTitleRepository titleRepository; + + @Test + void findById() { + Title title = titleRepository.findById(new Long(10)); + assertNotNull(title); + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // specifies the Spring configuration to load for this test fixture + @ContextConfiguration("repository-config.xml") + class HibernateTitleRepositoryTests { + + // this instance will be dependency injected by type + @Autowired + lateinit var titleRepository: HibernateTitleRepository + + @Test + fun findById() { + val title = titleRepository.findById(10) + assertNotNull(title) + } + } +---- + +Alternatively, you can configure the class to use `@Autowired` for setter injection, as +follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExtendWith(SpringExtension.class) + // specifies the Spring configuration to load for this test fixture + @ContextConfiguration("repository-config.xml") + class HibernateTitleRepositoryTests { + + // this instance will be dependency injected by type + HibernateTitleRepository titleRepository; + + @Autowired + void setTitleRepository(HibernateTitleRepository titleRepository) { + this.titleRepository = titleRepository; + } + + @Test + void findById() { + Title title = titleRepository.findById(new Long(10)); + assertNotNull(title); + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExtendWith(SpringExtension::class) + // specifies the Spring configuration to load for this test fixture + @ContextConfiguration("repository-config.xml") + class HibernateTitleRepositoryTests { + + // this instance will be dependency injected by type + lateinit var titleRepository: HibernateTitleRepository + + @Autowired + fun setTitleRepository(titleRepository: HibernateTitleRepository) { + this.titleRepository = titleRepository + } + + @Test + fun findById() { + val title = titleRepository.findById(10) + assertNotNull(title) + } + } +---- + +The preceding code listings use the same XML context file referenced by the +`@ContextConfiguration` annotation (that is, `repository-config.xml`). The following +shows this configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <?xml version="1.0" encoding="UTF-8"?> + <beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.springframework.org/schema/beans + https://www.springframework.org/schema/beans/spring-beans.xsd"> + + <!-- this bean will be injected into the HibernateTitleRepositoryTests class --> + <bean id="titleRepository" class="com.foo.repository.hibernate.HibernateTitleRepository"> + <property name="sessionFactory" ref="sessionFactory"/> + </bean> + + <bean id="sessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactoryBean"> + <!-- configuration elided for brevity --> + </bean> + + </beans> +---- + +[NOTE] +===== +If you are extending from a Spring-provided test base class that happens to use +`@Autowired` on one of its setter methods, you might have multiple beans of the affected +type defined in your application context (for example, multiple `DataSource` beans). In +such a case, you can override the setter method and use the `@Qualifier` annotation to +indicate a specific target bean, as follows (but make sure to delegate to the overridden +method in the superclass as well): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // ... + + @Autowired + @Override + public void setDataSource(@Qualifier("myDataSource") DataSource dataSource) { + super.setDataSource(dataSource); + } + + // ... +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // ... + + @Autowired + override fun setDataSource(@Qualifier("myDataSource") dataSource: DataSource) { + super.setDataSource(dataSource) + } + + // ... +---- + +The specified qualifier value indicates the specific `DataSource` bean to inject, +narrowing the set of type matches to a specific bean. Its value is matched against +`<qualifier>` declarations within the corresponding `<bean>` definitions. The bean name +is used as a fallback qualifier value, so you can effectively also point to a specific +bean by name there (as shown earlier, assuming that `myDataSource` is the bean `id`). +===== + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc new file mode 100644 index 000000000000..7a360139104f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc @@ -0,0 +1,86 @@ +[[testcontext-key-abstractions]] += Key Abstractions + +The core of the framework consists of the `TestContextManager` class and the +`TestContext`, `TestExecutionListener`, and `SmartContextLoader` interfaces. A +`TestContextManager` is created for each test class (for example, for the execution of +all test methods within a single test class in JUnit Jupiter). The `TestContextManager`, +in turn, manages a `TestContext` that holds the context of the current test. The +`TestContextManager` also updates the state of the `TestContext` as the test progresses +and delegates to `TestExecutionListener` implementations, which instrument the actual +test execution by providing dependency injection, managing transactions, and so on. A +`SmartContextLoader` is responsible for loading an `ApplicationContext` for a given test +class. See the {api-spring-framework}/test/context/package-summary.html[javadoc] and the +Spring test suite for further information and examples of various implementations. + +[[testcontext]] +== `TestContext` + +`TestContext` encapsulates the context in which a test is run (agnostic of the +actual testing framework in use) and provides context management and caching support for +the test instance for which it is responsible. The `TestContext` also delegates to a +`SmartContextLoader` to load an `ApplicationContext` if requested. + +[[testcontextmanager]] +== `TestContextManager` + +`TestContextManager` is the main entry point into the Spring TestContext Framework and is +responsible for managing a single `TestContext` and signaling events to each registered +`TestExecutionListener` at well-defined test execution points: + +* Prior to any "`before class`" or "`before all`" methods of a particular testing framework. +* Test instance post-processing. +* Prior to any "`before`" or "`before each`" methods of a particular testing framework. +* Immediately before execution of the test method but after test setup. +* Immediately after execution of the test method but before test tear down. +* After any "`after`" or "`after each`" methods of a particular testing framework. +* After any "`after class`" or "`after all`" methods of a particular testing framework. + +[[testexecutionlistener]] +== `TestExecutionListener` + +`TestExecutionListener` defines the API for reacting to test-execution events published by +the `TestContextManager` with which the listener is registered. See <<testcontext-tel-config>>. + +[[context-loaders]] +== Context Loaders + +`ContextLoader` is a strategy interface for loading an `ApplicationContext` for an +integration test managed by the Spring TestContext Framework. You should implement +`SmartContextLoader` instead of this interface to provide support for component classes, +active bean definition profiles, test property sources, context hierarchies, and +`WebApplicationContext` support. + +`SmartContextLoader` is an extension of the `ContextLoader` interface that supersedes the +original minimal `ContextLoader` SPI. Specifically, a `SmartContextLoader` can choose to +process resource locations, component classes, or context initializers. Furthermore, a +`SmartContextLoader` can set active bean definition profiles and test property sources in +the context that it loads. + +Spring provides the following implementations: + +* `DelegatingSmartContextLoader`: One of two default loaders, it delegates internally to + an `AnnotationConfigContextLoader`, a `GenericXmlContextLoader`, or a + `GenericGroovyXmlContextLoader`, depending either on the configuration declared for the + test class or on the presence of default locations or default configuration classes. + Groovy support is enabled only if Groovy is on the classpath. +* `WebDelegatingSmartContextLoader`: One of two default loaders, it delegates internally + to an `AnnotationConfigWebContextLoader`, a `GenericXmlWebContextLoader`, or a + `GenericGroovyXmlWebContextLoader`, depending either on the configuration declared for + the test class or on the presence of default locations or default configuration + classes. A web `ContextLoader` is used only if `@WebAppConfiguration` is present on the + test class. Groovy support is enabled only if Groovy is on the classpath. +* `AnnotationConfigContextLoader`: Loads a standard `ApplicationContext` from component + classes. +* `AnnotationConfigWebContextLoader`: Loads a `WebApplicationContext` from component + classes. +* `GenericGroovyXmlContextLoader`: Loads a standard `ApplicationContext` from resource + locations that are either Groovy scripts or XML configuration files. +* `GenericGroovyXmlWebContextLoader`: Loads a `WebApplicationContext` from resource + locations that are either Groovy scripts or XML configuration files. +* `GenericXmlContextLoader`: Loads a standard `ApplicationContext` from XML resource + locations. +* `GenericXmlWebContextLoader`: Loads a `WebApplicationContext` from XML resource + locations. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc new file mode 100644 index 000000000000..dfa8b13add10 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc @@ -0,0 +1,48 @@ +[[testcontext-parallel-test-execution]] += Parallel Test Execution + +Spring Framework 5.0 introduced basic support for executing tests in parallel within a +single JVM when using the Spring TestContext Framework. In general, this means that most +test classes or test methods can be run in parallel without any changes to test code +or configuration. + +TIP: For details on how to set up parallel test execution, see the documentation for your +testing framework, build tool, or IDE. + +Keep in mind that the introduction of concurrency into your test suite can result in +unexpected side effects, strange runtime behavior, and tests that fail intermittently or +seemingly randomly. The Spring Team therefore provides the following general guidelines +for when not to run tests in parallel. + +Do not run tests in parallel if the tests: + +* Use Spring Framework's `@DirtiesContext` support. +* Use Spring Boot's `@MockBean` or `@SpyBean` support. +* Use JUnit 4's `@FixMethodOrder` support or any testing framework feature + that is designed to ensure that test methods run in a particular order. Note, + however, that this does not apply if entire test classes are run in parallel. +* Change the state of shared services or systems such as a database, message broker, + filesystem, and others. This applies to both embedded and external systems. + +[TIP] +==== +If parallel test execution fails with an exception stating that the `ApplicationContext` +for the current test is no longer active, this typically means that the +`ApplicationContext` was removed from the `ContextCache` in a different thread. + +This may be due to the use of `@DirtiesContext` or due to automatic eviction from the +`ContextCache`. If `@DirtiesContext` is the culprit, you either need to find a way to +avoid using `@DirtiesContext` or exclude such tests from parallel execution. If the +maximum size of the `ContextCache` has been exceeded, you can increase the maximum size +of the cache. See the discussion on <<testcontext-ctx-management-caching, context caching>> +for details. +==== + +WARNING: Parallel test execution in the Spring TestContext Framework is only possible if +the underlying `TestContext` implementation provides a copy constructor, as explained in +the javadoc for {api-spring-framework}/test/context/TestContext.html[`TestContext`]. The +`DefaultTestContext` used in Spring provides such a constructor. However, if you use a +third-party library that provides a custom `TestContext` implementation, you need to +verify that it is suitable for parallel test execution. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc new file mode 100644 index 000000000000..543ee423e1f1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc @@ -0,0 +1,609 @@ +[[testcontext-support-classes]] += TestContext Framework Support Classes + +This section describes the various classes that support the Spring TestContext Framework. + +[[testcontext-junit4-runner]] +== Spring JUnit 4 Runner + +The Spring TestContext Framework offers full integration with JUnit 4 through a custom +runner (supported on JUnit 4.12 or higher). By annotating test classes with +`@RunWith(SpringJUnit4ClassRunner.class)` or the shorter `@RunWith(SpringRunner.class)` +variant, developers can implement standard JUnit 4-based unit and integration tests and +simultaneously reap the benefits of the TestContext framework, such as support for +loading application contexts, dependency injection of test instances, transactional test +method execution, and so on. If you want to use the Spring TestContext Framework with an +alternative runner (such as JUnit 4's `Parameterized` runner) or third-party runners +(such as the `MockitoJUnitRunner`), you can, optionally, use +<<testcontext-junit4-rules, Spring's support for JUnit rules>> instead. + +The following code listing shows the minimal requirements for configuring a test class to +run with the custom Spring `Runner`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RunWith(SpringRunner.class) + @TestExecutionListeners({}) + public class SimpleTest { + + @Test + public void testMethod() { + // test logic... + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RunWith(SpringRunner::class) + @TestExecutionListeners + class SimpleTest { + + @Test + fun testMethod() { + // test logic... + } + } +---- + +In the preceding example, `@TestExecutionListeners` is configured with an empty list, to +disable the default listeners, which otherwise would require an `ApplicationContext` to +be configured through `@ContextConfiguration`. + +[[testcontext-junit4-rules]] +== Spring JUnit 4 Rules + +The `org.springframework.test.context.junit4.rules` package provides the following JUnit +4 rules (supported on JUnit 4.12 or higher): + +* `SpringClassRule` +* `SpringMethodRule` + +`SpringClassRule` is a JUnit `TestRule` that supports class-level features of the Spring +TestContext Framework, whereas `SpringMethodRule` is a JUnit `MethodRule` that supports +instance-level and method-level features of the Spring TestContext Framework. + +In contrast to the `SpringRunner`, Spring's rule-based JUnit support has the advantage of +being independent of any `org.junit.runner.Runner` implementation and can, therefore, be +combined with existing alternative runners (such as JUnit 4's `Parameterized`) or +third-party runners (such as the `MockitoJUnitRunner`). + +To support the full functionality of the TestContext framework, you must combine a +`SpringClassRule` with a `SpringMethodRule`. The following example shows the proper way +to declare these rules in an integration test: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Optionally specify a non-Spring Runner via @RunWith(...) + @ContextConfiguration + public class IntegrationTest { + + @ClassRule + public static final SpringClassRule springClassRule = new SpringClassRule(); + + @Rule + public final SpringMethodRule springMethodRule = new SpringMethodRule(); + + @Test + public void testMethod() { + // test logic... + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Optionally specify a non-Spring Runner via @RunWith(...) + @ContextConfiguration + class IntegrationTest { + + @Rule + val springMethodRule = SpringMethodRule() + + @Test + fun testMethod() { + // test logic... + } + + companion object { + @ClassRule + val springClassRule = SpringClassRule() + } + } +---- + +[[testcontext-support-classes-junit4]] +== JUnit 4 Support Classes + +The `org.springframework.test.context.junit4` package provides the following support +classes for JUnit 4-based test cases (supported on JUnit 4.12 or higher): + +* `AbstractJUnit4SpringContextTests` +* `AbstractTransactionalJUnit4SpringContextTests` + +`AbstractJUnit4SpringContextTests` is an abstract base test class that integrates the +Spring TestContext Framework with explicit `ApplicationContext` testing support in a +JUnit 4 environment. When you extend `AbstractJUnit4SpringContextTests`, you can access a +`protected` `applicationContext` instance variable that you can use to perform explicit +bean lookups or to test the state of the context as a whole. + +`AbstractTransactionalJUnit4SpringContextTests` is an abstract transactional extension of +`AbstractJUnit4SpringContextTests` that adds some convenience functionality for JDBC +access. This class expects a `javax.sql.DataSource` bean and a +`PlatformTransactionManager` bean to be defined in the `ApplicationContext`. When you +extend `AbstractTransactionalJUnit4SpringContextTests`, you can access a `protected` +`jdbcTemplate` instance variable that you can use to run SQL statements to query the +database. You can use such queries to confirm database state both before and after +running database-related application code, and Spring ensures that such queries run in +the scope of the same transaction as the application code. When used in conjunction with +an ORM tool, be sure to avoid <<testcontext-tx-false-positives, false positives>>. +As mentioned in <<integration-testing-support-jdbc>>, +`AbstractTransactionalJUnit4SpringContextTests` also provides convenience methods that +delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`. +Furthermore, `AbstractTransactionalJUnit4SpringContextTests` provides an +`executeSqlScript(..)` method for running SQL scripts against the configured `DataSource`. + +TIP: These classes are a convenience for extension. If you do not want your test classes +to be tied to a Spring-specific class hierarchy, you can configure your own custom test +classes by using `@RunWith(SpringRunner.class)` or <<testcontext-junit4-rules, Spring's +JUnit rules>>. + +[[testcontext-junit-jupiter-extension]] +== SpringExtension for JUnit Jupiter + +The Spring TestContext Framework offers full integration with the JUnit Jupiter testing +framework, introduced in JUnit 5. By annotating test classes with +`@ExtendWith(SpringExtension.class)`, you can implement standard JUnit Jupiter-based unit +and integration tests and simultaneously reap the benefits of the TestContext framework, +such as support for loading application contexts, dependency injection of test instances, +transactional test method execution, and so on. + +Furthermore, thanks to the rich extension API in JUnit Jupiter, Spring provides the +following features above and beyond the feature set that Spring supports for JUnit 4 and +TestNG: + +* Dependency injection for test constructors, test methods, and test lifecycle callback + methods. See <<testcontext-junit-jupiter-di>> for further details. +* Powerful support for link:https://junit.org/junit5/docs/current/user-guide/#extensions-conditions[conditional + test execution] based on SpEL expressions, environment variables, system properties, + and so on. See the documentation for `@EnabledIf` and `@DisabledIf` in + <<integration-testing-annotations-junit-jupiter>> for further details and examples. +* Custom composed annotations that combine annotations from Spring and JUnit Jupiter. See + the `@TransactionalDevTestConfig` and `@TransactionalIntegrationTest` examples in + <<integration-testing-annotations-meta>> for further details. + +The following code listing shows how to configure a test class to use the +`SpringExtension` in conjunction with `@ContextConfiguration`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Instructs JUnit Jupiter to extend the test with Spring support. + @ExtendWith(SpringExtension.class) + // Instructs Spring to load an ApplicationContext from TestConfig.class + @ContextConfiguration(classes = TestConfig.class) + class SimpleTests { + + @Test + void testMethod() { + // test logic... + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Instructs JUnit Jupiter to extend the test with Spring support. + @ExtendWith(SpringExtension::class) + // Instructs Spring to load an ApplicationContext from TestConfig::class + @ContextConfiguration(classes = [TestConfig::class]) + class SimpleTests { + + @Test + fun testMethod() { + // test logic... + } + } +---- + +Since you can also use annotations in JUnit 5 as meta-annotations, Spring provides the +`@SpringJUnitConfig` and `@SpringJUnitWebConfig` composed annotations to simplify the +configuration of the test `ApplicationContext` and JUnit Jupiter. + +The following example uses `@SpringJUnitConfig` to reduce the amount of configuration +used in the previous example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Instructs Spring to register the SpringExtension with JUnit + // Jupiter and load an ApplicationContext from TestConfig.class + @SpringJUnitConfig(TestConfig.class) + class SimpleTests { + + @Test + void testMethod() { + // test logic... + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Instructs Spring to register the SpringExtension with JUnit + // Jupiter and load an ApplicationContext from TestConfig.class + @SpringJUnitConfig(TestConfig::class) + class SimpleTests { + + @Test + fun testMethod() { + // test logic... + } + } +---- + +Similarly, the following example uses `@SpringJUnitWebConfig` to create a +`WebApplicationContext` for use with JUnit Jupiter: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Instructs Spring to register the SpringExtension with JUnit + // Jupiter and load a WebApplicationContext from TestWebConfig.class + @SpringJUnitWebConfig(TestWebConfig.class) + class SimpleWebTests { + + @Test + void testMethod() { + // test logic... + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Instructs Spring to register the SpringExtension with JUnit + // Jupiter and load a WebApplicationContext from TestWebConfig::class + @SpringJUnitWebConfig(TestWebConfig::class) + class SimpleWebTests { + + @Test + fun testMethod() { + // test logic... + } + } +---- + +See the documentation for `@SpringJUnitConfig` and `@SpringJUnitWebConfig` in +<<integration-testing-annotations-junit-jupiter>> for further details. + +[[testcontext-junit-jupiter-di]] +=== Dependency Injection with `SpringExtension` + +`SpringExtension` implements the +link:https://junit.org/junit5/docs/current/user-guide/#extensions-parameter-resolution[`ParameterResolver`] +extension API from JUnit Jupiter, which lets Spring provide dependency injection for test +constructors, test methods, and test lifecycle callback methods. + +Specifically, `SpringExtension` can inject dependencies from the test's +`ApplicationContext` into test constructors and methods that are annotated with +`@BeforeAll`, `@AfterAll`, `@BeforeEach`, `@AfterEach`, `@Test`, `@RepeatedTest`, +`@ParameterizedTest`, and others. + +[[testcontext-junit-jupiter-di-constructor]] +==== Constructor Injection + +If a specific parameter in a constructor for a JUnit Jupiter test class is of type +`ApplicationContext` (or a sub-type thereof) or is annotated or meta-annotated with +`@Autowired`, `@Qualifier`, or `@Value`, Spring injects the value for that specific +parameter with the corresponding bean or value from the test's `ApplicationContext`. + +Spring can also be configured to autowire all arguments for a test class constructor if +the constructor is considered to be _autowirable_. A constructor is considered to be +autowirable if one of the following conditions is met (in order of precedence). + +* The constructor is annotated with `@Autowired`. +* `@TestConstructor` is present or meta-present on the test class with the `autowireMode` + attribute set to `ALL`. +* The default _test constructor autowire mode_ has been changed to `ALL`. + +See <<integration-testing-annotations-testconstructor>> for details on the use of +`@TestConstructor` and how to change the global _test constructor autowire mode_. + +WARNING: If the constructor for a test class is considered to be _autowirable_, Spring +assumes the responsibility for resolving arguments for all parameters in the constructor. +Consequently, no other `ParameterResolver` registered with JUnit Jupiter can resolve +parameters for such a constructor. + +[WARNING] +==== +Constructor injection for test classes must not be used in conjunction with JUnit +Jupiter's `@TestInstance(PER_CLASS)` support if `@DirtiesContext` is used to close the +test's `ApplicationContext` before or after test methods. + +The reason is that `@TestInstance(PER_CLASS)` instructs JUnit Jupiter to cache the test +instance between test method invocations. Consequently, the test instance will retain +references to beans that were originally injected from an `ApplicationContext` that has +been subsequently closed. Since the constructor for the test class will only be invoked +once in such scenarios, dependency injection will not occur again, and subsequent tests +will interact with beans from the closed `ApplicationContext` which may result in errors. + +To use `@DirtiesContext` with "before test method" or "after test method" modes in +conjunction with `@TestInstance(PER_CLASS)`, one must configure dependencies from Spring +to be supplied via field or setter injection so that they can be re-injected between test +method invocations. +==== + +In the following example, Spring injects the `OrderService` bean from the +`ApplicationContext` loaded from `TestConfig.class` into the +`OrderServiceIntegrationTests` constructor. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestConfig.class) + class OrderServiceIntegrationTests { + + private final OrderService orderService; + + @Autowired + OrderServiceIntegrationTests(OrderService orderService) { + this.orderService = orderService; + } + + // tests that use the injected OrderService + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestConfig::class) + class OrderServiceIntegrationTests @Autowired constructor(private val orderService: OrderService){ + // tests that use the injected OrderService + } + +---- + +Note that this feature lets test dependencies be `final` and therefore immutable. + +If the `spring.test.constructor.autowire.mode` property is to `all` (see +<<integration-testing-annotations-testconstructor>>), we can omit the declaration of +`@Autowired` on the constructor in the previous example, resulting in the following. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestConfig.class) + class OrderServiceIntegrationTests { + + private final OrderService orderService; + + OrderServiceIntegrationTests(OrderService orderService) { + this.orderService = orderService; + } + + // tests that use the injected OrderService + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestConfig::class) + class OrderServiceIntegrationTests(val orderService:OrderService) { + // tests that use the injected OrderService + } +---- + +[[testcontext-junit-jupiter-di-method]] +==== Method Injection + +If a parameter in a JUnit Jupiter test method or test lifecycle callback method is of +type `ApplicationContext` (or a sub-type thereof) or is annotated or meta-annotated with +`@Autowired`, `@Qualifier`, or `@Value`, Spring injects the value for that specific +parameter with the corresponding bean from the test's `ApplicationContext`. + +In the following example, Spring injects the `OrderService` from the `ApplicationContext` +loaded from `TestConfig.class` into the `deleteOrder()` test method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestConfig.class) + class OrderServiceIntegrationTests { + + @Test + void deleteOrder(@Autowired OrderService orderService) { + // use orderService from the test's ApplicationContext + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestConfig::class) + class OrderServiceIntegrationTests { + + @Test + fun deleteOrder(@Autowired orderService: OrderService) { + // use orderService from the test's ApplicationContext + } + } +---- + +Due to the robustness of the `ParameterResolver` support in JUnit Jupiter, you can also +have multiple dependencies injected into a single method, not only from Spring but also +from JUnit Jupiter itself or other third-party extensions. + +The following example shows how to have both Spring and JUnit Jupiter inject dependencies +into the `placeOrderRepeatedly()` test method simultaneously. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestConfig.class) + class OrderServiceIntegrationTests { + + @RepeatedTest(10) + void placeOrderRepeatedly(RepetitionInfo repetitionInfo, + @Autowired OrderService orderService) { + + // use orderService from the test's ApplicationContext + // and repetitionInfo from JUnit Jupiter + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestConfig::class) + class OrderServiceIntegrationTests { + + @RepeatedTest(10) + fun placeOrderRepeatedly(repetitionInfo:RepetitionInfo, @Autowired orderService:OrderService) { + + // use orderService from the test's ApplicationContext + // and repetitionInfo from JUnit Jupiter + } + } +---- + +Note that the use of `@RepeatedTest` from JUnit Jupiter lets the test method gain access +to the `RepetitionInfo`. + +[[testcontext-junit-jupiter-nested-test-configuration]] +=== `@Nested` test class configuration + +The _Spring TestContext Framework_ has supported the use of test-related annotations on +`@Nested` test classes in JUnit Jupiter since Spring Framework 5.0; however, until Spring +Framework 5.3 class-level test configuration annotations were not _inherited_ from +enclosing classes like they are from superclasses. + +Spring Framework 5.3 introduces first-class support for inheriting test class +configuration from enclosing classes, and such configuration will be inherited by +default. To change from the default `INHERIT` mode to `OVERRIDE` mode, you may annotate +an individual `@Nested` test class with +`@NestedTestConfiguration(EnclosingConfiguration.OVERRIDE)`. An explicit +`@NestedTestConfiguration` declaration will apply to the annotated test class as well as +any of its subclasses and nested classes. Thus, you may annotate a top-level test class +with `@NestedTestConfiguration`, and that will apply to all of its nested test classes +recursively. + +In order to allow development teams to change the default to `OVERRIDE` – for example, +for compatibility with Spring Framework 5.0 through 5.2 – the default mode can be changed +globally via a JVM system property or a `spring.properties` file in the root of the +classpath. See the <<integration-testing-annotations-nestedtestconfiguration, "Changing +the default enclosing configuration inheritance mode">> note for details. + +Although the following "Hello World" example is very simplistic, it shows how to declare +common configuration on a top-level class that is inherited by its `@Nested` test +classes. In this particular example, only the `TestConfig` configuration class is +inherited. Each nested test class provides its own set of active profiles, resulting in a +distinct `ApplicationContext` for each nested test class (see +<<testcontext-ctx-management-caching>> for details). Consult the list of +<<integration-testing-annotations-nestedtestconfiguration, supported annotations>> to see +which annotations can be inherited in `@Nested` test classes. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestConfig.class) + class GreetingServiceTests { + + @Nested + @ActiveProfiles("lang_en") + class EnglishGreetings { + + @Test + void hello(@Autowired GreetingService service) { + assertThat(service.greetWorld()).isEqualTo("Hello World"); + } + } + + @Nested + @ActiveProfiles("lang_de") + class GermanGreetings { + + @Test + void hello(@Autowired GreetingService service) { + assertThat(service.greetWorld()).isEqualTo("Hallo Welt"); + } + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestConfig::class) + class GreetingServiceTests { + + @Nested + @ActiveProfiles("lang_en") + inner class EnglishGreetings { + + @Test + fun hello(@Autowired service:GreetingService) { + assertThat(service.greetWorld()).isEqualTo("Hello World") + } + } + + @Nested + @ActiveProfiles("lang_de") + inner class GermanGreetings { + + @Test + fun hello(@Autowired service:GreetingService) { + assertThat(service.greetWorld()).isEqualTo("Hallo Welt") + } + } + } +---- + +[[testcontext-support-classes-testng]] +== TestNG Support Classes + +The `org.springframework.test.context.testng` package provides the following support +classes for TestNG based test cases: + +* `AbstractTestNGSpringContextTests` +* `AbstractTransactionalTestNGSpringContextTests` + +`AbstractTestNGSpringContextTests` is an abstract base test class that integrates the +Spring TestContext Framework with explicit `ApplicationContext` testing support in a +TestNG environment. When you extend `AbstractTestNGSpringContextTests`, you can access a +`protected` `applicationContext` instance variable that you can use to perform explicit +bean lookups or to test the state of the context as a whole. + +`AbstractTransactionalTestNGSpringContextTests` is an abstract transactional extension of +`AbstractTestNGSpringContextTests` that adds some convenience functionality for JDBC +access. This class expects a `javax.sql.DataSource` bean and a +`PlatformTransactionManager` bean to be defined in the `ApplicationContext`. When you +extend `AbstractTransactionalTestNGSpringContextTests`, you can access a `protected` +`jdbcTemplate` instance variable that you can use to run SQL statements to query the +database. You can use such queries to confirm database state both before and after +running database-related application code, and Spring ensures that such queries run in +the scope of the same transaction as the application code. When used in conjunction with +an ORM tool, be sure to avoid <<testcontext-tx-false-positives, false positives>>. +As mentioned in <<integration-testing-support-jdbc>>, +`AbstractTransactionalTestNGSpringContextTests` also provides convenience methods that +delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`. +Furthermore, `AbstractTransactionalTestNGSpringContextTests` provides an +`executeSqlScript(..)` method for running SQL scripts against the configured `DataSource`. + +TIP: These classes are a convenience for extension. If you do not want your test classes +to be tied to a Spring-specific class hierarchy, you can configure your own custom test +classes by using `@ContextConfiguration`, `@TestExecutionListeners`, and so on and by +manually instrumenting your test class with a `TestContextManager`. See the source code +of `AbstractTestNGSpringContextTests` for an example of how to instrument your test class. + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc new file mode 100644 index 000000000000..cb6856f261b1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc @@ -0,0 +1,192 @@ +[[testcontext-tel-config]] += `TestExecutionListener` Configuration + +Spring provides the following `TestExecutionListener` implementations that are registered +by default, exactly in the following order: + +* `ServletTestExecutionListener`: Configures Servlet API mocks for a + `WebApplicationContext`. +* `DirtiesContextBeforeModesTestExecutionListener`: Handles the `@DirtiesContext` + annotation for "`before`" modes. +* `ApplicationEventsTestExecutionListener`: Provides support for + <<testcontext-application-events, `ApplicationEvents`>>. +* `DependencyInjectionTestExecutionListener`: Provides dependency injection for the test + instance. +* `DirtiesContextTestExecutionListener`: Handles the `@DirtiesContext` annotation for + "`after`" modes. +* `TransactionalTestExecutionListener`: Provides transactional test execution with + default rollback semantics. +* `SqlScriptsTestExecutionListener`: Runs SQL scripts configured by using the `@Sql` + annotation. +* `EventPublishingTestExecutionListener`: Publishes test execution events to the test's + `ApplicationContext` (see <<testcontext-test-execution-events>>). + +[[testcontext-tel-config-registering-tels]] +== Registering `TestExecutionListener` Implementations + +You can register `TestExecutionListener` implementations explicitly for a test class, its +subclasses, and its nested classes by using the `@TestExecutionListeners` annotation. See +<<integration-testing-annotations, annotation support>> and the javadoc for +{api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners`] +for details and examples. + +.Switching to default `TestExecutionListener` implementations +[NOTE] +==== +If you extend a class that is annotated with `@TestExecutionListeners` and you need to +switch to using the default set of listeners, you can annotate your class with the +following. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Switch to default listeners + @TestExecutionListeners( + listeners = {}, + inheritListeners = false, + mergeMode = MERGE_WITH_DEFAULTS) + class MyTest extends BaseTest { + // class body... + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Switch to default listeners + @TestExecutionListeners( + listeners = [], + inheritListeners = false, + mergeMode = MERGE_WITH_DEFAULTS) + class MyTest : BaseTest { + // class body... + } +---- +==== + +[[testcontext-tel-config-automatic-discovery]] +== Automatic Discovery of Default `TestExecutionListener` Implementations + +Registering `TestExecutionListener` implementations by using `@TestExecutionListeners` is +suitable for custom listeners that are used in limited testing scenarios. However, it can +become cumbersome if a custom listener needs to be used across an entire test suite. This +issue is addressed through support for automatic discovery of default +`TestExecutionListener` implementations through the `SpringFactoriesLoader` mechanism. + +Specifically, the `spring-test` module declares all core default `TestExecutionListener` +implementations under the `org.springframework.test.context.TestExecutionListener` key in +its `META-INF/spring.factories` properties file. Third-party frameworks and developers +can contribute their own `TestExecutionListener` implementations to the list of default +listeners in the same manner through their own `META-INF/spring.factories` properties +file. + +[[testcontext-tel-config-ordering]] +== Ordering `TestExecutionListener` Implementations + +When the TestContext framework discovers default `TestExecutionListener` implementations +through the <<testcontext-tel-config-automatic-discovery, aforementioned>> +`SpringFactoriesLoader` mechanism, the instantiated listeners are sorted by using +Spring's `AnnotationAwareOrderComparator`, which honors Spring's `Ordered` interface and +`@Order` annotation for ordering. `AbstractTestExecutionListener` and all default +`TestExecutionListener` implementations provided by Spring implement `Ordered` with +appropriate values. Third-party frameworks and developers should therefore make sure that +their default `TestExecutionListener` implementations are registered in the proper order +by implementing `Ordered` or declaring `@Order`. See the javadoc for the `getOrder()` +methods of the core default `TestExecutionListener` implementations for details on what +values are assigned to each core listener. + +[[testcontext-tel-config-merging]] +== Merging `TestExecutionListener` Implementations + +If a custom `TestExecutionListener` is registered via `@TestExecutionListeners`, the +default listeners are not registered. In most common testing scenarios, this effectively +forces the developer to manually declare all default listeners in addition to any custom +listeners. The following listing demonstrates this style of configuration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @TestExecutionListeners({ + MyCustomTestExecutionListener.class, + ServletTestExecutionListener.class, + DirtiesContextBeforeModesTestExecutionListener.class, + DependencyInjectionTestExecutionListener.class, + DirtiesContextTestExecutionListener.class, + TransactionalTestExecutionListener.class, + SqlScriptsTestExecutionListener.class + }) + class MyTest { + // class body... + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @TestExecutionListeners( + MyCustomTestExecutionListener::class, + ServletTestExecutionListener::class, + DirtiesContextBeforeModesTestExecutionListener::class, + DependencyInjectionTestExecutionListener::class, + DirtiesContextTestExecutionListener::class, + TransactionalTestExecutionListener::class, + SqlScriptsTestExecutionListener::class + ) + class MyTest { + // class body... + } +---- + +The challenge with this approach is that it requires that the developer know exactly +which listeners are registered by default. Moreover, the set of default listeners can +change from release to release -- for example, `SqlScriptsTestExecutionListener` was +introduced in Spring Framework 4.1, and `DirtiesContextBeforeModesTestExecutionListener` +was introduced in Spring Framework 4.2. Furthermore, third-party frameworks like Spring +Boot and Spring Security register their own default `TestExecutionListener` +implementations by using the aforementioned <<testcontext-tel-config-automatic-discovery, +automatic discovery mechanism>>. + +To avoid having to be aware of and re-declare all default listeners, you can set the +`mergeMode` attribute of `@TestExecutionListeners` to `MergeMode.MERGE_WITH_DEFAULTS`. +`MERGE_WITH_DEFAULTS` indicates that locally declared listeners should be merged with the +default listeners. The merging algorithm ensures that duplicates are removed from the +list and that the resulting set of merged listeners is sorted according to the semantics +of `AnnotationAwareOrderComparator`, as described in <<testcontext-tel-config-ordering>>. +If a listener implements `Ordered` or is annotated with `@Order`, it can influence the +position in which it is merged with the defaults. Otherwise, locally declared listeners +are appended to the list of default listeners when merged. + +For example, if the `MyCustomTestExecutionListener` class in the previous example +configures its `order` value (for example, `500`) to be less than the order of the +`ServletTestExecutionListener` (which happens to be `1000`), the +`MyCustomTestExecutionListener` can then be automatically merged with the list of +defaults in front of the `ServletTestExecutionListener`, and the previous example could +be replaced with the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration + @TestExecutionListeners( + listeners = MyCustomTestExecutionListener.class, + mergeMode = MERGE_WITH_DEFAULTS + ) + class MyTest { + // class body... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration + @TestExecutionListeners( + listeners = [MyCustomTestExecutionListener::class], + mergeMode = MERGE_WITH_DEFAULTS + ) + class MyTest { + // class body... + } +---- + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc new file mode 100644 index 000000000000..73dda5f70c26 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc @@ -0,0 +1,88 @@ +[[testcontext-test-execution-events]] += Test Execution Events + +The `EventPublishingTestExecutionListener` introduced in Spring Framework 5.2 offers an +alternative approach to implementing a custom `TestExecutionListener`. Components in the +test's `ApplicationContext` can listen to the following events published by the +`EventPublishingTestExecutionListener`, each of which corresponds to a method in the +`TestExecutionListener` API. + +* `BeforeTestClassEvent` +* `PrepareTestInstanceEvent` +* `BeforeTestMethodEvent` +* `BeforeTestExecutionEvent` +* `AfterTestExecutionEvent` +* `AfterTestMethodEvent` +* `AfterTestClassEvent` + +These events may be consumed for various reasons, such as resetting mock beans or tracing +test execution. One advantage of consuming test execution events rather than implementing +a custom `TestExecutionListener` is that test execution events may be consumed by any +Spring bean registered in the test `ApplicationContext`, and such beans may benefit +directly from dependency injection and other features of the `ApplicationContext`. In +contrast, a `TestExecutionListener` is not a bean in the `ApplicationContext`. + +[NOTE] +==== +The `EventPublishingTestExecutionListener` is registered by default; however, it only +publishes events if the `ApplicationContext` has _already been loaded_. This prevents the +`ApplicationContext` from being loaded unnecessarily or too early. + +Consequently, a `BeforeTestClassEvent` will not be published until after the +`ApplicationContext` has been loaded by another `TestExecutionListener`. For example, with +the default set of `TestExecutionListener` implementations registered, a +`BeforeTestClassEvent` will not be published for the first test class that uses a +particular test `ApplicationContext`, but a `BeforeTestClassEvent` _will_ be published for +any subsequent test class in the same test suite that uses the same test +`ApplicationContext` since the context will already have been loaded when subsequent test +classes run (as long as the context has not been removed from the `ContextCache` via +`@DirtiesContext` or the max-size eviction policy). + +If you wish to ensure that a `BeforeTestClassEvent` is always published for every test +class, you need to register a `TestExecutionListener` that loads the `ApplicationContext` +in the `beforeTestClass` callback, and that `TestExecutionListener` must be registered +_before_ the `EventPublishingTestExecutionListener`. + +Similarly, if `@DirtiesContext` is used to remove the `ApplicationContext` from the +context cache after the last test method in a given test class, the `AfterTestClassEvent` +will not be published for that test class. +==== + +In order to listen to test execution events, a Spring bean may choose to implement the +`org.springframework.context.ApplicationListener` interface. Alternatively, listener +methods can be annotated with `@EventListener` and configured to listen to one of the +particular event types listed above (see +<<core.adoc#context-functionality-events-annotation, Annotation-based Event Listeners>>). +Due to the popularity of this approach, Spring provides the following dedicated +`@EventListener` annotations to simplify registration of test execution event listeners. +These annotations reside in the `org.springframework.test.context.event.annotation` +package. + +* `@BeforeTestClass` +* `@PrepareTestInstance` +* `@BeforeTestMethod` +* `@BeforeTestExecution` +* `@AfterTestExecution` +* `@AfterTestMethod` +* `@AfterTestClass` + +[[testcontext-test-execution-events-exception-handling]] +== Exception Handling + +By default, if a test execution event listener throws an exception while consuming an +event, that exception will propagate to the underlying testing framework in use (such as +JUnit or TestNG). For example, if the consumption of a `BeforeTestMethodEvent` results in +an exception, the corresponding test method will fail as a result of the exception. In +contrast, if an asynchronous test execution event listener throws an exception, the +exception will not propagate to the underlying testing framework. For further details on +asynchronous exception handling, consult the class-level javadoc for `@EventListener`. + +[[testcontext-test-execution-events-async]] +== Asynchronous Listeners + +If you want a particular test execution event listener to process events asynchronously, +you can use Spring's <<integration.adoc#scheduling-annotation-support-async,regular +`@Async` support>>. For further details, consult the class-level javadoc for +`@EventListener`. + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc new file mode 100644 index 000000000000..72e74703420f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc @@ -0,0 +1,600 @@ +[[testcontext-tx]] += Transaction Management + +In the TestContext framework, transactions are managed by the +`TransactionalTestExecutionListener`, which is configured by default, even if you do not +explicitly declare `@TestExecutionListeners` on your test class. To enable support for +transactions, however, you must configure a `PlatformTransactionManager` bean in the +`ApplicationContext` that is loaded with `@ContextConfiguration` semantics (further +details are provided later). In addition, you must declare Spring's `@Transactional` +annotation either at the class or the method level for your tests. + +[[testcontext-tx-test-managed-transactions]] +== Test-managed Transactions + +Test-managed transactions are transactions that are managed declaratively by using the +`TransactionalTestExecutionListener` or programmatically by using `TestTransaction` +(described later). You should not confuse such transactions with Spring-managed +transactions (those managed directly by Spring within the `ApplicationContext` loaded for +tests) or application-managed transactions (those managed programmatically within +application code that is invoked by tests). Spring-managed and application-managed +transactions typically participate in test-managed transactions. However, you should use +caution if Spring-managed or application-managed transactions are configured with any +propagation type other than `REQUIRED` or `SUPPORTS` (see the discussion on +<<data-access.adoc#tx-propagation, transaction propagation>> for details). + +.Preemptive timeouts and test-managed transactions +[WARNING] +==== +Caution must be taken when using any form of preemptive timeouts from a testing framework +in conjunction with Spring's test-managed transactions. + +Specifically, Spring’s testing support binds transaction state to the current thread (via +a `java.lang.ThreadLocal` variable) _before_ the current test method is invoked. If a +testing framework invokes the current test method in a new thread in order to support a +preemptive timeout, any actions performed within the current test method will _not_ be +invoked within the test-managed transaction. Consequently, the result of any such actions +will not be rolled back with the test-managed transaction. On the contrary, such actions +will be committed to the persistent store -- for example, a relational database -- even +though the test-managed transaction is properly rolled back by Spring. + +Situations in which this can occur include but are not limited to the following. + +* JUnit 4's `@Test(timeout = ...)` support and `TimeOut` rule +* JUnit Jupiter's `assertTimeoutPreemptively(...)` methods in the + `org.junit.jupiter.api.Assertions` class +* TestNG's `@Test(timeOut = ...)` support +==== + +[[testcontext-tx-enabling-transactions]] +== Enabling and Disabling Transactions + +Annotating a test method with `@Transactional` causes the test to be run within a +transaction that is, by default, automatically rolled back after completion of the test. +If a test class is annotated with `@Transactional`, each test method within that class +hierarchy runs within a transaction. Test methods that are not annotated with +`@Transactional` (at the class or method level) are not run within a transaction. Note +that `@Transactional` is not supported on test lifecycle methods — for example, methods +annotated with JUnit Jupiter's `@BeforeAll`, `@BeforeEach`, etc. Furthermore, tests that +are annotated with `@Transactional` but have the `propagation` attribute set to +`NOT_SUPPORTED` or `NEVER` are not run within a transaction. + +[[testcontext-tx-attribute-support]] +.`@Transactional` attribute support +|=== +|Attribute |Supported for test-managed transactions + +|`value` and `transactionManager` |yes + +|`propagation` |only `Propagation.NOT_SUPPORTED` and `Propagation.NEVER` are supported + +|`isolation` |no + +|`timeout` |no + +|`readOnly` |no + +|`rollbackFor` and `rollbackForClassName` |no: use `TestTransaction.flagForRollback()` instead + +|`noRollbackFor` and `noRollbackForClassName` |no: use `TestTransaction.flagForCommit()` instead +|=== + +[TIP] +==== +Method-level lifecycle methods — for example, methods annotated with JUnit Jupiter's +`@BeforeEach` or `@AfterEach` — are run within a test-managed transaction. On the other +hand, suite-level and class-level lifecycle methods — for example, methods annotated with +JUnit Jupiter's `@BeforeAll` or `@AfterAll` and methods annotated with TestNG's +`@BeforeSuite`, `@AfterSuite`, `@BeforeClass`, or `@AfterClass` — are _not_ run within a +test-managed transaction. + +If you need to run code in a suite-level or class-level lifecycle method within a +transaction, you may wish to inject a corresponding `PlatformTransactionManager` into +your test class and then use that with a `TransactionTemplate` for programmatic +transaction management. +==== + +Note that <<testcontext-support-classes-junit4, +`AbstractTransactionalJUnit4SpringContextTests`>> and +<<testcontext-support-classes-testng, `AbstractTransactionalTestNGSpringContextTests`>> +are preconfigured for transactional support at the class level. + +The following example demonstrates a common scenario for writing an integration test for +a Hibernate-based `UserRepository`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig(TestConfig.class) + @Transactional + class HibernateUserRepositoryTests { + + @Autowired + HibernateUserRepository repository; + + @Autowired + SessionFactory sessionFactory; + + JdbcTemplate jdbcTemplate; + + @Autowired + void setDataSource(DataSource dataSource) { + this.jdbcTemplate = new JdbcTemplate(dataSource); + } + + @Test + void createUser() { + // track initial state in test database: + final int count = countRowsInTable("user"); + + User user = new User(...); + repository.save(user); + + // Manual flush is required to avoid false positive in test + sessionFactory.getCurrentSession().flush(); + assertNumUsers(count + 1); + } + + private int countRowsInTable(String tableName) { + return JdbcTestUtils.countRowsInTable(this.jdbcTemplate, tableName); + } + + private void assertNumUsers(int expected) { + assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user")); + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig(TestConfig::class) + @Transactional + class HibernateUserRepositoryTests { + + @Autowired + lateinit var repository: HibernateUserRepository + + @Autowired + lateinit var sessionFactory: SessionFactory + + lateinit var jdbcTemplate: JdbcTemplate + + @Autowired + fun setDataSource(dataSource: DataSource) { + this.jdbcTemplate = JdbcTemplate(dataSource) + } + + @Test + fun createUser() { + // track initial state in test database: + val count = countRowsInTable("user") + + val user = User() + repository.save(user) + + // Manual flush is required to avoid false positive in test + sessionFactory.getCurrentSession().flush() + assertNumUsers(count + 1) + } + + private fun countRowsInTable(tableName: String): Int { + return JdbcTestUtils.countRowsInTable(jdbcTemplate, tableName) + } + + private fun assertNumUsers(expected: Int) { + assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user")) + } + } +---- + +As explained in <<testcontext-tx-rollback-and-commit-behavior>>, there is no need to +clean up the database after the `createUser()` method runs, since any changes made to the +database are automatically rolled back by the `TransactionalTestExecutionListener`. + +[[testcontext-tx-rollback-and-commit-behavior]] +== Transaction Rollback and Commit Behavior + +By default, test transactions will be automatically rolled back after completion of the +test; however, transactional commit and rollback behavior can be configured declaratively +via the `@Commit` and `@Rollback` annotations. See the corresponding entries in the +<<integration-testing-annotations, annotation support>> section for further details. + +[[testcontext-tx-programmatic-tx-mgt]] +== Programmatic Transaction Management + +You can interact with test-managed transactions programmatically by using the static +methods in `TestTransaction`. For example, you can use `TestTransaction` within test +methods, before methods, and after methods to start or end the current test-managed +transaction or to configure the current test-managed transaction for rollback or commit. +Support for `TestTransaction` is automatically available whenever the +`TransactionalTestExecutionListener` is enabled. + +The following example demonstrates some of the features of `TestTransaction`. See the +javadoc for {api-spring-framework}/test/context/transaction/TestTransaction.html[`TestTransaction`] +for further details. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ContextConfiguration(classes = TestConfig.class) + public class ProgrammaticTransactionManagementTests extends + AbstractTransactionalJUnit4SpringContextTests { + + @Test + public void transactionalTest() { + // assert initial state in test database: + assertNumUsers(2); + + deleteFromTables("user"); + + // changes to the database will be committed! + TestTransaction.flagForCommit(); + TestTransaction.end(); + assertFalse(TestTransaction.isActive()); + assertNumUsers(0); + + TestTransaction.start(); + // perform other actions against the database that will + // be automatically rolled back after the test completes... + } + + protected void assertNumUsers(int expected) { + assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user")); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ContextConfiguration(classes = [TestConfig::class]) + class ProgrammaticTransactionManagementTests : AbstractTransactionalJUnit4SpringContextTests() { + + @Test + fun transactionalTest() { + // assert initial state in test database: + assertNumUsers(2) + + deleteFromTables("user") + + // changes to the database will be committed! + TestTransaction.flagForCommit() + TestTransaction.end() + assertFalse(TestTransaction.isActive()) + assertNumUsers(0) + + TestTransaction.start() + // perform other actions against the database that will + // be automatically rolled back after the test completes... + } + + protected fun assertNumUsers(expected: Int) { + assertEquals("Number of rows in the [user] table.", expected, countRowsInTable("user")) + } + } +---- + +[[testcontext-tx-before-and-after-tx]] +== Running Code Outside of a Transaction + +Occasionally, you may need to run certain code before or after a transactional test +method but outside the transactional context -- for example, to verify the initial +database state prior to running your test or to verify expected transactional commit +behavior after your test runs (if the test was configured to commit the transaction). +`TransactionalTestExecutionListener` supports the `@BeforeTransaction` and +`@AfterTransaction` annotations for exactly such scenarios. You can annotate any `void` +method in a test class or any `void` default method in a test interface with one of these +annotations, and the `TransactionalTestExecutionListener` ensures that your before +transaction method or after transaction method runs at the appropriate time. + +TIP: Any before methods (such as methods annotated with JUnit Jupiter's `@BeforeEach`) +and any after methods (such as methods annotated with JUnit Jupiter's `@AfterEach`) are +run within a transaction. In addition, methods annotated with `@BeforeTransaction` or +`@AfterTransaction` are not run for test methods that are not configured to run within a +transaction. + +[[testcontext-tx-mgr-config]] +== Configuring a Transaction Manager + +`TransactionalTestExecutionListener` expects a `PlatformTransactionManager` bean to be +defined in the Spring `ApplicationContext` for the test. If there are multiple instances +of `PlatformTransactionManager` within the test's `ApplicationContext`, you can declare a +qualifier by using `@Transactional("myTxMgr")` or `@Transactional(transactionManager = +"myTxMgr")`, or `TransactionManagementConfigurer` can be implemented by an +`@Configuration` class. Consult the +{api-spring-framework}/test/context/transaction/TestContextTransactionUtils.html#retrieveTransactionManager-org.springframework.test.context.TestContext-java.lang.String-[javadoc +for `TestContextTransactionUtils.retrieveTransactionManager()`] for details on the +algorithm used to look up a transaction manager in the test's `ApplicationContext`. + +[[testcontext-tx-annotation-demo]] +== Demonstration of All Transaction-related Annotations + +The following JUnit Jupiter based example displays a fictitious integration testing +scenario that highlights all transaction-related annotations. The example is not intended +to demonstrate best practices but rather to demonstrate how these annotations can be +used. See the <<integration-testing-annotations, annotation support>> section for further +information and configuration examples. <<testcontext-executing-sql-declaratively-tx, +Transaction management for `@Sql`>> contains an additional example that uses `@Sql` for +declarative SQL script execution with default transaction rollback semantics. The +following example shows the relevant annotations: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitConfig + @Transactional(transactionManager = "txMgr") + @Commit + class FictitiousTransactionalTest { + + @BeforeTransaction + void verifyInitialDatabaseState() { + // logic to verify the initial state before a transaction is started + } + + @BeforeEach + void setUpTestDataWithinTransaction() { + // set up test data within the transaction + } + + @Test + // overrides the class-level @Commit setting + @Rollback + void modifyDatabaseWithinTransaction() { + // logic which uses the test data and modifies database state + } + + @AfterEach + void tearDownWithinTransaction() { + // run "tear down" logic within the transaction + } + + @AfterTransaction + void verifyFinalDatabaseState() { + // logic to verify the final state after transaction has rolled back + } + + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitConfig + @Transactional(transactionManager = "txMgr") + @Commit + class FictitiousTransactionalTest { + + @BeforeTransaction + fun verifyInitialDatabaseState() { + // logic to verify the initial state before a transaction is started + } + + @BeforeEach + fun setUpTestDataWithinTransaction() { + // set up test data within the transaction + } + + @Test + // overrides the class-level @Commit setting + @Rollback + fun modifyDatabaseWithinTransaction() { + // logic which uses the test data and modifies database state + } + + @AfterEach + fun tearDownWithinTransaction() { + // run "tear down" logic within the transaction + } + + @AfterTransaction + fun verifyFinalDatabaseState() { + // logic to verify the final state after transaction has rolled back + } + + } +---- + +[[testcontext-tx-false-positives]] +.Avoid false positives when testing ORM code +[NOTE] +===== +When you test application code that manipulates the state of a Hibernate session or JPA +persistence context, make sure to flush the underlying unit of work within test methods +that run that code. Failing to flush the underlying unit of work can produce false +positives: Your test passes, but the same code throws an exception in a live, production +environment. Note that this applies to any ORM framework that maintains an in-memory unit +of work. In the following Hibernate-based example test case, one method demonstrates a +false positive, and the other method correctly exposes the results of flushing the +session: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // ... + + @Autowired + SessionFactory sessionFactory; + + @Transactional + @Test // no expected exception! + public void falsePositive() { + updateEntityInHibernateSession(); + // False positive: an exception will be thrown once the Hibernate + // Session is finally flushed (i.e., in production code) + } + + @Transactional + @Test(expected = ...) + public void updateWithSessionFlush() { + updateEntityInHibernateSession(); + // Manual flush is required to avoid false positive in test + sessionFactory.getCurrentSession().flush(); + } + + // ... +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // ... + + @Autowired + lateinit var sessionFactory: SessionFactory + + @Transactional + @Test // no expected exception! + fun falsePositive() { + updateEntityInHibernateSession() + // False positive: an exception will be thrown once the Hibernate + // Session is finally flushed (i.e., in production code) + } + + @Transactional + @Test(expected = ...) + fun updateWithSessionFlush() { + updateEntityInHibernateSession() + // Manual flush is required to avoid false positive in test + sessionFactory.getCurrentSession().flush() + } + + // ... +---- + +The following example shows matching methods for JPA: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // ... + + @PersistenceContext + EntityManager entityManager; + + @Transactional + @Test // no expected exception! + public void falsePositive() { + updateEntityInJpaPersistenceContext(); + // False positive: an exception will be thrown once the JPA + // EntityManager is finally flushed (i.e., in production code) + } + + @Transactional + @Test(expected = ...) + public void updateWithEntityManagerFlush() { + updateEntityInJpaPersistenceContext(); + // Manual flush is required to avoid false positive in test + entityManager.flush(); + } + + // ... +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // ... + + @PersistenceContext + lateinit var entityManager:EntityManager + + @Transactional + @Test // no expected exception! + fun falsePositive() { + updateEntityInJpaPersistenceContext() + // False positive: an exception will be thrown once the JPA + // EntityManager is finally flushed (i.e., in production code) + } + + @Transactional + @Test(expected = ...) + void updateWithEntityManagerFlush() { + updateEntityInJpaPersistenceContext() + // Manual flush is required to avoid false positive in test + entityManager.flush() + } + + // ... +---- +===== + +[[testcontext-tx-orm-lifecycle-callbacks]] +.Testing ORM entity lifecycle callbacks +[NOTE] +===== +Similar to the note about avoiding <<testcontext-tx-false-positives, false positives>> +when testing ORM code, if your application makes use of entity lifecycle callbacks (also +known as entity listeners), make sure to flush the underlying unit of work within test +methods that run that code. Failing to _flush_ or _clear_ the underlying unit of work can +result in certain lifecycle callbacks not being invoked. + +For example, when using JPA, `@PostPersist`, `@PreUpdate`, and `@PostUpdate` callbacks +will not be called unless `entityManager.flush()` is invoked after an entity has been +saved or updated. Similarly, if an entity is already attached to the current unit of work +(associated with the current persistence context), an attempt to reload the entity will +not result in a `@PostLoad` callback unless `entityManager.clear()` is invoked before the +attempt to reload the entity. + +The following example shows how to flush the `EntityManager` to ensure that +`@PostPersist` callbacks are invoked when an entity is persisted. An entity listener with +a `@PostPersist` callback method has been registered for the `Person` entity used in the +example. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // ... + + @Autowired + JpaPersonRepository repo; + + @PersistenceContext + EntityManager entityManager; + + @Transactional + @Test + void savePerson() { + // EntityManager#persist(...) results in @PrePersist but not @PostPersist + repo.save(new Person("Jane")); + + // Manual flush is required for @PostPersist callback to be invoked + entityManager.flush(); + + // Test code that relies on the @PostPersist callback + // having been invoked... + } + + // ... +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // ... + + @Autowired + lateinit var repo: JpaPersonRepository + + @PersistenceContext + lateinit var entityManager: EntityManager + + @Transactional + @Test + fun savePerson() { + // EntityManager#persist(...) results in @PrePersist but not @PostPersist + repo.save(Person("Jane")) + + // Manual flush is required for @PostPersist callback to be invoked + entityManager.flush() + + // Test code that relies on the @PostPersist callback + // having been invoked... + } + + // ... +---- + +See +https://github.com/spring-projects/spring-framework/blob/main/spring-test/src/test/java/org/springframework/test/context/junit/jupiter/orm/JpaEntityListenerTests.java[JpaEntityListenerTests] +in the Spring Framework test suite for working examples using all JPA lifecycle callbacks. +===== + + diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc new file mode 100644 index 000000000000..fd70310f118c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc @@ -0,0 +1,160 @@ +[[testcontext-web-scoped-beans]] += Testing Request- and Session-scoped Beans + +Spring has supported <<core#beans-factory-scopes-other, Request- and session-scoped +beans>> since the early years, and you can test your request-scoped and session-scoped +beans by following these steps: + +* Ensure that a `WebApplicationContext` is loaded for your test by annotating your test + class with `@WebAppConfiguration`. +* Inject the mock request or session into your test instance and prepare your test + fixture as appropriate. +* Invoke your web component that you retrieved from the configured + `WebApplicationContext` (with dependency injection). +* Perform assertions against the mocks. + +The next code snippet shows the XML configuration for a login use case. Note that the +`userService` bean has a dependency on a request-scoped `loginAction` bean. Also, the +`LoginAction` is instantiated by using <<core.adoc#expressions, SpEL expressions>> that +retrieve the username and password from the current HTTP request. In our test, we want to +configure these request parameters through the mock managed by the TestContext framework. +The following listing shows the configuration for this use case: + +.Request-scoped bean configuration +[source,xml,indent=0] +---- + <beans> + + <bean id="userService" class="com.example.SimpleUserService" + c:loginAction-ref="loginAction"/> + + <bean id="loginAction" class="com.example.LoginAction" + c:username="#{request.getParameter('user')}" + c:password="#{request.getParameter('pswd')}" + scope="request"> + <aop:scoped-proxy/> + </bean> + + </beans> +---- + +In `RequestScopedBeanTests`, we inject both the `UserService` (that is, the subject under +test) and the `MockHttpServletRequest` into our test instance. Within our +`requestScope()` test method, we set up our test fixture by setting request parameters in +the provided `MockHttpServletRequest`. When the `loginUser()` method is invoked on our +`userService`, we are assured that the user service has access to the request-scoped +`loginAction` for the current `MockHttpServletRequest` (that is, the one in which we just +set parameters). We can then perform assertions against the results based on the known +inputs for the username and password. The following listing shows how to do so: + +.Request-scoped bean test +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitWebConfig + class RequestScopedBeanTests { + + @Autowired UserService userService; + @Autowired MockHttpServletRequest request; + + @Test + void requestScope() { + request.setParameter("user", "enigma"); + request.setParameter("pswd", "$pr!ng"); + + LoginResults results = userService.loginUser(); + // assert results + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitWebConfig + class RequestScopedBeanTests { + + @Autowired lateinit var userService: UserService + @Autowired lateinit var request: MockHttpServletRequest + + @Test + fun requestScope() { + request.setParameter("user", "enigma") + request.setParameter("pswd", "\$pr!ng") + + val results = userService.loginUser() + // assert results + } + } +---- + +The following code snippet is similar to the one we saw earlier for a request-scoped +bean. However, this time, the `userService` bean has a dependency on a session-scoped +`userPreferences` bean. Note that the `UserPreferences` bean is instantiated by using a +SpEL expression that retrieves the theme from the current HTTP session. In our test, we +need to configure a theme in the mock session managed by the TestContext framework. The +following example shows how to do so: + +.Session-scoped bean configuration +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <beans> + + <bean id="userService" class="com.example.SimpleUserService" + c:userPreferences-ref="userPreferences" /> + + <bean id="userPreferences" class="com.example.UserPreferences" + c:theme="#{session.getAttribute('theme')}" + scope="session"> + <aop:scoped-proxy/> + </bean> + + </beans> +---- + +In `SessionScopedBeanTests`, we inject the `UserService` and the `MockHttpSession` into +our test instance. Within our `sessionScope()` test method, we set up our test fixture by +setting the expected `theme` attribute in the provided `MockHttpSession`. When the +`processUserPreferences()` method is invoked on our `userService`, we are assured that +the user service has access to the session-scoped `userPreferences` for the current +`MockHttpSession`, and we can perform assertions against the results based on the +configured theme. The following example shows how to do so: + +.Session-scoped bean test +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @SpringJUnitWebConfig + class SessionScopedBeanTests { + + @Autowired UserService userService; + @Autowired MockHttpSession session; + + @Test + void sessionScope() throws Exception { + session.setAttribute("theme", "blue"); + + Results results = userService.processUserPreferences(); + // assert results + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @SpringJUnitWebConfig + class SessionScopedBeanTests { + + @Autowired lateinit var userService: UserService + @Autowired lateinit var session: MockHttpSession + + @Test + fun sessionScope() { + session.setAttribute("theme", "blue") + + val results = userService.processUserPreferences() + // assert results + } + } +---- + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc index 6116d9273be3..4f367cf44fd4 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc @@ -20,1205 +20,3 @@ support for the following: -[[webflux-client-builder]] -== Configuration - -The simplest way to create a `WebClient` is through one of the static factory methods: - -* `WebClient.create()` -* `WebClient.create(String baseUrl)` - -You can also use `WebClient.builder()` with further options: - -* `uriBuilderFactory`: Customized `UriBuilderFactory` to use as a base URL. -* `defaultUriVariables`: default values to use when expanding URI templates. -* `defaultHeader`: Headers for every request. -* `defaultCookie`: Cookies for every request. -* `defaultRequest`: `Consumer` to customize every request. -* `filter`: Client filter for every request. -* `exchangeStrategies`: HTTP message reader/writer customizations. -* `clientConnector`: HTTP client library settings. -* `observationRegistry`: the registry to use for enabling <<integration.adoc#integration.observability.http-client.webclient, Observability support>>. -* `observationConvention`: <<integration.adoc#integration.observability.config,an optional, custom convention to extract metadata>> for recorded observations. - -For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient client = WebClient.builder() - .codecs(configurer -> ... ) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val webClient = WebClient.builder() - .codecs { configurer -> ... } - .build() ----- - -Once built, a `WebClient` is immutable. However, you can clone it and build a -modified copy as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient client1 = WebClient.builder() - .filter(filterA).filter(filterB).build(); - - WebClient client2 = client1.mutate() - .filter(filterC).filter(filterD).build(); - - // client1 has filterA, filterB - - // client2 has filterA, filterB, filterC, filterD ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val client1 = WebClient.builder() - .filter(filterA).filter(filterB).build() - - val client2 = client1.mutate() - .filter(filterC).filter(filterD).build() - - // client1 has filterA, filterB - - // client2 has filterA, filterB, filterC, filterD ----- - -[[webflux-client-builder-maxinmemorysize]] -=== MaxInMemorySize - -Codecs have <<web-reactive.adoc#webflux-codecs-limits,limits>> for buffering data in -memory to avoid application memory issues. By default those are set to 256KB. -If that's not enough you'll get the following error: - ----- -org.springframework.core.io.buffer.DataBufferLimitException: Exceeded limit on max bytes to buffer ----- - -To change the limit for default codecs, use the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient webClient = WebClient.builder() - .codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024)) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val webClient = WebClient.builder() - .codecs { configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024) } - .build() ----- - - - -[[webflux-client-builder-reactor]] -=== Reactor Netty - -To customize Reactor Netty settings, provide a pre-configured `HttpClient`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpClient httpClient = HttpClient.create().secure(sslSpec -> ...); - - WebClient webClient = WebClient.builder() - .clientConnector(new ReactorClientHttpConnector(httpClient)) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val httpClient = HttpClient.create().secure { ... } - - val webClient = WebClient.builder() - .clientConnector(ReactorClientHttpConnector(httpClient)) - .build() ----- - - -[[webflux-client-builder-reactor-resources]] -==== Resources - -By default, `HttpClient` participates in the global Reactor Netty resources held in -`reactor.netty.http.HttpResources`, including event loop threads and a connection pool. -This is the recommended mode, since fixed, shared resources are preferred for event loop -concurrency. In this mode global resources remain active until the process exits. - -If the server is timed with the process, there is typically no need for an explicit -shutdown. However, if the server can start or stop in-process (for example, a Spring MVC -application deployed as a WAR), you can declare a Spring-managed bean of type -`ReactorResourceFactory` with `globalResources=true` (the default) to ensure that the Reactor -Netty global resources are shut down when the Spring `ApplicationContext` is closed, -as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Bean - public ReactorResourceFactory reactorResourceFactory() { - return new ReactorResourceFactory(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Bean - fun reactorResourceFactory() = ReactorResourceFactory() ----- --- - -You can also choose not to participate in the global Reactor Netty resources. However, -in this mode, the burden is on you to ensure that all Reactor Netty client and server -instances use shared resources, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Bean - public ReactorResourceFactory resourceFactory() { - ReactorResourceFactory factory = new ReactorResourceFactory(); - factory.setUseGlobalResources(false); // <1> - return factory; - } - - @Bean - public WebClient webClient() { - - Function<HttpClient, HttpClient> mapper = client -> { - // Further customizations... - }; - - ClientHttpConnector connector = - new ReactorClientHttpConnector(resourceFactory(), mapper); // <2> - - return WebClient.builder().clientConnector(connector).build(); // <3> - } ----- -<1> Create resources independent of global ones. -<2> Use the `ReactorClientHttpConnector` constructor with resource factory. -<3> Plug the connector into the `WebClient.Builder`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Bean - fun resourceFactory() = ReactorResourceFactory().apply { - isUseGlobalResources = false // <1> - } - - @Bean - fun webClient(): WebClient { - - val mapper: (HttpClient) -> HttpClient = { - // Further customizations... - } - - val connector = ReactorClientHttpConnector(resourceFactory(), mapper) // <2> - - return WebClient.builder().clientConnector(connector).build() // <3> - } ----- -<1> Create resources independent of global ones. -<2> Use the `ReactorClientHttpConnector` constructor with resource factory. -<3> Plug the connector into the `WebClient.Builder`. --- - - -[[webflux-client-builder-reactor-timeout]] -==== Timeouts - -To configure a connection timeout: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import io.netty.channel.ChannelOption; - - HttpClient httpClient = HttpClient.create() - .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000); - - WebClient webClient = WebClient.builder() - .clientConnector(new ReactorClientHttpConnector(httpClient)) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import io.netty.channel.ChannelOption - - val httpClient = HttpClient.create() - .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000); - - val webClient = WebClient.builder() - .clientConnector(ReactorClientHttpConnector(httpClient)) - .build(); ----- - -To configure a read or write timeout: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import io.netty.handler.timeout.ReadTimeoutHandler; - import io.netty.handler.timeout.WriteTimeoutHandler; - - HttpClient httpClient = HttpClient.create() - .doOnConnected(conn -> conn - .addHandlerLast(new ReadTimeoutHandler(10)) - .addHandlerLast(new WriteTimeoutHandler(10))); - - // Create WebClient... - ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import io.netty.handler.timeout.ReadTimeoutHandler - import io.netty.handler.timeout.WriteTimeoutHandler - - val httpClient = HttpClient.create() - .doOnConnected { conn -> conn - .addHandlerLast(ReadTimeoutHandler(10)) - .addHandlerLast(WriteTimeoutHandler(10)) - } - - // Create WebClient... ----- - -To configure a response timeout for all requests: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpClient httpClient = HttpClient.create() - .responseTimeout(Duration.ofSeconds(2)); - - // Create WebClient... ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val httpClient = HttpClient.create() - .responseTimeout(Duration.ofSeconds(2)); - - // Create WebClient... ----- - -To configure a response timeout for a specific request: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient.create().get() - .uri("https://example.org/path") - .httpRequest(httpRequest -> { - HttpClientRequest reactorRequest = httpRequest.getNativeRequest(); - reactorRequest.responseTimeout(Duration.ofSeconds(2)); - }) - .retrieve() - .bodyToMono(String.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - WebClient.create().get() - .uri("https://example.org/path") - .httpRequest { httpRequest: ClientHttpRequest -> - val reactorRequest = httpRequest.getNativeRequest<HttpClientRequest>() - reactorRequest.responseTimeout(Duration.ofSeconds(2)) - } - .retrieve() - .bodyToMono(String::class.java) ----- - - - -[[webflux-client-builder-jdk-httpclient]] -=== JDK HttpClient - -The following example shows how to customize the JDK `HttpClient`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpClient httpClient = HttpClient.newBuilder() - .followRedirects(Redirect.NORMAL) - .connectTimeout(Duration.ofSeconds(20)) - .build(); - - ClientHttpConnector connector = - new JdkClientHttpConnector(httpClient, new DefaultDataBufferFactory()); - - WebClient webClient = WebClient.builder().clientConnector(connector).build(); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val httpClient = HttpClient.newBuilder() - .followRedirects(Redirect.NORMAL) - .connectTimeout(Duration.ofSeconds(20)) - .build() - - val connector = JdkClientHttpConnector(httpClient, DefaultDataBufferFactory()) - - val webClient = WebClient.builder().clientConnector(connector).build() ----- - - - -[[webflux-client-builder-jetty]] -=== Jetty - -The following example shows how to customize Jetty `HttpClient` settings: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpClient httpClient = new HttpClient(); - httpClient.setCookieStore(...); - - WebClient webClient = WebClient.builder() - .clientConnector(new JettyClientHttpConnector(httpClient)) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val httpClient = HttpClient() - httpClient.cookieStore = ... - - val webClient = WebClient.builder() - .clientConnector(JettyClientHttpConnector(httpClient)) - .build(); ----- --- - -By default, `HttpClient` creates its own resources (`Executor`, `ByteBufferPool`, `Scheduler`), -which remain active until the process exits or `stop()` is called. - -You can share resources between multiple instances of the Jetty client (and server) and -ensure that the resources are shut down when the Spring `ApplicationContext` is closed by -declaring a Spring-managed bean of type `JettyResourceFactory`, as the following example -shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Bean - public JettyResourceFactory resourceFactory() { - return new JettyResourceFactory(); - } - - @Bean - public WebClient webClient() { - - HttpClient httpClient = new HttpClient(); - // Further customizations... - - ClientHttpConnector connector = - new JettyClientHttpConnector(httpClient, resourceFactory()); <1> - - return WebClient.builder().clientConnector(connector).build(); <2> - } ----- -<1> Use the `JettyClientHttpConnector` constructor with resource factory. -<2> Plug the connector into the `WebClient.Builder`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Bean - fun resourceFactory() = JettyResourceFactory() - - @Bean - fun webClient(): WebClient { - - val httpClient = HttpClient() - // Further customizations... - - val connector = JettyClientHttpConnector(httpClient, resourceFactory()) // <1> - - return WebClient.builder().clientConnector(connector).build() // <2> - } ----- -<1> Use the `JettyClientHttpConnector` constructor with resource factory. -<2> Plug the connector into the `WebClient.Builder`. --- - - - -[[webflux-client-builder-http-components]] -=== HttpComponents - -The following example shows how to customize Apache HttpComponents `HttpClient` settings: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpAsyncClientBuilder clientBuilder = HttpAsyncClients.custom(); - clientBuilder.setDefaultRequestConfig(...); - CloseableHttpAsyncClient client = clientBuilder.build(); - - ClientHttpConnector connector = new HttpComponentsClientHttpConnector(client); - - WebClient webClient = WebClient.builder().clientConnector(connector).build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val client = HttpAsyncClients.custom().apply { - setDefaultRequestConfig(...) - }.build() - val connector = HttpComponentsClientHttpConnector(client) - val webClient = WebClient.builder().clientConnector(connector).build() ----- - - -[[webflux-client-retrieve]] -== `retrieve()` - -The `retrieve()` method can be used to declare how to extract the response. For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient client = WebClient.create("https://example.org"); - - Mono<ResponseEntity<Person>> result = client.get() - .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) - .retrieve() - .toEntity(Person.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val client = WebClient.create("https://example.org") - - val result = client.get() - .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) - .retrieve() - .toEntity<Person>().awaitSingle() ----- - -Or to get only the body: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient client = WebClient.create("https://example.org"); - - Mono<Person> result = client.get() - .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) - .retrieve() - .bodyToMono(Person.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val client = WebClient.create("https://example.org") - - val result = client.get() - .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) - .retrieve() - .awaitBody<Person>() ----- - -To get a stream of decoded objects: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Flux<Quote> result = client.get() - .uri("/quotes").accept(MediaType.TEXT_EVENT_STREAM) - .retrieve() - .bodyToFlux(Quote.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val result = client.get() - .uri("/quotes").accept(MediaType.TEXT_EVENT_STREAM) - .retrieve() - .bodyToFlow<Quote>() ----- - -By default, 4xx or 5xx responses result in an `WebClientResponseException`, including -sub-classes for specific HTTP status codes. To customize the handling of error -responses, use `onStatus` handlers as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<Person> result = client.get() - .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) - .retrieve() - .onStatus(HttpStatus::is4xxClientError, response -> ...) - .onStatus(HttpStatus::is5xxServerError, response -> ...) - .bodyToMono(Person.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val result = client.get() - .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) - .retrieve() - .onStatus(HttpStatus::is4xxClientError) { ... } - .onStatus(HttpStatus::is5xxServerError) { ... } - .awaitBody<Person>() ----- - - - - -[[webflux-client-exchange]] -== Exchange - -The `exchangeToMono()` and `exchangeToFlux()` methods (or `awaitExchange { }` and `exchangeToFlow { }` in Kotlin) -are useful for more advanced cases that require more control, such as to decode the response differently -depending on the response status: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<Person> entityMono = client.get() - .uri("/persons/1") - .accept(MediaType.APPLICATION_JSON) - .exchangeToMono(response -> { - if (response.statusCode().equals(HttpStatus.OK)) { - return response.bodyToMono(Person.class); - } - else { - // Turn to error - return response.createError(); - } - }); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -val entity = client.get() - .uri("/persons/1") - .accept(MediaType.APPLICATION_JSON) - .awaitExchange { - if (response.statusCode() == HttpStatus.OK) { - return response.awaitBody<Person>() - } - else { - throw response.createExceptionAndAwait() - } - } ----- - -When using the above, after the returned `Mono` or `Flux` completes, the response body -is checked and if not consumed it is released to prevent memory and connection leaks. -Therefore the response cannot be decoded further downstream. It is up to the provided -function to declare how to decode the response if needed. - - - - -[[webflux-client-body]] -== Request Body - -The request body can be encoded from any asynchronous type handled by `ReactiveAdapterRegistry`, -like `Mono` or Kotlin Coroutines `Deferred` as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<Person> personMono = ... ; - - Mono<Void> result = client.post() - .uri("/persons/{id}", id) - .contentType(MediaType.APPLICATION_JSON) - .body(personMono, Person.class) - .retrieve() - .bodyToMono(Void.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val personDeferred: Deferred<Person> = ... - - client.post() - .uri("/persons/{id}", id) - .contentType(MediaType.APPLICATION_JSON) - .body<Person>(personDeferred) - .retrieve() - .awaitBody<Unit>() ----- - -You can also have a stream of objects be encoded, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Flux<Person> personFlux = ... ; - - Mono<Void> result = client.post() - .uri("/persons/{id}", id) - .contentType(MediaType.APPLICATION_STREAM_JSON) - .body(personFlux, Person.class) - .retrieve() - .bodyToMono(Void.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val people: Flow<Person> = ... - - client.post() - .uri("/persons/{id}", id) - .contentType(MediaType.APPLICATION_JSON) - .body(people) - .retrieve() - .awaitBody<Unit>() ----- - -Alternatively, if you have the actual value, you can use the `bodyValue` shortcut method, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Person person = ... ; - - Mono<Void> result = client.post() - .uri("/persons/{id}", id) - .contentType(MediaType.APPLICATION_JSON) - .bodyValue(person) - .retrieve() - .bodyToMono(Void.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val person: Person = ... - - client.post() - .uri("/persons/{id}", id) - .contentType(MediaType.APPLICATION_JSON) - .bodyValue(person) - .retrieve() - .awaitBody<Unit>() ----- - - - -[[webflux-client-body-form]] -=== Form Data - -To send form data, you can provide a `MultiValueMap<String, String>` as the body. Note that the -content is automatically set to `application/x-www-form-urlencoded` by the -`FormHttpMessageWriter`. The following example shows how to use `MultiValueMap<String, String>`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - MultiValueMap<String, String> formData = ... ; - - Mono<Void> result = client.post() - .uri("/path", id) - .bodyValue(formData) - .retrieve() - .bodyToMono(Void.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val formData: MultiValueMap<String, String> = ... - - client.post() - .uri("/path", id) - .bodyValue(formData) - .retrieve() - .awaitBody<Unit>() ----- - -You can also supply form data in-line by using `BodyInserters`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import static org.springframework.web.reactive.function.BodyInserters.*; - - Mono<Void> result = client.post() - .uri("/path", id) - .body(fromFormData("k1", "v1").with("k2", "v2")) - .retrieve() - .bodyToMono(Void.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.web.reactive.function.BodyInserters.* - - client.post() - .uri("/path", id) - .body(fromFormData("k1", "v1").with("k2", "v2")) - .retrieve() - .awaitBody<Unit>() ----- - - - -[[webflux-client-body-multipart]] -=== Multipart Data - -To send multipart data, you need to provide a `MultiValueMap<String, ?>` whose values are -either `Object` instances that represent part content or `HttpEntity` instances that represent the content and -headers for a part. `MultipartBodyBuilder` provides a convenient API to prepare a -multipart request. The following example shows how to create a `MultiValueMap<String, ?>`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - MultipartBodyBuilder builder = new MultipartBodyBuilder(); - builder.part("fieldPart", "fieldValue"); - builder.part("filePart1", new FileSystemResource("...logo.png")); - builder.part("jsonPart", new Person("Jason")); - builder.part("myPart", part); // Part from a server request - - MultiValueMap<String, HttpEntity<?>> parts = builder.build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val builder = MultipartBodyBuilder().apply { - part("fieldPart", "fieldValue") - part("filePart1", FileSystemResource("...logo.png")) - part("jsonPart", Person("Jason")) - part("myPart", part) // Part from a server request - } - - val parts = builder.build() ----- - -In most cases, you do not have to specify the `Content-Type` for each part. The content -type is determined automatically based on the `HttpMessageWriter` chosen to serialize it -or, in the case of a `Resource`, based on the file extension. If necessary, you can -explicitly provide the `MediaType` to use for each part through one of the overloaded -builder `part` methods. - -Once a `MultiValueMap` is prepared, the easiest way to pass it to the `WebClient` is -through the `body` method, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - MultipartBodyBuilder builder = ...; - - Mono<Void> result = client.post() - .uri("/path", id) - .body(builder.build()) - .retrieve() - .bodyToMono(Void.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val builder: MultipartBodyBuilder = ... - - client.post() - .uri("/path", id) - .body(builder.build()) - .retrieve() - .awaitBody<Unit>() ----- - -If the `MultiValueMap` contains at least one non-`String` value, which could also -represent regular form data (that is, `application/x-www-form-urlencoded`), you need not -set the `Content-Type` to `multipart/form-data`. This is always the case when using -`MultipartBodyBuilder`, which ensures an `HttpEntity` wrapper. - -As an alternative to `MultipartBodyBuilder`, you can also provide multipart content, -inline-style, through the built-in `BodyInserters`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import static org.springframework.web.reactive.function.BodyInserters.*; - - Mono<Void> result = client.post() - .uri("/path", id) - .body(fromMultipartData("fieldPart", "value").with("filePart", resource)) - .retrieve() - .bodyToMono(Void.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.web.reactive.function.BodyInserters.* - - client.post() - .uri("/path", id) - .body(fromMultipartData("fieldPart", "value").with("filePart", resource)) - .retrieve() - .awaitBody<Unit>() ----- - -[[partevent]] -==== `PartEvent` - -To stream multipart data sequentially, you can provide multipart content through `PartEvent` -objects. - -- Form fields can be created via `FormPartEvent::create`. -- File uploads can be created via `FilePartEvent::create`. - -You can concatenate the streams returned from methods via `Flux::concat`, and create a request for -the `WebClient`. - -For instance, this sample will POST a multipart form containing a form field and a file. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- -Resource resource = ... -Mono<String> result = webClient - .post() - .uri("https://example.com") - .body(Flux.concat( - FormPartEvent.create("field", "field value"), - FilePartEvent.create("file", resource) - ), PartEvent.class) - .retrieve() - .bodyToMono(String.class); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -var resource: Resource = ... -var result: Mono<String> = webClient - .post() - .uri("https://example.com") - .body( - Flux.concat( - FormPartEvent.create("field", "field value"), - FilePartEvent.create("file", resource) - ) - ) - .retrieve() - .bodyToMono() ----- - -On the server side, `PartEvent` objects that are received via `@RequestBody` or -`ServerRequest::bodyToFlux(PartEvent.class)` can be relayed to another service -via the `WebClient`. - - - -[[webflux-client-filter]] -== Filters - -You can register a client filter (`ExchangeFilterFunction`) through the `WebClient.Builder` -in order to intercept and modify requests, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient client = WebClient.builder() - .filter((request, next) -> { - - ClientRequest filtered = ClientRequest.from(request) - .header("foo", "bar") - .build(); - - return next.exchange(filtered); - }) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val client = WebClient.builder() - .filter { request, next -> - - val filtered = ClientRequest.from(request) - .header("foo", "bar") - .build() - - next.exchange(filtered) - } - .build() ----- - -This can be used for cross-cutting concerns, such as authentication. The following example uses -a filter for basic authentication through a static factory method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import static org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication; - - WebClient client = WebClient.builder() - .filter(basicAuthentication("user", "password")) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication - - val client = WebClient.builder() - .filter(basicAuthentication("user", "password")) - .build() ----- - -Filters can be added or removed by mutating an existing `WebClient` instance, resulting -in a new `WebClient` instance that does not affect the original one. For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import static org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication; - - WebClient client = webClient.mutate() - .filters(filterList -> { - filterList.add(0, basicAuthentication("user", "password")); - }) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val client = webClient.mutate() - .filters { it.add(0, basicAuthentication("user", "password")) } - .build() ----- - -`WebClient` is a thin facade around the chain of filters followed by an -`ExchangeFunction`. It provides a workflow to make requests, to encode to and from higher -level objects, and it helps to ensure that response content is always consumed. -When filters handle the response in some way, extra care must be taken to always consume -its content or to otherwise propagate it downstream to the `WebClient` which will ensure -the same. Below is a filter that handles the `UNAUTHORIZED` status code but ensures that -any response content, whether expected or not, is released: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public ExchangeFilterFunction renewTokenFilter() { - return (request, next) -> next.exchange(request).flatMap(response -> { - if (response.statusCode().value() == HttpStatus.UNAUTHORIZED.value()) { - return response.releaseBody() - .then(renewToken()) - .flatMap(token -> { - ClientRequest newRequest = ClientRequest.from(request).build(); - return next.exchange(newRequest); - }); - } else { - return Mono.just(response); - } - }); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun renewTokenFilter(): ExchangeFilterFunction? { - return ExchangeFilterFunction { request: ClientRequest?, next: ExchangeFunction -> - next.exchange(request!!).flatMap { response: ClientResponse -> - if (response.statusCode().value() == HttpStatus.UNAUTHORIZED.value()) { - return@flatMap response.releaseBody() - .then(renewToken()) - .flatMap { token: String? -> - val newRequest = ClientRequest.from(request).build() - next.exchange(newRequest) - } - } else { - return@flatMap Mono.just(response) - } - } - } - } ----- - - - -[[webflux-client-attributes]] -== Attributes - -You can add attributes to a request. This is convenient if you want to pass information -through the filter chain and influence the behavior of filters for a given request. -For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient client = WebClient.builder() - .filter((request, next) -> { - Optional<Object> usr = request.attribute("myAttribute"); - // ... - }) - .build(); - - client.get().uri("https://example.org/") - .attribute("myAttribute", "...") - .retrieve() - .bodyToMono(Void.class); - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val client = WebClient.builder() - .filter { request, _ -> - val usr = request.attributes()["myAttribute"]; - // ... - } - .build() - - client.get().uri("https://example.org/") - .attribute("myAttribute", "...") - .retrieve() - .awaitBody<Unit>() ----- - -Note that you can configure a `defaultRequest` callback globally at the -`WebClient.Builder` level which lets you insert attributes into all requests, -which could be used for example in a Spring MVC application to populate -request attributes based on `ThreadLocal` data. - - -[[webflux-client-context]] -== Context - -<<webflux-client-attributes>> provide a convenient way to pass information to the filter -chain but they only influence the current request. If you want to pass information that -propagates to additional requests that are nested, e.g. via `flatMap`, or executed after, -e.g. via `concatMap`, then you'll need to use the Reactor `Context`. - -The Reactor `Context` needs to be populated at the end of a reactive chain in order to -apply to all operations. For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient client = WebClient.builder() - .filter((request, next) -> - Mono.deferContextual(contextView -> { - String value = contextView.get("foo"); - // ... - })) - .build(); - - client.get().uri("https://example.org/") - .retrieve() - .bodyToMono(String.class) - .flatMap(body -> { - // perform nested request (context propagates automatically)... - }) - .contextWrite(context -> context.put("foo", ...)); ----- - - - -[[webflux-client-synchronous]] -== Synchronous Use - -`WebClient` can be used in synchronous style by blocking at the end for the result: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Person person = client.get().uri("/person/{id}", i).retrieve() - .bodyToMono(Person.class) - .block(); - - List<Person> persons = client.get().uri("/persons").retrieve() - .bodyToFlux(Person.class) - .collectList() - .block(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val person = runBlocking { - client.get().uri("/person/{id}", i).retrieve() - .awaitBody<Person>() - } - - val persons = runBlocking { - client.get().uri("/persons").retrieve() - .bodyToFlow<Person>() - .toList() - } ----- - -However if multiple calls need to be made, it's more efficient to avoid blocking on each -response individually, and instead wait for the combined result: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<Person> personMono = client.get().uri("/person/{id}", personId) - .retrieve().bodyToMono(Person.class); - - Mono<List<Hobby>> hobbiesMono = client.get().uri("/person/{id}/hobbies", personId) - .retrieve().bodyToFlux(Hobby.class).collectList(); - - Map<String, Object> data = Mono.zip(personMono, hobbiesMono, (person, hobbies) -> { - Map<String, String> map = new LinkedHashMap<>(); - map.put("person", person); - map.put("hobbies", hobbies); - return map; - }) - .block(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val data = runBlocking { - val personDeferred = async { - client.get().uri("/person/{id}", personId) - .retrieve().awaitBody<Person>() - } - - val hobbiesDeferred = async { - client.get().uri("/person/{id}/hobbies", personId) - .retrieve().bodyToFlow<Hobby>().toList() - } - - mapOf("person" to personDeferred.await(), "hobbies" to hobbiesDeferred.await()) - } ----- - -The above is merely one example. There are lots of other patterns and operators for putting -together a reactive pipeline that makes many remote calls, potentially some nested, -interdependent, without ever blocking until the end. - -[NOTE] -==== -With `Flux` or `Mono`, you should never have to block in a Spring MVC or Spring WebFlux controller. -Simply return the resulting reactive type from the controller method. The same principle apply to -Kotlin Coroutines and Spring WebFlux, just use suspending function or return `Flow` in your -controller method . -==== - - - - -[[webflux-client-testing]] -== Testing - -To test code that uses the `WebClient`, you can use a mock web server, such as the -https://github.com/square/okhttp#mockwebserver[OkHttp MockWebServer]. To see an example -of its use, check out -{spring-framework-main-code}/spring-webflux/src/test/java/org/springframework/web/reactive/function/client/WebClientIntegrationTests.java[`WebClientIntegrationTests`] -in the Spring Framework test suite or the -https://github.com/square/okhttp/tree/master/samples/static-server[`static-server`] -sample in the OkHttp repository. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-attributes.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-attributes.adoc new file mode 100644 index 000000000000..78fc4db2a525 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-attributes.adoc @@ -0,0 +1,46 @@ +[[webflux-client-attributes]] += Attributes + +You can add attributes to a request. This is convenient if you want to pass information +through the filter chain and influence the behavior of filters for a given request. +For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient client = WebClient.builder() + .filter((request, next) -> { + Optional<Object> usr = request.attribute("myAttribute"); + // ... + }) + .build(); + + client.get().uri("https://example.org/") + .attribute("myAttribute", "...") + .retrieve() + .bodyToMono(Void.class); + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val client = WebClient.builder() + .filter { request, _ -> + val usr = request.attributes()["myAttribute"]; + // ... + } + .build() + + client.get().uri("https://example.org/") + .attribute("myAttribute", "...") + .retrieve() + .awaitBody<Unit>() +---- + +Note that you can configure a `defaultRequest` callback globally at the +`WebClient.Builder` level which lets you insert attributes into all requests, +which could be used for example in a Spring MVC application to populate +request attributes based on `ThreadLocal` data. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-body.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-body.adoc new file mode 100644 index 000000000000..900041278a73 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-body.adoc @@ -0,0 +1,291 @@ +[[webflux-client-body]] += Request Body + +The request body can be encoded from any asynchronous type handled by `ReactiveAdapterRegistry`, +like `Mono` or Kotlin Coroutines `Deferred` as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<Person> personMono = ... ; + + Mono<Void> result = client.post() + .uri("/persons/{id}", id) + .contentType(MediaType.APPLICATION_JSON) + .body(personMono, Person.class) + .retrieve() + .bodyToMono(Void.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val personDeferred: Deferred<Person> = ... + + client.post() + .uri("/persons/{id}", id) + .contentType(MediaType.APPLICATION_JSON) + .body<Person>(personDeferred) + .retrieve() + .awaitBody<Unit>() +---- + +You can also have a stream of objects be encoded, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Flux<Person> personFlux = ... ; + + Mono<Void> result = client.post() + .uri("/persons/{id}", id) + .contentType(MediaType.APPLICATION_STREAM_JSON) + .body(personFlux, Person.class) + .retrieve() + .bodyToMono(Void.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val people: Flow<Person> = ... + + client.post() + .uri("/persons/{id}", id) + .contentType(MediaType.APPLICATION_JSON) + .body(people) + .retrieve() + .awaitBody<Unit>() +---- + +Alternatively, if you have the actual value, you can use the `bodyValue` shortcut method, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Person person = ... ; + + Mono<Void> result = client.post() + .uri("/persons/{id}", id) + .contentType(MediaType.APPLICATION_JSON) + .bodyValue(person) + .retrieve() + .bodyToMono(Void.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val person: Person = ... + + client.post() + .uri("/persons/{id}", id) + .contentType(MediaType.APPLICATION_JSON) + .bodyValue(person) + .retrieve() + .awaitBody<Unit>() +---- + + + +[[webflux-client-body-form]] +== Form Data + +To send form data, you can provide a `MultiValueMap<String, String>` as the body. Note that the +content is automatically set to `application/x-www-form-urlencoded` by the +`FormHttpMessageWriter`. The following example shows how to use `MultiValueMap<String, String>`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + MultiValueMap<String, String> formData = ... ; + + Mono<Void> result = client.post() + .uri("/path", id) + .bodyValue(formData) + .retrieve() + .bodyToMono(Void.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val formData: MultiValueMap<String, String> = ... + + client.post() + .uri("/path", id) + .bodyValue(formData) + .retrieve() + .awaitBody<Unit>() +---- + +You can also supply form data in-line by using `BodyInserters`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import static org.springframework.web.reactive.function.BodyInserters.*; + + Mono<Void> result = client.post() + .uri("/path", id) + .body(fromFormData("k1", "v1").with("k2", "v2")) + .retrieve() + .bodyToMono(Void.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.web.reactive.function.BodyInserters.* + + client.post() + .uri("/path", id) + .body(fromFormData("k1", "v1").with("k2", "v2")) + .retrieve() + .awaitBody<Unit>() +---- + + + +[[webflux-client-body-multipart]] +== Multipart Data + +To send multipart data, you need to provide a `MultiValueMap<String, ?>` whose values are +either `Object` instances that represent part content or `HttpEntity` instances that represent the content and +headers for a part. `MultipartBodyBuilder` provides a convenient API to prepare a +multipart request. The following example shows how to create a `MultiValueMap<String, ?>`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + MultipartBodyBuilder builder = new MultipartBodyBuilder(); + builder.part("fieldPart", "fieldValue"); + builder.part("filePart1", new FileSystemResource("...logo.png")); + builder.part("jsonPart", new Person("Jason")); + builder.part("myPart", part); // Part from a server request + + MultiValueMap<String, HttpEntity<?>> parts = builder.build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val builder = MultipartBodyBuilder().apply { + part("fieldPart", "fieldValue") + part("filePart1", FileSystemResource("...logo.png")) + part("jsonPart", Person("Jason")) + part("myPart", part) // Part from a server request + } + + val parts = builder.build() +---- + +In most cases, you do not have to specify the `Content-Type` for each part. The content +type is determined automatically based on the `HttpMessageWriter` chosen to serialize it +or, in the case of a `Resource`, based on the file extension. If necessary, you can +explicitly provide the `MediaType` to use for each part through one of the overloaded +builder `part` methods. + +Once a `MultiValueMap` is prepared, the easiest way to pass it to the `WebClient` is +through the `body` method, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + MultipartBodyBuilder builder = ...; + + Mono<Void> result = client.post() + .uri("/path", id) + .body(builder.build()) + .retrieve() + .bodyToMono(Void.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val builder: MultipartBodyBuilder = ... + + client.post() + .uri("/path", id) + .body(builder.build()) + .retrieve() + .awaitBody<Unit>() +---- + +If the `MultiValueMap` contains at least one non-`String` value, which could also +represent regular form data (that is, `application/x-www-form-urlencoded`), you need not +set the `Content-Type` to `multipart/form-data`. This is always the case when using +`MultipartBodyBuilder`, which ensures an `HttpEntity` wrapper. + +As an alternative to `MultipartBodyBuilder`, you can also provide multipart content, +inline-style, through the built-in `BodyInserters`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import static org.springframework.web.reactive.function.BodyInserters.*; + + Mono<Void> result = client.post() + .uri("/path", id) + .body(fromMultipartData("fieldPart", "value").with("filePart", resource)) + .retrieve() + .bodyToMono(Void.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.web.reactive.function.BodyInserters.* + + client.post() + .uri("/path", id) + .body(fromMultipartData("fieldPart", "value").with("filePart", resource)) + .retrieve() + .awaitBody<Unit>() +---- + +[[partevent]] +=== `PartEvent` + +To stream multipart data sequentially, you can provide multipart content through `PartEvent` +objects. + +- Form fields can be created via `FormPartEvent::create`. +- File uploads can be created via `FilePartEvent::create`. + +You can concatenate the streams returned from methods via `Flux::concat`, and create a request for +the `WebClient`. + +For instance, this sample will POST a multipart form containing a form field and a file. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- +Resource resource = ... +Mono<String> result = webClient + .post() + .uri("https://example.com") + .body(Flux.concat( + FormPartEvent.create("field", "field value"), + FilePartEvent.create("file", resource) + ), PartEvent.class) + .retrieve() + .bodyToMono(String.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +var resource: Resource = ... +var result: Mono<String> = webClient + .post() + .uri("https://example.com") + .body( + Flux.concat( + FormPartEvent.create("field", "field value"), + FilePartEvent.create("file", resource) + ) + ) + .retrieve() + .bodyToMono() +---- + +On the server side, `PartEvent` objects that are received via `@RequestBody` or +`ServerRequest::bodyToFlux(PartEvent.class)` can be relayed to another service +via the `WebClient`. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc new file mode 100644 index 000000000000..75c429669747 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc @@ -0,0 +1,466 @@ +[[webflux-client-builder]] += Configuration + +The simplest way to create a `WebClient` is through one of the static factory methods: + +* `WebClient.create()` +* `WebClient.create(String baseUrl)` + +You can also use `WebClient.builder()` with further options: + +* `uriBuilderFactory`: Customized `UriBuilderFactory` to use as a base URL. +* `defaultUriVariables`: default values to use when expanding URI templates. +* `defaultHeader`: Headers for every request. +* `defaultCookie`: Cookies for every request. +* `defaultRequest`: `Consumer` to customize every request. +* `filter`: Client filter for every request. +* `exchangeStrategies`: HTTP message reader/writer customizations. +* `clientConnector`: HTTP client library settings. +* `observationRegistry`: the registry to use for enabling <<integration.adoc#integration.observability.http-client.webclient, Observability support>>. +* `observationConvention`: <<integration.adoc#integration.observability.config,an optional, custom convention to extract metadata>> for recorded observations. + +For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient client = WebClient.builder() + .codecs(configurer -> ... ) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val webClient = WebClient.builder() + .codecs { configurer -> ... } + .build() +---- + +Once built, a `WebClient` is immutable. However, you can clone it and build a +modified copy as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient client1 = WebClient.builder() + .filter(filterA).filter(filterB).build(); + + WebClient client2 = client1.mutate() + .filter(filterC).filter(filterD).build(); + + // client1 has filterA, filterB + + // client2 has filterA, filterB, filterC, filterD +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val client1 = WebClient.builder() + .filter(filterA).filter(filterB).build() + + val client2 = client1.mutate() + .filter(filterC).filter(filterD).build() + + // client1 has filterA, filterB + + // client2 has filterA, filterB, filterC, filterD +---- + +[[webflux-client-builder-maxinmemorysize]] +== MaxInMemorySize + +Codecs have <<web-reactive.adoc#webflux-codecs-limits,limits>> for buffering data in +memory to avoid application memory issues. By default those are set to 256KB. +If that's not enough you'll get the following error: + +---- +org.springframework.core.io.buffer.DataBufferLimitException: Exceeded limit on max bytes to buffer +---- + +To change the limit for default codecs, use the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient webClient = WebClient.builder() + .codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024)) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val webClient = WebClient.builder() + .codecs { configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024) } + .build() +---- + + + +[[webflux-client-builder-reactor]] +== Reactor Netty + +To customize Reactor Netty settings, provide a pre-configured `HttpClient`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpClient httpClient = HttpClient.create().secure(sslSpec -> ...); + + WebClient webClient = WebClient.builder() + .clientConnector(new ReactorClientHttpConnector(httpClient)) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val httpClient = HttpClient.create().secure { ... } + + val webClient = WebClient.builder() + .clientConnector(ReactorClientHttpConnector(httpClient)) + .build() +---- + + +[[webflux-client-builder-reactor-resources]] +=== Resources + +By default, `HttpClient` participates in the global Reactor Netty resources held in +`reactor.netty.http.HttpResources`, including event loop threads and a connection pool. +This is the recommended mode, since fixed, shared resources are preferred for event loop +concurrency. In this mode global resources remain active until the process exits. + +If the server is timed with the process, there is typically no need for an explicit +shutdown. However, if the server can start or stop in-process (for example, a Spring MVC +application deployed as a WAR), you can declare a Spring-managed bean of type +`ReactorResourceFactory` with `globalResources=true` (the default) to ensure that the Reactor +Netty global resources are shut down when the Spring `ApplicationContext` is closed, +as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Bean + public ReactorResourceFactory reactorResourceFactory() { + return new ReactorResourceFactory(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Bean + fun reactorResourceFactory() = ReactorResourceFactory() +---- +-- + +You can also choose not to participate in the global Reactor Netty resources. However, +in this mode, the burden is on you to ensure that all Reactor Netty client and server +instances use shared resources, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Bean + public ReactorResourceFactory resourceFactory() { + ReactorResourceFactory factory = new ReactorResourceFactory(); + factory.setUseGlobalResources(false); // <1> + return factory; + } + + @Bean + public WebClient webClient() { + + Function<HttpClient, HttpClient> mapper = client -> { + // Further customizations... + }; + + ClientHttpConnector connector = + new ReactorClientHttpConnector(resourceFactory(), mapper); // <2> + + return WebClient.builder().clientConnector(connector).build(); // <3> + } +---- +<1> Create resources independent of global ones. +<2> Use the `ReactorClientHttpConnector` constructor with resource factory. +<3> Plug the connector into the `WebClient.Builder`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Bean + fun resourceFactory() = ReactorResourceFactory().apply { + isUseGlobalResources = false // <1> + } + + @Bean + fun webClient(): WebClient { + + val mapper: (HttpClient) -> HttpClient = { + // Further customizations... + } + + val connector = ReactorClientHttpConnector(resourceFactory(), mapper) // <2> + + return WebClient.builder().clientConnector(connector).build() // <3> + } +---- +<1> Create resources independent of global ones. +<2> Use the `ReactorClientHttpConnector` constructor with resource factory. +<3> Plug the connector into the `WebClient.Builder`. +-- + + +[[webflux-client-builder-reactor-timeout]] +=== Timeouts + +To configure a connection timeout: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import io.netty.channel.ChannelOption; + + HttpClient httpClient = HttpClient.create() + .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000); + + WebClient webClient = WebClient.builder() + .clientConnector(new ReactorClientHttpConnector(httpClient)) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import io.netty.channel.ChannelOption + + val httpClient = HttpClient.create() + .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000); + + val webClient = WebClient.builder() + .clientConnector(ReactorClientHttpConnector(httpClient)) + .build(); +---- + +To configure a read or write timeout: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import io.netty.handler.timeout.ReadTimeoutHandler; + import io.netty.handler.timeout.WriteTimeoutHandler; + + HttpClient httpClient = HttpClient.create() + .doOnConnected(conn -> conn + .addHandlerLast(new ReadTimeoutHandler(10)) + .addHandlerLast(new WriteTimeoutHandler(10))); + + // Create WebClient... + +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import io.netty.handler.timeout.ReadTimeoutHandler + import io.netty.handler.timeout.WriteTimeoutHandler + + val httpClient = HttpClient.create() + .doOnConnected { conn -> conn + .addHandlerLast(ReadTimeoutHandler(10)) + .addHandlerLast(WriteTimeoutHandler(10)) + } + + // Create WebClient... +---- + +To configure a response timeout for all requests: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpClient httpClient = HttpClient.create() + .responseTimeout(Duration.ofSeconds(2)); + + // Create WebClient... +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val httpClient = HttpClient.create() + .responseTimeout(Duration.ofSeconds(2)); + + // Create WebClient... +---- + +To configure a response timeout for a specific request: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient.create().get() + .uri("https://example.org/path") + .httpRequest(httpRequest -> { + HttpClientRequest reactorRequest = httpRequest.getNativeRequest(); + reactorRequest.responseTimeout(Duration.ofSeconds(2)); + }) + .retrieve() + .bodyToMono(String.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + WebClient.create().get() + .uri("https://example.org/path") + .httpRequest { httpRequest: ClientHttpRequest -> + val reactorRequest = httpRequest.getNativeRequest<HttpClientRequest>() + reactorRequest.responseTimeout(Duration.ofSeconds(2)) + } + .retrieve() + .bodyToMono(String::class.java) +---- + + + +[[webflux-client-builder-jdk-httpclient]] +== JDK HttpClient + +The following example shows how to customize the JDK `HttpClient`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpClient httpClient = HttpClient.newBuilder() + .followRedirects(Redirect.NORMAL) + .connectTimeout(Duration.ofSeconds(20)) + .build(); + + ClientHttpConnector connector = + new JdkClientHttpConnector(httpClient, new DefaultDataBufferFactory()); + + WebClient webClient = WebClient.builder().clientConnector(connector).build(); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val httpClient = HttpClient.newBuilder() + .followRedirects(Redirect.NORMAL) + .connectTimeout(Duration.ofSeconds(20)) + .build() + + val connector = JdkClientHttpConnector(httpClient, DefaultDataBufferFactory()) + + val webClient = WebClient.builder().clientConnector(connector).build() +---- + + + +[[webflux-client-builder-jetty]] +== Jetty + +The following example shows how to customize Jetty `HttpClient` settings: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpClient httpClient = new HttpClient(); + httpClient.setCookieStore(...); + + WebClient webClient = WebClient.builder() + .clientConnector(new JettyClientHttpConnector(httpClient)) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val httpClient = HttpClient() + httpClient.cookieStore = ... + + val webClient = WebClient.builder() + .clientConnector(JettyClientHttpConnector(httpClient)) + .build(); +---- +-- + +By default, `HttpClient` creates its own resources (`Executor`, `ByteBufferPool`, `Scheduler`), +which remain active until the process exits or `stop()` is called. + +You can share resources between multiple instances of the Jetty client (and server) and +ensure that the resources are shut down when the Spring `ApplicationContext` is closed by +declaring a Spring-managed bean of type `JettyResourceFactory`, as the following example +shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Bean + public JettyResourceFactory resourceFactory() { + return new JettyResourceFactory(); + } + + @Bean + public WebClient webClient() { + + HttpClient httpClient = new HttpClient(); + // Further customizations... + + ClientHttpConnector connector = + new JettyClientHttpConnector(httpClient, resourceFactory()); <1> + + return WebClient.builder().clientConnector(connector).build(); <2> + } +---- +<1> Use the `JettyClientHttpConnector` constructor with resource factory. +<2> Plug the connector into the `WebClient.Builder`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Bean + fun resourceFactory() = JettyResourceFactory() + + @Bean + fun webClient(): WebClient { + + val httpClient = HttpClient() + // Further customizations... + + val connector = JettyClientHttpConnector(httpClient, resourceFactory()) // <1> + + return WebClient.builder().clientConnector(connector).build() // <2> + } +---- +<1> Use the `JettyClientHttpConnector` constructor with resource factory. +<2> Plug the connector into the `WebClient.Builder`. +-- + + + +[[webflux-client-builder-http-components]] +== HttpComponents + +The following example shows how to customize Apache HttpComponents `HttpClient` settings: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpAsyncClientBuilder clientBuilder = HttpAsyncClients.custom(); + clientBuilder.setDefaultRequestConfig(...); + CloseableHttpAsyncClient client = clientBuilder.build(); + + ClientHttpConnector connector = new HttpComponentsClientHttpConnector(client); + + WebClient webClient = WebClient.builder().clientConnector(connector).build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val client = HttpAsyncClients.custom().apply { + setDefaultRequestConfig(...) + }.build() + val connector = HttpComponentsClientHttpConnector(client) + val webClient = WebClient.builder().clientConnector(connector).build() +---- + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc new file mode 100644 index 000000000000..406f80c4de15 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc @@ -0,0 +1,33 @@ +[[webflux-client-context]] += Context + +<<webflux-client-attributes>> provide a convenient way to pass information to the filter +chain but they only influence the current request. If you want to pass information that +propagates to additional requests that are nested, e.g. via `flatMap`, or executed after, +e.g. via `concatMap`, then you'll need to use the Reactor `Context`. + +The Reactor `Context` needs to be populated at the end of a reactive chain in order to +apply to all operations. For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient client = WebClient.builder() + .filter((request, next) -> + Mono.deferContextual(contextView -> { + String value = contextView.get("foo"); + // ... + })) + .build(); + + client.get().uri("https://example.org/") + .retrieve() + .bodyToMono(String.class) + .flatMap(body -> { + // perform nested request (context propagates automatically)... + }) + .contextWrite(context -> context.put("foo", ...)); +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-exchange.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-exchange.adoc new file mode 100644 index 000000000000..e1f1f3976501 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-exchange.adoc @@ -0,0 +1,47 @@ +[[webflux-client-exchange]] += Exchange + +The `exchangeToMono()` and `exchangeToFlux()` methods (or `awaitExchange { }` and `exchangeToFlow { }` in Kotlin) +are useful for more advanced cases that require more control, such as to decode the response differently +depending on the response status: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<Person> entityMono = client.get() + .uri("/persons/1") + .accept(MediaType.APPLICATION_JSON) + .exchangeToMono(response -> { + if (response.statusCode().equals(HttpStatus.OK)) { + return response.bodyToMono(Person.class); + } + else { + // Turn to error + return response.createError(); + } + }); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +val entity = client.get() + .uri("/persons/1") + .accept(MediaType.APPLICATION_JSON) + .awaitExchange { + if (response.statusCode() == HttpStatus.OK) { + return response.awaitBody<Person>() + } + else { + throw response.createExceptionAndAwait() + } + } +---- + +When using the above, after the returned `Mono` or `Flux` completes, the response body +is checked and if not consumed it is released to prevent memory and connection leaks. +Therefore the response cannot be decoded further downstream. It is up to the provided +function to declare how to decode the response if needed. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-filter.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-filter.adoc new file mode 100644 index 000000000000..c571ed258cf9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-filter.adoc @@ -0,0 +1,128 @@ +[[webflux-client-filter]] += Filters + +You can register a client filter (`ExchangeFilterFunction`) through the `WebClient.Builder` +in order to intercept and modify requests, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient client = WebClient.builder() + .filter((request, next) -> { + + ClientRequest filtered = ClientRequest.from(request) + .header("foo", "bar") + .build(); + + return next.exchange(filtered); + }) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val client = WebClient.builder() + .filter { request, next -> + + val filtered = ClientRequest.from(request) + .header("foo", "bar") + .build() + + next.exchange(filtered) + } + .build() +---- + +This can be used for cross-cutting concerns, such as authentication. The following example uses +a filter for basic authentication through a static factory method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import static org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication; + + WebClient client = WebClient.builder() + .filter(basicAuthentication("user", "password")) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication + + val client = WebClient.builder() + .filter(basicAuthentication("user", "password")) + .build() +---- + +Filters can be added or removed by mutating an existing `WebClient` instance, resulting +in a new `WebClient` instance that does not affect the original one. For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import static org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication; + + WebClient client = webClient.mutate() + .filters(filterList -> { + filterList.add(0, basicAuthentication("user", "password")); + }) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val client = webClient.mutate() + .filters { it.add(0, basicAuthentication("user", "password")) } + .build() +---- + +`WebClient` is a thin facade around the chain of filters followed by an +`ExchangeFunction`. It provides a workflow to make requests, to encode to and from higher +level objects, and it helps to ensure that response content is always consumed. +When filters handle the response in some way, extra care must be taken to always consume +its content or to otherwise propagate it downstream to the `WebClient` which will ensure +the same. Below is a filter that handles the `UNAUTHORIZED` status code but ensures that +any response content, whether expected or not, is released: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public ExchangeFilterFunction renewTokenFilter() { + return (request, next) -> next.exchange(request).flatMap(response -> { + if (response.statusCode().value() == HttpStatus.UNAUTHORIZED.value()) { + return response.releaseBody() + .then(renewToken()) + .flatMap(token -> { + ClientRequest newRequest = ClientRequest.from(request).build(); + return next.exchange(newRequest); + }); + } else { + return Mono.just(response); + } + }); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + fun renewTokenFilter(): ExchangeFilterFunction? { + return ExchangeFilterFunction { request: ClientRequest?, next: ExchangeFunction -> + next.exchange(request!!).flatMap { response: ClientResponse -> + if (response.statusCode().value() == HttpStatus.UNAUTHORIZED.value()) { + return@flatMap response.releaseBody() + .then(renewToken()) + .flatMap { token: String? -> + val newRequest = ClientRequest.from(request).build() + next.exchange(newRequest) + } + } else { + return@flatMap Mono.just(response) + } + } + } + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-retrieve.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-retrieve.adoc new file mode 100644 index 000000000000..500ae9d3a8b3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-retrieve.adoc @@ -0,0 +1,96 @@ +[[webflux-client-retrieve]] += `retrieve()` + +The `retrieve()` method can be used to declare how to extract the response. For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient client = WebClient.create("https://example.org"); + + Mono<ResponseEntity<Person>> result = client.get() + .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) + .retrieve() + .toEntity(Person.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val client = WebClient.create("https://example.org") + + val result = client.get() + .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) + .retrieve() + .toEntity<Person>().awaitSingle() +---- + +Or to get only the body: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient client = WebClient.create("https://example.org"); + + Mono<Person> result = client.get() + .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) + .retrieve() + .bodyToMono(Person.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val client = WebClient.create("https://example.org") + + val result = client.get() + .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) + .retrieve() + .awaitBody<Person>() +---- + +To get a stream of decoded objects: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Flux<Quote> result = client.get() + .uri("/quotes").accept(MediaType.TEXT_EVENT_STREAM) + .retrieve() + .bodyToFlux(Quote.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val result = client.get() + .uri("/quotes").accept(MediaType.TEXT_EVENT_STREAM) + .retrieve() + .bodyToFlow<Quote>() +---- + +By default, 4xx or 5xx responses result in an `WebClientResponseException`, including +sub-classes for specific HTTP status codes. To customize the handling of error +responses, use `onStatus` handlers as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<Person> result = client.get() + .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) + .retrieve() + .onStatus(HttpStatus::is4xxClientError, response -> ...) + .onStatus(HttpStatus::is5xxServerError, response -> ...) + .bodyToMono(Person.class); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val result = client.get() + .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) + .retrieve() + .onStatus(HttpStatus::is4xxClientError) { ... } + .onStatus(HttpStatus::is5xxServerError) { ... } + .awaitBody<Person>() +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-synchronous.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-synchronous.adoc new file mode 100644 index 000000000000..07cb96ad72c9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-synchronous.adoc @@ -0,0 +1,85 @@ +[[webflux-client-synchronous]] += Synchronous Use + +`WebClient` can be used in synchronous style by blocking at the end for the result: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Person person = client.get().uri("/person/{id}", i).retrieve() + .bodyToMono(Person.class) + .block(); + + List<Person> persons = client.get().uri("/persons").retrieve() + .bodyToFlux(Person.class) + .collectList() + .block(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val person = runBlocking { + client.get().uri("/person/{id}", i).retrieve() + .awaitBody<Person>() + } + + val persons = runBlocking { + client.get().uri("/persons").retrieve() + .bodyToFlow<Person>() + .toList() + } +---- + +However if multiple calls need to be made, it's more efficient to avoid blocking on each +response individually, and instead wait for the combined result: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<Person> personMono = client.get().uri("/person/{id}", personId) + .retrieve().bodyToMono(Person.class); + + Mono<List<Hobby>> hobbiesMono = client.get().uri("/person/{id}/hobbies", personId) + .retrieve().bodyToFlux(Hobby.class).collectList(); + + Map<String, Object> data = Mono.zip(personMono, hobbiesMono, (person, hobbies) -> { + Map<String, String> map = new LinkedHashMap<>(); + map.put("person", person); + map.put("hobbies", hobbies); + return map; + }) + .block(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val data = runBlocking { + val personDeferred = async { + client.get().uri("/person/{id}", personId) + .retrieve().awaitBody<Person>() + } + + val hobbiesDeferred = async { + client.get().uri("/person/{id}/hobbies", personId) + .retrieve().bodyToFlow<Hobby>().toList() + } + + mapOf("person" to personDeferred.await(), "hobbies" to hobbiesDeferred.await()) + } +---- + +The above is merely one example. There are lots of other patterns and operators for putting +together a reactive pipeline that makes many remote calls, potentially some nested, +interdependent, without ever blocking until the end. + +[NOTE] +==== +With `Flux` or `Mono`, you should never have to block in a Spring MVC or Spring WebFlux controller. +Simply return the resulting reactive type from the controller method. The same principle apply to +Kotlin Coroutines and Spring WebFlux, just use suspending function or return `Flow` in your +controller method . +==== + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-testing.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-testing.adoc new file mode 100644 index 000000000000..756e5172c513 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-testing.adoc @@ -0,0 +1,10 @@ +[[webflux-client-testing]] += Testing + +To test code that uses the `WebClient`, you can use a mock web server, such as the +https://github.com/square/okhttp#mockwebserver[OkHttp MockWebServer]. To see an example +of its use, check out +{spring-framework-main-code}/spring-webflux/src/test/java/org/springframework/web/reactive/function/client/WebClientIntegrationTests.java[`WebClientIntegrationTests`] +in the Spring Framework test suite or the +https://github.com/square/okhttp/tree/master/samples/static-server[`static-server`] +sample in the OkHttp repository. diff --git a/framework-docs/modules/ROOT/pages/web/webflux.adoc b/framework-docs/modules/ROOT/pages/web/webflux.adoc index a50f9f08e1fc..57b07ca6a165 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux.adoc @@ -18,4689 +18,3 @@ in some cases, both -- for example, Spring MVC controllers with the reactive `We -[[webflux-new-framework]] -== Overview - -Why was Spring WebFlux created? - -Part of the answer is the need for a non-blocking web stack to handle concurrency with a -small number of threads and scale with fewer hardware resources. Servlet non-blocking I/O -leads away from the rest of the Servlet API, where contracts are synchronous -(`Filter`, `Servlet`) or blocking (`getParameter`, `getPart`). This was the motivation -for a new common API to serve as a foundation across any non-blocking runtime. That is -important because of servers (such as Netty) that are well-established in the async, -non-blocking space. - -The other part of the answer is functional programming. Much as the addition of annotations -in Java 5 created opportunities (such as annotated REST controllers or unit tests), the -addition of lambda expressions in Java 8 created opportunities for functional APIs in Java. -This is a boon for non-blocking applications and continuation-style APIs (as popularized -by `CompletableFuture` and https://reactivex.io/[ReactiveX]) that allow declarative -composition of asynchronous logic. At the programming-model level, Java 8 enabled Spring -WebFlux to offer functional web endpoints alongside annotated controllers. - - - -[[webflux-why-reactive]] -=== Define "`Reactive`" - -We touched on "`non-blocking`" and "`functional`" but what does reactive mean? - -The term, "`reactive,`" refers to programming models that are built around reacting to change -- -network components reacting to I/O events, UI controllers reacting to mouse events, and others. -In that sense, non-blocking is reactive, because, instead of being blocked, we are now in the mode -of reacting to notifications as operations complete or data becomes available. - -There is also another important mechanism that we on the Spring team associate with "`reactive`" -and that is non-blocking back pressure. In synchronous, imperative code, blocking calls -serve as a natural form of back pressure that forces the caller to wait. In non-blocking -code, it becomes important to control the rate of events so that a fast producer does not -overwhelm its destination. - -Reactive Streams is a -https://github.com/reactive-streams/reactive-streams-jvm/blob/master/README.md#specification[small spec] -(also https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html[adopted] in Java 9) -that defines the interaction between asynchronous components with back pressure. -For example a data repository (acting as -https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Publisher.html[Publisher]) -can produce data that an HTTP server (acting as -https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Subscriber.html[Subscriber]) -can then write to the response. The main purpose of Reactive Streams is to let the - subscriber control how quickly or how slowly the publisher produces data. - -NOTE: *Common question: what if a publisher cannot slow down?* + -The purpose of Reactive Streams is only to establish the mechanism and a boundary. -If a publisher cannot slow down, it has to decide whether to buffer, drop, or fail. - - - -[[webflux-reactive-api]] -=== Reactive API - -Reactive Streams plays an important role for interoperability. It is of interest to libraries -and infrastructure components but less useful as an application API, because it is too -low-level. Applications need a higher-level and richer, functional API to -compose async logic -- similar to the Java 8 `Stream` API but not only for collections. -This is the role that reactive libraries play. - -https://github.com/reactor/reactor[Reactor] is the reactive library of choice for -Spring WebFlux. It provides the -https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html[`Mono`] and -https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Flux.html[`Flux`] API types -to work on data sequences of 0..1 (`Mono`) and 0..N (`Flux`) through a rich set of operators aligned with the -ReactiveX https://reactivex.io/documentation/operators.html[vocabulary of operators]. -Reactor is a Reactive Streams library and, therefore, all of its operators support non-blocking back pressure. -Reactor has a strong focus on server-side Java. It is developed in close collaboration -with Spring. - -WebFlux requires Reactor as a core dependency but it is interoperable with other reactive -libraries via Reactive Streams. As a general rule, a WebFlux API accepts a plain `Publisher` -as input, adapts it to a Reactor type internally, uses that, and returns either a -`Flux` or a `Mono` as output. So, you can pass any `Publisher` as input and you can apply -operations on the output, but you need to adapt the output for use with another reactive library. -Whenever feasible (for example, annotated controllers), WebFlux adapts transparently to the use -of RxJava or another reactive library. See <<webflux-reactive-libraries>> for more details. - -NOTE: In addition to Reactive APIs, WebFlux can also be used with -<<languages.adoc#coroutines, Coroutines>> APIs in Kotlin which provides a more imperative style of programming. -The following Kotlin code samples will be provided with Coroutines APIs. - - - -[[webflux-programming-models]] -=== Programming Models - -The `spring-web` module contains the reactive foundation that underlies Spring WebFlux, -including HTTP abstractions, Reactive Streams <<webflux-httphandler, adapters>> for supported -servers, <<webflux-codecs, codecs>>, and a core <<webflux-web-handler-api>> comparable to -the Servlet API but with non-blocking contracts. - -On that foundation, Spring WebFlux provides a choice of two programming models: - -* <<webflux-controller>>: Consistent with Spring MVC and based on the same annotations -from the `spring-web` module. Both Spring MVC and WebFlux controllers support reactive -(Reactor and RxJava) return types, and, as a result, it is not easy to tell them apart. One notable -difference is that WebFlux also supports reactive `@RequestBody` arguments. -* <<webflux-fn>>: Lambda-based, lightweight, and functional programming model. You can think of -this as a small library or a set of utilities that an application can use to route and -handle requests. The big difference with annotated controllers is that the application -is in charge of request handling from start to finish versus declaring intent through -annotations and being called back. - - - -[[webflux-framework-choice]] -=== Applicability - -Spring MVC or WebFlux? - -A natural question to ask but one that sets up an unsound dichotomy. Actually, both -work together to expand the range of available options. The two are designed for -continuity and consistency with each other, they are available side by side, and feedback -from each side benefits both sides. The following diagram shows how the two relate, what they -have in common, and what each supports uniquely: - -image::spring-mvc-and-webflux-venn.png[] - -We suggest that you consider the following specific points: - -* If you have a Spring MVC application that works fine, there is no need to change. -Imperative programming is the easiest way to write, understand, and debug code. -You have maximum choice of libraries, since, historically, most are blocking. - -* If you are already shopping for a non-blocking web stack, Spring WebFlux offers the same -execution model benefits as others in this space and also provides a choice of servers -(Netty, Tomcat, Jetty, Undertow, and Servlet containers), a choice of programming models -(annotated controllers and functional web endpoints), and a choice of reactive libraries -(Reactor, RxJava, or other). - -* If you are interested in a lightweight, functional web framework for use with Java 8 lambdas -or Kotlin, you can use the Spring WebFlux functional web endpoints. That can also be a good choice -for smaller applications or microservices with less complex requirements that can benefit -from greater transparency and control. - -* In a microservice architecture, you can have a mix of applications with either Spring MVC -or Spring WebFlux controllers or with Spring WebFlux functional endpoints. Having support -for the same annotation-based programming model in both frameworks makes it easier to -re-use knowledge while also selecting the right tool for the right job. - -* A simple way to evaluate an application is to check its dependencies. If you have blocking -persistence APIs (JPA, JDBC) or networking APIs to use, Spring MVC is the best choice -for common architectures at least. It is technically feasible with both Reactor and -RxJava to perform blocking calls on a separate thread but you would not be making the -most of a non-blocking web stack. - -* If you have a Spring MVC application with calls to remote services, try the reactive `WebClient`. -You can return reactive types (Reactor, RxJava, <<webflux-reactive-libraries, or other>>) -directly from Spring MVC controller methods. The greater the latency per call or the -interdependency among calls, the more dramatic the benefits. Spring MVC controllers -can call other reactive components too. - -* If you have a large team, keep in mind the steep learning curve in the shift to non-blocking, -functional, and declarative programming. A practical way to start without a full switch -is to use the reactive `WebClient`. Beyond that, start small and measure the benefits. -We expect that, for a wide range of applications, the shift is unnecessary. If you are -unsure what benefits to look for, start by learning about how non-blocking I/O works -(for example, concurrency on single-threaded Node.js) and its effects. - - - -[[webflux-server-choice]] -=== Servers - -Spring WebFlux is supported on Tomcat, Jetty, Servlet containers, as well as on -non-Servlet runtimes such as Netty and Undertow. All servers are adapted to a low-level, -<<webflux-httphandler, common API>> so that higher-level -<<webflux-programming-models, programming models>> can be supported across servers. - -Spring WebFlux does not have built-in support to start or stop a server. However, it is -easy to <<webflux-web-handler-api, assemble>> an application from Spring configuration and -<<webflux-config, WebFlux infrastructure>> and <<webflux-httphandler, run it>> with a few -lines of code. - -Spring Boot has a WebFlux starter that automates these steps. By default, the starter uses -Netty, but it is easy to switch to Tomcat, Jetty, or Undertow by changing your -Maven or Gradle dependencies. Spring Boot defaults to Netty, because it is more widely -used in the asynchronous, non-blocking space and lets a client and a server share resources. - -Tomcat and Jetty can be used with both Spring MVC and WebFlux. Keep in mind, however, that -the way they are used is very different. Spring MVC relies on Servlet blocking I/O and -lets applications use the Servlet API directly if they need to. Spring WebFlux -relies on Servlet non-blocking I/O and uses the Servlet API behind a low-level -adapter. It is not exposed for direct use. - -For Undertow, Spring WebFlux uses Undertow APIs directly without the Servlet API. - - - -[[webflux-performance]] -=== Performance - -Performance has many characteristics and meanings. Reactive and non-blocking generally -do not make applications run faster. They can, in some cases, (for example, if using the -`WebClient` to run remote calls in parallel). On the whole, it requires more work to do -things the non-blocking way and that can slightly increase the required processing time. - -The key expected benefit of reactive and non-blocking is the ability to scale with a small, -fixed number of threads and less memory. That makes applications more resilient under load, -because they scale in a more predictable way. In order to observe those benefits, however, you -need to have some latency (including a mix of slow and unpredictable network I/O). -That is where the reactive stack begins to show its strengths, and the differences can be -dramatic. - - - -[[webflux-concurrency-model]] -=== Concurrency Model - -Both Spring MVC and Spring WebFlux support annotated controllers, but there is a key -difference in the concurrency model and the default assumptions for blocking and threads. - -In Spring MVC (and servlet applications in general), it is assumed that applications can -block the current thread, (for example, for remote calls). For this reason, servlet containers -use a large thread pool to absorb potential blocking during request handling. - -In Spring WebFlux (and non-blocking servers in general), it is assumed that applications -do not block. Therefore, non-blocking servers use a small, fixed-size thread pool -(event loop workers) to handle requests. - -TIP: "`To scale`" and "`small number of threads`" may sound contradictory but to never block the -current thread (and rely on callbacks instead) means that you do not need extra threads, as -there are no blocking calls to absorb. - - -[[invoking-a-blocking-api]] -==== Invoking a Blocking API - -What if you do need to use a blocking library? Both Reactor and RxJava provide the -`publishOn` operator to continue processing on a different thread. That means there is an -easy escape hatch. Keep in mind, however, that blocking APIs are not a good fit for -this concurrency model. - -[[mutable-state]] -==== Mutable State - -In Reactor and RxJava, you declare logic through operators. At runtime, a reactive -pipeline is formed where data is processed sequentially, in distinct stages. A key benefit -of this is that it frees applications from having to protect mutable state because -application code within that pipeline is never invoked concurrently. - -[[threading-model]] -==== Threading Model - -What threads should you expect to see on a server running with Spring WebFlux? - -* On a "`vanilla`" Spring WebFlux server (for example, no data access nor other optional -dependencies), you can expect one thread for the server and several others for request -processing (typically as many as the number of CPU cores). Servlet containers, however, -may start with more threads (for example, 10 on Tomcat), in support of both servlet (blocking) I/O -and servlet 3.1 (non-blocking) I/O usage. - -* The reactive `WebClient` operates in event loop style. So you can see a small, fixed -number of processing threads related to that (for example, `reactor-http-nio-` with the Reactor -Netty connector). However, if Reactor Netty is used for both client and server, the two -share event loop resources by default. - -* Reactor and RxJava provide thread pool abstractions, called schedulers, to use with the -`publishOn` operator that is used to switch processing to a different thread pool. -The schedulers have names that suggest a specific concurrency strategy -- for example, "`parallel`" -(for CPU-bound work with a limited number of threads) or "`elastic`" (for I/O-bound work with -a large number of threads). If you see such threads, it means some code is using a -specific thread pool `Scheduler` strategy. - -* Data access libraries and other third party dependencies can also create and use threads -of their own. - -[[configuring]] -==== Configuring - -The Spring Framework does not provide support for starting and stopping -<<webflux-server-choice, servers>>. To configure the threading model for a server, -you need to use server-specific configuration APIs, or, if you use Spring Boot, -check the Spring Boot configuration options for each server. You can -<<web-reactive.adoc#webflux-client-builder, configure>> the `WebClient` directly. -For all other libraries, see their respective documentation. - - - - -[[webflux-reactive-spring-web]] -== Reactive Core - -The `spring-web` module contains the following foundational support for reactive web -applications: - -* For server request processing there are two levels of support. -** <<webflux-httphandler, HttpHandler>>: Basic contract for HTTP request handling with -non-blocking I/O and Reactive Streams back pressure, along with adapters for Reactor Netty, -Undertow, Tomcat, Jetty, and any Servlet container. -** <<webflux-web-handler-api>>: Slightly higher level, general-purpose web API for -request handling, on top of which concrete programming models such as annotated -controllers and functional endpoints are built. -* For the client side, there is a basic `ClientHttpConnector` contract to perform HTTP -requests with non-blocking I/O and Reactive Streams back pressure, along with adapters for -https://github.com/reactor/reactor-netty[Reactor Netty], reactive -https://github.com/jetty-project/jetty-reactive-httpclient[Jetty HttpClient] -and https://hc.apache.org/[Apache HttpComponents]. -The higher level <<web-reactive.adoc#webflux-client, WebClient>> used in applications -builds on this basic contract. -* For client and server, <<webflux-codecs, codecs>> for serialization and -deserialization of HTTP request and response content. - - - -[[webflux-httphandler]] -=== `HttpHandler` - -{api-spring-framework}/http/server/reactive/HttpHandler.html[HttpHandler] -is a simple contract with a single method to handle a request and a response. It is -intentionally minimal, and its main and only purpose is to be a minimal abstraction -over different HTTP server APIs. - -The following table describes the supported server APIs: - -[cols="1,2,2", options="header"] -|=== -| Server name | Server API used | Reactive Streams support - -| Netty -| Netty API -| https://github.com/reactor/reactor-netty[Reactor Netty] - -| Undertow -| Undertow API -| spring-web: Undertow to Reactive Streams bridge - -| Tomcat -| Servlet non-blocking I/O; Tomcat API to read and write ByteBuffers vs byte[] -| spring-web: Servlet non-blocking I/O to Reactive Streams bridge - -| Jetty -| Servlet non-blocking I/O; Jetty API to write ByteBuffers vs byte[] -| spring-web: Servlet non-blocking I/O to Reactive Streams bridge - -| Servlet container -| Servlet non-blocking I/O -| spring-web: Servlet non-blocking I/O to Reactive Streams bridge -|=== - -The following table describes server dependencies (also see -https://github.com/spring-projects/spring-framework/wiki/What%27s-New-in-the-Spring-Framework[supported versions]): - -|=== -|Server name|Group id|Artifact name - -|Reactor Netty -|io.projectreactor.netty -|reactor-netty - -|Undertow -|io.undertow -|undertow-core - -|Tomcat -|org.apache.tomcat.embed -|tomcat-embed-core - -|Jetty -|org.eclipse.jetty -|jetty-server, jetty-servlet -|=== - -The code snippets below show using the `HttpHandler` adapters with each server API: - -*Reactor Netty* -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpHandler handler = ... - ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(handler); - HttpServer.create().host(host).port(port).handle(adapter).bindNow(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val handler: HttpHandler = ... - val adapter = ReactorHttpHandlerAdapter(handler) - HttpServer.create().host(host).port(port).handle(adapter).bindNow() ----- - -*Undertow* -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpHandler handler = ... - UndertowHttpHandlerAdapter adapter = new UndertowHttpHandlerAdapter(handler); - Undertow server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build(); - server.start(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val handler: HttpHandler = ... - val adapter = UndertowHttpHandlerAdapter(handler) - val server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build() - server.start() ----- - -*Tomcat* -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpHandler handler = ... - Servlet servlet = new TomcatHttpHandlerAdapter(handler); - - Tomcat server = new Tomcat(); - File base = new File(System.getProperty("java.io.tmpdir")); - Context rootContext = server.addContext("", base.getAbsolutePath()); - Tomcat.addServlet(rootContext, "main", servlet); - rootContext.addServletMappingDecoded("/", "main"); - server.setHost(host); - server.setPort(port); - server.start(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val handler: HttpHandler = ... - val servlet = TomcatHttpHandlerAdapter(handler) - - val server = Tomcat() - val base = File(System.getProperty("java.io.tmpdir")) - val rootContext = server.addContext("", base.absolutePath) - Tomcat.addServlet(rootContext, "main", servlet) - rootContext.addServletMappingDecoded("/", "main") - server.host = host - server.setPort(port) - server.start() ----- - -*Jetty* - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpHandler handler = ... - Servlet servlet = new JettyHttpHandlerAdapter(handler); - - Server server = new Server(); - ServletContextHandler contextHandler = new ServletContextHandler(server, ""); - contextHandler.addServlet(new ServletHolder(servlet), "/"); - contextHandler.start(); - - ServerConnector connector = new ServerConnector(server); - connector.setHost(host); - connector.setPort(port); - server.addConnector(connector); - server.start(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val handler: HttpHandler = ... - val servlet = JettyHttpHandlerAdapter(handler) - - val server = Server() - val contextHandler = ServletContextHandler(server, "") - contextHandler.addServlet(ServletHolder(servlet), "/") - contextHandler.start(); - - val connector = ServerConnector(server) - connector.host = host - connector.port = port - server.addConnector(connector) - server.start() ----- - -*Servlet Container* - -To deploy as a WAR to any Servlet container, you can extend and include -{api-spring-framework}/web/server/adapter/AbstractReactiveWebInitializer.html[`AbstractReactiveWebInitializer`] -in the WAR. That class wraps an `HttpHandler` with `ServletHttpHandlerAdapter` and registers -that as a `Servlet`. - - - -[[webflux-web-handler-api]] -=== `WebHandler` API - -The `org.springframework.web.server` package builds on the <<webflux-httphandler>> contract -to provide a general-purpose web API for processing requests through a chain of multiple -{api-spring-framework}/web/server/WebExceptionHandler.html[`WebExceptionHandler`], multiple -{api-spring-framework}/web/server/WebFilter.html[`WebFilter`], and a single -{api-spring-framework}/web/server/WebHandler.html[`WebHandler`] component. The chain can -be put together with `WebHttpHandlerBuilder` by simply pointing to a Spring -`ApplicationContext` where components are -<<webflux-web-handler-api-special-beans, auto-detected>>, and/or by registering components -with the builder. - -While `HttpHandler` has a simple goal to abstract the use of different HTTP servers, the -`WebHandler` API aims to provide a broader set of features commonly used in web applications -such as: - -* User session with attributes. -* Request attributes. -* Resolved `Locale` or `Principal` for the request. -* Access to parsed and cached form data. -* Abstractions for multipart data. -* and more.. - -[[webflux-web-handler-api-special-beans]] -==== Special bean types - -The table below lists the components that `WebHttpHandlerBuilder` can auto-detect in a -Spring ApplicationContext, or that can be registered directly with it: - -[cols="2,2,1,3", options="header"] -|=== -| Bean name | Bean type | Count | Description - -| <any> -| `WebExceptionHandler` -| 0..N -| Provide handling for exceptions from the chain of `WebFilter` instances and the target - `WebHandler`. For more details, see <<webflux-exception-handler>>. - -| <any> -| `WebFilter` -| 0..N -| Apply interception style logic to before and after the rest of the filter chain and - the target `WebHandler`. For more details, see <<webflux-filters>>. - -| `webHandler` -| `WebHandler` -| 1 -| The handler for the request. - -| `webSessionManager` -| `WebSessionManager` -| 0..1 -| The manager for `WebSession` instances exposed through a method on `ServerWebExchange`. - `DefaultWebSessionManager` by default. - -| `serverCodecConfigurer` -| `ServerCodecConfigurer` -| 0..1 -| For access to `HttpMessageReader` instances for parsing form data and multipart data that is then - exposed through methods on `ServerWebExchange`. `ServerCodecConfigurer.create()` by default. - -| `localeContextResolver` -| `LocaleContextResolver` -| 0..1 -| The resolver for `LocaleContext` exposed through a method on `ServerWebExchange`. - `AcceptHeaderLocaleContextResolver` by default. - -| `forwardedHeaderTransformer` -| `ForwardedHeaderTransformer` -| 0..1 -| For processing forwarded type headers, either by extracting and removing them or by removing them only. - Not used by default. -|=== - - -[[webflux-form-data]] -==== Form Data - -`ServerWebExchange` exposes the following method for accessing form data: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<MultiValueMap<String, String>> getFormData(); ----- -[source,Kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - suspend fun getFormData(): MultiValueMap<String, String> ----- - -The `DefaultServerWebExchange` uses the configured `HttpMessageReader` to parse form data -(`application/x-www-form-urlencoded`) into a `MultiValueMap`. By default, -`FormHttpMessageReader` is configured for use by the `ServerCodecConfigurer` bean -(see the <<webflux-web-handler-api, Web Handler API>>). - - -[[webflux-multipart]] -==== Multipart Data -[.small]#<<web.adoc#mvc-multipart, See equivalent in the Servlet stack>># - -`ServerWebExchange` exposes the following method for accessing multipart data: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Mono<MultiValueMap<String, Part>> getMultipartData(); ----- -[source,Kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - suspend fun getMultipartData(): MultiValueMap<String, Part> ----- - -The `DefaultServerWebExchange` uses the configured -`HttpMessageReader<MultiValueMap<String, Part>>` to parse `multipart/form-data`, -`multipart/mixed`, and `multipart/related` content into a `MultiValueMap`. -By default, this is the `DefaultPartHttpMessageReader`, which does not have any third-party -dependencies. -Alternatively, the `SynchronossPartHttpMessageReader` can be used, which is based on the -https://github.com/synchronoss/nio-multipart[Synchronoss NIO Multipart] library. -Both are configured through the `ServerCodecConfigurer` bean -(see the <<webflux-web-handler-api, Web Handler API>>). - -To parse multipart data in streaming fashion, you can use the `Flux<PartEvent>` returned from the -`PartEventHttpMessageReader` instead of using `@RequestPart`, as that implies `Map`-like access -to individual parts by name and, hence, requires parsing multipart data in full. -By contrast, you can use `@RequestBody` to decode the content to `Flux<PartEvent>` without -collecting to a `MultiValueMap`. - - -[[webflux-forwarded-headers]] -==== Forwarded Headers -[.small]#<<web.adoc#filters-forwarded-headers, See equivalent in the Servlet stack>># - -As a request goes through proxies (such as load balancers), the host, port, and -scheme may change. That makes it a challenge, from a client perspective, to create links that point to the correct -host, port, and scheme. - -https://tools.ietf.org/html/rfc7239[RFC 7239] defines the `Forwarded` HTTP header -that proxies can use to provide information about the original request. There are other -non-standard headers, too, including `X-Forwarded-Host`, `X-Forwarded-Port`, -`X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`. - -`ForwardedHeaderTransformer` is a component that modifies the host, port, and scheme of -the request, based on forwarded headers, and then removes those headers. If you declare -it as a bean with the name `forwardedHeaderTransformer`, it will be -<<webflux-web-handler-api-special-beans, detected>> and used. - -There are security considerations for forwarded headers, since an application cannot know -if the headers were added by a proxy, as intended, or by a malicious client. This is why -a proxy at the boundary of trust should be configured to remove untrusted forwarded traffic coming -from the outside. You can also configure the `ForwardedHeaderTransformer` with -`removeOnly=true`, in which case it removes but does not use the headers. - -NOTE: In 5.1 `ForwardedHeaderFilter` was deprecated and superseded by -`ForwardedHeaderTransformer` so forwarded headers can be processed earlier, before the -exchange is created. If the filter is configured anyway, it is taken out of the list of -filters, and `ForwardedHeaderTransformer` is used instead. - - - -[[webflux-filters]] -=== Filters -[.small]#<<web.adoc#filters, See equivalent in the Servlet stack>># - -In the <<webflux-web-handler-api>>, you can use a `WebFilter` to apply interception-style -logic before and after the rest of the processing chain of filters and the target -`WebHandler`. When using the <<webflux-config>>, registering a `WebFilter` is as simple -as declaring it as a Spring bean and (optionally) expressing precedence by using `@Order` on -the bean declaration or by implementing `Ordered`. - - -[[webflux-filters-cors]] -==== CORS -[.small]#<<web.adoc#filters-cors, See equivalent in the Servlet stack>># - -Spring WebFlux provides fine-grained support for CORS configuration through annotations on -controllers. However, when you use it with Spring Security, we advise relying on the built-in -`CorsFilter`, which must be ordered ahead of Spring Security's chain of filters. - -See the section on <<webflux-cors>> and the <<webflux-cors-webfilter>> for more details. - - -[[webflux-exception-handler]] -=== Exceptions -[.small]#<<web.adoc#mvc-ann-customer-servlet-container-error-page, See equivalent in the Servlet stack>># - -In the <<webflux-web-handler-api>>, you can use a `WebExceptionHandler` to handle -exceptions from the chain of `WebFilter` instances and the target `WebHandler`. When using the -<<webflux-config>>, registering a `WebExceptionHandler` is as simple as declaring it as a -Spring bean and (optionally) expressing precedence by using `@Order` on the bean declaration or -by implementing `Ordered`. - -The following table describes the available `WebExceptionHandler` implementations: - -[cols="1,2", options="header"] -|=== -| Exception Handler | Description - -| `ResponseStatusExceptionHandler` -| Provides handling for exceptions of type - {api-spring-framework}/web/server/ResponseStatusException.html[`ResponseStatusException`] - by setting the response to the HTTP status code of the exception. - -| `WebFluxResponseStatusExceptionHandler` -| Extension of `ResponseStatusExceptionHandler` that can also determine the HTTP status - code of a `@ResponseStatus` annotation on any exception. - - This handler is declared in the <<webflux-config>>. - -|=== - - - -[[webflux-codecs]] -=== Codecs -[.small]#<<integration.adoc#rest-message-conversion, See equivalent in the Servlet stack>># - -The `spring-web` and `spring-core` modules provide support for serializing and -deserializing byte content to and from higher level objects through non-blocking I/O with -Reactive Streams back pressure. The following describes this support: - -* {api-spring-framework}/core/codec/Encoder.html[`Encoder`] and -{api-spring-framework}/core/codec/Decoder.html[`Decoder`] are low level contracts to -encode and decode content independent of HTTP. -* {api-spring-framework}/http/codec/HttpMessageReader.html[`HttpMessageReader`] and -{api-spring-framework}/http/codec/HttpMessageWriter.html[`HttpMessageWriter`] are contracts -to encode and decode HTTP message content. -* An `Encoder` can be wrapped with `EncoderHttpMessageWriter` to adapt it for use in a web -application, while a `Decoder` can be wrapped with `DecoderHttpMessageReader`. -* {api-spring-framework}/core/io/buffer/DataBuffer.html[`DataBuffer`] abstracts different -byte buffer representations (e.g. Netty `ByteBuf`, `java.nio.ByteBuffer`, etc.) and is -what all codecs work on. See <<core#databuffers,Data Buffers and Codecs>> in the -"Spring Core" section for more on this topic. - -The `spring-core` module provides `byte[]`, `ByteBuffer`, `DataBuffer`, `Resource`, and -`String` encoder and decoder implementations. The `spring-web` module provides Jackson -JSON, Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders along with -web-only HTTP message reader and writer implementations for form data, multipart content, -server-sent events, and others. - -`ClientCodecConfigurer` and `ServerCodecConfigurer` are typically used to configure and -customize the codecs to use in an application. See the section on configuring -<<webflux-config-message-codecs>>. - -[[webflux-codecs-jackson]] -==== Jackson JSON - -JSON and binary JSON (https://github.com/FasterXML/smile-format-specification[Smile]) are -both supported when the Jackson library is present. - -The `Jackson2Decoder` works as follows: - -* Jackson's asynchronous, non-blocking parser is used to aggregate a stream of byte chunks -into ``TokenBuffer``'s each representing a JSON object. -* Each `TokenBuffer` is passed to Jackson's `ObjectMapper` to create a higher level object. -* When decoding to a single-value publisher (e.g. `Mono`), there is one `TokenBuffer`. -* When decoding to a multi-value publisher (e.g. `Flux`), each `TokenBuffer` is passed to -the `ObjectMapper` as soon as enough bytes are received for a fully formed object. The -input content can be a JSON array, or any -https://en.wikipedia.org/wiki/JSON_streaming[line-delimited JSON] format such as NDJSON, -JSON Lines, or JSON Text Sequences. - -The `Jackson2Encoder` works as follows: - -* For a single value publisher (e.g. `Mono`), simply serialize it through the -`ObjectMapper`. -* For a multi-value publisher with `application/json`, by default collect the values with -`Flux#collectToList()` and then serialize the resulting collection. -* For a multi-value publisher with a streaming media type such as -`application/x-ndjson` or `application/stream+x-jackson-smile`, encode, write, and -flush each value individually using a -https://en.wikipedia.org/wiki/JSON_streaming[line-delimited JSON] format. Other -streaming media types may be registered with the encoder. -* For SSE the `Jackson2Encoder` is invoked per event and the output is flushed to ensure -delivery without delay. - -[NOTE] -==== -By default both `Jackson2Encoder` and `Jackson2Decoder` do not support elements of type -`String`. Instead the default assumption is that a string or a sequence of strings -represent serialized JSON content, to be rendered by the `CharSequenceEncoder`. If what -you need is to render a JSON array from `Flux<String>`, use `Flux#collectToList()` and -encode a `Mono<List<String>>`. -==== - -[[webflux-codecs-forms]] -==== Form Data - -`FormHttpMessageReader` and `FormHttpMessageWriter` support decoding and encoding -`application/x-www-form-urlencoded` content. - -On the server side where form content often needs to be accessed from multiple places, -`ServerWebExchange` provides a dedicated `getFormData()` method that parses the content -through `FormHttpMessageReader` and then caches the result for repeated access. -See <<webflux-form-data>> in the <<webflux-web-handler-api>> section. - -Once `getFormData()` is used, the original raw content can no longer be read from the -request body. For this reason, applications are expected to go through `ServerWebExchange` -consistently for access to the cached form data versus reading from the raw request body. - - -[[webflux-codecs-multipart]] -==== Multipart - -`MultipartHttpMessageReader` and `MultipartHttpMessageWriter` support decoding and -encoding "multipart/form-data", "multipart/mixed", and "multipart/related" content. -In turn `MultipartHttpMessageReader` delegates to another `HttpMessageReader` -for the actual parsing to a `Flux<Part>` and then simply collects the parts into a `MultiValueMap`. -By default, the `DefaultPartHttpMessageReader` is used, but this can be changed through the -`ServerCodecConfigurer`. -For more information about the `DefaultPartHttpMessageReader`, refer to the -{api-spring-framework}/http/codec/multipart/DefaultPartHttpMessageReader.html[javadoc of `DefaultPartHttpMessageReader`]. - -On the server side where multipart form content may need to be accessed from multiple -places, `ServerWebExchange` provides a dedicated `getMultipartData()` method that parses -the content through `MultipartHttpMessageReader` and then caches the result for repeated access. -See <<webflux-multipart>> in the <<webflux-web-handler-api>> section. - -Once `getMultipartData()` is used, the original raw content can no longer be read from the -request body. For this reason applications have to consistently use `getMultipartData()` -for repeated, map-like access to parts, or otherwise rely on the -`SynchronossPartHttpMessageReader` for a one-time access to `Flux<Part>`. - - -[[webflux-codecs-limits]] -==== Limits - -`Decoder` and `HttpMessageReader` implementations that buffer some or all of the input -stream can be configured with a limit on the maximum number of bytes to buffer in memory. -In some cases buffering occurs because input is aggregated and represented as a single -object — for example, a controller method with `@RequestBody byte[]`, -`x-www-form-urlencoded` data, and so on. Buffering can also occur with streaming, when -splitting the input stream — for example, delimited text, a stream of JSON objects, and -so on. For those streaming cases, the limit applies to the number of bytes associated -with one object in the stream. - -To configure buffer sizes, you can check if a given `Decoder` or `HttpMessageReader` -exposes a `maxInMemorySize` property and if so the Javadoc will have details about default -values. On the server side, `ServerCodecConfigurer` provides a single place from where to -set all codecs, see <<webflux-config-message-codecs>>. On the client side, the limit for -all codecs can be changed in -<<web-reactive.adoc#webflux-client-builder-maxinmemorysize, WebClient.Builder>>. - -For <<webflux-codecs-multipart,Multipart parsing>> the `maxInMemorySize` property limits -the size of non-file parts. For file parts, it determines the threshold at which the part -is written to disk. For file parts written to disk, there is an additional -`maxDiskUsagePerPart` property to limit the amount of disk space per part. There is also -a `maxParts` property to limit the overall number of parts in a multipart request. -To configure all three in WebFlux, you'll need to supply a pre-configured instance of -`MultipartHttpMessageReader` to `ServerCodecConfigurer`. - - - -[[webflux-codecs-streaming]] -==== Streaming -[.small]#<<web.adoc#mvc-ann-async-http-streaming, See equivalent in the Servlet stack>># - -When streaming to the HTTP response (for example, `text/event-stream`, -`application/x-ndjson`), it is important to send data periodically, in order to -reliably detect a disconnected client sooner rather than later. Such a send could be a -comment-only, empty SSE event or any other "no-op" data that would effectively serve as -a heartbeat. - - -[[webflux-codecs-buffers]] -==== `DataBuffer` - -`DataBuffer` is the representation for a byte buffer in WebFlux. The Spring Core part of -this reference has more on that in the section on -<<core#databuffers, Data Buffers and Codecs>>. The key point to understand is that on some -servers like Netty, byte buffers are pooled and reference counted, and must be released -when consumed to avoid memory leaks. - -WebFlux applications generally do not need to be concerned with such issues, unless they -consume or produce data buffers directly, as opposed to relying on codecs to convert to -and from higher level objects, or unless they choose to create custom codecs. For such -cases please review the information in <<core#databuffers, Data Buffers and Codecs>>, -especially the section on <<core#databuffers-using, Using DataBuffer>>. - - - -[[webflux-logging]] -=== Logging -[.small]#<<web.adoc#mvc-logging, See equivalent in the Servlet stack>># - -`DEBUG` level logging in Spring WebFlux is designed to be compact, minimal, and -human-friendly. It focuses on high value bits of information that are useful over and -over again vs others that are useful only when debugging a specific issue. - -`TRACE` level logging generally follows the same principles as `DEBUG` (and for example also -should not be a firehose) but can be used for debugging any issue. In addition, some log -messages may show a different level of detail at `TRACE` vs `DEBUG`. - -Good logging comes from the experience of using the logs. If you spot anything that does -not meet the stated goals, please let us know. - - -[[webflux-logging-id]] -==== Log Id - -In WebFlux, a single request can be run over multiple threads and the thread ID -is not useful for correlating log messages that belong to a specific request. This is why -WebFlux log messages are prefixed with a request-specific ID by default. - -On the server side, the log ID is stored in the `ServerWebExchange` attribute -({api-spring-framework}/web/server/ServerWebExchange.html#LOG_ID_ATTRIBUTE[`LOG_ID_ATTRIBUTE`]), -while a fully formatted prefix based on that ID is available from -`ServerWebExchange#getLogPrefix()`. On the `WebClient` side, the log ID is stored in the -`ClientRequest` attribute -({api-spring-framework}/web/reactive/function/client/ClientRequest.html#LOG_ID_ATTRIBUTE[`LOG_ID_ATTRIBUTE`]) -,while a fully formatted prefix is available from `ClientRequest#logPrefix()`. - - -[[webflux-logging-sensitive-data]] -==== Sensitive Data -[.small]#<<web.adoc#mvc-logging-sensitive-data, See equivalent in the Servlet stack>># - -`DEBUG` and `TRACE` logging can log sensitive information. This is why form parameters and -headers are masked by default and you must explicitly enable their logging in full. - -The following example shows how to do so for server-side requests: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - class MyConfig implements WebFluxConfigurer { - - @Override - public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) { - configurer.defaultCodecs().enableLoggingRequestDetails(true); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class MyConfig : WebFluxConfigurer { - - override fun configureHttpMessageCodecs(configurer: ServerCodecConfigurer) { - configurer.defaultCodecs().enableLoggingRequestDetails(true) - } - } ----- - -The following example shows how to do so for client-side requests: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - Consumer<ClientCodecConfigurer> consumer = configurer -> - configurer.defaultCodecs().enableLoggingRequestDetails(true); - - WebClient webClient = WebClient.builder() - .exchangeStrategies(strategies -> strategies.codecs(consumer)) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val consumer: (ClientCodecConfigurer) -> Unit = { configurer -> configurer.defaultCodecs().enableLoggingRequestDetails(true) } - - val webClient = WebClient.builder() - .exchangeStrategies({ strategies -> strategies.codecs(consumer) }) - .build() ----- - - -[[webflux-logging-appenders]] -==== Appenders - -Logging libraries such as SLF4J and Log4J 2 provide asynchronous loggers that avoid -blocking. While those have their own drawbacks such as potentially dropping messages -that could not be queued for logging, they are the best available options currently -for use in a reactive, non-blocking application. - - - -[[webflux-codecs-custom]] -==== Custom codecs - -Applications can register custom codecs for supporting additional media types, -or specific behaviors that are not supported by the default codecs. - -Some configuration options expressed by developers are enforced on default codecs. -Custom codecs might want to get a chance to align with those preferences, -like <<webflux-codecs-limits, enforcing buffering limits>> -or <<webflux-logging-sensitive-data, logging sensitive data>>. - -The following example shows how to do so for client-side requests: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - WebClient webClient = WebClient.builder() - .codecs(configurer -> { - CustomDecoder decoder = new CustomDecoder(); - configurer.customCodecs().registerWithDefaultConfig(decoder); - }) - .build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val webClient = WebClient.builder() - .codecs({ configurer -> - val decoder = CustomDecoder() - configurer.customCodecs().registerWithDefaultConfig(decoder) - }) - .build() ----- - -[[webflux-dispatcher-handler]] -== `DispatcherHandler` -[.small]#<<web.adoc#mvc-servlet, See equivalent in the Servlet stack>># - -Spring WebFlux, similarly to Spring MVC, is designed around the front controller pattern, -where a central `WebHandler`, the `DispatcherHandler`, provides a shared algorithm for -request processing, while actual work is performed by configurable, delegate components. -This model is flexible and supports diverse workflows. - -`DispatcherHandler` discovers the delegate components it needs from Spring configuration. -It is also designed to be a Spring bean itself and implements `ApplicationContextAware` -for access to the context in which it runs. If `DispatcherHandler` is declared with a bean -name of `webHandler`, it is, in turn, discovered by -{api-spring-framework}/web/server/adapter/WebHttpHandlerBuilder.html[`WebHttpHandlerBuilder`], -which puts together a request-processing chain, as described in <<webflux-web-handler-api>>. - -Spring configuration in a WebFlux application typically contains: - -* `DispatcherHandler` with the bean name `webHandler` -* `WebFilter` and `WebExceptionHandler` beans -* <<webflux-special-bean-types,`DispatcherHandler` special beans>> -* Others - -The configuration is given to `WebHttpHandlerBuilder` to build the processing chain, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ApplicationContext context = ... - HttpHandler handler = WebHttpHandlerBuilder.applicationContext(context).build(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val context: ApplicationContext = ... - val handler = WebHttpHandlerBuilder.applicationContext(context).build() ----- - -The resulting `HttpHandler` is ready for use with a <<webflux-httphandler, server adapter>>. - - - -[[webflux-special-bean-types]] -=== Special Bean Types -[.small]#<<web.adoc#mvc-servlet-special-bean-types, See equivalent in the Servlet stack>># - -The `DispatcherHandler` delegates to special beans to process requests and render the -appropriate responses. By "`special beans,`" we mean Spring-managed `Object` instances that -implement WebFlux framework contracts. Those usually come with built-in contracts, but -you can customize their properties, extend them, or replace them. - -The following table lists the special beans detected by the `DispatcherHandler`. Note that -there are also some other beans detected at a lower level (see -<<webflux-web-handler-api-special-beans>> in the Web Handler API). - -[[webflux-special-beans-table]] -[cols="1,2", options="header"] -|=== -| Bean type | Explanation - -| `HandlerMapping` -| Map a request to a handler. The mapping is based on some criteria, the details of - which vary by `HandlerMapping` implementation -- annotated controllers, simple - URL pattern mappings, and others. - - The main `HandlerMapping` implementations are `RequestMappingHandlerMapping` for - `@RequestMapping` annotated methods, `RouterFunctionMapping` for functional endpoint - routes, and `SimpleUrlHandlerMapping` for explicit registrations of URI path patterns - and `WebHandler` instances. - -| `HandlerAdapter` -| Help the `DispatcherHandler` to invoke a handler mapped to a request regardless of - how the handler is actually invoked. For example, invoking an annotated controller - requires resolving annotations. The main purpose of a `HandlerAdapter` is to shield the - `DispatcherHandler` from such details. - -| `HandlerResultHandler` -| Process the result from the handler invocation and finalize the response. - See <<webflux-resulthandling>>. - -|=== - - - -[[webflux-framework-config]] -=== WebFlux Config -[.small]#<<web.adoc#mvc-servlet-config, See equivalent in the Servlet stack>># - -Applications can declare the infrastructure beans (listed under -<<webflux-web-handler-api-special-beans, Web Handler API>> and -<<webflux-special-bean-types, `DispatcherHandler`>>) that are required to process requests. -However, in most cases, the <<webflux-config>> is the best starting point. It declares the -required beans and provides a higher-level configuration callback API to customize it. - -NOTE: Spring Boot relies on the WebFlux config to configure Spring WebFlux and also provides -many extra convenient options. - - - -[[webflux-dispatcher-handler-sequence]] -=== Processing -[.small]#<<web.adoc#mvc-servlet-sequence, See equivalent in the Servlet stack>># - -`DispatcherHandler` processes requests as follows: - -* Each `HandlerMapping` is asked to find a matching handler, and the first match is used. -* If a handler is found, it is run through an appropriate `HandlerAdapter`, which -exposes the return value from the execution as `HandlerResult`. -* The `HandlerResult` is given to an appropriate `HandlerResultHandler` to complete -processing by writing to the response directly or by using a view to render. - - - -[[webflux-resulthandling]] -=== Result Handling - -The return value from the invocation of a handler, through a `HandlerAdapter`, is wrapped -as a `HandlerResult`, along with some additional context, and passed to the first -`HandlerResultHandler` that claims support for it. The following table shows the available -`HandlerResultHandler` implementations, all of which are declared in the <<webflux-config>>: - -[cols="1,2,1", options="header"] -|=== -| Result Handler Type | Return Values | Default Order - -| `ResponseEntityResultHandler` -| `ResponseEntity`, typically from `@Controller` instances. -| 0 - -| `ServerResponseResultHandler` -| `ServerResponse`, typically from functional endpoints. -| 0 - -| `ResponseBodyResultHandler` -| Handle return values from `@ResponseBody` methods or `@RestController` classes. -| 100 - -| `ViewResolutionResultHandler` -| `CharSequence`, {api-spring-framework}/web/reactive/result/view/View.html[`View`], - {api-spring-framework}/ui/Model.html[Model], `Map`, - {api-spring-framework}/web/reactive/result/view/Rendering.html[Rendering], - or any other `Object` is treated as a model attribute. - - See also <<webflux-viewresolution>>. -| `Integer.MAX_VALUE` - -|=== - - - -[[webflux-dispatcher-exceptions]] -=== Exceptions -[.small]#<<web.adoc#mvc-exceptionhandlers, See equivalent in the Servlet stack>># - -`HandlerAdapter` implementations can handle internally exceptions from invoking a request -handler, such as a controller method. However, an exception may be deferred if the request -handler returns an asynchronous value. - -A `HandlerAdapter` may expose its exception handling mechanism as a -`DispatchExceptionHandler` set on the `HandlerResult` it returns. When that's set, -`DispatcherHandler` will also apply it to the handling of the result. - -A `HandlerAdapter` may also choose to implement `DispatchExceptionHandler`. In that case -`DispatcherHandler` will apply it to exceptions that arise before a handler is mapped, -e.g. during handler mapping, or earlier, e.g. in a `WebFilter`. - -See also <<webflux-ann-controller-exceptions>> in the "`Annotated Controller`" section or -<<webflux-exception-handler>> in the WebHandler API section. - - - -[[webflux-viewresolution]] -=== View Resolution -[.small]#<<web.adoc#mvc-viewresolver, See equivalent in the Servlet stack>># - -View resolution enables rendering to a browser with an HTML template and a model without -tying you to a specific view technology. In Spring WebFlux, view resolution is -supported through a dedicated <<webflux-resulthandling, HandlerResultHandler>> that uses - `ViewResolver` instances to map a String (representing a logical view name) to a `View` -instance. The `View` is then used to render the response. - - -[[webflux-viewresolution-handling]] -==== Handling -[.small]#<<web.adoc#mvc-viewresolver-handling, See equivalent in the Servlet stack>># - -The `HandlerResult` passed into `ViewResolutionResultHandler` contains the return value -from the handler and the model that contains attributes added during request -handling. The return value is processed as one of the following: - -* `String`, `CharSequence`: A logical view name to be resolved to a `View` through -the list of configured `ViewResolver` implementations. -* `void`: Select a default view name based on the request path, minus the leading and -trailing slash, and resolve it to a `View`. The same also happens when a view name -was not provided (for example, model attribute was returned) or an async return value -(for example, `Mono` completed empty). -* {api-spring-framework}/web/reactive/result/view/Rendering.html[Rendering]: API for -view resolution scenarios. Explore the options in your IDE with code completion. -* `Model`, `Map`: Extra model attributes to be added to the model for the request. -* Any other: Any other return value (except for simple types, as determined by -{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) -is treated as a model attribute to be added to the model. The attribute name is derived -from the class name by using {api-spring-framework}/core/Conventions.html[conventions], -unless a handler method `@ModelAttribute` annotation is present. - -The model can contain asynchronous, reactive types (for example, from Reactor or RxJava). Prior -to rendering, `AbstractView` resolves such model attributes into concrete values -and updates the model. Single-value reactive types are resolved to a single -value or no value (if empty), while multi-value reactive types (for example, `Flux<T>`) are -collected and resolved to `List<T>`. - -To configure view resolution is as simple as adding a `ViewResolutionResultHandler` bean -to your Spring configuration. <<webflux-config-view-resolvers, WebFlux Config>> provides a -dedicated configuration API for view resolution. - -See <<webflux-view>> for more on the view technologies integrated with Spring WebFlux. - - -[[webflux-redirecting-redirect-prefix]] -==== Redirecting -[.small]#<<web.adoc#mvc-redirecting-redirect-prefix, See equivalent in the Servlet stack>># - -The special `redirect:` prefix in a view name lets you perform a redirect. The -`UrlBasedViewResolver` (and sub-classes) recognize this as an instruction that a -redirect is needed. The rest of the view name is the redirect URL. - -The net effect is the same as if the controller had returned a `RedirectView` or -`Rendering.redirectTo("abc").build()`, but now the controller itself can -operate in terms of logical view names. A view name such as -`redirect:/some/resource` is relative to the current application, while a view name such as -`redirect:https://example.com/arbitrary/path` redirects to an absolute URL. - - -[[webflux-multiple-representations]] -==== Content Negotiation -[.small]#<<web.adoc#mvc-multiple-representations, See equivalent in the Servlet stack>># - -`ViewResolutionResultHandler` supports content negotiation. It compares the request -media types with the media types supported by each selected `View`. The first `View` -that supports the requested media type(s) is used. - -In order to support media types such as JSON and XML, Spring WebFlux provides -`HttpMessageWriterView`, which is a special `View` that renders through an -<<webflux-codecs, HttpMessageWriter>>. Typically, you would configure these as default -views through the <<webflux-config-view-resolvers, WebFlux Configuration>>. Default views are -always selected and used if they match the requested media type. - - - - -[[webflux-controller]] -== Annotated Controllers -[.small]#<<web.adoc#mvc-controller, See equivalent in the Servlet stack>># - -Spring WebFlux provides an annotation-based programming model, where `@Controller` and -`@RestController` components use annotations to express request mappings, request input, -handle exceptions, and more. Annotated controllers have flexible method signatures and -do not have to extend base classes nor implement specific interfaces. - -The following listing shows a basic example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RestController - public class HelloController { - - @GetMapping("/hello") - public String handle() { - return "Hello WebFlux"; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RestController - class HelloController { - - @GetMapping("/hello") - fun handle() = "Hello WebFlux" - } ----- - -In the preceding example, the method returns a `String` to be written to the response body. - - - -[[webflux-ann-controller]] -=== `@Controller` -[.small]#<<web.adoc#mvc-ann-controller, See equivalent in the Servlet stack>># - -You can define controller beans by using a standard Spring bean definition. -The `@Controller` stereotype allows for auto-detection and is aligned with Spring general support -for detecting `@Component` classes in the classpath and auto-registering bean definitions -for them. It also acts as a stereotype for the annotated class, indicating its role as -a web component. - -To enable auto-detection of such `@Controller` beans, you can add component scanning to -your Java configuration, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ComponentScan("org.example.web") // <1> - public class WebConfig { - - // ... - } ----- -<1> Scan the `org.example.web` package. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ComponentScan("org.example.web") // <1> - class WebConfig { - - // ... - } ----- -<1> Scan the `org.example.web` package. - -`@RestController` is a <<core.adoc#beans-meta-annotations, composed annotation>> that is -itself meta-annotated with `@Controller` and `@ResponseBody`, indicating a controller whose -every method inherits the type-level `@ResponseBody` annotation and, therefore, writes -directly to the response body versus view resolution and rendering with an HTML template. - - - -[[webflux-ann-requestmapping-proxying]] -==== AOP Proxies -[.small]#<<web.adoc#mvc-ann-requestmapping-proxying, See equivalent in the Servlet stack>># - -In some cases, you may need to decorate a controller with an AOP proxy at runtime. -One example is if you choose to have `@Transactional` annotations directly on the -controller. When this is the case, for controllers specifically, we recommend -using class-based proxying. This is automatically the case with such annotations -directly on the controller. - -If the controller implements an interface, and needs AOP proxying, you may need to -explicitly configure class-based proxying. For example, with `@EnableTransactionManagement` -you can change to `@EnableTransactionManagement(proxyTargetClass = true)`, and with -`<tx:annotation-driven/>` you can change to `<tx:annotation-driven proxy-target-class="true"/>`. - -NOTE: Keep in mind that as of 6.0, with interface proxying, Spring WebFlux no longer detects -controllers based solely on a type-level `@RequestMapping` annotation on the interface. -Please, enable class based proxying, or otherwise the interface must also have an -`@Controller` annotation. - - - - -[[webflux-ann-requestmapping]] -=== Request Mapping -[.small]#<<web.adoc#mvc-ann-requestmapping, See equivalent in the Servlet stack>># - -The `@RequestMapping` annotation is used to map requests to controllers methods. It has -various attributes to match by URL, HTTP method, request parameters, headers, and media -types. You can use it at the class level to express shared mappings or at the method level -to narrow down to a specific endpoint mapping. - -There are also HTTP method specific shortcut variants of `@RequestMapping`: - -* `@GetMapping` -* `@PostMapping` -* `@PutMapping` -* `@DeleteMapping` -* `@PatchMapping` - -The preceding annotations are <<webflux-ann-requestmapping-composed>> that are provided -because, arguably, most controller methods should be mapped to a specific HTTP method versus -using `@RequestMapping`, which, by default, matches to all HTTP methods. At the same time, a -`@RequestMapping` is still needed at the class level to express shared mappings. - -The following example uses type and method level mappings: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RestController - @RequestMapping("/persons") - class PersonController { - - @GetMapping("/{id}") - public Person getPerson(@PathVariable Long id) { - // ... - } - - @PostMapping - @ResponseStatus(HttpStatus.CREATED) - public void add(@RequestBody Person person) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RestController - @RequestMapping("/persons") - class PersonController { - - @GetMapping("/{id}") - fun getPerson(@PathVariable id: Long): Person { - // ... - } - - @PostMapping - @ResponseStatus(HttpStatus.CREATED) - fun add(@RequestBody person: Person) { - // ... - } - } ----- - - -[[webflux-ann-requestmapping-uri-templates]] -==== URI Patterns -[.small]#<<web.adoc#mvc-ann-requestmapping-uri-templates, See equivalent in the Servlet stack>># - -You can map requests by using glob patterns and wildcards: - -[cols="2,3,5"] -|=== -|Pattern |Description |Example - -| `+?+` -| Matches one character -| `+"/pages/t?st.html"+` matches `+"/pages/test.html"+` and `+"/pages/t3st.html"+` - -| `+*+` -| Matches zero or more characters within a path segment -| `+"/resources/*.png"+` matches `+"/resources/file.png"+` - -`+"/projects/*/versions"+` matches `+"/projects/spring/versions"+` but does not match `+"/projects/spring/boot/versions"+` - -| `+**+` -| Matches zero or more path segments until the end of the path -| `+"/resources/**"+` matches `+"/resources/file.png"+` and `+"/resources/images/file.png"+` - -`+"/resources/**/file.png"+` is invalid as `+**+` is only allowed at the end of the path. - -| `+{name}+` -| Matches a path segment and captures it as a variable named "name" -| `+"/projects/{project}/versions"+` matches `+"/projects/spring/versions"+` and captures `+project=spring+` - -| `+{name:[a-z]+}+` -| Matches the regexp `+"[a-z]+"+` as a path variable named "name" -| `+"/projects/{project:[a-z]+}/versions"+` matches `+"/projects/spring/versions"+` but not `+"/projects/spring1/versions"+` - -| `+{*path}+` -| Matches zero or more path segments until the end of the path and captures it as a variable named "path" -| `+"/resources/{*file}"+` matches `+"/resources/images/file.png"+` and captures `+file=/images/file.png+` - -|=== - -Captured URI variables can be accessed with `@PathVariable`, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/owners/{ownerId}/pets/{petId}") - public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/owners/{ownerId}/pets/{petId}") - fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { - // ... - } ----- --- - -You can declare URI variables at the class and method levels, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - @RequestMapping("/owners/{ownerId}") // <1> - public class OwnerController { - - @GetMapping("/pets/{petId}") // <2> - public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { - // ... - } - } ----- -<1> Class-level URI mapping. -<2> Method-level URI mapping. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - @RequestMapping("/owners/{ownerId}") // <1> - class OwnerController { - - @GetMapping("/pets/{petId}") // <2> - fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { - // ... - } - } ----- -<1> Class-level URI mapping. -<2> Method-level URI mapping. --- - - -URI variables are automatically converted to the appropriate type or a `TypeMismatchException` -is raised. Simple types (`int`, `long`, `Date`, and so on) are supported by default and you can -register support for any other data type. -See <<webflux-ann-typeconversion>> and <<webflux-ann-initbinder>>. - -URI variables can be named explicitly (for example, `@PathVariable("customId")`), but you can -leave that detail out if the names are the same and you compile your code with the `-parameters` -compiler flag. - -The syntax `{*varName}` declares a URI variable that matches zero or more remaining path -segments. For example `/resources/{*path}` matches all files under `/resources/`, and the -`"path"` variable captures the complete path under `/resources`. - -The syntax `{varName:regex}` declares a URI variable with a regular expression that has the -syntax: `{varName:regex}`. For example, given a URL of `/spring-web-3.0.5.jar`, the following method -extracts the name, version, and file extension: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") - public void handle(@PathVariable String version, @PathVariable String ext) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") - fun handle(@PathVariable version: String, @PathVariable ext: String) { - // ... - } ----- --- - -URI path patterns can also have embedded `${...}` placeholders that are resolved on startup -through `PropertySourcesPlaceholderConfigurer` against local, system, environment, and -other property sources. You can use this to, for example, parameterize a base URL based on -some external configuration. - -NOTE: Spring WebFlux uses `PathPattern` and the `PathPatternParser` for URI path matching support. -Both classes are located in `spring-web` and are expressly designed for use with HTTP URL -paths in web applications where a large number of URI path patterns are matched at runtime. - -Spring WebFlux does not support suffix pattern matching -- unlike Spring MVC, where a -mapping such as `/person` also matches to `/person.{asterisk}`. For URL-based content -negotiation, if needed, we recommend using a query parameter, which is simpler, more -explicit, and less vulnerable to URL path based exploits. - - -[[webflux-ann-requestmapping-pattern-comparison]] -==== Pattern Comparison -[.small]#<<web.adoc#mvc-ann-requestmapping-pattern-comparison, See equivalent in the Servlet stack>># - -When multiple patterns match a URL, they must be compared to find the best match. This is done -with `PathPattern.SPECIFICITY_COMPARATOR`, which looks for patterns that are more specific. - -For every pattern, a score is computed, based on the number of URI variables and wildcards, -where a URI variable scores lower than a wildcard. A pattern with a lower total score -wins. If two patterns have the same score, the longer is chosen. - -Catch-all patterns (for example, `**`, `{*varName}`) are excluded from the scoring and are always -sorted last instead. If two patterns are both catch-all, the longer is chosen. - - -[[webflux-ann-requestmapping-consumes]] -==== Consumable Media Types -[.small]#<<web.adoc#mvc-ann-requestmapping-consumes, See equivalent in the Servlet stack>># - -You can narrow the request mapping based on the `Content-Type` of the request, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping(path = "/pets", consumes = "application/json") - public void addPet(@RequestBody Pet pet) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/pets", consumes = ["application/json"]) - fun addPet(@RequestBody pet: Pet) { - // ... - } ----- - -The consumes attribute also supports negation expressions -- for example, `!text/plain` means any -content type other than `text/plain`. - -You can declare a shared `consumes` attribute at the class level. Unlike most other request -mapping attributes, however, when used at the class level, a method-level `consumes` attribute -overrides rather than extends the class-level declaration. - -TIP: `MediaType` provides constants for commonly used media types -- for example, -`APPLICATION_JSON_VALUE` and `APPLICATION_XML_VALUE`. - - -[[webflux-ann-requestmapping-produces]] -==== Producible Media Types -[.small]#<<web.adoc#mvc-ann-requestmapping-produces, See equivalent in the Servlet stack>># - -You can narrow the request mapping based on the `Accept` request header and the list of -content types that a controller method produces, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping(path = "/pets/{petId}", produces = "application/json") - @ResponseBody - public Pet getPet(@PathVariable String petId) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/pets/{petId}", produces = ["application/json"]) - @ResponseBody - fun getPet(@PathVariable petId: String): Pet { - // ... - } ----- - -The media type can specify a character set. Negated expressions are supported -- for example, -`!text/plain` means any content type other than `text/plain`. - -You can declare a shared `produces` attribute at the class level. Unlike most other request -mapping attributes, however, when used at the class level, a method-level `produces` attribute -overrides rather than extend the class level declaration. - -TIP: `MediaType` provides constants for commonly used media types -- e.g. -`APPLICATION_JSON_VALUE`, `APPLICATION_XML_VALUE`. - - -[[webflux-ann-requestmapping-params-and-headers]] -==== Parameters and Headers -[.small]#<<web.adoc#mvc-ann-requestmapping-params-and-headers, See equivalent in the Servlet stack>># - -You can narrow request mappings based on query parameter conditions. You can test for the -presence of a query parameter (`myParam`), for its absence (`!myParam`), or for a -specific value (`myParam=myValue`). The following examples tests for a parameter with a value: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping(path = "/pets/{petId}", params = "myParam=myValue") // <1> - public void findPet(@PathVariable String petId) { - // ... - } ----- -<1> Check that `myParam` equals `myValue`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/pets/{petId}", params = ["myParam=myValue"]) // <1> - fun findPet(@PathVariable petId: String) { - // ... - } ----- -<1> Check that `myParam` equals `myValue`. - -You can also use the same with request header conditions, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") // <1> - public void findPet(@PathVariable String petId) { - // ... - } ----- -<1> Check that `myHeader` equals `myValue`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/pets/{petId}", headers = ["myHeader=myValue"]) // <1> - fun findPet(@PathVariable petId: String) { - // ... - } ----- -<1> Check that `myHeader` equals `myValue`. - - - -[[webflux-ann-requestmapping-head-options]] -==== HTTP HEAD, OPTIONS -[.small]#<<web.adoc#mvc-ann-requestmapping-head-options, See equivalent in the Servlet stack>># - -`@GetMapping` and `@RequestMapping(method=HttpMethod.GET)` support HTTP HEAD -transparently for request mapping purposes. Controller methods need not change. -A response wrapper, applied in the `HttpHandler` server adapter, ensures a `Content-Length` -header is set to the number of bytes written without actually writing to the response. - -By default, HTTP OPTIONS is handled by setting the `Allow` response header to the list of HTTP -methods listed in all `@RequestMapping` methods with matching URL patterns. - -For a `@RequestMapping` without HTTP method declarations, the `Allow` header is set to -`GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS`. Controller methods should always declare the -supported HTTP methods (for example, by using the HTTP method specific variants -- -`@GetMapping`, `@PostMapping`, and others). - -You can explicitly map a `@RequestMapping` method to HTTP HEAD and HTTP OPTIONS, but that -is not necessary in the common case. - - -[[webflux-ann-requestmapping-composed]] -==== Custom Annotations -[.small]#<<web.adoc#mvc-ann-requestmapping-composed, See equivalent in the Servlet stack>># - -Spring WebFlux supports the use of <<core.adoc#beans-meta-annotations, composed annotations>> -for request mapping. Those are annotations that are themselves meta-annotated with -`@RequestMapping` and composed to redeclare a subset (or all) of the `@RequestMapping` -attributes with a narrower, more specific purpose. - -`@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, and `@PatchMapping` are -examples of composed annotations. They are provided, because, arguably, most -controller methods should be mapped to a specific HTTP method versus using `@RequestMapping`, -which, by default, matches to all HTTP methods. If you need an example of composed -annotations, look at how those are declared. - -Spring WebFlux also supports custom request mapping attributes with custom request matching -logic. This is a more advanced option that requires sub-classing -`RequestMappingHandlerMapping` and overriding the `getCustomMethodCondition` method, where -you can check the custom attribute and return your own `RequestCondition`. - - -[[webflux-ann-requestmapping-registration]] -==== Explicit Registrations -[.small]#<<web.adoc#mvc-ann-requestmapping-registration, See equivalent in the Servlet stack>># - -You can programmatically register Handler methods, which can be used for dynamic -registrations or for advanced cases, such as different instances of the same handler -under different URLs. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class MyConfig { - - @Autowired - public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) // <1> - throws NoSuchMethodException { - - RequestMappingInfo info = RequestMappingInfo - .paths("/user/{id}").methods(RequestMethod.GET).build(); // <2> - - Method method = UserHandler.class.getMethod("getUser", Long.class); // <3> - - mapping.registerMapping(info, handler, method); // <4> - } - - } ----- -<1> Inject target handlers and the handler mapping for controllers. -<2> Prepare the request mapping metadata. -<3> Get the handler method. -<4> Add the registration. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class MyConfig { - - @Autowired - fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) { // <1> - - val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build() // <2> - - val method = UserHandler::class.java.getMethod("getUser", Long::class.java) // <3> - - mapping.registerMapping(info, handler, method) // <4> - } - } ----- -<1> Inject target handlers and the handler mapping for controllers. -<2> Prepare the request mapping metadata. -<3> Get the handler method. -<4> Add the registration. - - - -[[webflux-ann-methods]] -=== Handler Methods -[.small]#<<web.adoc#mvc-ann-methods, See equivalent in the Servlet stack>># - -`@RequestMapping` handler methods have a flexible signature and can choose from a range of -supported controller method arguments and return values. - - -[[webflux-ann-arguments]] -==== Method Arguments -[.small]#<<web.adoc#mvc-ann-arguments, See equivalent in the Servlet stack>># - -The following table shows the supported controller method arguments. - -Reactive types (Reactor, RxJava, <<webflux-reactive-libraries, or other>>) are -supported on arguments that require blocking I/O (for example, reading the request body) to -be resolved. This is marked in the Description column. Reactive types are not expected -on arguments that do not require blocking. - -JDK 1.8's `java.util.Optional` is supported as a method argument in combination with -annotations that have a `required` attribute (for example, `@RequestParam`, `@RequestHeader`, -and others) and is equivalent to `required=false`. - -[cols="1,2", options="header"] -|=== -| Controller method argument | Description - -| `ServerWebExchange` -| Access to the full `ServerWebExchange` -- container for the HTTP request and response, - request and session attributes, `checkNotModified` methods, and others. - -| `ServerHttpRequest`, `ServerHttpResponse` -| Access to the HTTP request or response. - -| `WebSession` -| Access to the session. This does not force the start of a new session unless attributes - are added. Supports reactive types. - -| `java.security.Principal` -| The currently authenticated user -- possibly a specific `Principal` implementation class if known. - Supports reactive types. - -| `org.springframework.http.HttpMethod` -| The HTTP method of the request. - -| `java.util.Locale` -| The current request locale, determined by the most specific `LocaleResolver` available -- in - effect, the configured `LocaleResolver`/`LocaleContextResolver`. - -| `java.util.TimeZone` + `java.time.ZoneId` -| The time zone associated with the current request, as determined by a `LocaleContextResolver`. - -| `@PathVariable` -| For access to URI template variables. See <<webflux-ann-requestmapping-uri-templates>>. - -| `@MatrixVariable` -| For access to name-value pairs in URI path segments. See <<webflux-ann-matrix-variables>>. - -| `@RequestParam` -| For access to query parameters. Parameter values are converted to the declared method argument - type. See <<webflux-ann-requestparam>>. - - Note that use of `@RequestParam` is optional -- for example, to set its attributes. - See "`Any other argument`" later in this table. - -| `@RequestHeader` -| For access to request headers. Header values are converted to the declared method argument - type. See <<webflux-ann-requestheader>>. - -| `@CookieValue` -| For access to cookies. Cookie values are converted to the declared method argument type. - See <<webflux-ann-cookievalue>>. - -| `@RequestBody` -| For access to the HTTP request body. Body content is converted to the declared method - argument type by using `HttpMessageReader` instances. Supports reactive types. - See <<webflux-ann-requestbody>>. - -| `HttpEntity<B>` -| For access to request headers and body. The body is converted with `HttpMessageReader` instances. - Supports reactive types. See <<webflux-ann-httpentity>>. - -| `@RequestPart` -| For access to a part in a `multipart/form-data` request. Supports reactive types. - See <<webflux-multipart-forms>> and <<webflux-multipart>>. - -| `java.util.Map`, `org.springframework.ui.Model`, and `org.springframework.ui.ModelMap`. -| For access to the model that is used in HTML controllers and is exposed to templates as - part of view rendering. - -| `@ModelAttribute` -| For access to an existing attribute in the model (instantiated if not present) with - data binding and validation applied. See <<webflux-ann-modelattrib-method-args>> as well - as <<webflux-ann-modelattrib-methods>> and <<webflux-ann-initbinder>>. - - Note that use of `@ModelAttribute` is optional -- for example, to set its attributes. - See "`Any other argument`" later in this table. - -| `Errors`, `BindingResult` -| For access to errors from validation and data binding for a command object, i.e. a - `@ModelAttribute` argument. An `Errors`, or `BindingResult` argument must be declared - immediately after the validated method argument. - -| `SessionStatus` + class-level `@SessionAttributes` -| For marking form processing complete, which triggers cleanup of session attributes - declared through a class-level `@SessionAttributes` annotation. - See <<webflux-ann-sessionattributes>> for more details. - -| `UriComponentsBuilder` -| For preparing a URL relative to the current request's host, port, scheme, and - context path. See <<webflux-uri-building>>. - -| `@SessionAttribute` -| For access to any session attribute -- in contrast to model attributes stored in the session - as a result of a class-level `@SessionAttributes` declaration. See - <<webflux-ann-sessionattribute>> for more details. - -| `@RequestAttribute` -| For access to request attributes. See <<webflux-ann-requestattrib>> for more details. - -| Any other argument -| If a method argument is not matched to any of the above, it is, by default, resolved as - a `@RequestParam` if it is a simple type, as determined by - {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], - or as a `@ModelAttribute`, otherwise. -|=== - - -[[webflux-ann-return-types]] -==== Return Values -[.small]#<<web.adoc#mvc-ann-return-types, See equivalent in the Servlet stack>># - -The following table shows the supported controller method return values. Note that reactive -types from libraries such as Reactor, RxJava, <<webflux-reactive-libraries, or other>> are -generally supported for all return values. - -[cols="1,2", options="header"] -|=== -| Controller method return value | Description - -| `@ResponseBody` -| The return value is encoded through `HttpMessageWriter` instances and written to the response. - See <<webflux-ann-responsebody>>. - -| `HttpEntity<B>`, `ResponseEntity<B>` -| The return value specifies the full response, including HTTP headers, and the body is encoded - through `HttpMessageWriter` instances and written to the response. - See <<webflux-ann-responseentity>>. - -| `HttpHeaders` -| For returning a response with headers and no body. - -| `ErrorResponse` -| To render an RFC 7807 error response with details in the body, - see <<webflux-ann-rest-exceptions>> - -| `ProblemDetail` -| To render an RFC 7807 error response with details in the body, - see <<webflux-ann-rest-exceptions>> - -| `String` -| A view name to be resolved with `ViewResolver` instances and used together with the implicit - model -- determined through command objects and `@ModelAttribute` methods. The handler - method can also programmatically enrich the model by declaring a `Model` argument - (described <<webflux-viewresolution-handling, earlier>>). - -| `View` -| A `View` instance to use for rendering together with the implicit model -- determined - through command objects and `@ModelAttribute` methods. The handler method can also - programmatically enrich the model by declaring a `Model` argument - (described <<webflux-viewresolution-handling, earlier>>). - -| `java.util.Map`, `org.springframework.ui.Model` -| Attributes to be added to the implicit model, with the view name implicitly determined - based on the request path. - -| `@ModelAttribute` -| An attribute to be added to the model, with the view name implicitly determined based - on the request path. - - Note that `@ModelAttribute` is optional. See "`Any other return value`" later in - this table. - -| `Rendering` -| An API for model and view rendering scenarios. - -| `void` -| A method with a `void`, possibly asynchronous (for example, `Mono<Void>`), return type (or a `null` return - value) is considered to have fully handled the response if it also has a `ServerHttpResponse`, - a `ServerWebExchange` argument, or an `@ResponseStatus` annotation. The same is also true - if the controller has made a positive ETag or `lastModified` timestamp check. - See <<webflux-caching-etag-lastmodified>> for details. - - If none of the above is true, a `void` return type can also indicate "`no response body`" for - REST controllers or default view name selection for HTML controllers. - -| `Flux<ServerSentEvent>`, `Observable<ServerSentEvent>`, or other reactive type -| Emit server-sent events. The `ServerSentEvent` wrapper can be omitted when only data needs - to be written (however, `text/event-stream` must be requested or declared in the mapping - through the `produces` attribute). - -| Other return values -| If a return value remains unresolved in any other way, it is treated as a model - attribute, unless it is a simple type as determined by - {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], - in which case it remains unresolved. -|=== - - -[[webflux-ann-typeconversion]] -==== Type Conversion -[.small]#<<web.adoc#mvc-ann-typeconversion, See equivalent in the Servlet stack>># - -Some annotated controller method arguments that represent String-based request input (for example, -`@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) -can require type conversion if the argument is declared as something other than `String`. - -For such cases, type conversion is automatically applied based on the configured converters. -By default, simple types (such as `int`, `long`, `Date`, and others) are supported. Type conversion -can be customized through a `WebDataBinder` (see <<webflux-ann-initbinder>>) or by registering -`Formatters` with the `FormattingConversionService` (see <<core.adoc#format, Spring Field Formatting>>). - -A practical issue in type conversion is the treatment of an empty String source value. -Such a value is treated as missing if it becomes `null` as a result of type conversion. -This can be the case for `Long`, `UUID`, and other target types. If you want to allow `null` -to be injected, either use the `required` flag on the argument annotation, or declare the -argument as `@Nullable`. - - -[[webflux-ann-matrix-variables]] -==== Matrix Variables -[.small]#<<web.adoc#mvc-ann-matrix-variables, See equivalent in the Servlet stack>># - -https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in -path segments. In Spring WebFlux, we refer to those as "`matrix variables`" based on an -https://www.w3.org/DesignIssues/MatrixURIs.html["`old post`"] by Tim Berners-Lee, but they -can be also be referred to as URI path parameters. - -Matrix variables can appear in any path segment, with each variable separated by a semicolon and -multiple values separated by commas -- for example, `"/cars;color=red,green;year=2012"`. Multiple -values can also be specified through repeated variable names -- for example, -`"color=red;color=green;color=blue"`. - -Unlike Spring MVC, in WebFlux, the presence or absence of matrix variables in a URL does -not affect request mappings. In other words, you are not required to use a URI variable -to mask variable content. That said, if you want to access matrix variables from a -controller method, you need to add a URI variable to the path segment where matrix -variables are expected. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // GET /pets/42;q=11;r=22 - - @GetMapping("/pets/{petId}") - public void findPet(@PathVariable String petId, @MatrixVariable int q) { - - // petId == 42 - // q == 11 - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // GET /pets/42;q=11;r=22 - - @GetMapping("/pets/{petId}") - fun findPet(@PathVariable petId: String, @MatrixVariable q: Int) { - - // petId == 42 - // q == 11 - } ----- - - -Given that all path segments can contain matrix variables, you may sometimes need to -disambiguate which path variable the matrix variable is expected to be in, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // GET /owners/42;q=11/pets/21;q=22 - - @GetMapping("/owners/{ownerId}/pets/{petId}") - public void findPet( - @MatrixVariable(name="q", pathVar="ownerId") int q1, - @MatrixVariable(name="q", pathVar="petId") int q2) { - - // q1 == 11 - // q2 == 22 - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/owners/{ownerId}/pets/{petId}") - fun findPet( - @MatrixVariable(name = "q", pathVar = "ownerId") q1: Int, - @MatrixVariable(name = "q", pathVar = "petId") q2: Int) { - - // q1 == 11 - // q2 == 22 - } ----- - -You can define a matrix variable may be defined as optional and specify a default value -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // GET /pets/42 - - @GetMapping("/pets/{petId}") - public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) { - - // q == 1 - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // GET /pets/42 - - @GetMapping("/pets/{petId}") - fun findPet(@MatrixVariable(required = false, defaultValue = "1") q: Int) { - - // q == 1 - } ----- - -To get all matrix variables, use a `MultiValueMap`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 - - @GetMapping("/owners/{ownerId}/pets/{petId}") - public void findPet( - @MatrixVariable MultiValueMap<String, String> matrixVars, - @MatrixVariable(pathVar="petId") MultiValueMap<String, String> petMatrixVars) { - - // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] - // petMatrixVars: ["q" : 22, "s" : 23] - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 - - @GetMapping("/owners/{ownerId}/pets/{petId}") - fun findPet( - @MatrixVariable matrixVars: MultiValueMap<String, String>, - @MatrixVariable(pathVar="petId") petMatrixVars: MultiValueMap<String, String>) { - - // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] - // petMatrixVars: ["q" : 22, "s" : 23] - } ----- - - -[[webflux-ann-requestparam]] -==== `@RequestParam` -[.small]#<<web.adoc#mvc-ann-requestparam, See equivalent in the Servlet stack>># - -You can use the `@RequestParam` annotation to bind query parameters to a method argument in a -controller. The following code snippet shows the usage: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - @RequestMapping("/pets") - public class EditPetForm { - - // ... - - @GetMapping - public String setupForm(@RequestParam("petId") int petId, Model model) { <1> - Pet pet = this.clinic.loadPet(petId); - model.addAttribute("pet", pet); - return "petForm"; - } - - // ... - } ----- -<1> Using `@RequestParam`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.ui.set - - @Controller - @RequestMapping("/pets") - class EditPetForm { - - // ... - - @GetMapping - fun setupForm(@RequestParam("petId") petId: Int, model: Model): String { // <1> - val pet = clinic.loadPet(petId) - model["pet"] = pet - return "petForm" - } - - // ... - } ----- -<1> Using `@RequestParam`. - -TIP: The Servlet API "`request parameter`" concept conflates query parameters, form -data, and multiparts into one. However, in WebFlux, each is accessed individually through -`ServerWebExchange`. While `@RequestParam` binds to query parameters only, you can use -data binding to apply query parameters, form data, and multiparts to a -<<webflux-ann-modelattrib-method-args, command object>>. - -Method parameters that use the `@RequestParam` annotation are required by default, but -you can specify that a method parameter is optional by setting the required flag of a `@RequestParam` -to `false` or by declaring the argument with a `java.util.Optional` -wrapper. - -Type conversion is applied automatically if the target method parameter type is not -`String`. See <<webflux-ann-typeconversion>>. - -When a `@RequestParam` annotation is declared on a `Map<String, String>` or -`MultiValueMap<String, String>` argument, the map is populated with all query parameters. - -Note that use of `@RequestParam` is optional -- for example, to set its attributes. By -default, any argument that is a simple value type (as determined by -{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) -and is not resolved by any other argument resolver is treated as if it were annotated -with `@RequestParam`. - - -[[webflux-ann-requestheader]] -==== `@RequestHeader` -[.small]#<<web.adoc#mvc-ann-requestheader, See equivalent in the Servlet stack>># - -You can use the `@RequestHeader` annotation to bind a request header to a method argument in a -controller. - -The following example shows a request with headers: - -[literal] -[subs="verbatim,quotes"] ----- -Host localhost:8080 -Accept text/html,application/xhtml+xml,application/xml;q=0.9 -Accept-Language fr,en-gb;q=0.7,en;q=0.3 -Accept-Encoding gzip,deflate -Accept-Charset ISO-8859-1,utf-8;q=0.7,*;q=0.7 -Keep-Alive 300 ----- - -The following example gets the value of the `Accept-Encoding` and `Keep-Alive` headers: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/demo") - public void handle( - @RequestHeader("Accept-Encoding") String encoding, // <1> - @RequestHeader("Keep-Alive") long keepAlive) { // <2> - //... - } ----- -<1> Get the value of the `Accept-Encoding` header. -<2> Get the value of the `Keep-Alive` header. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/demo") - fun handle( - @RequestHeader("Accept-Encoding") encoding: String, // <1> - @RequestHeader("Keep-Alive") keepAlive: Long) { // <2> - //... - } ----- -<1> Get the value of the `Accept-Encoding` header. -<2> Get the value of the `Keep-Alive` header. - -Type conversion is applied automatically if the target method parameter type is not -`String`. See <<webflux-ann-typeconversion>>. - -When a `@RequestHeader` annotation is used on a `Map<String, String>`, -`MultiValueMap<String, String>`, or `HttpHeaders` argument, the map is populated -with all header values. - -TIP: Built-in support is available for converting a comma-separated string into an -array or collection of strings or other types known to the type conversion system. For -example, a method parameter annotated with `@RequestHeader("Accept")` may be of type -`String` but also of `String[]` or `List<String>`. - - -[[webflux-ann-cookievalue]] -==== `@CookieValue` -[.small]#<<web.adoc#mvc-ann-cookievalue, See equivalent in the Servlet stack>># - -You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument -in a controller. - -The following example shows a request with a cookie: - -[literal,subs="verbatim,quotes"] ----- -JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84 ----- - -The following code sample demonstrates how to get the cookie value: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/demo") - public void handle(@CookieValue("JSESSIONID") String cookie) { // <1> - //... - } ----- -<1> Get the cookie value. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/demo") - fun handle(@CookieValue("JSESSIONID") cookie: String) { // <1> - //... - } ----- -<1> Get the cookie value. - - -Type conversion is applied automatically if the target method parameter type is not -`String`. See <<webflux-ann-typeconversion>>. - - -[[webflux-ann-modelattrib-method-args]] -==== `@ModelAttribute` -[.small]#<<web.adoc#mvc-ann-modelattrib-method-args, See equivalent in the Servlet stack>># - -You can use the `@ModelAttribute` annotation on a method argument to access an attribute from the -model or have it instantiated if not present. The model attribute is also overlaid with -the values of query parameters and form fields whose names match to field names. This is -referred to as data binding, and it saves you from having to deal with parsing and -converting individual query parameters and form fields. The following example binds an instance of `Pet`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - public String processSubmit(@ModelAttribute Pet pet) { } // <1> ----- -<1> Bind an instance of `Pet`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - fun processSubmit(@ModelAttribute pet: Pet): String { } // <1> ----- -<1> Bind an instance of `Pet`. - -The `Pet` instance in the preceding example is resolved as follows: - -* From the model if already added through <<webflux-ann-modelattrib-methods>>. -* From the HTTP session through <<webflux-ann-sessionattributes>>. -* From the invocation of a default constructor. -* From the invocation of a "`primary constructor`" with arguments that match query -parameters or form fields. Argument names are determined through JavaBeans -`@ConstructorProperties` or through runtime-retained parameter names in the bytecode. - -After the model attribute instance is obtained, data binding is applied. The -`WebExchangeDataBinder` class matches names of query parameters and form fields to field -names on the target `Object`. Matching fields are populated after type conversion is applied -where necessary. For more on data binding (and validation), see -<<core.adoc#validation, Validation>>. For more on customizing data binding, see -<<webflux-ann-initbinder>>. - -Data binding can result in errors. By default, a `WebExchangeBindException` is raised, but, -to check for such errors in the controller method, you can add a `BindingResult` argument -immediately next to the `@ModelAttribute`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { <1> - if (result.hasErrors()) { - return "petForm"; - } - // ... - } ----- -<1> Adding a `BindingResult`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - fun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { // <1> - if (result.hasErrors()) { - return "petForm" - } - // ... - } ----- -<1> Adding a `BindingResult`. - -You can automatically apply validation after data binding by adding the -`jakarta.validation.Valid` annotation or Spring's `@Validated` annotation (see also -<<core.adoc#validation-beanvalidation, Bean Validation>> and -<<core.adoc#validation, Spring validation>>). The following example uses the `@Valid` annotation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { // <1> - if (result.hasErrors()) { - return "petForm"; - } - // ... - } ----- -<1> Using `@Valid` on a model attribute argument. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { // <1> - if (result.hasErrors()) { - return "petForm" - } - // ... - } ----- -<1> Using `@Valid` on a model attribute argument. - -Spring WebFlux, unlike Spring MVC, supports reactive types in the model -- for example, -`Mono<Account>` or `io.reactivex.Single<Account>`. You can declare a `@ModelAttribute` argument -with or without a reactive type wrapper, and it will be resolved accordingly, -to the actual value if necessary. However, note that, to use a `BindingResult` -argument, you must declare the `@ModelAttribute` argument before it without a reactive -type wrapper, as shown earlier. Alternatively, you can handle any errors through the -reactive type, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - public Mono<String> processSubmit(@Valid @ModelAttribute("pet") Mono<Pet> petMono) { - return petMono - .flatMap(pet -> { - // ... - }) - .onErrorResume(ex -> { - // ... - }); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - fun processSubmit(@Valid @ModelAttribute("pet") petMono: Mono<Pet>): Mono<String> { - return petMono - .flatMap { pet -> - // ... - } - .onErrorResume{ ex -> - // ... - } - } ----- - -Note that use of `@ModelAttribute` is optional -- for example, to set its attributes. -By default, any argument that is not a simple value type (as determined by -{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) -and is not resolved by any other argument resolver is treated as if it were annotated -with `@ModelAttribute`. - - -[[webflux-ann-sessionattributes]] -==== `@SessionAttributes` -[.small]#<<web.adoc#mvc-ann-sessionattributes, See equivalent in the Servlet stack>># - -`@SessionAttributes` is used to store model attributes in the `WebSession` between -requests. It is a type-level annotation that declares session attributes used by a -specific controller. This typically lists the names of model attributes or types of -model attributes that should be transparently stored in the session for subsequent -requests to access. - -Consider the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - @SessionAttributes("pet") <1> - public class EditPetForm { - // ... - } ----- -<1> Using the `@SessionAttributes` annotation. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - @SessionAttributes("pet") // <1> - class EditPetForm { - // ... - } ----- -<1> Using the `@SessionAttributes` annotation. - -On the first request, when a model attribute with the name, `pet`, is added to the model, -it is automatically promoted to and saved in the `WebSession`. It remains there until -another controller method uses a `SessionStatus` method argument to clear the storage, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - @SessionAttributes("pet") // <1> - public class EditPetForm { - - // ... - - @PostMapping("/pets/{id}") - public String handle(Pet pet, BindingResult errors, SessionStatus status) { // <2> - if (errors.hasErrors()) { - // ... - } - status.setComplete(); - // ... - } - } - } ----- -<1> Using the `@SessionAttributes` annotation. -<2> Using a `SessionStatus` variable. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - @SessionAttributes("pet") // <1> - class EditPetForm { - - // ... - - @PostMapping("/pets/{id}") - fun handle(pet: Pet, errors: BindingResult, status: SessionStatus): String { // <2> - if (errors.hasErrors()) { - // ... - } - status.setComplete() - // ... - } - } ----- -<1> Using the `@SessionAttributes` annotation. -<2> Using a `SessionStatus` variable. - - -[[webflux-ann-sessionattribute]] -==== `@SessionAttribute` -[.small]#<<web.adoc#mvc-ann-sessionattribute, See equivalent in the Servlet stack>># - -If you need access to pre-existing session attributes that are managed globally -(that is, outside the controller -- for example, by a filter) and may or may not be present, -you can use the `@SessionAttribute` annotation on a method parameter, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/") - public String handle(@SessionAttribute User user) { // <1> - // ... - } ----- -<1> Using `@SessionAttribute`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/") - fun handle(@SessionAttribute user: User): String { // <1> - // ... - } ----- -<1> Using `@SessionAttribute`. - -For use cases that require adding or removing session attributes, consider injecting -`WebSession` into the controller method. - -For temporary storage of model attributes in the session as part of a controller -workflow, consider using `SessionAttributes`, as described in -<<webflux-ann-sessionattributes>>. - - -[[webflux-ann-requestattrib]] -==== `@RequestAttribute` -[.small]#<<web.adoc#mvc-ann-requestattrib, See equivalent in the Servlet stack>># - -Similarly to `@SessionAttribute`, you can use the `@RequestAttribute` annotation to -access pre-existing request attributes created earlier (for example, by a `WebFilter`), -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/") - public String handle(@RequestAttribute Client client) { <1> - // ... - } ----- -<1> Using `@RequestAttribute`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/") - fun handle(@RequestAttribute client: Client): String { // <1> - // ... - } ----- -<1> Using `@RequestAttribute`. - - -[[webflux-multipart-forms]] -==== Multipart Content -[.small]#<<web.adoc#mvc-multipart-forms, See equivalent in the Servlet stack>># - -As explained in <<webflux-multipart>>, `ServerWebExchange` provides access to multipart -content. The best way to handle a file upload form (for example, from a browser) in a controller -is through data binding to a <<webflux-ann-modelattrib-method-args, command object>>, -as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - class MyForm { - - private String name; - - private MultipartFile file; - - // ... - - } - - @Controller - public class FileUploadController { - - @PostMapping("/form") - public String handleFormUpload(MyForm form, BindingResult errors) { - // ... - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyForm( - val name: String, - val file: MultipartFile) - - @Controller - class FileUploadController { - - @PostMapping("/form") - fun handleFormUpload(form: MyForm, errors: BindingResult): String { - // ... - } - - } ----- --- - -You can also submit multipart requests from non-browser clients in a RESTful service -scenario. The following example uses a file along with JSON: - -[literal,subs="verbatim,quotes"] ----- -POST /someUrl -Content-Type: multipart/mixed - ---edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp -Content-Disposition: form-data; name="meta-data" -Content-Type: application/json; charset=UTF-8 -Content-Transfer-Encoding: 8bit - -{ - "name": "value" -} ---edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp -Content-Disposition: form-data; name="file-data"; filename="file.properties" -Content-Type: text/xml -Content-Transfer-Encoding: 8bit -... File Data ... ----- - -You can access individual parts with `@RequestPart`, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/") - public String handle(@RequestPart("meta-data") Part metadata, // <1> - @RequestPart("file-data") FilePart file) { // <2> - // ... - } ----- -<1> Using `@RequestPart` to get the metadata. -<2> Using `@RequestPart` to get the file. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/") - fun handle(@RequestPart("meta-data") Part metadata, // <1> - @RequestPart("file-data") FilePart file): String { // <2> - // ... - } ----- -<1> Using `@RequestPart` to get the metadata. -<2> Using `@RequestPart` to get the file. --- - - -To deserialize the raw part content (for example, to JSON -- similar to `@RequestBody`), -you can declare a concrete target `Object`, instead of `Part`, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/") - public String handle(@RequestPart("meta-data") MetaData metadata) { // <1> - // ... - } ----- -<1> Using `@RequestPart` to get the metadata. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/") - fun handle(@RequestPart("meta-data") metadata: MetaData): String { // <1> - // ... - } ----- -<1> Using `@RequestPart` to get the metadata. --- - -You can use `@RequestPart` in combination with `jakarta.validation.Valid` or Spring's -`@Validated` annotation, which causes Standard Bean Validation to be applied. Validation -errors lead to a `WebExchangeBindException` that results in a 400 (BAD_REQUEST) response. -The exception contains a `BindingResult` with the error details and can also be handled -in the controller method by declaring the argument with an async wrapper and then using -error related operators: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/") - public String handle(@Valid @RequestPart("meta-data") Mono<MetaData> metadata) { - // use one of the onError* operators... - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/") - fun handle(@Valid @RequestPart("meta-data") metadata: MetaData): String { - // ... - } ----- --- - -To access all multipart data as a `MultiValueMap`, you can use `@RequestBody`, -as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/") - public String handle(@RequestBody Mono<MultiValueMap<String, Part>> parts) { // <1> - // ... - } ----- -<1> Using `@RequestBody`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/") - fun handle(@RequestBody parts: MultiValueMap<String, Part>): String { // <1> - // ... - } ----- -<1> Using `@RequestBody`. --- - -[[partevent]] -===== `PartEvent` - -To access multipart data sequentially, in a streaming fashion, you can use `@RequestBody` with -`Flux<PartEvent>` (or `Flow<PartEvent>` in Kotlin). -Each part in a multipart HTTP message will produce at -least one `PartEvent` containing both headers and a buffer with the contents of the part. - -- Form fields will produce a *single* `FormPartEvent`, containing the value of the field. -- File uploads will produce *one or more* `FilePartEvent` objects, containing the filename used -when uploading. If the file is large enough to be split across multiple buffers, the first -`FilePartEvent` will be followed by subsequent events. - - -For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/") - public void handle(@RequestBody Flux<PartEvent> allPartsEvents) { <1> - allPartsEvents.windowUntil(PartEvent::isLast) <2> - .concatMap(p -> p.switchOnFirst((signal, partEvents) -> { <3> - if (signal.hasValue()) { - PartEvent event = signal.get(); - if (event instanceof FormPartEvent formEvent) { <4> - String value = formEvent.value(); - // handle form field - } - else if (event instanceof FilePartEvent fileEvent) { <5> - String filename = fileEvent.filename(); - Flux<DataBuffer> contents = partEvents.map(PartEvent::content); <6> - // handle file upload - } - else { - return Mono.error(new RuntimeException("Unexpected event: " + event)); - } - } - else { - return partEvents; // either complete or error signal - } - })); - } ----- -<1> Using `@RequestBody`. -<2> The final `PartEvent` for a particular part will have `isLast()` set to `true`, and can be -followed by additional events belonging to subsequent parts. -This makes the `isLast` property suitable as a predicate for the `Flux::windowUntil` operator, to -split events from all parts into windows that each belong to a single part. -<3> The `Flux::switchOnFirst` operator allows you to see whether you are handling a form field or -file upload. -<4> Handling the form field. -<5> Handling the file upload. -<6> The body contents must be completely consumed, relayed, or released to avoid memory leaks. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/") - fun handle(@RequestBody allPartsEvents: Flux<PartEvent>) = { // <1> - allPartsEvents.windowUntil(PartEvent::isLast) <2> - .concatMap { - it.switchOnFirst { signal, partEvents -> <3> - if (signal.hasValue()) { - val event = signal.get() - if (event is FormPartEvent) { <4> - val value: String = event.value(); - // handle form field - } else if (event is FilePartEvent) { <5> - val filename: String = event.filename(); - val contents: Flux<DataBuffer> = partEvents.map(PartEvent::content); <6> - // handle file upload - } else { - return Mono.error(RuntimeException("Unexpected event: " + event)); - } - } else { - return partEvents; // either complete or error signal - } - } - } -} ----- -<1> Using `@RequestBody`. -<2> The final `PartEvent` for a particular part will have `isLast()` set to `true`, and can be -followed by additional events belonging to subsequent parts. -This makes the `isLast` property suitable as a predicate for the `Flux::windowUntil` operator, to -split events from all parts into windows that each belong to a single part. -<3> The `Flux::switchOnFirst` operator allows you to see whether you are handling a form field or -file upload. -<4> Handling the form field. -<5> Handling the file upload. -<6> The body contents must be completely consumed, relayed, or released to avoid memory leaks. - -Received part events can also be relayed to another service by using the `WebClient`. -See <<webflux-client-body-multipart>>. - - -[[webflux-ann-requestbody]] -==== `@RequestBody` -[.small]#<<web.adoc#mvc-ann-requestbody, See equivalent in the Servlet stack>># - -You can use the `@RequestBody` annotation to have the request body read and deserialized into an -`Object` through an <<webflux-codecs,HttpMessageReader>>. -The following example uses a `@RequestBody` argument: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/accounts") - public void handle(@RequestBody Account account) { - // ... - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/accounts") - fun handle(@RequestBody account: Account) { - // ... - } ----- - -Unlike Spring MVC, in WebFlux, the `@RequestBody` method argument supports reactive types -and fully non-blocking reading and (client-to-server) streaming. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/accounts") - public void handle(@RequestBody Mono<Account> account) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/accounts") - fun handle(@RequestBody accounts: Flow<Account>) { - // ... - } ----- - -You can use the <<webflux-config-message-codecs>> option of the <<webflux-config>> to -configure or customize message readers. - -You can use `@RequestBody` in combination with `jakarta.validation.Valid` or Spring's -`@Validated` annotation, which causes Standard Bean Validation to be applied. Validation -errors cause a `WebExchangeBindException`, which results in a 400 (BAD_REQUEST) response. -The exception contains a `BindingResult` with error details and can be handled in the -controller method by declaring the argument with an async wrapper and then using error -related operators: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/accounts") - public void handle(@Valid @RequestBody Mono<Account> account) { - // use one of the onError* operators... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/accounts") - fun handle(@Valid @RequestBody account: Mono<Account>) { - // ... - } ----- - - -[[webflux-ann-httpentity]] -==== `HttpEntity` -[.small]#<<web.adoc#mvc-ann-httpentity, See equivalent in the Servlet stack>># - -`HttpEntity` is more or less identical to using <<webflux-ann-requestbody>> but is based on a -container object that exposes request headers and the body. The following example uses an -`HttpEntity`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/accounts") - public void handle(HttpEntity<Account> entity) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/accounts") - fun handle(entity: HttpEntity<Account>) { - // ... - } ----- - - -[[webflux-ann-responsebody]] -==== `@ResponseBody` -[.small]#<<web.adoc#mvc-ann-responsebody, See equivalent in the Servlet stack>># - -You can use the `@ResponseBody` annotation on a method to have the return serialized -to the response body through an <<webflux-codecs, HttpMessageWriter>>. The following -example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/accounts/{id}") - @ResponseBody - public Account handle() { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/accounts/{id}") - @ResponseBody - fun handle(): Account { - // ... - } ----- - -`@ResponseBody` is also supported at the class level, in which case it is inherited by -all controller methods. This is the effect of `@RestController`, which is nothing more -than a meta-annotation marked with `@Controller` and `@ResponseBody`. - -`@ResponseBody` supports reactive types, which means you can return Reactor or RxJava -types and have the asynchronous values they produce rendered to the response. -For additional details, see <<webflux-codecs-streaming>> and -<<webflux-codecs-jackson,JSON rendering>>. - -You can combine `@ResponseBody` methods with JSON serialization views. -See <<webflux-ann-jackson>> for details. - -You can use the <<webflux-config-message-codecs>> option of the <<webflux-config>> to -configure or customize message writing. - - -[[webflux-ann-responseentity]] -==== `ResponseEntity` -[.small]#<<web.adoc#mvc-ann-responseentity, See equivalent in the Servlet stack>># - -`ResponseEntity` is like <<webflux-ann-responsebody>> but with status and headers. For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/something") - public ResponseEntity<String> handle() { - String body = ... ; - String etag = ... ; - return ResponseEntity.ok().eTag(etag).body(body); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/something") - fun handle(): ResponseEntity<String> { - val body: String = ... - val etag: String = ... - return ResponseEntity.ok().eTag(etag).build(body) - } ----- - -WebFlux supports using a single value <<webflux-reactive-libraries, reactive type>> to -produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive types -for the body. This allows a variety of async responses with `ResponseEntity` as follows: - -* `ResponseEntity<Mono<T>>` or `ResponseEntity<Flux<T>>` make the response status and - headers known immediately while the body is provided asynchronously at a later point. - Use `Mono` if the body consists of 0..1 values or `Flux` if it can produce multiple values. -* `Mono<ResponseEntity<T>>` provides all three -- response status, headers, and body, - asynchronously at a later point. This allows the response status and headers to vary - depending on the outcome of asynchronous request handling. -* `Mono<ResponseEntity<Mono<T>>>` or `Mono<ResponseEntity<Flux<T>>>` are yet another - possible, albeit less common alternative. They provide the response status and headers - asynchronously first and then the response body, also asynchronously, second. - - -[[webflux-ann-jackson]] -==== Jackson JSON - -Spring offers support for the Jackson JSON library. - -[[webflux-ann-jsonview]] -===== JSON Views -[.small]#<<web.adoc#mvc-ann-jackson, See equivalent in the Servlet stack>># - -Spring WebFlux provides built-in support for -https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], -which allows rendering only a subset of all fields in an `Object`. To use it with -`@ResponseBody` or `ResponseEntity` controller methods, you can use Jackson's -`@JsonView` annotation to activate a serialization view class, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RestController - public class UserController { - - @GetMapping("/user") - @JsonView(User.WithoutPasswordView.class) - public User getUser() { - return new User("eric", "7!jd#h23"); - } - } - - public class User { - - public interface WithoutPasswordView {}; - public interface WithPasswordView extends WithoutPasswordView {}; - - private String username; - private String password; - - public User() { - } - - public User(String username, String password) { - this.username = username; - this.password = password; - } - - @JsonView(WithoutPasswordView.class) - public String getUsername() { - return this.username; - } - - @JsonView(WithPasswordView.class) - public String getPassword() { - return this.password; - } - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RestController - class UserController { - - @GetMapping("/user") - @JsonView(User.WithoutPasswordView::class) - fun getUser(): User { - return User("eric", "7!jd#h23") - } - } - - class User( - @JsonView(WithoutPasswordView::class) val username: String, - @JsonView(WithPasswordView::class) val password: String - ) { - interface WithoutPasswordView - interface WithPasswordView : WithoutPasswordView - } ----- - -NOTE: `@JsonView` allows an array of view classes but you can only specify only one per -controller method. Use a composite interface if you need to activate multiple views. - - - -[[webflux-ann-modelattrib-methods]] -=== `Model` -[.small]#<<web.adoc#mvc-ann-modelattrib-methods, See equivalent in the Servlet stack>># - -You can use the `@ModelAttribute` annotation: - -* On a <<webflux-ann-modelattrib-method-args, method argument>> in `@RequestMapping` methods -to create or access an Object from the model and to bind it to the request through a -`WebDataBinder`. -* As a method-level annotation in `@Controller` or `@ControllerAdvice` classes, helping -to initialize the model prior to any `@RequestMapping` method invocation. -* On a `@RequestMapping` method to mark its return value as a model attribute. - -This section discusses `@ModelAttribute` methods, or the second item from the preceding list. -A controller can have any number of `@ModelAttribute` methods. All such methods are -invoked before `@RequestMapping` methods in the same controller. A `@ModelAttribute` -method can also be shared across controllers through `@ControllerAdvice`. See the section on -<<webflux-ann-controller-advice>> for more details. - -`@ModelAttribute` methods have flexible method signatures. They support many of the same -arguments as `@RequestMapping` methods (except for `@ModelAttribute` itself and anything -related to the request body). - -The following example uses a `@ModelAttribute` method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ModelAttribute - public void populateModel(@RequestParam String number, Model model) { - model.addAttribute(accountRepository.findAccount(number)); - // add more ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ModelAttribute - fun populateModel(@RequestParam number: String, model: Model) { - model.addAttribute(accountRepository.findAccount(number)) - // add more ... - } ----- - -The following example adds one attribute only: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ModelAttribute - public Account addAccount(@RequestParam String number) { - return accountRepository.findAccount(number); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ModelAttribute - fun addAccount(@RequestParam number: String): Account { - return accountRepository.findAccount(number); - } ----- - -NOTE: When a name is not explicitly specified, a default name is chosen based on the type, -as explained in the javadoc for {api-spring-framework}/core/Conventions.html[`Conventions`]. -You can always assign an explicit name by using the overloaded `addAttribute` method or -through the name attribute on `@ModelAttribute` (for a return value). - -Spring WebFlux, unlike Spring MVC, explicitly supports reactive types in the model -(for example, `Mono<Account>` or `io.reactivex.Single<Account>`). Such asynchronous model -attributes can be transparently resolved (and the model updated) to their actual values -at the time of `@RequestMapping` invocation, provided a `@ModelAttribute` argument is -declared without a wrapper, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ModelAttribute - public void addAccount(@RequestParam String number) { - Mono<Account> accountMono = accountRepository.findAccount(number); - model.addAttribute("account", accountMono); - } - - @PostMapping("/accounts") - public String handle(@ModelAttribute Account account, BindingResult errors) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.ui.set - - @ModelAttribute - fun addAccount(@RequestParam number: String) { - val accountMono: Mono<Account> = accountRepository.findAccount(number) - model["account"] = accountMono - } - - @PostMapping("/accounts") - fun handle(@ModelAttribute account: Account, errors: BindingResult): String { - // ... - } ----- - - -In addition, any model attributes that have a reactive type wrapper are resolved to their -actual values (and the model updated) just prior to view rendering. - -You can also use `@ModelAttribute` as a method-level annotation on `@RequestMapping` -methods, in which case the return value of the `@RequestMapping` method is interpreted as a -model attribute. This is typically not required, as it is the default behavior in HTML -controllers, unless the return value is a `String` that would otherwise be interpreted -as a view name. `@ModelAttribute` can also help to customize the model attribute name, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/accounts/{id}") - @ModelAttribute("myAccount") - public Account handle() { - // ... - return account; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/accounts/{id}") - @ModelAttribute("myAccount") - fun handle(): Account { - // ... - return account - } ----- - - - -[[webflux-ann-initbinder]] -=== `DataBinder` -[.small]#<<web.adoc#mvc-ann-initbinder, See equivalent in the Servlet stack>># - -`@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods, to -initialize instances of `WebDataBinder`. Those, in turn, are used to: - -* Bind request parameters (that is, form data or query) to a model object. -* Convert `String`-based request values (such as request parameters, path variables, -headers, cookies, and others) to the target type of controller method arguments. -* Format model object values as `String` values when rendering HTML forms. - -`@InitBinder` methods can register controller-specific `java.beans.PropertyEditor` or -Spring `Converter` and `Formatter` components. In addition, you can use the -<<webflux-config-conversion, WebFlux Java configuration>> to register `Converter` and -`Formatter` types in a globally shared `FormattingConversionService`. - -`@InitBinder` methods support many of the same arguments that `@RequestMapping` methods -do, except for `@ModelAttribute` (command object) arguments. Typically, they are declared -with a `WebDataBinder` argument, for registrations, and a `void` return value. -The following example uses the `@InitBinder` annotation: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class FormController { - - @InitBinder // <1> - public void initBinder(WebDataBinder binder) { - SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd"); - dateFormat.setLenient(false); - binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false)); - } - - // ... - } ----- -<1> Using the `@InitBinder` annotation. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class FormController { - - @InitBinder // <1> - fun initBinder(binder: WebDataBinder) { - val dateFormat = SimpleDateFormat("yyyy-MM-dd") - dateFormat.isLenient = false - binder.registerCustomEditor(Date::class.java, CustomDateEditor(dateFormat, false)) - } - - // ... - } ----- -<1> Using the `@InitBinder` annotation. --- - -Alternatively, when using a `Formatter`-based setup through a shared -`FormattingConversionService`, you could re-use the same approach and register -controller-specific `Formatter` instances, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class FormController { - - @InitBinder - protected void initBinder(WebDataBinder binder) { - binder.addCustomFormatter(new DateFormatter("yyyy-MM-dd")); <1> - } - - // ... - } ----- -<1> Adding a custom formatter (a `DateFormatter`, in this case). - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class FormController { - - @InitBinder - fun initBinder(binder: WebDataBinder) { - binder.addCustomFormatter(DateFormatter("yyyy-MM-dd")) // <1> - } - - // ... - } ----- -<1> Adding a custom formatter (a `DateFormatter`, in this case). --- - - -[[webflux-ann-initbinder-model-design]] -==== Model Design -[.small]#<<web.adoc#mvc-ann-initbinder-model-design, See equivalent in the Servlet stack>># - -include::web-data-binding-model-design.adoc[] - - -[[webflux-ann-controller-exceptions]] -=== Exceptions -[.small]#<<web.adoc#mvc-ann-exceptionhandler, See equivalent in the Servlet stack>># - -`@Controller` and <<webflux-ann-controller-advice, @ControllerAdvice>> classes can have -`@ExceptionHandler` methods to handle exceptions from controller methods. The following -example includes such a handler method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class SimpleController { - - // ... - - @ExceptionHandler // <1> - public ResponseEntity<String> handle(IOException ex) { - // ... - } - } ----- -<1> Declaring an `@ExceptionHandler`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class SimpleController { - - // ... - - @ExceptionHandler // <1> - fun handle(ex: IOException): ResponseEntity<String> { - // ... - } - } ----- -<1> Declaring an `@ExceptionHandler`. - - -The exception can match against a top-level exception being propagated (that is, a direct -`IOException` being thrown) or against the immediate cause within a top-level wrapper -exception (for example, an `IOException` wrapped inside an `IllegalStateException`). - -For matching exception types, preferably declare the target exception as a method argument, -as shown in the preceding example. Alternatively, the annotation declaration can narrow the -exception types to match. We generally recommend being as specific as possible in the -argument signature and to declare your primary root exception mappings on a -`@ControllerAdvice` prioritized with a corresponding order. -See <<web.adoc#mvc-ann-exceptionhandler, the MVC section>> for details. - -NOTE: An `@ExceptionHandler` method in WebFlux supports the same method arguments and -return values as a `@RequestMapping` method, with the exception of request body- -and `@ModelAttribute`-related method arguments. - -Support for `@ExceptionHandler` methods in Spring WebFlux is provided by the -`HandlerAdapter` for `@RequestMapping` methods. See <<webflux-dispatcher-handler>> -for more detail. - - - -[[webflux-ann-exceptionhandler-args]] -==== Method Arguments -[.small]#<<web.adoc#mvc-ann-exceptionhandler-args, See equivalent in the Servlet stack>># - -`@ExceptionHandler` methods support the same <<webflux-ann-arguments,method arguments>> -as `@RequestMapping` methods, except the request body might have been consumed already. - - - -[[webflux-ann-exceptionhandler-return-values]] -==== Return Values -[.small]#<<web.adoc#mvc-ann-exceptionhandler-return-values, See equivalent in the Servlet stack>># - -`@ExceptionHandler` methods support the same <<webflux-ann-return-types,return values>> -as `@RequestMapping` methods. - - - -[[webflux-ann-controller-advice]] -=== Controller Advice -[.small]#<<web.adoc#mvc-ann-controller-advice, See equivalent in the Servlet stack>># - -Typically, the `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply -within the `@Controller` class (or class hierarchy) in which they are declared. If you -want such methods to apply more globally (across controllers), you can declare them in a -class annotated with `@ControllerAdvice` or `@RestControllerAdvice`. - -`@ControllerAdvice` is annotated with `@Component`, which means that such classes can be -registered as Spring beans through <<core.adoc#beans-java-instantiating-container-scan, -component scanning>>. `@RestControllerAdvice` is a composed annotation that is annotated -with both `@ControllerAdvice` and `@ResponseBody`, which essentially means -`@ExceptionHandler` methods are rendered to the response body through message conversion -(versus view resolution or template rendering). - -On startup, the infrastructure classes for `@RequestMapping` and `@ExceptionHandler` -methods detect Spring beans annotated with `@ControllerAdvice` and then apply their -methods at runtime. Global `@ExceptionHandler` methods (from a `@ControllerAdvice`) are -applied _after_ local ones (from the `@Controller`). By contrast, global `@ModelAttribute` -and `@InitBinder` methods are applied _before_ local ones. - -By default, `@ControllerAdvice` methods apply to every request (that is, all controllers), -but you can narrow that down to a subset of controllers by using attributes on the -annotation, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Target all Controllers annotated with @RestController - @ControllerAdvice(annotations = RestController.class) - public class ExampleAdvice1 {} - - // Target all Controllers within specific packages - @ControllerAdvice("org.example.controllers") - public class ExampleAdvice2 {} - - // Target all Controllers assignable to specific classes - @ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class}) - public class ExampleAdvice3 {} ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Target all Controllers annotated with @RestController - @ControllerAdvice(annotations = [RestController::class]) - public class ExampleAdvice1 {} - - // Target all Controllers within specific packages - @ControllerAdvice("org.example.controllers") - public class ExampleAdvice2 {} - - // Target all Controllers assignable to specific classes - @ControllerAdvice(assignableTypes = [ControllerInterface::class, AbstractController::class]) - public class ExampleAdvice3 {} ----- - -The selectors in the preceding example are evaluated at runtime and may negatively impact -performance if used extensively. See the -{api-spring-framework}/web/bind/annotation/ControllerAdvice.html[`@ControllerAdvice`] -javadoc for more details. - -include::webflux-functional.adoc[leveloffset=+1] - - - - -[[webflux-uri-building]] -== URI Links -[.small]#<<web.adoc#mvc-uri-building, See equivalent in the Servlet stack>># - -This section describes various options available in the Spring Framework to prepare URIs. - -include::web-uris.adoc[leveloffset=+2] - -include::webflux-cors.adoc[leveloffset=+1] - - -[[webflux-ann-rest-exceptions]] -== Error Responses -[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions, See equivalent in the Servlet stack>># - -A common requirement for REST services is to include details in the body of error -responses. The Spring Framework supports the "Problem Details for HTTP APIs" -specification, https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807]. - -The following are the main abstractions for this support: - -- `ProblemDetail` -- representation for an RFC 7807 problem detail; a simple container -for both standard fields defined in the spec, and for non-standard ones. -- `ErrorResponse` -- contract to expose HTTP error response details including HTTP -status, response headers, and a body in the format of RFC 7807; this allows exceptions to -encapsulate and expose the details of how they map to an HTTP response. All Spring WebFlux -exceptions implement this. -- `ErrorResponseException` -- basic `ErrorResponse` implementation that others -can use as a convenient base class. -- `ResponseEntityExceptionHandler` -- convenient base class for an -<<webflux-ann-controller-advice,@ControllerAdvice>> that handles all Spring WebFlux exceptions, -and any `ErrorResponseException`, and renders an error response with a body. - - - -[[webflux-ann-rest-exceptions-render]] -=== Render -[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions-render, See equivalent in the Servlet stack>># - -You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from -any `@RequestMapping` method to render an RFC 7807 response. This is processed as follows: - -- The `status` property of `ProblemDetail` determines the HTTP status. -- The `instance` property of `ProblemDetail` is set from the current URL path, if not -already set. -- For content negotiation, the Jackson `HttpMessageConverter` prefers -"application/problem+json" over "application/json" when rendering a `ProblemDetail`, -and also falls back on it if no compatible media type is found. - -To enable RFC 7807 responses for Spring WebFlux exceptions and for any -`ErrorResponseException`, extend `ResponseEntityExceptionHandler` and declare it as an -<<webflux-ann-controller-advice,@ControllerAdvice>> in Spring configuration. The handler -has an `@ExceptionHandler` method that handles any `ErrorResponse` exception, which -includes all built-in web exceptions. You can add more exception handling methods, and -use a protected method to map any exception to a `ProblemDetail`. - - - -[[webflux-ann-rest-exceptions-non-standard]] -=== Non-Standard Fields -[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions-non-standard, See equivalent in the Servlet stack>># - -You can extend an RFC 7807 response with non-standard fields in one of two ways. - -One, insert into the "properties" `Map` of `ProblemDetail`. When using the Jackson -library, the Spring Framework registers `ProblemDetailJacksonMixin` that ensures this -"properties" `Map` is unwrapped and rendered as top level JSON properties in the -response, and likewise any unknown property during deserialization is inserted into -this `Map`. - -You can also extend `ProblemDetail` to add dedicated non-standard properties. -The copy constructor in `ProblemDetail` allows a subclass to make it easy to be created -from an existing `ProblemDetail`. This could be done centrally, e.g. from an -`@ControllerAdvice` such as `ResponseEntityExceptionHandler` that re-creates the -`ProblemDetail` of an exception into a subclass with the additional non-standard fields. - - - -[[webflux-ann-rest-exceptions-i18n]] -=== Internationalization -[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions-i18n, See equivalent in the Servlet stack>># - -It is a common requirement to internationalize error response details, and good practice -to customize the problem details for Spring WebFlux exceptions. This is supported as follows: - -- Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field -through a <<core.adoc#context-functionality-messagesource,MessageSource>>. -The actual message code value is parameterized with placeholders, e.g. -`"HTTP method {0} not supported"` to be expanded from the arguments. -- Each `ErrorResponse` also exposes a message code to resolve the "title" field. -- `ResponseEntityExceptionHandler` uses the message code and arguments to resolve the -"detail" and the "title" fields. - -By default, the message code for the "detail" field is "problemDetail." + the fully -qualified exception class name. Some exceptions may expose additional message codes in -which case a suffix is added to the default message code. The table below lists message -arguments and codes for Spring WebFlux exceptions: - -[[webflux-ann-rest-exceptions-codes]] -[cols="1,1,2", options="header"] -|=== -| Exception | Message Code | Message Code Arguments - -| `UnsupportedMediaTypeStatusException` -| (default) -| `{0}` the media type that is not supported, `{1}` list of supported media types - -| `UnsupportedMediaTypeStatusException` -| (default) + ".parseError" -| - -| `MissingRequestValueException` -| (default) -| `{0}` a label for the value (e.g. "request header", "cookie value", ...), `{1}` the value name - -| `UnsatisfiedRequestParameterException` -| (default) -| `{0}` the list of parameter conditions - -| `WebExchangeBindException` -| (default) -| `{0}` the list of global errors, `{1}` the list of field errors. -Message codes and arguments for each error within the `BindingResult` are also resolved -via `MessageSource`. - -| `NotAcceptableStatusException` -| (default) -| `{0}` list of supported media types - -| `NotAcceptableStatusException` -| (default) + ".parseError" -| - -| `ServerErrorException` -| (default) -| `{0}` the failure reason provided to the class constructor - -| `MethodNotAllowedException` -| (default) -| `{0}` the current HTTP method, `{1}` the list of supported HTTP methods - -|=== - -By default, the message code for the "title" field is "problemDetail.title." + the fully -qualified exception class name. - - - - -[[webflux-ann-rest-exceptions-client]] -=== Client Handling -[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions-client, See equivalent in the Servlet stack>># - -A client application can catch `WebClientResponseException`, when using the `WebClient`, -or `RestClientResponseException` when using the `RestTemplate`, and use their -`getResponseBodyAs` methods to decode the error response body to any target type such as -`ProblemDetail`, or a subclass of `ProblemDetail`. - - - - -[[webflux-web-security]] -== Web Security -[.small]#<<web.adoc#mvc-web-security, See equivalent in the Servlet stack>># - -The https://spring.io/projects/spring-security[Spring Security] project provides support -for protecting web applications from malicious exploits. See the Spring Security -reference documentation, including: - -* {docs-spring-security}/reactive/configuration/webflux.html[WebFlux Security] -* {docs-spring-security}/reactive/test/index.html[WebFlux Testing Support] -* {docs-spring-security}/features/exploits/csrf.html#csrf-protection[CSRF protection] -* {docs-spring-security}/features/exploits/headers.html[Security Response Headers] - - - - -[[webflux-caching]] -== HTTP Caching -[.small]#<<web.adoc#mvc-caching, See equivalent in the Servlet stack>># - -HTTP caching can significantly improve the performance of a web application. HTTP caching -revolves around the `Cache-Control` response header and subsequent conditional request -headers, such as `Last-Modified` and `ETag`. `Cache-Control` advises private (for example, browser) -and public (for example, proxy) caches how to cache and re-use responses. An `ETag` header is used -to make a conditional request that may result in a 304 (NOT_MODIFIED) without a body, -if the content has not changed. `ETag` can be seen as a more sophisticated successor to -the `Last-Modified` header. - -This section describes the HTTP caching related options available in Spring WebFlux. - - - -[[webflux-caching-cachecontrol]] -=== `CacheControl` -[.small]#<<web.adoc#mvc-caching-cachecontrol, See equivalent in the Servlet stack>># - -{api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for -configuring settings related to the `Cache-Control` header and is accepted as an argument -in a number of places: - -* <<webflux-caching-etag-lastmodified>> -* <<webflux-caching-static-resources>> - -While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all possible -directives for the `Cache-Control` response header, the `CacheControl` type takes a -use case-oriented approach that focuses on the common scenarios, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Cache for an hour - "Cache-Control: max-age=3600" - CacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS); - - // Prevent caching - "Cache-Control: no-store" - CacheControl ccNoStore = CacheControl.noStore(); - - // Cache for ten days in public and private caches, - // public caches should not transform the response - // "Cache-Control: max-age=864000, public, no-transform" - CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic(); ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Cache for an hour - "Cache-Control: max-age=3600" - val ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS) - - // Prevent caching - "Cache-Control: no-store" - val ccNoStore = CacheControl.noStore() - - // Cache for ten days in public and private caches, - // public caches should not transform the response - // "Cache-Control: max-age=864000, public, no-transform" - val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic() - ----- - - - -[[webflux-caching-etag-lastmodified]] -=== Controllers -[.small]#<<web.adoc#mvc-caching-etag-lastmodified, See equivalent in the Servlet stack>># - -Controllers can add explicit support for HTTP caching. We recommend doing so, since the -`lastModified` or `ETag` value for a resource needs to be calculated before it can be compared -against conditional request headers. A controller can add an `ETag` and `Cache-Control` -settings to a `ResponseEntity`, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/book/{id}") - public ResponseEntity<Book> showBook(@PathVariable Long id) { - - Book book = findBook(id); - String version = book.getVersion(); - - return ResponseEntity - .ok() - .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS)) - .eTag(version) // lastModified is also available - .body(book); - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/book/{id}") - fun showBook(@PathVariable id: Long): ResponseEntity<Book> { - - val book = findBook(id) - val version = book.getVersion() - - return ResponseEntity - .ok() - .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS)) - .eTag(version) // lastModified is also available - .body(book) - } ----- --- - -The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison -to the conditional request headers indicates the content has not changed. Otherwise, the -`ETag` and `Cache-Control` headers are added to the response. - -You can also make the check against conditional request headers in the controller, -as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RequestMapping - public String myHandleMethod(ServerWebExchange exchange, Model model) { - - long eTag = ... // <1> - - if (exchange.checkNotModified(eTag)) { - return null; // <2> - } - - model.addAttribute(...); // <3> - return "myViewName"; - } ----- -<1> Application-specific calculation. -<2> Response has been set to 304 (NOT_MODIFIED). No further processing. -<3> Continue with request processing. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RequestMapping - fun myHandleMethod(exchange: ServerWebExchange, model: Model): String? { - - val eTag: Long = ... // <1> - - if (exchange.checkNotModified(eTag)) { - return null// <2> - } - - model.addAttribute(...) // <3> - return "myViewName" - } ----- -<1> Application-specific calculation. -<2> Response has been set to 304 (NOT_MODIFIED). No further processing. -<3> Continue with request processing. --- - -There are three variants for checking conditional requests against `eTag` values, `lastModified` -values, or both. For conditional `GET` and `HEAD` requests, you can set the response to -304 (NOT_MODIFIED). For conditional `POST`, `PUT`, and `DELETE`, you can instead set the response -to 412 (PRECONDITION_FAILED) to prevent concurrent modification. - - - -[[webflux-caching-static-resources]] -=== Static Resources -[.small]#<<web.adoc#mvc-caching-static-resources, See equivalent in the Servlet stack>># - -You should serve static resources with a `Cache-Control` and conditional response headers -for optimal performance. See the section on configuring <<webflux-config-static-resources>>. - - -include::webflux-view.adoc[leveloffset=+1] - - -[[webflux-config]] -== WebFlux Config -[.small]#<<web.adoc#mvc-config, See equivalent in the Servlet stack>># - -The WebFlux Java configuration declares the components that are required to process -requests with annotated controllers or functional endpoints, and it offers an API to -customize the configuration. That means you do not need to understand the underlying -beans created by the Java configuration. However, if you want to understand them, -you can see them in `WebFluxConfigurationSupport` or read more about what they are -in <<webflux-special-bean-types>>. - -For more advanced customizations, not available in the configuration API, you can -gain full control over the configuration through the -<<webflux-config-advanced-java>>. - - - -[[webflux-config-enable]] -=== Enabling WebFlux Config -[.small]#<<web.adoc#mvc-config-enable, See equivalent in the Servlet stack>># - -You can use the `@EnableWebFlux` annotation in your Java config, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig { - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig ----- - -The preceding example registers a number of Spring WebFlux -<<webflux-special-bean-types, infrastructure beans>> and adapts to dependencies -available on the classpath -- for JSON, XML, and others. - - - -[[webflux-config-customize]] -=== WebFlux config API -[.small]#<<web.adoc#mvc-config-customize, See equivalent in the Servlet stack>># - -In your Java configuration, you can implement the `WebFluxConfigurer` interface, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - // Implement configuration methods... - } ----- - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -@Configuration -@EnableWebFlux -class WebConfig : WebFluxConfigurer { - - // Implement configuration methods... -} ----- - - - -[[webflux-config-conversion]] -=== Conversion, formatting -[.small]#<<web.adoc#mvc-config-conversion, See equivalent in the Servlet stack>># - -By default, formatters for various number and date types are installed, along with support -for customization via `@NumberFormat` and `@DateTimeFormat` on fields. - -To register custom formatters and converters in Java config, use the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public void addFormatters(FormatterRegistry registry) { - // ... - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun addFormatters(registry: FormatterRegistry) { - // ... - } - } ----- - -By default Spring WebFlux considers the request Locale when parsing and formatting date -values. This works for forms where dates are represented as Strings with "input" form -fields. For "date" and "time" form fields, however, browsers use a fixed format defined -in the HTML spec. For such cases date and time formatting can be customized as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public void addFormatters(FormatterRegistry registry) { - DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar(); - registrar.setUseIsoFormat(true); - registrar.registerFormatters(registry); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun addFormatters(registry: FormatterRegistry) { - val registrar = DateTimeFormatterRegistrar() - registrar.setUseIsoFormat(true) - registrar.registerFormatters(registry) - } - } ----- - -NOTE: See <<core.adoc#format-FormatterRegistrar-SPI, `FormatterRegistrar` SPI>> -and the `FormattingConversionServiceFactoryBean` for more information on when to -use `FormatterRegistrar` implementations. - - - -[[webflux-config-validation]] -=== Validation -[.small]#<<web.adoc#mvc-config-validation, See equivalent in the Servlet stack>># - -By default, if <<core.adoc#validation-beanvalidation-overview, Bean Validation>> is present -on the classpath (for example, the Hibernate Validator), the `LocalValidatorFactoryBean` -is registered as a global <<core.adoc#validator,validator>> for use with `@Valid` and -`@Validated` on `@Controller` method arguments. - -In your Java configuration, you can customize the global `Validator` instance, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public Validator getValidator() { - // ... - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun getValidator(): Validator { - // ... - } - - } ----- - -Note that you can also register `Validator` implementations locally, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class MyController { - - @InitBinder - protected void initBinder(WebDataBinder binder) { - binder.addValidators(new FooValidator()); - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class MyController { - - @InitBinder - protected fun initBinder(binder: WebDataBinder) { - binder.addValidators(FooValidator()) - } - } ----- - - -TIP: If you need to have a `LocalValidatorFactoryBean` injected somewhere, create a bean and -mark it with `@Primary` in order to avoid conflict with the one declared in the MVC config. - - - -[[webflux-config-content-negotiation]] -=== Content Type Resolvers -[.small]#<<web.adoc#mvc-config-content-negotiation, See equivalent in the Servlet stack>># - -You can configure how Spring WebFlux determines the requested media types for -`@Controller` instances from the request. By default, only the `Accept` header is checked, -but you can also enable a query parameter-based strategy. - -The following example shows how to customize the requested content type resolution: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun configureContentTypeResolver(builder: RequestedContentTypeResolverBuilder) { - // ... - } - } ----- - - - -[[webflux-config-message-codecs]] -=== HTTP message codecs -[.small]#<<web.adoc#mvc-config-message-converters, See equivalent in the Servlet stack>># - -The following example shows how to customize how the request and response body are read and written: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) { - configurer.defaultCodecs().maxInMemorySize(512 * 1024); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun configureHttpMessageCodecs(configurer: ServerCodecConfigurer) { - // ... - } - } ----- - -`ServerCodecConfigurer` provides a set of default readers and writers. You can use it to add -more readers and writers, customize the default ones, or replace the default ones completely. - -For Jackson JSON and XML, consider using -{api-spring-framework}/http/converter/json/Jackson2ObjectMapperBuilder.html[`Jackson2ObjectMapperBuilder`], -which customizes Jackson's default properties with the following ones: - -* https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/DeserializationFeature.html#FAIL_ON_UNKNOWN_PROPERTIES[`DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES`] is disabled. -* https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/MapperFeature.html#DEFAULT_VIEW_INCLUSION[`MapperFeature.DEFAULT_VIEW_INCLUSION`] is disabled. - -It also automatically registers the following well-known modules if they are detected on the classpath: - -* https://github.com/FasterXML/jackson-datatype-joda[`jackson-datatype-joda`]: Support for Joda-Time types. -* https://github.com/FasterXML/jackson-datatype-jsr310[`jackson-datatype-jsr310`]: Support for Java 8 Date and Time API types. -* https://github.com/FasterXML/jackson-datatype-jdk8[`jackson-datatype-jdk8`]: Support for other Java 8 types, such as `Optional`. -* https://github.com/FasterXML/jackson-module-kotlin[`jackson-module-kotlin`]: Support for Kotlin classes and data classes. - - - -[[webflux-config-view-resolvers]] -=== View Resolvers -[.small]#<<web.adoc#mvc-config-view-resolvers, See equivalent in the Servlet stack>># - -The following example shows how to configure view resolution: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - // ... - } - } ----- - -The `ViewResolverRegistry` has shortcuts for view technologies with which the Spring Framework -integrates. The following example uses FreeMarker (which also requires configuring the -underlying FreeMarker view technology): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - registry.freeMarker(); - } - - // Configure Freemarker... - - @Bean - public FreeMarkerConfigurer freeMarkerConfigurer() { - FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); - configurer.setTemplateLoaderPath("classpath:/templates"); - return configurer; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - registry.freeMarker() - } - - // Configure Freemarker... - - @Bean - fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply { - setTemplateLoaderPath("classpath:/templates") - } - } ----- - -You can also plug in any `ViewResolver` implementation, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - ViewResolver resolver = ... ; - registry.viewResolver(resolver); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - val resolver: ViewResolver = ... - registry.viewResolver(resolver - } - } ----- - -To support <<webflux-multiple-representations>> and rendering other formats -through view resolution (besides HTML), you can configure one or more default views based -on the `HttpMessageWriterView` implementation, which accepts any of the available -<<webflux-codecs>> from `spring-web`. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - registry.freeMarker(); - - Jackson2JsonEncoder encoder = new Jackson2JsonEncoder(); - registry.defaultViews(new HttpMessageWriterView(encoder)); - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - registry.freeMarker() - - val encoder = Jackson2JsonEncoder() - registry.defaultViews(HttpMessageWriterView(encoder)) - } - - // ... - } ----- - -See <<webflux-view>> for more on the view technologies that are integrated with Spring WebFlux. - - - -[[webflux-config-static-resources]] -=== Static Resources -[.small]#<<web.adoc#mvc-config-static-resources, See equivalent in the Servlet stack>># - -This option provides a convenient way to serve static resources from a list of -{api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. - -In the next example, given a request that starts with `/resources`, the relative path is -used to find and serve static resources relative to `/static` on the classpath. Resources -are served with a one-year future expiration to ensure maximum use of the browser cache -and a reduction in HTTP requests made by the browser. The `Last-Modified` header is also -evaluated and, if present, a `304` status code is returned. The following listing shows -the example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public void addResourceHandlers(ResourceHandlerRegistry registry) { - registry.addResourceHandler("/resources/**") - .addResourceLocations("/public", "classpath:/static/") - .setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS)); - } - - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun addResourceHandlers(registry: ResourceHandlerRegistry) { - registry.addResourceHandler("/resources/**") - .addResourceLocations("/public", "classpath:/static/") - .setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS)) - } - } ----- - -See also <<webflux-caching-static-resources, HTTP caching support for static resources>>. - -The resource handler also supports a chain of -{api-spring-framework}/web/reactive/resource/ResourceResolver.html[`ResourceResolver`] implementations and -{api-spring-framework}/web/reactive/resource/ResourceTransformer.html[`ResourceTransformer`] implementations, -which can be used to create a toolchain for working with optimized resources. - -You can use the `VersionResourceResolver` for versioned resource URLs based on an MD5 hash -computed from the content, a fixed application version, or other information. A -`ContentVersionStrategy` (MD5 hash) is a good choice with some notable exceptions (such as -JavaScript resources used with a module loader). - -The following example shows how to use `VersionResourceResolver` in your Java configuration: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public void addResourceHandlers(ResourceHandlerRegistry registry) { - registry.addResourceHandler("/resources/**") - .addResourceLocations("/public/") - .resourceChain(true) - .addResolver(new VersionResourceResolver().addContentVersionStrategy("/**")); - } - - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - override fun addResourceHandlers(registry: ResourceHandlerRegistry) { - registry.addResourceHandler("/resources/**") - .addResourceLocations("/public/") - .resourceChain(true) - .addResolver(VersionResourceResolver().addContentVersionStrategy("/**")) - } - - } ----- - -You can use `ResourceUrlProvider` to rewrite URLs and apply the full chain of resolvers and -transformers (for example, to insert versions). The WebFlux configuration provides a `ResourceUrlProvider` -so that it can be injected into others. - -Unlike Spring MVC, at present, in WebFlux, there is no way to transparently rewrite static -resource URLs, since there are no view technologies that can make use of a non-blocking chain -of resolvers and transformers. When serving only local resources, the workaround is to use -`ResourceUrlProvider` directly (for example, through a custom element) and block. - -Note that, when using both `EncodedResourceResolver` (for example, Gzip, Brotli encoded) and -`VersionedResourceResolver`, they must be registered in that order, to ensure content-based -versions are always computed reliably based on the unencoded file. - -For https://www.webjars.org/documentation[WebJars], versioned URLs like -`/webjars/jquery/1.2.0/jquery.min.js` are the recommended and most efficient way to use them. -The related resource location is configured out of the box with Spring Boot (or can be configured -manually via `ResourceHandlerRegistry`) and does not require to add the -`org.webjars:webjars-locator-core` dependency. - -Version-less URLs like `/webjars/jquery/jquery.min.js` are supported through the -`WebJarsResourceResolver` which is automatically registered when the -`org.webjars:webjars-locator-core` library is present on the classpath, at the cost of a -classpath scanning that could slow down application startup. The resolver can re-write URLs to -include the version of the jar and can also match against incoming URLs without versions --- for example, from `/webjars/jquery/jquery.min.js` to `/webjars/jquery/1.2.0/jquery.min.js`. - -TIP: The Java configuration based on `ResourceHandlerRegistry` provides further options -for fine-grained control, e.g. last-modified behavior and optimized resource resolution. - - - -[[webflux-config-path-matching]] -=== Path Matching -[.small]#<<web.adoc#mvc-config-path-matching, See equivalent in the Servlet stack>># - -You can customize options related to path matching. For details on the individual options, see the -{api-spring-framework}/web/reactive/config/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc. -The following example shows how to use `PathMatchConfigurer`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public void configurePathMatch(PathMatchConfigurer configurer) { - configurer - .setUseCaseSensitiveMatch(true) - .addPathPrefix("/api", HandlerTypePredicate.forAnnotation(RestController.class)); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - @Override - fun configurePathMatch(configurer: PathMatchConfigurer) { - configurer - .setUseCaseSensitiveMatch(true) - .addPathPrefix("/api", HandlerTypePredicate.forAnnotation(RestController::class.java)) - } - } ----- - -[TIP] -==== -Spring WebFlux relies on a parsed representation of the request path called -`RequestPath` for access to decoded path segment values, with semicolon content removed -(that is, path or matrix variables). That means, unlike in Spring MVC, you need not indicate -whether to decode the request path nor whether to remove semicolon content for -path matching purposes. - -Spring WebFlux also does not support suffix pattern matching, unlike in Spring MVC, where we -are also <<web.adoc#mvc-ann-requestmapping-suffix-pattern-match, recommend>> moving away from -reliance on it. -==== - - - -[[webflux-config-websocket-service]] -=== WebSocketService - -The WebFlux Java config declares of a `WebSocketHandlerAdapter` bean which provides -support for the invocation of WebSocket handlers. That means all that remains to do in -order to handle a WebSocket handshake request is to map a `WebSocketHandler` to a URL -via `SimpleUrlHandlerMapping`. - -In some cases it may be necessary to create the `WebSocketHandlerAdapter` bean with a -provided `WebSocketService` service which allows configuring WebSocket server properties. -For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebFlux - public class WebConfig implements WebFluxConfigurer { - - @Override - public WebSocketService getWebSocketService() { - TomcatRequestUpgradeStrategy strategy = new TomcatRequestUpgradeStrategy(); - strategy.setMaxSessionIdleTimeout(0L); - return new HandshakeWebSocketService(strategy); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebFlux - class WebConfig : WebFluxConfigurer { - - @Override - fun webSocketService(): WebSocketService { - val strategy = TomcatRequestUpgradeStrategy().apply { - setMaxSessionIdleTimeout(0L) - } - return HandshakeWebSocketService(strategy) - } - } ----- - - - - -[[webflux-config-advanced-java]] -=== Advanced Configuration Mode -[.small]#<<web.adoc#mvc-config-advanced-java, See equivalent in the Servlet stack>># - -`@EnableWebFlux` imports `DelegatingWebFluxConfiguration` that: - -* Provides default Spring configuration for WebFlux applications - -* detects and delegates to `WebFluxConfigurer` implementations to customize that configuration. - -For advanced mode, you can remove `@EnableWebFlux` and extend directly from -`DelegatingWebFluxConfiguration` instead of implementing `WebFluxConfigurer`, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class WebConfig extends DelegatingWebFluxConfiguration { - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class WebConfig : DelegatingWebFluxConfiguration { - - // ... - } ----- - -You can keep existing methods in `WebConfig`, but you can now also override bean declarations -from the base class and still have any number of other `WebMvcConfigurer` implementations on -the classpath. - - - - -[[webflux-http2]] -== HTTP/2 -[.small]#<<web.adoc#mvc-http2, See equivalent in the Servlet stack>># - -HTTP/2 is supported with Reactor Netty, Tomcat, Jetty, and Undertow. However, there are -considerations related to server configuration. For more details, see the -https://github.com/spring-projects/spring-framework/wiki/HTTP-2-support[HTTP/2 wiki page]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc new file mode 100644 index 000000000000..e46f27228f5e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc @@ -0,0 +1,151 @@ +[[webflux-ann-rest-exceptions]] += Error Responses + +[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions, See equivalent in the Servlet stack>># + +A common requirement for REST services is to include details in the body of error +responses. The Spring Framework supports the "Problem Details for HTTP APIs" +specification, https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807]. + +The following are the main abstractions for this support: + +- `ProblemDetail` -- representation for an RFC 7807 problem detail; a simple container +for both standard fields defined in the spec, and for non-standard ones. +- `ErrorResponse` -- contract to expose HTTP error response details including HTTP +status, response headers, and a body in the format of RFC 7807; this allows exceptions to +encapsulate and expose the details of how they map to an HTTP response. All Spring WebFlux +exceptions implement this. +- `ErrorResponseException` -- basic `ErrorResponse` implementation that others +can use as a convenient base class. +- `ResponseEntityExceptionHandler` -- convenient base class for an +<<webflux-ann-controller-advice,@ControllerAdvice>> that handles all Spring WebFlux exceptions, +and any `ErrorResponseException`, and renders an error response with a body. + + + +[[webflux-ann-rest-exceptions-render]] +== Render +[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions-render, See equivalent in the Servlet stack>># + +You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from +any `@RequestMapping` method to render an RFC 7807 response. This is processed as follows: + +- The `status` property of `ProblemDetail` determines the HTTP status. +- The `instance` property of `ProblemDetail` is set from the current URL path, if not +already set. +- For content negotiation, the Jackson `HttpMessageConverter` prefers +"application/problem+json" over "application/json" when rendering a `ProblemDetail`, +and also falls back on it if no compatible media type is found. + +To enable RFC 7807 responses for Spring WebFlux exceptions and for any +`ErrorResponseException`, extend `ResponseEntityExceptionHandler` and declare it as an +<<webflux-ann-controller-advice,@ControllerAdvice>> in Spring configuration. The handler +has an `@ExceptionHandler` method that handles any `ErrorResponse` exception, which +includes all built-in web exceptions. You can add more exception handling methods, and +use a protected method to map any exception to a `ProblemDetail`. + + + +[[webflux-ann-rest-exceptions-non-standard]] +== Non-Standard Fields +[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions-non-standard, See equivalent in the Servlet stack>># + +You can extend an RFC 7807 response with non-standard fields in one of two ways. + +One, insert into the "properties" `Map` of `ProblemDetail`. When using the Jackson +library, the Spring Framework registers `ProblemDetailJacksonMixin` that ensures this +"properties" `Map` is unwrapped and rendered as top level JSON properties in the +response, and likewise any unknown property during deserialization is inserted into +this `Map`. + +You can also extend `ProblemDetail` to add dedicated non-standard properties. +The copy constructor in `ProblemDetail` allows a subclass to make it easy to be created +from an existing `ProblemDetail`. This could be done centrally, e.g. from an +`@ControllerAdvice` such as `ResponseEntityExceptionHandler` that re-creates the +`ProblemDetail` of an exception into a subclass with the additional non-standard fields. + + + +[[webflux-ann-rest-exceptions-i18n]] +== Internationalization +[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions-i18n, See equivalent in the Servlet stack>># + +It is a common requirement to internationalize error response details, and good practice +to customize the problem details for Spring WebFlux exceptions. This is supported as follows: + +- Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field +through a <<core.adoc#context-functionality-messagesource,MessageSource>>. +The actual message code value is parameterized with placeholders, e.g. +`"HTTP method {0} not supported"` to be expanded from the arguments. +- Each `ErrorResponse` also exposes a message code to resolve the "title" field. +- `ResponseEntityExceptionHandler` uses the message code and arguments to resolve the +"detail" and the "title" fields. + +By default, the message code for the "detail" field is "problemDetail." + the fully +qualified exception class name. Some exceptions may expose additional message codes in +which case a suffix is added to the default message code. The table below lists message +arguments and codes for Spring WebFlux exceptions: + +[[webflux-ann-rest-exceptions-codes]] +[cols="1,1,2", options="header"] +|=== +| Exception | Message Code | Message Code Arguments + +| `UnsupportedMediaTypeStatusException` +| (default) +| `{0}` the media type that is not supported, `{1}` list of supported media types + +| `UnsupportedMediaTypeStatusException` +| (default) + ".parseError" +| + +| `MissingRequestValueException` +| (default) +| `{0}` a label for the value (e.g. "request header", "cookie value", ...), `{1}` the value name + +| `UnsatisfiedRequestParameterException` +| (default) +| `{0}` the list of parameter conditions + +| `WebExchangeBindException` +| (default) +| `{0}` the list of global errors, `{1}` the list of field errors. +Message codes and arguments for each error within the `BindingResult` are also resolved +via `MessageSource`. + +| `NotAcceptableStatusException` +| (default) +| `{0}` list of supported media types + +| `NotAcceptableStatusException` +| (default) + ".parseError" +| + +| `ServerErrorException` +| (default) +| `{0}` the failure reason provided to the class constructor + +| `MethodNotAllowedException` +| (default) +| `{0}` the current HTTP method, `{1}` the list of supported HTTP methods + +|=== + +By default, the message code for the "title" field is "problemDetail.title." + the fully +qualified exception class name. + + + + +[[webflux-ann-rest-exceptions-client]] +== Client Handling +[.small]#<<webmvc.adoc#mvc-ann-rest-exceptions-client, See equivalent in the Servlet stack>># + +A client application can catch `WebClientResponseException`, when using the `WebClient`, +or `RestClientResponseException` when using the `RestTemplate`, and use their +`getResponseBodyAs` methods to decode the error response body to any target type such as +`ProblemDetail`, or a subclass of `ProblemDetail`. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc new file mode 100644 index 000000000000..0178ebf2b162 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc @@ -0,0 +1,177 @@ +[[webflux-caching]] += HTTP Caching + +[.small]#<<web.adoc#mvc-caching, See equivalent in the Servlet stack>># + +HTTP caching can significantly improve the performance of a web application. HTTP caching +revolves around the `Cache-Control` response header and subsequent conditional request +headers, such as `Last-Modified` and `ETag`. `Cache-Control` advises private (for example, browser) +and public (for example, proxy) caches how to cache and re-use responses. An `ETag` header is used +to make a conditional request that may result in a 304 (NOT_MODIFIED) without a body, +if the content has not changed. `ETag` can be seen as a more sophisticated successor to +the `Last-Modified` header. + +This section describes the HTTP caching related options available in Spring WebFlux. + + + +[[webflux-caching-cachecontrol]] +== `CacheControl` +[.small]#<<web.adoc#mvc-caching-cachecontrol, See equivalent in the Servlet stack>># + +{api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for +configuring settings related to the `Cache-Control` header and is accepted as an argument +in a number of places: + +* <<webflux-caching-etag-lastmodified>> +* <<webflux-caching-static-resources>> + +While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all possible +directives for the `Cache-Control` response header, the `CacheControl` type takes a +use case-oriented approach that focuses on the common scenarios, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Cache for an hour - "Cache-Control: max-age=3600" + CacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS); + + // Prevent caching - "Cache-Control: no-store" + CacheControl ccNoStore = CacheControl.noStore(); + + // Cache for ten days in public and private caches, + // public caches should not transform the response + // "Cache-Control: max-age=864000, public, no-transform" + CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic(); +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Cache for an hour - "Cache-Control: max-age=3600" + val ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS) + + // Prevent caching - "Cache-Control: no-store" + val ccNoStore = CacheControl.noStore() + + // Cache for ten days in public and private caches, + // public caches should not transform the response + // "Cache-Control: max-age=864000, public, no-transform" + val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic() + +---- + + + +[[webflux-caching-etag-lastmodified]] +== Controllers +[.small]#<<web.adoc#mvc-caching-etag-lastmodified, See equivalent in the Servlet stack>># + +Controllers can add explicit support for HTTP caching. We recommend doing so, since the +`lastModified` or `ETag` value for a resource needs to be calculated before it can be compared +against conditional request headers. A controller can add an `ETag` and `Cache-Control` +settings to a `ResponseEntity`, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/book/{id}") + public ResponseEntity<Book> showBook(@PathVariable Long id) { + + Book book = findBook(id); + String version = book.getVersion(); + + return ResponseEntity + .ok() + .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS)) + .eTag(version) // lastModified is also available + .body(book); + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/book/{id}") + fun showBook(@PathVariable id: Long): ResponseEntity<Book> { + + val book = findBook(id) + val version = book.getVersion() + + return ResponseEntity + .ok() + .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS)) + .eTag(version) // lastModified is also available + .body(book) + } +---- +-- + +The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison +to the conditional request headers indicates the content has not changed. Otherwise, the +`ETag` and `Cache-Control` headers are added to the response. + +You can also make the check against conditional request headers in the controller, +as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RequestMapping + public String myHandleMethod(ServerWebExchange exchange, Model model) { + + long eTag = ... // <1> + + if (exchange.checkNotModified(eTag)) { + return null; // <2> + } + + model.addAttribute(...); // <3> + return "myViewName"; + } +---- +<1> Application-specific calculation. +<2> Response has been set to 304 (NOT_MODIFIED). No further processing. +<3> Continue with request processing. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RequestMapping + fun myHandleMethod(exchange: ServerWebExchange, model: Model): String? { + + val eTag: Long = ... // <1> + + if (exchange.checkNotModified(eTag)) { + return null// <2> + } + + model.addAttribute(...) // <3> + return "myViewName" + } +---- +<1> Application-specific calculation. +<2> Response has been set to 304 (NOT_MODIFIED). No further processing. +<3> Continue with request processing. +-- + +There are three variants for checking conditional requests against `eTag` values, `lastModified` +values, or both. For conditional `GET` and `HEAD` requests, you can set the response to +304 (NOT_MODIFIED). For conditional `POST`, `PUT`, and `DELETE`, you can instead set the response +to 412 (PRECONDITION_FAILED) to prevent concurrent modification. + + + +[[webflux-caching-static-resources]] +== Static Resources +[.small]#<<web.adoc#mvc-caching-static-resources, See equivalent in the Servlet stack>># + +You should serve static resources with a `Cache-Control` and conditional response headers +for optimal performance. See the section on configuring <<webflux-config-static-resources>>. + + +include:../:webflux-view.adoc[leveloffset=+1] + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc new file mode 100644 index 000000000000..62b53bb86357 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc @@ -0,0 +1,741 @@ +[[webflux-config]] += WebFlux Config + +[.small]#<<web.adoc#mvc-config, See equivalent in the Servlet stack>># + +The WebFlux Java configuration declares the components that are required to process +requests with annotated controllers or functional endpoints, and it offers an API to +customize the configuration. That means you do not need to understand the underlying +beans created by the Java configuration. However, if you want to understand them, +you can see them in `WebFluxConfigurationSupport` or read more about what they are +in <<webflux-special-bean-types>>. + +For more advanced customizations, not available in the configuration API, you can +gain full control over the configuration through the +<<webflux-config-advanced-java>>. + + + +[[webflux-config-enable]] +== Enabling WebFlux Config +[.small]#<<web.adoc#mvc-config-enable, See equivalent in the Servlet stack>># + +You can use the `@EnableWebFlux` annotation in your Java config, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig { + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig +---- + +The preceding example registers a number of Spring WebFlux +<<webflux-special-bean-types, infrastructure beans>> and adapts to dependencies +available on the classpath -- for JSON, XML, and others. + + + +[[webflux-config-customize]] +== WebFlux config API +[.small]#<<web.adoc#mvc-config-customize, See equivalent in the Servlet stack>># + +In your Java configuration, you can implement the `WebFluxConfigurer` interface, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + // Implement configuration methods... + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +@Configuration +@EnableWebFlux +class WebConfig : WebFluxConfigurer { + + // Implement configuration methods... +} +---- + + + +[[webflux-config-conversion]] +== Conversion, formatting +[.small]#<<web.adoc#mvc-config-conversion, See equivalent in the Servlet stack>># + +By default, formatters for various number and date types are installed, along with support +for customization via `@NumberFormat` and `@DateTimeFormat` on fields. + +To register custom formatters and converters in Java config, use the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public void addFormatters(FormatterRegistry registry) { + // ... + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun addFormatters(registry: FormatterRegistry) { + // ... + } + } +---- + +By default Spring WebFlux considers the request Locale when parsing and formatting date +values. This works for forms where dates are represented as Strings with "input" form +fields. For "date" and "time" form fields, however, browsers use a fixed format defined +in the HTML spec. For such cases date and time formatting can be customized as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public void addFormatters(FormatterRegistry registry) { + DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar(); + registrar.setUseIsoFormat(true); + registrar.registerFormatters(registry); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun addFormatters(registry: FormatterRegistry) { + val registrar = DateTimeFormatterRegistrar() + registrar.setUseIsoFormat(true) + registrar.registerFormatters(registry) + } + } +---- + +NOTE: See <<core.adoc#format-FormatterRegistrar-SPI, `FormatterRegistrar` SPI>> +and the `FormattingConversionServiceFactoryBean` for more information on when to +use `FormatterRegistrar` implementations. + + + +[[webflux-config-validation]] +== Validation +[.small]#<<web.adoc#mvc-config-validation, See equivalent in the Servlet stack>># + +By default, if <<core.adoc#validation-beanvalidation-overview, Bean Validation>> is present +on the classpath (for example, the Hibernate Validator), the `LocalValidatorFactoryBean` +is registered as a global <<core.adoc#validator,validator>> for use with `@Valid` and +`@Validated` on `@Controller` method arguments. + +In your Java configuration, you can customize the global `Validator` instance, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public Validator getValidator() { + // ... + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun getValidator(): Validator { + // ... + } + + } +---- + +Note that you can also register `Validator` implementations locally, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class MyController { + + @InitBinder + protected void initBinder(WebDataBinder binder) { + binder.addValidators(new FooValidator()); + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class MyController { + + @InitBinder + protected fun initBinder(binder: WebDataBinder) { + binder.addValidators(FooValidator()) + } + } +---- + + +TIP: If you need to have a `LocalValidatorFactoryBean` injected somewhere, create a bean and +mark it with `@Primary` in order to avoid conflict with the one declared in the MVC config. + + + +[[webflux-config-content-negotiation]] +== Content Type Resolvers +[.small]#<<web.adoc#mvc-config-content-negotiation, See equivalent in the Servlet stack>># + +You can configure how Spring WebFlux determines the requested media types for +`@Controller` instances from the request. By default, only the `Accept` header is checked, +but you can also enable a query parameter-based strategy. + +The following example shows how to customize the requested content type resolution: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun configureContentTypeResolver(builder: RequestedContentTypeResolverBuilder) { + // ... + } + } +---- + + + +[[webflux-config-message-codecs]] +== HTTP message codecs +[.small]#<<web.adoc#mvc-config-message-converters, See equivalent in the Servlet stack>># + +The following example shows how to customize how the request and response body are read and written: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) { + configurer.defaultCodecs().maxInMemorySize(512 * 1024); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun configureHttpMessageCodecs(configurer: ServerCodecConfigurer) { + // ... + } + } +---- + +`ServerCodecConfigurer` provides a set of default readers and writers. You can use it to add +more readers and writers, customize the default ones, or replace the default ones completely. + +For Jackson JSON and XML, consider using +{api-spring-framework}/http/converter/json/Jackson2ObjectMapperBuilder.html[`Jackson2ObjectMapperBuilder`], +which customizes Jackson's default properties with the following ones: + +* https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/DeserializationFeature.html#FAIL_ON_UNKNOWN_PROPERTIES[`DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES`] is disabled. +* https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/MapperFeature.html#DEFAULT_VIEW_INCLUSION[`MapperFeature.DEFAULT_VIEW_INCLUSION`] is disabled. + +It also automatically registers the following well-known modules if they are detected on the classpath: + +* https://github.com/FasterXML/jackson-datatype-joda[`jackson-datatype-joda`]: Support for Joda-Time types. +* https://github.com/FasterXML/jackson-datatype-jsr310[`jackson-datatype-jsr310`]: Support for Java 8 Date and Time API types. +* https://github.com/FasterXML/jackson-datatype-jdk8[`jackson-datatype-jdk8`]: Support for other Java 8 types, such as `Optional`. +* https://github.com/FasterXML/jackson-module-kotlin[`jackson-module-kotlin`]: Support for Kotlin classes and data classes. + + + +[[webflux-config-view-resolvers]] +== View Resolvers +[.small]#<<web.adoc#mvc-config-view-resolvers, See equivalent in the Servlet stack>># + +The following example shows how to configure view resolution: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + // ... + } + } +---- + +The `ViewResolverRegistry` has shortcuts for view technologies with which the Spring Framework +integrates. The following example uses FreeMarker (which also requires configuring the +underlying FreeMarker view technology): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + registry.freeMarker(); + } + + // Configure Freemarker... + + @Bean + public FreeMarkerConfigurer freeMarkerConfigurer() { + FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); + configurer.setTemplateLoaderPath("classpath:/templates"); + return configurer; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + registry.freeMarker() + } + + // Configure Freemarker... + + @Bean + fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply { + setTemplateLoaderPath("classpath:/templates") + } + } +---- + +You can also plug in any `ViewResolver` implementation, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + ViewResolver resolver = ... ; + registry.viewResolver(resolver); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + val resolver: ViewResolver = ... + registry.viewResolver(resolver + } + } +---- + +To support <<webflux-multiple-representations>> and rendering other formats +through view resolution (besides HTML), you can configure one or more default views based +on the `HttpMessageWriterView` implementation, which accepts any of the available +<<webflux-codecs>> from `spring-web`. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + registry.freeMarker(); + + Jackson2JsonEncoder encoder = new Jackson2JsonEncoder(); + registry.defaultViews(new HttpMessageWriterView(encoder)); + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + registry.freeMarker() + + val encoder = Jackson2JsonEncoder() + registry.defaultViews(HttpMessageWriterView(encoder)) + } + + // ... + } +---- + +See <<webflux-view>> for more on the view technologies that are integrated with Spring WebFlux. + + + +[[webflux-config-static-resources]] +== Static Resources +[.small]#<<web.adoc#mvc-config-static-resources, See equivalent in the Servlet stack>># + +This option provides a convenient way to serve static resources from a list of +{api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. + +In the next example, given a request that starts with `/resources`, the relative path is +used to find and serve static resources relative to `/static` on the classpath. Resources +are served with a one-year future expiration to ensure maximum use of the browser cache +and a reduction in HTTP requests made by the browser. The `Last-Modified` header is also +evaluated and, if present, a `304` status code is returned. The following listing shows +the example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public void addResourceHandlers(ResourceHandlerRegistry registry) { + registry.addResourceHandler("/resources/**") + .addResourceLocations("/public", "classpath:/static/") + .setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS)); + } + + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun addResourceHandlers(registry: ResourceHandlerRegistry) { + registry.addResourceHandler("/resources/**") + .addResourceLocations("/public", "classpath:/static/") + .setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS)) + } + } +---- + +See also <<webflux-caching-static-resources, HTTP caching support for static resources>>. + +The resource handler also supports a chain of +{api-spring-framework}/web/reactive/resource/ResourceResolver.html[`ResourceResolver`] implementations and +{api-spring-framework}/web/reactive/resource/ResourceTransformer.html[`ResourceTransformer`] implementations, +which can be used to create a toolchain for working with optimized resources. + +You can use the `VersionResourceResolver` for versioned resource URLs based on an MD5 hash +computed from the content, a fixed application version, or other information. A +`ContentVersionStrategy` (MD5 hash) is a good choice with some notable exceptions (such as +JavaScript resources used with a module loader). + +The following example shows how to use `VersionResourceResolver` in your Java configuration: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public void addResourceHandlers(ResourceHandlerRegistry registry) { + registry.addResourceHandler("/resources/**") + .addResourceLocations("/public/") + .resourceChain(true) + .addResolver(new VersionResourceResolver().addContentVersionStrategy("/**")); + } + + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + override fun addResourceHandlers(registry: ResourceHandlerRegistry) { + registry.addResourceHandler("/resources/**") + .addResourceLocations("/public/") + .resourceChain(true) + .addResolver(VersionResourceResolver().addContentVersionStrategy("/**")) + } + + } +---- + +You can use `ResourceUrlProvider` to rewrite URLs and apply the full chain of resolvers and +transformers (for example, to insert versions). The WebFlux configuration provides a `ResourceUrlProvider` +so that it can be injected into others. + +Unlike Spring MVC, at present, in WebFlux, there is no way to transparently rewrite static +resource URLs, since there are no view technologies that can make use of a non-blocking chain +of resolvers and transformers. When serving only local resources, the workaround is to use +`ResourceUrlProvider` directly (for example, through a custom element) and block. + +Note that, when using both `EncodedResourceResolver` (for example, Gzip, Brotli encoded) and +`VersionedResourceResolver`, they must be registered in that order, to ensure content-based +versions are always computed reliably based on the unencoded file. + +For https://www.webjars.org/documentation[WebJars], versioned URLs like +`/webjars/jquery/1.2.0/jquery.min.js` are the recommended and most efficient way to use them. +The related resource location is configured out of the box with Spring Boot (or can be configured +manually via `ResourceHandlerRegistry`) and does not require to add the +`org.webjars:webjars-locator-core` dependency. + +Version-less URLs like `/webjars/jquery/jquery.min.js` are supported through the +`WebJarsResourceResolver` which is automatically registered when the +`org.webjars:webjars-locator-core` library is present on the classpath, at the cost of a +classpath scanning that could slow down application startup. The resolver can re-write URLs to +include the version of the jar and can also match against incoming URLs without versions +-- for example, from `/webjars/jquery/jquery.min.js` to `/webjars/jquery/1.2.0/jquery.min.js`. + +TIP: The Java configuration based on `ResourceHandlerRegistry` provides further options +for fine-grained control, e.g. last-modified behavior and optimized resource resolution. + + + +[[webflux-config-path-matching]] +== Path Matching +[.small]#<<web.adoc#mvc-config-path-matching, See equivalent in the Servlet stack>># + +You can customize options related to path matching. For details on the individual options, see the +{api-spring-framework}/web/reactive/config/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc. +The following example shows how to use `PathMatchConfigurer`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public void configurePathMatch(PathMatchConfigurer configurer) { + configurer + .setUseCaseSensitiveMatch(true) + .addPathPrefix("/api", HandlerTypePredicate.forAnnotation(RestController.class)); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + @Override + fun configurePathMatch(configurer: PathMatchConfigurer) { + configurer + .setUseCaseSensitiveMatch(true) + .addPathPrefix("/api", HandlerTypePredicate.forAnnotation(RestController::class.java)) + } + } +---- + +[TIP] +==== +Spring WebFlux relies on a parsed representation of the request path called +`RequestPath` for access to decoded path segment values, with semicolon content removed +(that is, path or matrix variables). That means, unlike in Spring MVC, you need not indicate +whether to decode the request path nor whether to remove semicolon content for +path matching purposes. + +Spring WebFlux also does not support suffix pattern matching, unlike in Spring MVC, where we +are also <<web.adoc#mvc-ann-requestmapping-suffix-pattern-match, recommend>> moving away from +reliance on it. +==== + + + +[[webflux-config-websocket-service]] +== WebSocketService + +The WebFlux Java config declares of a `WebSocketHandlerAdapter` bean which provides +support for the invocation of WebSocket handlers. That means all that remains to do in +order to handle a WebSocket handshake request is to map a `WebSocketHandler` to a URL +via `SimpleUrlHandlerMapping`. + +In some cases it may be necessary to create the `WebSocketHandlerAdapter` bean with a +provided `WebSocketService` service which allows configuring WebSocket server properties. +For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + public class WebConfig implements WebFluxConfigurer { + + @Override + public WebSocketService getWebSocketService() { + TomcatRequestUpgradeStrategy strategy = new TomcatRequestUpgradeStrategy(); + strategy.setMaxSessionIdleTimeout(0L); + return new HandshakeWebSocketService(strategy); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class WebConfig : WebFluxConfigurer { + + @Override + fun webSocketService(): WebSocketService { + val strategy = TomcatRequestUpgradeStrategy().apply { + setMaxSessionIdleTimeout(0L) + } + return HandshakeWebSocketService(strategy) + } + } +---- + + + + +[[webflux-config-advanced-java]] +== Advanced Configuration Mode +[.small]#<<web.adoc#mvc-config-advanced-java, See equivalent in the Servlet stack>># + +`@EnableWebFlux` imports `DelegatingWebFluxConfiguration` that: + +* Provides default Spring configuration for WebFlux applications + +* detects and delegates to `WebFluxConfigurer` implementations to customize that configuration. + +For advanced mode, you can remove `@EnableWebFlux` and extend directly from +`DelegatingWebFluxConfiguration` instead of implementing `WebFluxConfigurer`, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class WebConfig extends DelegatingWebFluxConfiguration { + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class WebConfig : DelegatingWebFluxConfiguration { + + // ... + } +---- + +You can keep existing methods in `WebConfig`, but you can now also override bean declarations +from the base class and still have any number of other `WebMvcConfigurer` implementations on +the classpath. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc new file mode 100644 index 000000000000..2f8e72ac0e1b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc @@ -0,0 +1,39 @@ +[[webflux-controller]] += Annotated Controllers + +[.small]#<<web.adoc#mvc-controller, See equivalent in the Servlet stack>># + +Spring WebFlux provides an annotation-based programming model, where `@Controller` and +`@RestController` components use annotations to express request mappings, request input, +handle exceptions, and more. Annotated controllers have flexible method signatures and +do not have to extend base classes nor implement specific interfaces. + +The following listing shows a basic example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RestController + public class HelloController { + + @GetMapping("/hello") + public String handle() { + return "Hello WebFlux"; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RestController + class HelloController { + + @GetMapping("/hello") + fun handle() = "Hello WebFlux" + } +---- + +In the preceding example, the method returns a `String` to be written to the response body. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc new file mode 100644 index 000000000000..0af8667d8aff --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc @@ -0,0 +1,69 @@ +[[webflux-ann-controller-advice]] += Controller Advice + +[.small]#<<web.adoc#mvc-ann-controller-advice, See equivalent in the Servlet stack>># + +Typically, the `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply +within the `@Controller` class (or class hierarchy) in which they are declared. If you +want such methods to apply more globally (across controllers), you can declare them in a +class annotated with `@ControllerAdvice` or `@RestControllerAdvice`. + +`@ControllerAdvice` is annotated with `@Component`, which means that such classes can be +registered as Spring beans through <<core.adoc#beans-java-instantiating-container-scan, +component scanning>>. `@RestControllerAdvice` is a composed annotation that is annotated +with both `@ControllerAdvice` and `@ResponseBody`, which essentially means +`@ExceptionHandler` methods are rendered to the response body through message conversion +(versus view resolution or template rendering). + +On startup, the infrastructure classes for `@RequestMapping` and `@ExceptionHandler` +methods detect Spring beans annotated with `@ControllerAdvice` and then apply their +methods at runtime. Global `@ExceptionHandler` methods (from a `@ControllerAdvice`) are +applied _after_ local ones (from the `@Controller`). By contrast, global `@ModelAttribute` +and `@InitBinder` methods are applied _before_ local ones. + +By default, `@ControllerAdvice` methods apply to every request (that is, all controllers), +but you can narrow that down to a subset of controllers by using attributes on the +annotation, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Target all Controllers annotated with @RestController + @ControllerAdvice(annotations = RestController.class) + public class ExampleAdvice1 {} + + // Target all Controllers within specific packages + @ControllerAdvice("org.example.controllers") + public class ExampleAdvice2 {} + + // Target all Controllers assignable to specific classes + @ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class}) + public class ExampleAdvice3 {} +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Target all Controllers annotated with @RestController + @ControllerAdvice(annotations = [RestController::class]) + public class ExampleAdvice1 {} + + // Target all Controllers within specific packages + @ControllerAdvice("org.example.controllers") + public class ExampleAdvice2 {} + + // Target all Controllers assignable to specific classes + @ControllerAdvice(assignableTypes = [ControllerInterface::class, AbstractController::class]) + public class ExampleAdvice3 {} +---- + +The selectors in the preceding example are evaluated at runtime and may negatively impact +performance if used extensively. See the +{api-spring-framework}/web/bind/annotation/ControllerAdvice.html[`@ControllerAdvice`] +javadoc for more details. + +include:../../:webflux-functional.adoc[leveloffset=+1] + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc new file mode 100644 index 000000000000..fd0d2779f8d7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc @@ -0,0 +1,81 @@ +[[webflux-ann-controller-exceptions]] += Exceptions + +[.small]#<<web.adoc#mvc-ann-exceptionhandler, See equivalent in the Servlet stack>># + +`@Controller` and <<webflux-ann-controller-advice, @ControllerAdvice>> classes can have +`@ExceptionHandler` methods to handle exceptions from controller methods. The following +example includes such a handler method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class SimpleController { + + // ... + + @ExceptionHandler // <1> + public ResponseEntity<String> handle(IOException ex) { + // ... + } + } +---- +<1> Declaring an `@ExceptionHandler`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class SimpleController { + + // ... + + @ExceptionHandler // <1> + fun handle(ex: IOException): ResponseEntity<String> { + // ... + } + } +---- +<1> Declaring an `@ExceptionHandler`. + + +The exception can match against a top-level exception being propagated (that is, a direct +`IOException` being thrown) or against the immediate cause within a top-level wrapper +exception (for example, an `IOException` wrapped inside an `IllegalStateException`). + +For matching exception types, preferably declare the target exception as a method argument, +as shown in the preceding example. Alternatively, the annotation declaration can narrow the +exception types to match. We generally recommend being as specific as possible in the +argument signature and to declare your primary root exception mappings on a +`@ControllerAdvice` prioritized with a corresponding order. +See <<web.adoc#mvc-ann-exceptionhandler, the MVC section>> for details. + +NOTE: An `@ExceptionHandler` method in WebFlux supports the same method arguments and +return values as a `@RequestMapping` method, with the exception of request body- +and `@ModelAttribute`-related method arguments. + +Support for `@ExceptionHandler` methods in Spring WebFlux is provided by the +`HandlerAdapter` for `@RequestMapping` methods. See <<webflux-dispatcher-handler>> +for more detail. + + + +[[webflux-ann-exceptionhandler-args]] +== Method Arguments +[.small]#<<web.adoc#mvc-ann-exceptionhandler-args, See equivalent in the Servlet stack>># + +`@ExceptionHandler` methods support the same <<webflux-ann-arguments,method arguments>> +as `@RequestMapping` methods, except the request body might have been consumed already. + + + +[[webflux-ann-exceptionhandler-return-values]] +== Return Values +[.small]#<<web.adoc#mvc-ann-exceptionhandler-return-values, See equivalent in the Servlet stack>># + +`@ExceptionHandler` methods support the same <<webflux-ann-return-types,return values>> +as `@RequestMapping` methods. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc new file mode 100644 index 000000000000..6ffe7b6e54bd --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc @@ -0,0 +1,107 @@ +[[webflux-ann-initbinder]] += `DataBinder` + +[.small]#<<web.adoc#mvc-ann-initbinder, See equivalent in the Servlet stack>># + +`@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods, to +initialize instances of `WebDataBinder`. Those, in turn, are used to: + +* Bind request parameters (that is, form data or query) to a model object. +* Convert `String`-based request values (such as request parameters, path variables, +headers, cookies, and others) to the target type of controller method arguments. +* Format model object values as `String` values when rendering HTML forms. + +`@InitBinder` methods can register controller-specific `java.beans.PropertyEditor` or +Spring `Converter` and `Formatter` components. In addition, you can use the +<<webflux-config-conversion, WebFlux Java configuration>> to register `Converter` and +`Formatter` types in a globally shared `FormattingConversionService`. + +`@InitBinder` methods support many of the same arguments that `@RequestMapping` methods +do, except for `@ModelAttribute` (command object) arguments. Typically, they are declared +with a `WebDataBinder` argument, for registrations, and a `void` return value. +The following example uses the `@InitBinder` annotation: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class FormController { + + @InitBinder // <1> + public void initBinder(WebDataBinder binder) { + SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd"); + dateFormat.setLenient(false); + binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false)); + } + + // ... + } +---- +<1> Using the `@InitBinder` annotation. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class FormController { + + @InitBinder // <1> + fun initBinder(binder: WebDataBinder) { + val dateFormat = SimpleDateFormat("yyyy-MM-dd") + dateFormat.isLenient = false + binder.registerCustomEditor(Date::class.java, CustomDateEditor(dateFormat, false)) + } + + // ... + } +---- +<1> Using the `@InitBinder` annotation. +-- + +Alternatively, when using a `Formatter`-based setup through a shared +`FormattingConversionService`, you could re-use the same approach and register +controller-specific `Formatter` instances, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class FormController { + + @InitBinder + protected void initBinder(WebDataBinder binder) { + binder.addCustomFormatter(new DateFormatter("yyyy-MM-dd")); <1> + } + + // ... + } +---- +<1> Adding a custom formatter (a `DateFormatter`, in this case). + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class FormController { + + @InitBinder + fun initBinder(binder: WebDataBinder) { + binder.addCustomFormatter(DateFormatter("yyyy-MM-dd")) // <1> + } + + // ... + } +---- +<1> Adding a custom formatter (a `DateFormatter`, in this case). +-- + + +[[webflux-ann-initbinder-model-design]] +== Model Design +[.small]#<<web.adoc#mvc-ann-initbinder-model-design, See equivalent in the Servlet stack>># + +include:../../:web-data-binding-model-design.adoc[] + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc new file mode 100644 index 000000000000..6389dada1e4d --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc @@ -0,0 +1,9 @@ +[[webflux-ann-methods]] += Handler Methods + +[.small]#<<web.adoc#mvc-ann-methods, See equivalent in the Servlet stack>># + +`@RequestMapping` handler methods have a flexible signature and can choose from a range of +supported controller method arguments and return values. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc new file mode 100644 index 000000000000..9ac95fa05eee --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc @@ -0,0 +1,121 @@ +[[webflux-ann-arguments]] += Method Arguments + +[.small]#<<web.adoc#mvc-ann-arguments, See equivalent in the Servlet stack>># + +The following table shows the supported controller method arguments. + +Reactive types (Reactor, RxJava, <<webflux-reactive-libraries, or other>>) are +supported on arguments that require blocking I/O (for example, reading the request body) to +be resolved. This is marked in the Description column. Reactive types are not expected +on arguments that do not require blocking. + +JDK 1.8's `java.util.Optional` is supported as a method argument in combination with +annotations that have a `required` attribute (for example, `@RequestParam`, `@RequestHeader`, +and others) and is equivalent to `required=false`. + +[cols="1,2", options="header"] +|=== +| Controller method argument | Description + +| `ServerWebExchange` +| Access to the full `ServerWebExchange` -- container for the HTTP request and response, + request and session attributes, `checkNotModified` methods, and others. + +| `ServerHttpRequest`, `ServerHttpResponse` +| Access to the HTTP request or response. + +| `WebSession` +| Access to the session. This does not force the start of a new session unless attributes + are added. Supports reactive types. + +| `java.security.Principal` +| The currently authenticated user -- possibly a specific `Principal` implementation class if known. + Supports reactive types. + +| `org.springframework.http.HttpMethod` +| The HTTP method of the request. + +| `java.util.Locale` +| The current request locale, determined by the most specific `LocaleResolver` available -- in + effect, the configured `LocaleResolver`/`LocaleContextResolver`. + +| `java.util.TimeZone` + `java.time.ZoneId` +| The time zone associated with the current request, as determined by a `LocaleContextResolver`. + +| `@PathVariable` +| For access to URI template variables. See <<webflux-ann-requestmapping-uri-templates>>. + +| `@MatrixVariable` +| For access to name-value pairs in URI path segments. See <<webflux-ann-matrix-variables>>. + +| `@RequestParam` +| For access to query parameters. Parameter values are converted to the declared method argument + type. See <<webflux-ann-requestparam>>. + + Note that use of `@RequestParam` is optional -- for example, to set its attributes. + See "`Any other argument`" later in this table. + +| `@RequestHeader` +| For access to request headers. Header values are converted to the declared method argument + type. See <<webflux-ann-requestheader>>. + +| `@CookieValue` +| For access to cookies. Cookie values are converted to the declared method argument type. + See <<webflux-ann-cookievalue>>. + +| `@RequestBody` +| For access to the HTTP request body. Body content is converted to the declared method + argument type by using `HttpMessageReader` instances. Supports reactive types. + See <<webflux-ann-requestbody>>. + +| `HttpEntity<B>` +| For access to request headers and body. The body is converted with `HttpMessageReader` instances. + Supports reactive types. See <<webflux-ann-httpentity>>. + +| `@RequestPart` +| For access to a part in a `multipart/form-data` request. Supports reactive types. + See <<webflux-multipart-forms>> and <<webflux-multipart>>. + +| `java.util.Map`, `org.springframework.ui.Model`, and `org.springframework.ui.ModelMap`. +| For access to the model that is used in HTML controllers and is exposed to templates as + part of view rendering. + +| `@ModelAttribute` +| For access to an existing attribute in the model (instantiated if not present) with + data binding and validation applied. See <<webflux-ann-modelattrib-method-args>> as well + as <<webflux-ann-modelattrib-methods>> and <<webflux-ann-initbinder>>. + + Note that use of `@ModelAttribute` is optional -- for example, to set its attributes. + See "`Any other argument`" later in this table. + +| `Errors`, `BindingResult` +| For access to errors from validation and data binding for a command object, i.e. a + `@ModelAttribute` argument. An `Errors`, or `BindingResult` argument must be declared + immediately after the validated method argument. + +| `SessionStatus` + class-level `@SessionAttributes` +| For marking form processing complete, which triggers cleanup of session attributes + declared through a class-level `@SessionAttributes` annotation. + See <<webflux-ann-sessionattributes>> for more details. + +| `UriComponentsBuilder` +| For preparing a URL relative to the current request's host, port, scheme, and + context path. See <<webflux-uri-building>>. + +| `@SessionAttribute` +| For access to any session attribute -- in contrast to model attributes stored in the session + as a result of a class-level `@SessionAttributes` declaration. See + <<webflux-ann-sessionattribute>> for more details. + +| `@RequestAttribute` +| For access to request attributes. See <<webflux-ann-requestattrib>> for more details. + +| Any other argument +| If a method argument is not matched to any of the above, it is, by default, resolved as + a `@RequestParam` if it is a simple type, as determined by + {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], + or as a `@ModelAttribute`, otherwise. +|=== + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc new file mode 100644 index 000000000000..92abcfe6bc40 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc @@ -0,0 +1,42 @@ +[[webflux-ann-cookievalue]] += `@CookieValue` + +[.small]#<<web.adoc#mvc-ann-cookievalue, See equivalent in the Servlet stack>># + +You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument +in a controller. + +The following example shows a request with a cookie: + +[literal,subs="verbatim,quotes"] +---- +JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84 +---- + +The following code sample demonstrates how to get the cookie value: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/demo") + public void handle(@CookieValue("JSESSIONID") String cookie) { // <1> + //... + } +---- +<1> Get the cookie value. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/demo") + fun handle(@CookieValue("JSESSIONID") cookie: String) { // <1> + //... + } +---- +<1> Get the cookie value. + + +Type conversion is applied automatically if the target method parameter type is not +`String`. See <<webflux-ann-typeconversion>>. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc new file mode 100644 index 000000000000..d43d137f8e3e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc @@ -0,0 +1,27 @@ +[[webflux-ann-httpentity]] += `HttpEntity` + +[.small]#<<web.adoc#mvc-ann-httpentity, See equivalent in the Servlet stack>># + +`HttpEntity` is more or less identical to using <<webflux-ann-requestbody>> but is based on a +container object that exposes request headers and the body. The following example uses an +`HttpEntity`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/accounts") + public void handle(HttpEntity<Account> entity) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/accounts") + fun handle(entity: HttpEntity<Account>) { + // ... + } +---- + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc new file mode 100644 index 000000000000..36930e54d4e4 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc @@ -0,0 +1,83 @@ +[[webflux-ann-jackson]] += Jackson JSON + +Spring offers support for the Jackson JSON library. + +[[webflux-ann-jsonview]] +== JSON Views +[.small]#<<web.adoc#mvc-ann-jackson, See equivalent in the Servlet stack>># + +Spring WebFlux provides built-in support for +https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], +which allows rendering only a subset of all fields in an `Object`. To use it with +`@ResponseBody` or `ResponseEntity` controller methods, you can use Jackson's +`@JsonView` annotation to activate a serialization view class, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RestController + public class UserController { + + @GetMapping("/user") + @JsonView(User.WithoutPasswordView.class) + public User getUser() { + return new User("eric", "7!jd#h23"); + } + } + + public class User { + + public interface WithoutPasswordView {}; + public interface WithPasswordView extends WithoutPasswordView {}; + + private String username; + private String password; + + public User() { + } + + public User(String username, String password) { + this.username = username; + this.password = password; + } + + @JsonView(WithoutPasswordView.class) + public String getUsername() { + return this.username; + } + + @JsonView(WithPasswordView.class) + public String getPassword() { + return this.password; + } + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RestController + class UserController { + + @GetMapping("/user") + @JsonView(User.WithoutPasswordView::class) + fun getUser(): User { + return User("eric", "7!jd#h23") + } + } + + class User( + @JsonView(WithoutPasswordView::class) val username: String, + @JsonView(WithPasswordView::class) val password: String + ) { + interface WithoutPasswordView + interface WithPasswordView : WithoutPasswordView + } +---- + +NOTE: `@JsonView` allows an array of view classes but you can only specify only one per +controller method. Use a composite interface if you need to activate multiple views. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc new file mode 100644 index 000000000000..439260713738 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc @@ -0,0 +1,136 @@ +[[webflux-ann-matrix-variables]] += Matrix Variables + +[.small]#<<web.adoc#mvc-ann-matrix-variables, See equivalent in the Servlet stack>># + +https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in +path segments. In Spring WebFlux, we refer to those as "`matrix variables`" based on an +https://www.w3.org/DesignIssues/MatrixURIs.html["`old post`"] by Tim Berners-Lee, but they +can be also be referred to as URI path parameters. + +Matrix variables can appear in any path segment, with each variable separated by a semicolon and +multiple values separated by commas -- for example, `"/cars;color=red,green;year=2012"`. Multiple +values can also be specified through repeated variable names -- for example, +`"color=red;color=green;color=blue"`. + +Unlike Spring MVC, in WebFlux, the presence or absence of matrix variables in a URL does +not affect request mappings. In other words, you are not required to use a URI variable +to mask variable content. That said, if you want to access matrix variables from a +controller method, you need to add a URI variable to the path segment where matrix +variables are expected. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // GET /pets/42;q=11;r=22 + + @GetMapping("/pets/{petId}") + public void findPet(@PathVariable String petId, @MatrixVariable int q) { + + // petId == 42 + // q == 11 + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // GET /pets/42;q=11;r=22 + + @GetMapping("/pets/{petId}") + fun findPet(@PathVariable petId: String, @MatrixVariable q: Int) { + + // petId == 42 + // q == 11 + } +---- + + +Given that all path segments can contain matrix variables, you may sometimes need to +disambiguate which path variable the matrix variable is expected to be in, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // GET /owners/42;q=11/pets/21;q=22 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + public void findPet( + @MatrixVariable(name="q", pathVar="ownerId") int q1, + @MatrixVariable(name="q", pathVar="petId") int q2) { + + // q1 == 11 + // q2 == 22 + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/owners/{ownerId}/pets/{petId}") + fun findPet( + @MatrixVariable(name = "q", pathVar = "ownerId") q1: Int, + @MatrixVariable(name = "q", pathVar = "petId") q2: Int) { + + // q1 == 11 + // q2 == 22 + } +---- + +You can define a matrix variable may be defined as optional and specify a default value +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // GET /pets/42 + + @GetMapping("/pets/{petId}") + public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) { + + // q == 1 + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // GET /pets/42 + + @GetMapping("/pets/{petId}") + fun findPet(@MatrixVariable(required = false, defaultValue = "1") q: Int) { + + // q == 1 + } +---- + +To get all matrix variables, use a `MultiValueMap`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + public void findPet( + @MatrixVariable MultiValueMap<String, String> matrixVars, + @MatrixVariable(pathVar="petId") MultiValueMap<String, String> petMatrixVars) { + + // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] + // petMatrixVars: ["q" : 22, "s" : 23] + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + fun findPet( + @MatrixVariable matrixVars: MultiValueMap<String, String>, + @MatrixVariable(pathVar="petId") petMatrixVars: MultiValueMap<String, String>) { + + // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] + // petMatrixVars: ["q" : 22, "s" : 23] + } +---- + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc new file mode 100644 index 000000000000..140b5d68e320 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc @@ -0,0 +1,148 @@ +[[webflux-ann-modelattrib-method-args]] += `@ModelAttribute` + +[.small]#<<web.adoc#mvc-ann-modelattrib-method-args, See equivalent in the Servlet stack>># + +You can use the `@ModelAttribute` annotation on a method argument to access an attribute from the +model or have it instantiated if not present. The model attribute is also overlaid with +the values of query parameters and form fields whose names match to field names. This is +referred to as data binding, and it saves you from having to deal with parsing and +converting individual query parameters and form fields. The following example binds an instance of `Pet`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + public String processSubmit(@ModelAttribute Pet pet) { } // <1> +---- +<1> Bind an instance of `Pet`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + fun processSubmit(@ModelAttribute pet: Pet): String { } // <1> +---- +<1> Bind an instance of `Pet`. + +The `Pet` instance in the preceding example is resolved as follows: + +* From the model if already added through <<webflux-ann-modelattrib-methods>>. +* From the HTTP session through <<webflux-ann-sessionattributes>>. +* From the invocation of a default constructor. +* From the invocation of a "`primary constructor`" with arguments that match query +parameters or form fields. Argument names are determined through JavaBeans +`@ConstructorProperties` or through runtime-retained parameter names in the bytecode. + +After the model attribute instance is obtained, data binding is applied. The +`WebExchangeDataBinder` class matches names of query parameters and form fields to field +names on the target `Object`. Matching fields are populated after type conversion is applied +where necessary. For more on data binding (and validation), see +<<core.adoc#validation, Validation>>. For more on customizing data binding, see +<<webflux-ann-initbinder>>. + +Data binding can result in errors. By default, a `WebExchangeBindException` is raised, but, +to check for such errors in the controller method, you can add a `BindingResult` argument +immediately next to the `@ModelAttribute`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { <1> + if (result.hasErrors()) { + return "petForm"; + } + // ... + } +---- +<1> Adding a `BindingResult`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + fun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { // <1> + if (result.hasErrors()) { + return "petForm" + } + // ... + } +---- +<1> Adding a `BindingResult`. + +You can automatically apply validation after data binding by adding the +`jakarta.validation.Valid` annotation or Spring's `@Validated` annotation (see also +<<core.adoc#validation-beanvalidation, Bean Validation>> and +<<core.adoc#validation, Spring validation>>). The following example uses the `@Valid` annotation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { // <1> + if (result.hasErrors()) { + return "petForm"; + } + // ... + } +---- +<1> Using `@Valid` on a model attribute argument. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { // <1> + if (result.hasErrors()) { + return "petForm" + } + // ... + } +---- +<1> Using `@Valid` on a model attribute argument. + +Spring WebFlux, unlike Spring MVC, supports reactive types in the model -- for example, +`Mono<Account>` or `io.reactivex.Single<Account>`. You can declare a `@ModelAttribute` argument +with or without a reactive type wrapper, and it will be resolved accordingly, +to the actual value if necessary. However, note that, to use a `BindingResult` +argument, you must declare the `@ModelAttribute` argument before it without a reactive +type wrapper, as shown earlier. Alternatively, you can handle any errors through the +reactive type, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + public Mono<String> processSubmit(@Valid @ModelAttribute("pet") Mono<Pet> petMono) { + return petMono + .flatMap(pet -> { + // ... + }) + .onErrorResume(ex -> { + // ... + }); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + fun processSubmit(@Valid @ModelAttribute("pet") petMono: Mono<Pet>): Mono<String> { + return petMono + .flatMap { pet -> + // ... + } + .onErrorResume{ ex -> + // ... + } + } +---- + +Note that use of `@ModelAttribute` is optional -- for example, to set its attributes. +By default, any argument that is not a simple value type (as determined by +{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) +and is not resolved by any other argument resolver is treated as if it were annotated +with `@ModelAttribute`. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc new file mode 100644 index 000000000000..a89f22184dda --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc @@ -0,0 +1,279 @@ +[[webflux-multipart-forms]] += Multipart Content + +[.small]#<<web.adoc#mvc-multipart-forms, See equivalent in the Servlet stack>># + +As explained in <<webflux-multipart>>, `ServerWebExchange` provides access to multipart +content. The best way to handle a file upload form (for example, from a browser) in a controller +is through data binding to a <<webflux-ann-modelattrib-method-args, command object>>, +as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + class MyForm { + + private String name; + + private MultipartFile file; + + // ... + + } + + @Controller + public class FileUploadController { + + @PostMapping("/form") + public String handleFormUpload(MyForm form, BindingResult errors) { + // ... + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyForm( + val name: String, + val file: MultipartFile) + + @Controller + class FileUploadController { + + @PostMapping("/form") + fun handleFormUpload(form: MyForm, errors: BindingResult): String { + // ... + } + + } +---- +-- + +You can also submit multipart requests from non-browser clients in a RESTful service +scenario. The following example uses a file along with JSON: + +[literal,subs="verbatim,quotes"] +---- +POST /someUrl +Content-Type: multipart/mixed + +--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp +Content-Disposition: form-data; name="meta-data" +Content-Type: application/json; charset=UTF-8 +Content-Transfer-Encoding: 8bit + +{ + "name": "value" +} +--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp +Content-Disposition: form-data; name="file-data"; filename="file.properties" +Content-Type: text/xml +Content-Transfer-Encoding: 8bit +... File Data ... +---- + +You can access individual parts with `@RequestPart`, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/") + public String handle(@RequestPart("meta-data") Part metadata, // <1> + @RequestPart("file-data") FilePart file) { // <2> + // ... + } +---- +<1> Using `@RequestPart` to get the metadata. +<2> Using `@RequestPart` to get the file. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/") + fun handle(@RequestPart("meta-data") Part metadata, // <1> + @RequestPart("file-data") FilePart file): String { // <2> + // ... + } +---- +<1> Using `@RequestPart` to get the metadata. +<2> Using `@RequestPart` to get the file. +-- + + +To deserialize the raw part content (for example, to JSON -- similar to `@RequestBody`), +you can declare a concrete target `Object`, instead of `Part`, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/") + public String handle(@RequestPart("meta-data") MetaData metadata) { // <1> + // ... + } +---- +<1> Using `@RequestPart` to get the metadata. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/") + fun handle(@RequestPart("meta-data") metadata: MetaData): String { // <1> + // ... + } +---- +<1> Using `@RequestPart` to get the metadata. +-- + +You can use `@RequestPart` in combination with `jakarta.validation.Valid` or Spring's +`@Validated` annotation, which causes Standard Bean Validation to be applied. Validation +errors lead to a `WebExchangeBindException` that results in a 400 (BAD_REQUEST) response. +The exception contains a `BindingResult` with the error details and can also be handled +in the controller method by declaring the argument with an async wrapper and then using +error related operators: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/") + public String handle(@Valid @RequestPart("meta-data") Mono<MetaData> metadata) { + // use one of the onError* operators... + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/") + fun handle(@Valid @RequestPart("meta-data") metadata: MetaData): String { + // ... + } +---- +-- + +To access all multipart data as a `MultiValueMap`, you can use `@RequestBody`, +as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/") + public String handle(@RequestBody Mono<MultiValueMap<String, Part>> parts) { // <1> + // ... + } +---- +<1> Using `@RequestBody`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/") + fun handle(@RequestBody parts: MultiValueMap<String, Part>): String { // <1> + // ... + } +---- +<1> Using `@RequestBody`. +-- + +[[partevent]] +== `PartEvent` + +To access multipart data sequentially, in a streaming fashion, you can use `@RequestBody` with +`Flux<PartEvent>` (or `Flow<PartEvent>` in Kotlin). +Each part in a multipart HTTP message will produce at +least one `PartEvent` containing both headers and a buffer with the contents of the part. + +- Form fields will produce a *single* `FormPartEvent`, containing the value of the field. +- File uploads will produce *one or more* `FilePartEvent` objects, containing the filename used +when uploading. If the file is large enough to be split across multiple buffers, the first +`FilePartEvent` will be followed by subsequent events. + + +For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/") + public void handle(@RequestBody Flux<PartEvent> allPartsEvents) { <1> + allPartsEvents.windowUntil(PartEvent::isLast) <2> + .concatMap(p -> p.switchOnFirst((signal, partEvents) -> { <3> + if (signal.hasValue()) { + PartEvent event = signal.get(); + if (event instanceof FormPartEvent formEvent) { <4> + String value = formEvent.value(); + // handle form field + } + else if (event instanceof FilePartEvent fileEvent) { <5> + String filename = fileEvent.filename(); + Flux<DataBuffer> contents = partEvents.map(PartEvent::content); <6> + // handle file upload + } + else { + return Mono.error(new RuntimeException("Unexpected event: " + event)); + } + } + else { + return partEvents; // either complete or error signal + } + })); + } +---- +<1> Using `@RequestBody`. +<2> The final `PartEvent` for a particular part will have `isLast()` set to `true`, and can be +followed by additional events belonging to subsequent parts. +This makes the `isLast` property suitable as a predicate for the `Flux::windowUntil` operator, to +split events from all parts into windows that each belong to a single part. +<3> The `Flux::switchOnFirst` operator allows you to see whether you are handling a form field or +file upload. +<4> Handling the form field. +<5> Handling the file upload. +<6> The body contents must be completely consumed, relayed, or released to avoid memory leaks. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/") + fun handle(@RequestBody allPartsEvents: Flux<PartEvent>) = { // <1> + allPartsEvents.windowUntil(PartEvent::isLast) <2> + .concatMap { + it.switchOnFirst { signal, partEvents -> <3> + if (signal.hasValue()) { + val event = signal.get() + if (event is FormPartEvent) { <4> + val value: String = event.value(); + // handle form field + } else if (event is FilePartEvent) { <5> + val filename: String = event.filename(); + val contents: Flux<DataBuffer> = partEvents.map(PartEvent::content); <6> + // handle file upload + } else { + return Mono.error(RuntimeException("Unexpected event: " + event)); + } + } else { + return partEvents; // either complete or error signal + } + } + } +} +---- +<1> Using `@RequestBody`. +<2> The final `PartEvent` for a particular part will have `isLast()` set to `true`, and can be +followed by additional events belonging to subsequent parts. +This makes the `isLast` property suitable as a predicate for the `Flux::windowUntil` operator, to +split events from all parts into windows that each belong to a single part. +<3> The `Flux::switchOnFirst` operator allows you to see whether you are handling a form field or +file upload. +<4> Handling the form field. +<5> Handling the file upload. +<6> The body contents must be completely consumed, relayed, or released to avoid memory leaks. + +Received part events can also be relayed to another service by using the `WebClient`. +See <<webflux-client-body-multipart>>. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc new file mode 100644 index 000000000000..bcd9cfcc16ed --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc @@ -0,0 +1,30 @@ +[[webflux-ann-requestattrib]] += `@RequestAttribute` + +[.small]#<<web.adoc#mvc-ann-requestattrib, See equivalent in the Servlet stack>># + +Similarly to `@SessionAttribute`, you can use the `@RequestAttribute` annotation to +access pre-existing request attributes created earlier (for example, by a `WebFilter`), +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/") + public String handle(@RequestAttribute Client client) { <1> + // ... + } +---- +<1> Using `@RequestAttribute`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/") + fun handle(@RequestAttribute client: Client): String { // <1> + // ... + } +---- +<1> Using `@RequestAttribute`. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc new file mode 100644 index 000000000000..3349acccf556 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc @@ -0,0 +1,75 @@ +[[webflux-ann-requestbody]] += `@RequestBody` + +[.small]#<<web.adoc#mvc-ann-requestbody, See equivalent in the Servlet stack>># + +You can use the `@RequestBody` annotation to have the request body read and deserialized into an +`Object` through an <<webflux-codecs,HttpMessageReader>>. +The following example uses a `@RequestBody` argument: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/accounts") + public void handle(@RequestBody Account account) { + // ... + } +---- + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/accounts") + fun handle(@RequestBody account: Account) { + // ... + } +---- + +Unlike Spring MVC, in WebFlux, the `@RequestBody` method argument supports reactive types +and fully non-blocking reading and (client-to-server) streaming. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/accounts") + public void handle(@RequestBody Mono<Account> account) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/accounts") + fun handle(@RequestBody accounts: Flow<Account>) { + // ... + } +---- + +You can use the <<webflux-config-message-codecs>> option of the <<webflux-config>> to +configure or customize message readers. + +You can use `@RequestBody` in combination with `jakarta.validation.Valid` or Spring's +`@Validated` annotation, which causes Standard Bean Validation to be applied. Validation +errors cause a `WebExchangeBindException`, which results in a 400 (BAD_REQUEST) response. +The exception contains a `BindingResult` with error details and can be handled in the +controller method by declaring the argument with an async wrapper and then using error +related operators: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/accounts") + public void handle(@Valid @RequestBody Mono<Account> account) { + // use one of the onError* operators... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/accounts") + fun handle(@Valid @RequestBody account: Mono<Account>) { + // ... + } +---- + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc new file mode 100644 index 000000000000..7c29618b73a0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc @@ -0,0 +1,62 @@ +[[webflux-ann-requestheader]] += `@RequestHeader` + +[.small]#<<web.adoc#mvc-ann-requestheader, See equivalent in the Servlet stack>># + +You can use the `@RequestHeader` annotation to bind a request header to a method argument in a +controller. + +The following example shows a request with headers: + +[literal] +[subs="verbatim,quotes"] +---- +Host localhost:8080 +Accept text/html,application/xhtml+xml,application/xml;q=0.9 +Accept-Language fr,en-gb;q=0.7,en;q=0.3 +Accept-Encoding gzip,deflate +Accept-Charset ISO-8859-1,utf-8;q=0.7,*;q=0.7 +Keep-Alive 300 +---- + +The following example gets the value of the `Accept-Encoding` and `Keep-Alive` headers: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/demo") + public void handle( + @RequestHeader("Accept-Encoding") String encoding, // <1> + @RequestHeader("Keep-Alive") long keepAlive) { // <2> + //... + } +---- +<1> Get the value of the `Accept-Encoding` header. +<2> Get the value of the `Keep-Alive` header. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/demo") + fun handle( + @RequestHeader("Accept-Encoding") encoding: String, // <1> + @RequestHeader("Keep-Alive") keepAlive: Long) { // <2> + //... + } +---- +<1> Get the value of the `Accept-Encoding` header. +<2> Get the value of the `Keep-Alive` header. + +Type conversion is applied automatically if the target method parameter type is not +`String`. See <<webflux-ann-typeconversion>>. + +When a `@RequestHeader` annotation is used on a `Map<String, String>`, +`MultiValueMap<String, String>`, or `HttpHeaders` argument, the map is populated +with all header values. + +TIP: Built-in support is available for converting a comma-separated string into an +array or collection of strings or other types known to the type conversion system. For +example, a method parameter annotated with `@RequestHeader("Accept")` may be of type +`String` but also of `String[]` or `List<String>`. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc new file mode 100644 index 000000000000..59b7a1d45c88 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc @@ -0,0 +1,76 @@ +[[webflux-ann-requestparam]] += `@RequestParam` + +[.small]#<<web.adoc#mvc-ann-requestparam, See equivalent in the Servlet stack>># + +You can use the `@RequestParam` annotation to bind query parameters to a method argument in a +controller. The following code snippet shows the usage: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + @RequestMapping("/pets") + public class EditPetForm { + + // ... + + @GetMapping + public String setupForm(@RequestParam("petId") int petId, Model model) { <1> + Pet pet = this.clinic.loadPet(petId); + model.addAttribute("pet", pet); + return "petForm"; + } + + // ... + } +---- +<1> Using `@RequestParam`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.ui.set + + @Controller + @RequestMapping("/pets") + class EditPetForm { + + // ... + + @GetMapping + fun setupForm(@RequestParam("petId") petId: Int, model: Model): String { // <1> + val pet = clinic.loadPet(petId) + model["pet"] = pet + return "petForm" + } + + // ... + } +---- +<1> Using `@RequestParam`. + +TIP: The Servlet API "`request parameter`" concept conflates query parameters, form +data, and multiparts into one. However, in WebFlux, each is accessed individually through +`ServerWebExchange`. While `@RequestParam` binds to query parameters only, you can use +data binding to apply query parameters, form data, and multiparts to a +<<webflux-ann-modelattrib-method-args, command object>>. + +Method parameters that use the `@RequestParam` annotation are required by default, but +you can specify that a method parameter is optional by setting the required flag of a `@RequestParam` +to `false` or by declaring the argument with a `java.util.Optional` +wrapper. + +Type conversion is applied automatically if the target method parameter type is not +`String`. See <<webflux-ann-typeconversion>>. + +When a `@RequestParam` annotation is declared on a `Map<String, String>` or +`MultiValueMap<String, String>` argument, the map is populated with all query parameters. + +Note that use of `@RequestParam` is optional -- for example, to set its attributes. By +default, any argument that is a simple value type (as determined by +{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) +and is not resolved by any other argument resolver is treated as if it were annotated +with `@RequestParam`. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc new file mode 100644 index 000000000000..212343784d11 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc @@ -0,0 +1,44 @@ +[[webflux-ann-responsebody]] += `@ResponseBody` + +[.small]#<<web.adoc#mvc-ann-responsebody, See equivalent in the Servlet stack>># + +You can use the `@ResponseBody` annotation on a method to have the return serialized +to the response body through an <<webflux-codecs, HttpMessageWriter>>. The following +example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/accounts/{id}") + @ResponseBody + public Account handle() { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/accounts/{id}") + @ResponseBody + fun handle(): Account { + // ... + } +---- + +`@ResponseBody` is also supported at the class level, in which case it is inherited by +all controller methods. This is the effect of `@RestController`, which is nothing more +than a meta-annotation marked with `@Controller` and `@ResponseBody`. + +`@ResponseBody` supports reactive types, which means you can return Reactor or RxJava +types and have the asynchronous values they produce rendered to the response. +For additional details, see <<webflux-codecs-streaming>> and +<<webflux-codecs-jackson,JSON rendering>>. + +You can combine `@ResponseBody` methods with JSON serialization views. +See <<webflux-ann-jackson>> for details. + +You can use the <<webflux-config-message-codecs>> option of the <<webflux-config>> to +configure or customize message writing. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc new file mode 100644 index 000000000000..317a49d5fd45 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc @@ -0,0 +1,43 @@ +[[webflux-ann-responseentity]] += `ResponseEntity` + +[.small]#<<web.adoc#mvc-ann-responseentity, See equivalent in the Servlet stack>># + +`ResponseEntity` is like <<webflux-ann-responsebody>> but with status and headers. For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/something") + public ResponseEntity<String> handle() { + String body = ... ; + String etag = ... ; + return ResponseEntity.ok().eTag(etag).body(body); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/something") + fun handle(): ResponseEntity<String> { + val body: String = ... + val etag: String = ... + return ResponseEntity.ok().eTag(etag).build(body) + } +---- + +WebFlux supports using a single value <<webflux-reactive-libraries, reactive type>> to +produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive types +for the body. This allows a variety of async responses with `ResponseEntity` as follows: + +* `ResponseEntity<Mono<T>>` or `ResponseEntity<Flux<T>>` make the response status and + headers known immediately while the body is provided asynchronously at a later point. + Use `Mono` if the body consists of 0..1 values or `Flux` if it can produce multiple values. +* `Mono<ResponseEntity<T>>` provides all three -- response status, headers, and body, + asynchronously at a later point. This allows the response status and headers to vary + depending on the outcome of asynchronous request handling. +* `Mono<ResponseEntity<Mono<T>>>` or `Mono<ResponseEntity<Flux<T>>>` are yet another + possible, albeit less common alternative. They provide the response status and headers + asynchronously first and then the response body, also asynchronously, second. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc new file mode 100644 index 000000000000..499ac55f501e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc @@ -0,0 +1,82 @@ +[[webflux-ann-return-types]] += Return Values + +[.small]#<<web.adoc#mvc-ann-return-types, See equivalent in the Servlet stack>># + +The following table shows the supported controller method return values. Note that reactive +types from libraries such as Reactor, RxJava, <<webflux-reactive-libraries, or other>> are +generally supported for all return values. + +[cols="1,2", options="header"] +|=== +| Controller method return value | Description + +| `@ResponseBody` +| The return value is encoded through `HttpMessageWriter` instances and written to the response. + See <<webflux-ann-responsebody>>. + +| `HttpEntity<B>`, `ResponseEntity<B>` +| The return value specifies the full response, including HTTP headers, and the body is encoded + through `HttpMessageWriter` instances and written to the response. + See <<webflux-ann-responseentity>>. + +| `HttpHeaders` +| For returning a response with headers and no body. + +| `ErrorResponse` +| To render an RFC 7807 error response with details in the body, + see <<webflux-ann-rest-exceptions>> + +| `ProblemDetail` +| To render an RFC 7807 error response with details in the body, + see <<webflux-ann-rest-exceptions>> + +| `String` +| A view name to be resolved with `ViewResolver` instances and used together with the implicit + model -- determined through command objects and `@ModelAttribute` methods. The handler + method can also programmatically enrich the model by declaring a `Model` argument + (described <<webflux-viewresolution-handling, earlier>>). + +| `View` +| A `View` instance to use for rendering together with the implicit model -- determined + through command objects and `@ModelAttribute` methods. The handler method can also + programmatically enrich the model by declaring a `Model` argument + (described <<webflux-viewresolution-handling, earlier>>). + +| `java.util.Map`, `org.springframework.ui.Model` +| Attributes to be added to the implicit model, with the view name implicitly determined + based on the request path. + +| `@ModelAttribute` +| An attribute to be added to the model, with the view name implicitly determined based + on the request path. + + Note that `@ModelAttribute` is optional. See "`Any other return value`" later in + this table. + +| `Rendering` +| An API for model and view rendering scenarios. + +| `void` +| A method with a `void`, possibly asynchronous (for example, `Mono<Void>`), return type (or a `null` return + value) is considered to have fully handled the response if it also has a `ServerHttpResponse`, + a `ServerWebExchange` argument, or an `@ResponseStatus` annotation. The same is also true + if the controller has made a positive ETag or `lastModified` timestamp check. + See <<webflux-caching-etag-lastmodified>> for details. + + If none of the above is true, a `void` return type can also indicate "`no response body`" for + REST controllers or default view name selection for HTML controllers. + +| `Flux<ServerSentEvent>`, `Observable<ServerSentEvent>`, or other reactive type +| Emit server-sent events. The `ServerSentEvent` wrapper can be omitted when only data needs + to be written (however, `text/event-stream` must be requested or declared in the mapping + through the `produces` attribute). + +| Other return values +| If a return value remains unresolved in any other way, it is treated as a model + attribute, unless it is a simple type as determined by + {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], + in which case it remains unresolved. +|=== + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc new file mode 100644 index 000000000000..e570ac477381 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc @@ -0,0 +1,37 @@ +[[webflux-ann-sessionattribute]] += `@SessionAttribute` + +[.small]#<<web.adoc#mvc-ann-sessionattribute, See equivalent in the Servlet stack>># + +If you need access to pre-existing session attributes that are managed globally +(that is, outside the controller -- for example, by a filter) and may or may not be present, +you can use the `@SessionAttribute` annotation on a method parameter, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/") + public String handle(@SessionAttribute User user) { // <1> + // ... + } +---- +<1> Using `@SessionAttribute`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/") + fun handle(@SessionAttribute user: User): String { // <1> + // ... + } +---- +<1> Using `@SessionAttribute`. + +For use cases that require adding or removing session attributes, consider injecting +`WebSession` into the controller method. + +For temporary storage of model attributes in the session as part of a controller +workflow, consider using `SessionAttributes`, as described in +<<webflux-ann-sessionattributes>>. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc new file mode 100644 index 000000000000..8cdb3758306e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc @@ -0,0 +1,86 @@ +[[webflux-ann-sessionattributes]] += `@SessionAttributes` + +[.small]#<<web.adoc#mvc-ann-sessionattributes, See equivalent in the Servlet stack>># + +`@SessionAttributes` is used to store model attributes in the `WebSession` between +requests. It is a type-level annotation that declares session attributes used by a +specific controller. This typically lists the names of model attributes or types of +model attributes that should be transparently stored in the session for subsequent +requests to access. + +Consider the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + @SessionAttributes("pet") <1> + public class EditPetForm { + // ... + } +---- +<1> Using the `@SessionAttributes` annotation. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + @SessionAttributes("pet") // <1> + class EditPetForm { + // ... + } +---- +<1> Using the `@SessionAttributes` annotation. + +On the first request, when a model attribute with the name, `pet`, is added to the model, +it is automatically promoted to and saved in the `WebSession`. It remains there until +another controller method uses a `SessionStatus` method argument to clear the storage, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + @SessionAttributes("pet") // <1> + public class EditPetForm { + + // ... + + @PostMapping("/pets/{id}") + public String handle(Pet pet, BindingResult errors, SessionStatus status) { // <2> + if (errors.hasErrors()) { + // ... + } + status.setComplete(); + // ... + } + } + } +---- +<1> Using the `@SessionAttributes` annotation. +<2> Using a `SessionStatus` variable. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + @SessionAttributes("pet") // <1> + class EditPetForm { + + // ... + + @PostMapping("/pets/{id}") + fun handle(pet: Pet, errors: BindingResult, status: SessionStatus): String { // <2> + if (errors.hasErrors()) { + // ... + } + status.setComplete() + // ... + } + } +---- +<1> Using the `@SessionAttributes` annotation. +<2> Using a `SessionStatus` variable. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc new file mode 100644 index 000000000000..7d83d27e28b3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc @@ -0,0 +1,21 @@ +[[webflux-ann-typeconversion]] += Type Conversion + +[.small]#<<web.adoc#mvc-ann-typeconversion, See equivalent in the Servlet stack>># + +Some annotated controller method arguments that represent String-based request input (for example, +`@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) +can require type conversion if the argument is declared as something other than `String`. + +For such cases, type conversion is automatically applied based on the configured converters. +By default, simple types (such as `int`, `long`, `Date`, and others) are supported. Type conversion +can be customized through a `WebDataBinder` (see <<webflux-ann-initbinder>>) or by registering +`Formatters` with the `FormattingConversionService` (see <<core.adoc#format, Spring Field Formatting>>). + +A practical issue in type conversion is the treatment of an empty String source value. +Such a value is treated as missing if it becomes `null` as a result of type conversion. +This can be the case for `Long`, `UUID`, and other target types. If you want to allow `null` +to be injected, either use the `required` flag on the argument annotation, or declare the +argument as `@Nullable`. + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc new file mode 100644 index 000000000000..a04b99f8c19c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc @@ -0,0 +1,140 @@ +[[webflux-ann-modelattrib-methods]] += `Model` + +[.small]#<<web.adoc#mvc-ann-modelattrib-methods, See equivalent in the Servlet stack>># + +You can use the `@ModelAttribute` annotation: + +* On a <<webflux-ann-modelattrib-method-args, method argument>> in `@RequestMapping` methods +to create or access an Object from the model and to bind it to the request through a +`WebDataBinder`. +* As a method-level annotation in `@Controller` or `@ControllerAdvice` classes, helping +to initialize the model prior to any `@RequestMapping` method invocation. +* On a `@RequestMapping` method to mark its return value as a model attribute. + +This section discusses `@ModelAttribute` methods, or the second item from the preceding list. +A controller can have any number of `@ModelAttribute` methods. All such methods are +invoked before `@RequestMapping` methods in the same controller. A `@ModelAttribute` +method can also be shared across controllers through `@ControllerAdvice`. See the section on +<<webflux-ann-controller-advice>> for more details. + +`@ModelAttribute` methods have flexible method signatures. They support many of the same +arguments as `@RequestMapping` methods (except for `@ModelAttribute` itself and anything +related to the request body). + +The following example uses a `@ModelAttribute` method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ModelAttribute + public void populateModel(@RequestParam String number, Model model) { + model.addAttribute(accountRepository.findAccount(number)); + // add more ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ModelAttribute + fun populateModel(@RequestParam number: String, model: Model) { + model.addAttribute(accountRepository.findAccount(number)) + // add more ... + } +---- + +The following example adds one attribute only: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ModelAttribute + public Account addAccount(@RequestParam String number) { + return accountRepository.findAccount(number); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ModelAttribute + fun addAccount(@RequestParam number: String): Account { + return accountRepository.findAccount(number); + } +---- + +NOTE: When a name is not explicitly specified, a default name is chosen based on the type, +as explained in the javadoc for {api-spring-framework}/core/Conventions.html[`Conventions`]. +You can always assign an explicit name by using the overloaded `addAttribute` method or +through the name attribute on `@ModelAttribute` (for a return value). + +Spring WebFlux, unlike Spring MVC, explicitly supports reactive types in the model +(for example, `Mono<Account>` or `io.reactivex.Single<Account>`). Such asynchronous model +attributes can be transparently resolved (and the model updated) to their actual values +at the time of `@RequestMapping` invocation, provided a `@ModelAttribute` argument is +declared without a wrapper, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ModelAttribute + public void addAccount(@RequestParam String number) { + Mono<Account> accountMono = accountRepository.findAccount(number); + model.addAttribute("account", accountMono); + } + + @PostMapping("/accounts") + public String handle(@ModelAttribute Account account, BindingResult errors) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.ui.set + + @ModelAttribute + fun addAccount(@RequestParam number: String) { + val accountMono: Mono<Account> = accountRepository.findAccount(number) + model["account"] = accountMono + } + + @PostMapping("/accounts") + fun handle(@ModelAttribute account: Account, errors: BindingResult): String { + // ... + } +---- + + +In addition, any model attributes that have a reactive type wrapper are resolved to their +actual values (and the model updated) just prior to view rendering. + +You can also use `@ModelAttribute` as a method-level annotation on `@RequestMapping` +methods, in which case the return value of the `@RequestMapping` method is interpreted as a +model attribute. This is typically not required, as it is the default behavior in HTML +controllers, unless the return value is a `String` that would otherwise be interpreted +as a view name. `@ModelAttribute` can also help to customize the model attribute name, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/accounts/{id}") + @ModelAttribute("myAccount") + public Account handle() { + // ... + return account; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/accounts/{id}") + @ModelAttribute("myAccount") + fun handle(): Account { + // ... + return account + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc new file mode 100644 index 000000000000..743d015c5ec8 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc @@ -0,0 +1,452 @@ +[[webflux-ann-requestmapping]] += Request Mapping + +[.small]#<<web.adoc#mvc-ann-requestmapping, See equivalent in the Servlet stack>># + +The `@RequestMapping` annotation is used to map requests to controllers methods. It has +various attributes to match by URL, HTTP method, request parameters, headers, and media +types. You can use it at the class level to express shared mappings or at the method level +to narrow down to a specific endpoint mapping. + +There are also HTTP method specific shortcut variants of `@RequestMapping`: + +* `@GetMapping` +* `@PostMapping` +* `@PutMapping` +* `@DeleteMapping` +* `@PatchMapping` + +The preceding annotations are <<webflux-ann-requestmapping-composed>> that are provided +because, arguably, most controller methods should be mapped to a specific HTTP method versus +using `@RequestMapping`, which, by default, matches to all HTTP methods. At the same time, a +`@RequestMapping` is still needed at the class level to express shared mappings. + +The following example uses type and method level mappings: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RestController + @RequestMapping("/persons") + class PersonController { + + @GetMapping("/{id}") + public Person getPerson(@PathVariable Long id) { + // ... + } + + @PostMapping + @ResponseStatus(HttpStatus.CREATED) + public void add(@RequestBody Person person) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RestController + @RequestMapping("/persons") + class PersonController { + + @GetMapping("/{id}") + fun getPerson(@PathVariable id: Long): Person { + // ... + } + + @PostMapping + @ResponseStatus(HttpStatus.CREATED) + fun add(@RequestBody person: Person) { + // ... + } + } +---- + + +[[webflux-ann-requestmapping-uri-templates]] +== URI Patterns +[.small]#<<web.adoc#mvc-ann-requestmapping-uri-templates, See equivalent in the Servlet stack>># + +You can map requests by using glob patterns and wildcards: + +[cols="2,3,5"] +|=== +|Pattern |Description |Example + +| `+?+` +| Matches one character +| `+"/pages/t?st.html"+` matches `+"/pages/test.html"+` and `+"/pages/t3st.html"+` + +| `+*+` +| Matches zero or more characters within a path segment +| `+"/resources/*.png"+` matches `+"/resources/file.png"+` + +`+"/projects/*/versions"+` matches `+"/projects/spring/versions"+` but does not match `+"/projects/spring/boot/versions"+` + +| `+**+` +| Matches zero or more path segments until the end of the path +| `+"/resources/**"+` matches `+"/resources/file.png"+` and `+"/resources/images/file.png"+` + +`+"/resources/**/file.png"+` is invalid as `+**+` is only allowed at the end of the path. + +| `+{name}+` +| Matches a path segment and captures it as a variable named "name" +| `+"/projects/{project}/versions"+` matches `+"/projects/spring/versions"+` and captures `+project=spring+` + +| `+{name:[a-z]+}+` +| Matches the regexp `+"[a-z]+"+` as a path variable named "name" +| `+"/projects/{project:[a-z]+}/versions"+` matches `+"/projects/spring/versions"+` but not `+"/projects/spring1/versions"+` + +| `+{*path}+` +| Matches zero or more path segments until the end of the path and captures it as a variable named "path" +| `+"/resources/{*file}"+` matches `+"/resources/images/file.png"+` and captures `+file=/images/file.png+` + +|=== + +Captured URI variables can be accessed with `@PathVariable`, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/owners/{ownerId}/pets/{petId}") + public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/owners/{ownerId}/pets/{petId}") + fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { + // ... + } +---- +-- + +You can declare URI variables at the class and method levels, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + @RequestMapping("/owners/{ownerId}") // <1> + public class OwnerController { + + @GetMapping("/pets/{petId}") // <2> + public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { + // ... + } + } +---- +<1> Class-level URI mapping. +<2> Method-level URI mapping. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + @RequestMapping("/owners/{ownerId}") // <1> + class OwnerController { + + @GetMapping("/pets/{petId}") // <2> + fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { + // ... + } + } +---- +<1> Class-level URI mapping. +<2> Method-level URI mapping. +-- + + +URI variables are automatically converted to the appropriate type or a `TypeMismatchException` +is raised. Simple types (`int`, `long`, `Date`, and so on) are supported by default and you can +register support for any other data type. +See <<webflux-ann-typeconversion>> and <<webflux-ann-initbinder>>. + +URI variables can be named explicitly (for example, `@PathVariable("customId")`), but you can +leave that detail out if the names are the same and you compile your code with the `-parameters` +compiler flag. + +The syntax `{*varName}` declares a URI variable that matches zero or more remaining path +segments. For example `/resources/{*path}` matches all files under `/resources/`, and the +`"path"` variable captures the complete path under `/resources`. + +The syntax `{varName:regex}` declares a URI variable with a regular expression that has the +syntax: `{varName:regex}`. For example, given a URL of `/spring-web-3.0.5.jar`, the following method +extracts the name, version, and file extension: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") + public void handle(@PathVariable String version, @PathVariable String ext) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") + fun handle(@PathVariable version: String, @PathVariable ext: String) { + // ... + } +---- +-- + +URI path patterns can also have embedded `${...}` placeholders that are resolved on startup +through `PropertySourcesPlaceholderConfigurer` against local, system, environment, and +other property sources. You can use this to, for example, parameterize a base URL based on +some external configuration. + +NOTE: Spring WebFlux uses `PathPattern` and the `PathPatternParser` for URI path matching support. +Both classes are located in `spring-web` and are expressly designed for use with HTTP URL +paths in web applications where a large number of URI path patterns are matched at runtime. + +Spring WebFlux does not support suffix pattern matching -- unlike Spring MVC, where a +mapping such as `/person` also matches to `/person.{asterisk}`. For URL-based content +negotiation, if needed, we recommend using a query parameter, which is simpler, more +explicit, and less vulnerable to URL path based exploits. + + +[[webflux-ann-requestmapping-pattern-comparison]] +== Pattern Comparison +[.small]#<<web.adoc#mvc-ann-requestmapping-pattern-comparison, See equivalent in the Servlet stack>># + +When multiple patterns match a URL, they must be compared to find the best match. This is done +with `PathPattern.SPECIFICITY_COMPARATOR`, which looks for patterns that are more specific. + +For every pattern, a score is computed, based on the number of URI variables and wildcards, +where a URI variable scores lower than a wildcard. A pattern with a lower total score +wins. If two patterns have the same score, the longer is chosen. + +Catch-all patterns (for example, `**`, `{*varName}`) are excluded from the scoring and are always +sorted last instead. If two patterns are both catch-all, the longer is chosen. + + +[[webflux-ann-requestmapping-consumes]] +== Consumable Media Types +[.small]#<<web.adoc#mvc-ann-requestmapping-consumes, See equivalent in the Servlet stack>># + +You can narrow the request mapping based on the `Content-Type` of the request, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping(path = "/pets", consumes = "application/json") + public void addPet(@RequestBody Pet pet) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/pets", consumes = ["application/json"]) + fun addPet(@RequestBody pet: Pet) { + // ... + } +---- + +The consumes attribute also supports negation expressions -- for example, `!text/plain` means any +content type other than `text/plain`. + +You can declare a shared `consumes` attribute at the class level. Unlike most other request +mapping attributes, however, when used at the class level, a method-level `consumes` attribute +overrides rather than extends the class-level declaration. + +TIP: `MediaType` provides constants for commonly used media types -- for example, +`APPLICATION_JSON_VALUE` and `APPLICATION_XML_VALUE`. + + +[[webflux-ann-requestmapping-produces]] +== Producible Media Types +[.small]#<<web.adoc#mvc-ann-requestmapping-produces, See equivalent in the Servlet stack>># + +You can narrow the request mapping based on the `Accept` request header and the list of +content types that a controller method produces, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping(path = "/pets/{petId}", produces = "application/json") + @ResponseBody + public Pet getPet(@PathVariable String petId) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/pets/{petId}", produces = ["application/json"]) + @ResponseBody + fun getPet(@PathVariable petId: String): Pet { + // ... + } +---- + +The media type can specify a character set. Negated expressions are supported -- for example, +`!text/plain` means any content type other than `text/plain`. + +You can declare a shared `produces` attribute at the class level. Unlike most other request +mapping attributes, however, when used at the class level, a method-level `produces` attribute +overrides rather than extend the class level declaration. + +TIP: `MediaType` provides constants for commonly used media types -- e.g. +`APPLICATION_JSON_VALUE`, `APPLICATION_XML_VALUE`. + + +[[webflux-ann-requestmapping-params-and-headers]] +== Parameters and Headers +[.small]#<<web.adoc#mvc-ann-requestmapping-params-and-headers, See equivalent in the Servlet stack>># + +You can narrow request mappings based on query parameter conditions. You can test for the +presence of a query parameter (`myParam`), for its absence (`!myParam`), or for a +specific value (`myParam=myValue`). The following examples tests for a parameter with a value: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping(path = "/pets/{petId}", params = "myParam=myValue") // <1> + public void findPet(@PathVariable String petId) { + // ... + } +---- +<1> Check that `myParam` equals `myValue`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/pets/{petId}", params = ["myParam=myValue"]) // <1> + fun findPet(@PathVariable petId: String) { + // ... + } +---- +<1> Check that `myParam` equals `myValue`. + +You can also use the same with request header conditions, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") // <1> + public void findPet(@PathVariable String petId) { + // ... + } +---- +<1> Check that `myHeader` equals `myValue`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/pets/{petId}", headers = ["myHeader=myValue"]) // <1> + fun findPet(@PathVariable petId: String) { + // ... + } +---- +<1> Check that `myHeader` equals `myValue`. + + + +[[webflux-ann-requestmapping-head-options]] +== HTTP HEAD, OPTIONS +[.small]#<<web.adoc#mvc-ann-requestmapping-head-options, See equivalent in the Servlet stack>># + +`@GetMapping` and `@RequestMapping(method=HttpMethod.GET)` support HTTP HEAD +transparently for request mapping purposes. Controller methods need not change. +A response wrapper, applied in the `HttpHandler` server adapter, ensures a `Content-Length` +header is set to the number of bytes written without actually writing to the response. + +By default, HTTP OPTIONS is handled by setting the `Allow` response header to the list of HTTP +methods listed in all `@RequestMapping` methods with matching URL patterns. + +For a `@RequestMapping` without HTTP method declarations, the `Allow` header is set to +`GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS`. Controller methods should always declare the +supported HTTP methods (for example, by using the HTTP method specific variants -- +`@GetMapping`, `@PostMapping`, and others). + +You can explicitly map a `@RequestMapping` method to HTTP HEAD and HTTP OPTIONS, but that +is not necessary in the common case. + + +[[webflux-ann-requestmapping-composed]] +== Custom Annotations +[.small]#<<web.adoc#mvc-ann-requestmapping-composed, See equivalent in the Servlet stack>># + +Spring WebFlux supports the use of <<core.adoc#beans-meta-annotations, composed annotations>> +for request mapping. Those are annotations that are themselves meta-annotated with +`@RequestMapping` and composed to redeclare a subset (or all) of the `@RequestMapping` +attributes with a narrower, more specific purpose. + +`@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, and `@PatchMapping` are +examples of composed annotations. They are provided, because, arguably, most +controller methods should be mapped to a specific HTTP method versus using `@RequestMapping`, +which, by default, matches to all HTTP methods. If you need an example of composed +annotations, look at how those are declared. + +Spring WebFlux also supports custom request mapping attributes with custom request matching +logic. This is a more advanced option that requires sub-classing +`RequestMappingHandlerMapping` and overriding the `getCustomMethodCondition` method, where +you can check the custom attribute and return your own `RequestCondition`. + + +[[webflux-ann-requestmapping-registration]] +== Explicit Registrations +[.small]#<<web.adoc#mvc-ann-requestmapping-registration, See equivalent in the Servlet stack>># + +You can programmatically register Handler methods, which can be used for dynamic +registrations or for advanced cases, such as different instances of the same handler +under different URLs. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class MyConfig { + + @Autowired + public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) // <1> + throws NoSuchMethodException { + + RequestMappingInfo info = RequestMappingInfo + .paths("/user/{id}").methods(RequestMethod.GET).build(); // <2> + + Method method = UserHandler.class.getMethod("getUser", Long.class); // <3> + + mapping.registerMapping(info, handler, method); // <4> + } + + } +---- +<1> Inject target handlers and the handler mapping for controllers. +<2> Prepare the request mapping metadata. +<3> Get the handler method. +<4> Add the registration. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class MyConfig { + + @Autowired + fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) { // <1> + + val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build() // <2> + + val method = UserHandler::class.java.getMethod("getUser", Long::class.java) // <3> + + mapping.registerMapping(info, handler, method) // <4> + } + } +---- +<1> Inject target handlers and the handler mapping for controllers. +<2> Prepare the request mapping metadata. +<3> Get the handler method. +<4> Add the registration. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc new file mode 100644 index 000000000000..555a8a5876ae --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc @@ -0,0 +1,68 @@ +[[webflux-ann-controller]] += `@Controller` + +[.small]#<<web.adoc#mvc-ann-controller, See equivalent in the Servlet stack>># + +You can define controller beans by using a standard Spring bean definition. +The `@Controller` stereotype allows for auto-detection and is aligned with Spring general support +for detecting `@Component` classes in the classpath and auto-registering bean definitions +for them. It also acts as a stereotype for the annotated class, indicating its role as +a web component. + +To enable auto-detection of such `@Controller` beans, you can add component scanning to +your Java configuration, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ComponentScan("org.example.web") // <1> + public class WebConfig { + + // ... + } +---- +<1> Scan the `org.example.web` package. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ComponentScan("org.example.web") // <1> + class WebConfig { + + // ... + } +---- +<1> Scan the `org.example.web` package. + +`@RestController` is a <<core.adoc#beans-meta-annotations, composed annotation>> that is +itself meta-annotated with `@Controller` and `@ResponseBody`, indicating a controller whose +every method inherits the type-level `@ResponseBody` annotation and, therefore, writes +directly to the response body versus view resolution and rendering with an HTML template. + + + +[[webflux-ann-requestmapping-proxying]] +== AOP Proxies +[.small]#<<web.adoc#mvc-ann-requestmapping-proxying, See equivalent in the Servlet stack>># + +In some cases, you may need to decorate a controller with an AOP proxy at runtime. +One example is if you choose to have `@Transactional` annotations directly on the +controller. When this is the case, for controllers specifically, we recommend +using class-based proxying. This is automatically the case with such annotations +directly on the controller. + +If the controller implements an interface, and needs AOP proxying, you may need to +explicitly configure class-based proxying. For example, with `@EnableTransactionManagement` +you can change to `@EnableTransactionManagement(proxyTargetClass = true)`, and with +`<tx:annotation-driven/>` you can change to `<tx:annotation-driven proxy-target-class="true"/>`. + +NOTE: Keep in mind that as of 6.0, with interface proxying, Spring WebFlux no longer detects +controllers based solely on a type-level `@RequestMapping` annotation on the interface. +Please, enable class based proxying, or otherwise the interface must also have an +`@Controller` annotation. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc b/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc new file mode 100644 index 000000000000..8afcc14d7e0f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc @@ -0,0 +1,252 @@ +[[webflux-dispatcher-handler]] += `DispatcherHandler` + +[.small]#<<web.adoc#mvc-servlet, See equivalent in the Servlet stack>># + +Spring WebFlux, similarly to Spring MVC, is designed around the front controller pattern, +where a central `WebHandler`, the `DispatcherHandler`, provides a shared algorithm for +request processing, while actual work is performed by configurable, delegate components. +This model is flexible and supports diverse workflows. + +`DispatcherHandler` discovers the delegate components it needs from Spring configuration. +It is also designed to be a Spring bean itself and implements `ApplicationContextAware` +for access to the context in which it runs. If `DispatcherHandler` is declared with a bean +name of `webHandler`, it is, in turn, discovered by +{api-spring-framework}/web/server/adapter/WebHttpHandlerBuilder.html[`WebHttpHandlerBuilder`], +which puts together a request-processing chain, as described in <<webflux-web-handler-api>>. + +Spring configuration in a WebFlux application typically contains: + +* `DispatcherHandler` with the bean name `webHandler` +* `WebFilter` and `WebExceptionHandler` beans +* <<webflux-special-bean-types,`DispatcherHandler` special beans>> +* Others + +The configuration is given to `WebHttpHandlerBuilder` to build the processing chain, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ApplicationContext context = ... + HttpHandler handler = WebHttpHandlerBuilder.applicationContext(context).build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val context: ApplicationContext = ... + val handler = WebHttpHandlerBuilder.applicationContext(context).build() +---- + +The resulting `HttpHandler` is ready for use with a <<webflux-httphandler, server adapter>>. + + + +[[webflux-special-bean-types]] +== Special Bean Types +[.small]#<<web.adoc#mvc-servlet-special-bean-types, See equivalent in the Servlet stack>># + +The `DispatcherHandler` delegates to special beans to process requests and render the +appropriate responses. By "`special beans,`" we mean Spring-managed `Object` instances that +implement WebFlux framework contracts. Those usually come with built-in contracts, but +you can customize their properties, extend them, or replace them. + +The following table lists the special beans detected by the `DispatcherHandler`. Note that +there are also some other beans detected at a lower level (see +<<webflux-web-handler-api-special-beans>> in the Web Handler API). + +[[webflux-special-beans-table]] +[cols="1,2", options="header"] +|=== +| Bean type | Explanation + +| `HandlerMapping` +| Map a request to a handler. The mapping is based on some criteria, the details of + which vary by `HandlerMapping` implementation -- annotated controllers, simple + URL pattern mappings, and others. + + The main `HandlerMapping` implementations are `RequestMappingHandlerMapping` for + `@RequestMapping` annotated methods, `RouterFunctionMapping` for functional endpoint + routes, and `SimpleUrlHandlerMapping` for explicit registrations of URI path patterns + and `WebHandler` instances. + +| `HandlerAdapter` +| Help the `DispatcherHandler` to invoke a handler mapped to a request regardless of + how the handler is actually invoked. For example, invoking an annotated controller + requires resolving annotations. The main purpose of a `HandlerAdapter` is to shield the + `DispatcherHandler` from such details. + +| `HandlerResultHandler` +| Process the result from the handler invocation and finalize the response. + See <<webflux-resulthandling>>. + +|=== + + + +[[webflux-framework-config]] +== WebFlux Config +[.small]#<<web.adoc#mvc-servlet-config, See equivalent in the Servlet stack>># + +Applications can declare the infrastructure beans (listed under +<<webflux-web-handler-api-special-beans, Web Handler API>> and +<<webflux-special-bean-types, `DispatcherHandler`>>) that are required to process requests. +However, in most cases, the <<webflux-config>> is the best starting point. It declares the +required beans and provides a higher-level configuration callback API to customize it. + +NOTE: Spring Boot relies on the WebFlux config to configure Spring WebFlux and also provides +many extra convenient options. + + + +[[webflux-dispatcher-handler-sequence]] +== Processing +[.small]#<<web.adoc#mvc-servlet-sequence, See equivalent in the Servlet stack>># + +`DispatcherHandler` processes requests as follows: + +* Each `HandlerMapping` is asked to find a matching handler, and the first match is used. +* If a handler is found, it is run through an appropriate `HandlerAdapter`, which +exposes the return value from the execution as `HandlerResult`. +* The `HandlerResult` is given to an appropriate `HandlerResultHandler` to complete +processing by writing to the response directly or by using a view to render. + + + +[[webflux-resulthandling]] +== Result Handling + +The return value from the invocation of a handler, through a `HandlerAdapter`, is wrapped +as a `HandlerResult`, along with some additional context, and passed to the first +`HandlerResultHandler` that claims support for it. The following table shows the available +`HandlerResultHandler` implementations, all of which are declared in the <<webflux-config>>: + +[cols="1,2,1", options="header"] +|=== +| Result Handler Type | Return Values | Default Order + +| `ResponseEntityResultHandler` +| `ResponseEntity`, typically from `@Controller` instances. +| 0 + +| `ServerResponseResultHandler` +| `ServerResponse`, typically from functional endpoints. +| 0 + +| `ResponseBodyResultHandler` +| Handle return values from `@ResponseBody` methods or `@RestController` classes. +| 100 + +| `ViewResolutionResultHandler` +| `CharSequence`, {api-spring-framework}/web/reactive/result/view/View.html[`View`], + {api-spring-framework}/ui/Model.html[Model], `Map`, + {api-spring-framework}/web/reactive/result/view/Rendering.html[Rendering], + or any other `Object` is treated as a model attribute. + + See also <<webflux-viewresolution>>. +| `Integer.MAX_VALUE` + +|=== + + + +[[webflux-dispatcher-exceptions]] +== Exceptions +[.small]#<<web.adoc#mvc-exceptionhandlers, See equivalent in the Servlet stack>># + +`HandlerAdapter` implementations can handle internally exceptions from invoking a request +handler, such as a controller method. However, an exception may be deferred if the request +handler returns an asynchronous value. + +A `HandlerAdapter` may expose its exception handling mechanism as a +`DispatchExceptionHandler` set on the `HandlerResult` it returns. When that's set, +`DispatcherHandler` will also apply it to the handling of the result. + +A `HandlerAdapter` may also choose to implement `DispatchExceptionHandler`. In that case +`DispatcherHandler` will apply it to exceptions that arise before a handler is mapped, +e.g. during handler mapping, or earlier, e.g. in a `WebFilter`. + +See also <<webflux-ann-controller-exceptions>> in the "`Annotated Controller`" section or +<<webflux-exception-handler>> in the WebHandler API section. + + + +[[webflux-viewresolution]] +== View Resolution +[.small]#<<web.adoc#mvc-viewresolver, See equivalent in the Servlet stack>># + +View resolution enables rendering to a browser with an HTML template and a model without +tying you to a specific view technology. In Spring WebFlux, view resolution is +supported through a dedicated <<webflux-resulthandling, HandlerResultHandler>> that uses + `ViewResolver` instances to map a String (representing a logical view name) to a `View` +instance. The `View` is then used to render the response. + + +[[webflux-viewresolution-handling]] +=== Handling +[.small]#<<web.adoc#mvc-viewresolver-handling, See equivalent in the Servlet stack>># + +The `HandlerResult` passed into `ViewResolutionResultHandler` contains the return value +from the handler and the model that contains attributes added during request +handling. The return value is processed as one of the following: + +* `String`, `CharSequence`: A logical view name to be resolved to a `View` through +the list of configured `ViewResolver` implementations. +* `void`: Select a default view name based on the request path, minus the leading and +trailing slash, and resolve it to a `View`. The same also happens when a view name +was not provided (for example, model attribute was returned) or an async return value +(for example, `Mono` completed empty). +* {api-spring-framework}/web/reactive/result/view/Rendering.html[Rendering]: API for +view resolution scenarios. Explore the options in your IDE with code completion. +* `Model`, `Map`: Extra model attributes to be added to the model for the request. +* Any other: Any other return value (except for simple types, as determined by +{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) +is treated as a model attribute to be added to the model. The attribute name is derived +from the class name by using {api-spring-framework}/core/Conventions.html[conventions], +unless a handler method `@ModelAttribute` annotation is present. + +The model can contain asynchronous, reactive types (for example, from Reactor or RxJava). Prior +to rendering, `AbstractView` resolves such model attributes into concrete values +and updates the model. Single-value reactive types are resolved to a single +value or no value (if empty), while multi-value reactive types (for example, `Flux<T>`) are +collected and resolved to `List<T>`. + +To configure view resolution is as simple as adding a `ViewResolutionResultHandler` bean +to your Spring configuration. <<webflux-config-view-resolvers, WebFlux Config>> provides a +dedicated configuration API for view resolution. + +See <<webflux-view>> for more on the view technologies integrated with Spring WebFlux. + + +[[webflux-redirecting-redirect-prefix]] +=== Redirecting +[.small]#<<web.adoc#mvc-redirecting-redirect-prefix, See equivalent in the Servlet stack>># + +The special `redirect:` prefix in a view name lets you perform a redirect. The +`UrlBasedViewResolver` (and sub-classes) recognize this as an instruction that a +redirect is needed. The rest of the view name is the redirect URL. + +The net effect is the same as if the controller had returned a `RedirectView` or +`Rendering.redirectTo("abc").build()`, but now the controller itself can +operate in terms of logical view names. A view name such as +`redirect:/some/resource` is relative to the current application, while a view name such as +`redirect:https://example.com/arbitrary/path` redirects to an absolute URL. + + +[[webflux-multiple-representations]] +=== Content Negotiation +[.small]#<<web.adoc#mvc-multiple-representations, See equivalent in the Servlet stack>># + +`ViewResolutionResultHandler` supports content negotiation. It compares the request +media types with the media types supported by each selected `View`. The first `View` +that supports the requested media type(s) is used. + +In order to support media types such as JSON and XML, Spring WebFlux provides +`HttpMessageWriterView`, which is a special `View` that renders through an +<<webflux-codecs, HttpMessageWriter>>. Typically, you would configure these as default +views through the <<webflux-config-view-resolvers, WebFlux Configuration>>. Default views are +always selected and used if they match the requested media type. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc b/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc new file mode 100644 index 000000000000..ac8879e0d262 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc @@ -0,0 +1,8 @@ +[[webflux-http2]] += HTTP/2 + +[.small]#<<web.adoc#mvc-http2, See equivalent in the Servlet stack>># + +HTTP/2 is supported with Reactor Netty, Tomcat, Jetty, and Undertow. However, there are +considerations related to server configuration. For more details, see the +https://github.com/spring-projects/spring-framework/wiki/HTTP-2-support[HTTP/2 wiki page]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc b/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc new file mode 100644 index 000000000000..70e6be40dbd3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc @@ -0,0 +1,286 @@ +[[webflux-new-framework]] += Overview + +Why was Spring WebFlux created? + +Part of the answer is the need for a non-blocking web stack to handle concurrency with a +small number of threads and scale with fewer hardware resources. Servlet non-blocking I/O +leads away from the rest of the Servlet API, where contracts are synchronous +(`Filter`, `Servlet`) or blocking (`getParameter`, `getPart`). This was the motivation +for a new common API to serve as a foundation across any non-blocking runtime. That is +important because of servers (such as Netty) that are well-established in the async, +non-blocking space. + +The other part of the answer is functional programming. Much as the addition of annotations +in Java 5 created opportunities (such as annotated REST controllers or unit tests), the +addition of lambda expressions in Java 8 created opportunities for functional APIs in Java. +This is a boon for non-blocking applications and continuation-style APIs (as popularized +by `CompletableFuture` and https://reactivex.io/[ReactiveX]) that allow declarative +composition of asynchronous logic. At the programming-model level, Java 8 enabled Spring +WebFlux to offer functional web endpoints alongside annotated controllers. + + + +[[webflux-why-reactive]] +== Define "`Reactive`" + +We touched on "`non-blocking`" and "`functional`" but what does reactive mean? + +The term, "`reactive,`" refers to programming models that are built around reacting to change -- +network components reacting to I/O events, UI controllers reacting to mouse events, and others. +In that sense, non-blocking is reactive, because, instead of being blocked, we are now in the mode +of reacting to notifications as operations complete or data becomes available. + +There is also another important mechanism that we on the Spring team associate with "`reactive`" +and that is non-blocking back pressure. In synchronous, imperative code, blocking calls +serve as a natural form of back pressure that forces the caller to wait. In non-blocking +code, it becomes important to control the rate of events so that a fast producer does not +overwhelm its destination. + +Reactive Streams is a +https://github.com/reactive-streams/reactive-streams-jvm/blob/master/README.md#specification[small spec] +(also https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html[adopted] in Java 9) +that defines the interaction between asynchronous components with back pressure. +For example a data repository (acting as +https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Publisher.html[Publisher]) +can produce data that an HTTP server (acting as +https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Subscriber.html[Subscriber]) +can then write to the response. The main purpose of Reactive Streams is to let the + subscriber control how quickly or how slowly the publisher produces data. + +NOTE: *Common question: what if a publisher cannot slow down?* + +The purpose of Reactive Streams is only to establish the mechanism and a boundary. +If a publisher cannot slow down, it has to decide whether to buffer, drop, or fail. + + + +[[webflux-reactive-api]] +== Reactive API + +Reactive Streams plays an important role for interoperability. It is of interest to libraries +and infrastructure components but less useful as an application API, because it is too +low-level. Applications need a higher-level and richer, functional API to +compose async logic -- similar to the Java 8 `Stream` API but not only for collections. +This is the role that reactive libraries play. + +https://github.com/reactor/reactor[Reactor] is the reactive library of choice for +Spring WebFlux. It provides the +https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html[`Mono`] and +https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Flux.html[`Flux`] API types +to work on data sequences of 0..1 (`Mono`) and 0..N (`Flux`) through a rich set of operators aligned with the +ReactiveX https://reactivex.io/documentation/operators.html[vocabulary of operators]. +Reactor is a Reactive Streams library and, therefore, all of its operators support non-blocking back pressure. +Reactor has a strong focus on server-side Java. It is developed in close collaboration +with Spring. + +WebFlux requires Reactor as a core dependency but it is interoperable with other reactive +libraries via Reactive Streams. As a general rule, a WebFlux API accepts a plain `Publisher` +as input, adapts it to a Reactor type internally, uses that, and returns either a +`Flux` or a `Mono` as output. So, you can pass any `Publisher` as input and you can apply +operations on the output, but you need to adapt the output for use with another reactive library. +Whenever feasible (for example, annotated controllers), WebFlux adapts transparently to the use +of RxJava or another reactive library. See <<webflux-reactive-libraries>> for more details. + +NOTE: In addition to Reactive APIs, WebFlux can also be used with +<<languages.adoc#coroutines, Coroutines>> APIs in Kotlin which provides a more imperative style of programming. +The following Kotlin code samples will be provided with Coroutines APIs. + + + +[[webflux-programming-models]] +== Programming Models + +The `spring-web` module contains the reactive foundation that underlies Spring WebFlux, +including HTTP abstractions, Reactive Streams <<webflux-httphandler, adapters>> for supported +servers, <<webflux-codecs, codecs>>, and a core <<webflux-web-handler-api>> comparable to +the Servlet API but with non-blocking contracts. + +On that foundation, Spring WebFlux provides a choice of two programming models: + +* <<webflux-controller>>: Consistent with Spring MVC and based on the same annotations +from the `spring-web` module. Both Spring MVC and WebFlux controllers support reactive +(Reactor and RxJava) return types, and, as a result, it is not easy to tell them apart. One notable +difference is that WebFlux also supports reactive `@RequestBody` arguments. +* <<webflux-fn>>: Lambda-based, lightweight, and functional programming model. You can think of +this as a small library or a set of utilities that an application can use to route and +handle requests. The big difference with annotated controllers is that the application +is in charge of request handling from start to finish versus declaring intent through +annotations and being called back. + + + +[[webflux-framework-choice]] +== Applicability + +Spring MVC or WebFlux? + +A natural question to ask but one that sets up an unsound dichotomy. Actually, both +work together to expand the range of available options. The two are designed for +continuity and consistency with each other, they are available side by side, and feedback +from each side benefits both sides. The following diagram shows how the two relate, what they +have in common, and what each supports uniquely: + +image::spring-mvc-and-webflux-venn.png[] + +We suggest that you consider the following specific points: + +* If you have a Spring MVC application that works fine, there is no need to change. +Imperative programming is the easiest way to write, understand, and debug code. +You have maximum choice of libraries, since, historically, most are blocking. + +* If you are already shopping for a non-blocking web stack, Spring WebFlux offers the same +execution model benefits as others in this space and also provides a choice of servers +(Netty, Tomcat, Jetty, Undertow, and Servlet containers), a choice of programming models +(annotated controllers and functional web endpoints), and a choice of reactive libraries +(Reactor, RxJava, or other). + +* If you are interested in a lightweight, functional web framework for use with Java 8 lambdas +or Kotlin, you can use the Spring WebFlux functional web endpoints. That can also be a good choice +for smaller applications or microservices with less complex requirements that can benefit +from greater transparency and control. + +* In a microservice architecture, you can have a mix of applications with either Spring MVC +or Spring WebFlux controllers or with Spring WebFlux functional endpoints. Having support +for the same annotation-based programming model in both frameworks makes it easier to +re-use knowledge while also selecting the right tool for the right job. + +* A simple way to evaluate an application is to check its dependencies. If you have blocking +persistence APIs (JPA, JDBC) or networking APIs to use, Spring MVC is the best choice +for common architectures at least. It is technically feasible with both Reactor and +RxJava to perform blocking calls on a separate thread but you would not be making the +most of a non-blocking web stack. + +* If you have a Spring MVC application with calls to remote services, try the reactive `WebClient`. +You can return reactive types (Reactor, RxJava, <<webflux-reactive-libraries, or other>>) +directly from Spring MVC controller methods. The greater the latency per call or the +interdependency among calls, the more dramatic the benefits. Spring MVC controllers +can call other reactive components too. + +* If you have a large team, keep in mind the steep learning curve in the shift to non-blocking, +functional, and declarative programming. A practical way to start without a full switch +is to use the reactive `WebClient`. Beyond that, start small and measure the benefits. +We expect that, for a wide range of applications, the shift is unnecessary. If you are +unsure what benefits to look for, start by learning about how non-blocking I/O works +(for example, concurrency on single-threaded Node.js) and its effects. + + + +[[webflux-server-choice]] +== Servers + +Spring WebFlux is supported on Tomcat, Jetty, Servlet containers, as well as on +non-Servlet runtimes such as Netty and Undertow. All servers are adapted to a low-level, +<<webflux-httphandler, common API>> so that higher-level +<<webflux-programming-models, programming models>> can be supported across servers. + +Spring WebFlux does not have built-in support to start or stop a server. However, it is +easy to <<webflux-web-handler-api, assemble>> an application from Spring configuration and +<<webflux-config, WebFlux infrastructure>> and <<webflux-httphandler, run it>> with a few +lines of code. + +Spring Boot has a WebFlux starter that automates these steps. By default, the starter uses +Netty, but it is easy to switch to Tomcat, Jetty, or Undertow by changing your +Maven or Gradle dependencies. Spring Boot defaults to Netty, because it is more widely +used in the asynchronous, non-blocking space and lets a client and a server share resources. + +Tomcat and Jetty can be used with both Spring MVC and WebFlux. Keep in mind, however, that +the way they are used is very different. Spring MVC relies on Servlet blocking I/O and +lets applications use the Servlet API directly if they need to. Spring WebFlux +relies on Servlet non-blocking I/O and uses the Servlet API behind a low-level +adapter. It is not exposed for direct use. + +For Undertow, Spring WebFlux uses Undertow APIs directly without the Servlet API. + + + +[[webflux-performance]] +== Performance + +Performance has many characteristics and meanings. Reactive and non-blocking generally +do not make applications run faster. They can, in some cases, (for example, if using the +`WebClient` to run remote calls in parallel). On the whole, it requires more work to do +things the non-blocking way and that can slightly increase the required processing time. + +The key expected benefit of reactive and non-blocking is the ability to scale with a small, +fixed number of threads and less memory. That makes applications more resilient under load, +because they scale in a more predictable way. In order to observe those benefits, however, you +need to have some latency (including a mix of slow and unpredictable network I/O). +That is where the reactive stack begins to show its strengths, and the differences can be +dramatic. + + + +[[webflux-concurrency-model]] +== Concurrency Model + +Both Spring MVC and Spring WebFlux support annotated controllers, but there is a key +difference in the concurrency model and the default assumptions for blocking and threads. + +In Spring MVC (and servlet applications in general), it is assumed that applications can +block the current thread, (for example, for remote calls). For this reason, servlet containers +use a large thread pool to absorb potential blocking during request handling. + +In Spring WebFlux (and non-blocking servers in general), it is assumed that applications +do not block. Therefore, non-blocking servers use a small, fixed-size thread pool +(event loop workers) to handle requests. + +TIP: "`To scale`" and "`small number of threads`" may sound contradictory but to never block the +current thread (and rely on callbacks instead) means that you do not need extra threads, as +there are no blocking calls to absorb. + + +[[invoking-a-blocking-api]] +=== Invoking a Blocking API + +What if you do need to use a blocking library? Both Reactor and RxJava provide the +`publishOn` operator to continue processing on a different thread. That means there is an +easy escape hatch. Keep in mind, however, that blocking APIs are not a good fit for +this concurrency model. + +[[mutable-state]] +=== Mutable State + +In Reactor and RxJava, you declare logic through operators. At runtime, a reactive +pipeline is formed where data is processed sequentially, in distinct stages. A key benefit +of this is that it frees applications from having to protect mutable state because +application code within that pipeline is never invoked concurrently. + +[[threading-model]] +=== Threading Model + +What threads should you expect to see on a server running with Spring WebFlux? + +* On a "`vanilla`" Spring WebFlux server (for example, no data access nor other optional +dependencies), you can expect one thread for the server and several others for request +processing (typically as many as the number of CPU cores). Servlet containers, however, +may start with more threads (for example, 10 on Tomcat), in support of both servlet (blocking) I/O +and servlet 3.1 (non-blocking) I/O usage. + +* The reactive `WebClient` operates in event loop style. So you can see a small, fixed +number of processing threads related to that (for example, `reactor-http-nio-` with the Reactor +Netty connector). However, if Reactor Netty is used for both client and server, the two +share event loop resources by default. + +* Reactor and RxJava provide thread pool abstractions, called schedulers, to use with the +`publishOn` operator that is used to switch processing to a different thread pool. +The schedulers have names that suggest a specific concurrency strategy -- for example, "`parallel`" +(for CPU-bound work with a limited number of threads) or "`elastic`" (for I/O-bound work with +a large number of threads). If you see such threads, it means some code is using a +specific thread pool `Scheduler` strategy. + +* Data access libraries and other third party dependencies can also create and use threads +of their own. + +[[configuring]] +=== Configuring + +The Spring Framework does not provide support for starting and stopping +<<webflux-server-choice, servers>>. To configure the threading model for a server, +you need to use server-specific configuration APIs, or, if you use Spring Boot, +check the Spring Boot configuration options for each server. You can +<<web-reactive.adoc#webflux-client-builder, configure>> the `WebClient` directly. +For all other libraries, see their respective documentation. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc new file mode 100644 index 000000000000..cfef50ee7424 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc @@ -0,0 +1,716 @@ +[[webflux-reactive-spring-web]] += Reactive Core + +The `spring-web` module contains the following foundational support for reactive web +applications: + +* For server request processing there are two levels of support. +** <<webflux-httphandler, HttpHandler>>: Basic contract for HTTP request handling with +non-blocking I/O and Reactive Streams back pressure, along with adapters for Reactor Netty, +Undertow, Tomcat, Jetty, and any Servlet container. +** <<webflux-web-handler-api>>: Slightly higher level, general-purpose web API for +request handling, on top of which concrete programming models such as annotated +controllers and functional endpoints are built. +* For the client side, there is a basic `ClientHttpConnector` contract to perform HTTP +requests with non-blocking I/O and Reactive Streams back pressure, along with adapters for +https://github.com/reactor/reactor-netty[Reactor Netty], reactive +https://github.com/jetty-project/jetty-reactive-httpclient[Jetty HttpClient] +and https://hc.apache.org/[Apache HttpComponents]. +The higher level <<web-reactive.adoc#webflux-client, WebClient>> used in applications +builds on this basic contract. +* For client and server, <<webflux-codecs, codecs>> for serialization and +deserialization of HTTP request and response content. + + + +[[webflux-httphandler]] +== `HttpHandler` + +{api-spring-framework}/http/server/reactive/HttpHandler.html[HttpHandler] +is a simple contract with a single method to handle a request and a response. It is +intentionally minimal, and its main and only purpose is to be a minimal abstraction +over different HTTP server APIs. + +The following table describes the supported server APIs: + +[cols="1,2,2", options="header"] +|=== +| Server name | Server API used | Reactive Streams support + +| Netty +| Netty API +| https://github.com/reactor/reactor-netty[Reactor Netty] + +| Undertow +| Undertow API +| spring-web: Undertow to Reactive Streams bridge + +| Tomcat +| Servlet non-blocking I/O; Tomcat API to read and write ByteBuffers vs byte[] +| spring-web: Servlet non-blocking I/O to Reactive Streams bridge + +| Jetty +| Servlet non-blocking I/O; Jetty API to write ByteBuffers vs byte[] +| spring-web: Servlet non-blocking I/O to Reactive Streams bridge + +| Servlet container +| Servlet non-blocking I/O +| spring-web: Servlet non-blocking I/O to Reactive Streams bridge +|=== + +The following table describes server dependencies (also see +https://github.com/spring-projects/spring-framework/wiki/What%27s-New-in-the-Spring-Framework[supported versions]): + +|=== +|Server name|Group id|Artifact name + +|Reactor Netty +|io.projectreactor.netty +|reactor-netty + +|Undertow +|io.undertow +|undertow-core + +|Tomcat +|org.apache.tomcat.embed +|tomcat-embed-core + +|Jetty +|org.eclipse.jetty +|jetty-server, jetty-servlet +|=== + +The code snippets below show using the `HttpHandler` adapters with each server API: + +*Reactor Netty* +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpHandler handler = ... + ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(handler); + HttpServer.create().host(host).port(port).handle(adapter).bindNow(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val handler: HttpHandler = ... + val adapter = ReactorHttpHandlerAdapter(handler) + HttpServer.create().host(host).port(port).handle(adapter).bindNow() +---- + +*Undertow* +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpHandler handler = ... + UndertowHttpHandlerAdapter adapter = new UndertowHttpHandlerAdapter(handler); + Undertow server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build(); + server.start(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val handler: HttpHandler = ... + val adapter = UndertowHttpHandlerAdapter(handler) + val server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build() + server.start() +---- + +*Tomcat* +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpHandler handler = ... + Servlet servlet = new TomcatHttpHandlerAdapter(handler); + + Tomcat server = new Tomcat(); + File base = new File(System.getProperty("java.io.tmpdir")); + Context rootContext = server.addContext("", base.getAbsolutePath()); + Tomcat.addServlet(rootContext, "main", servlet); + rootContext.addServletMappingDecoded("/", "main"); + server.setHost(host); + server.setPort(port); + server.start(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val handler: HttpHandler = ... + val servlet = TomcatHttpHandlerAdapter(handler) + + val server = Tomcat() + val base = File(System.getProperty("java.io.tmpdir")) + val rootContext = server.addContext("", base.absolutePath) + Tomcat.addServlet(rootContext, "main", servlet) + rootContext.addServletMappingDecoded("/", "main") + server.host = host + server.setPort(port) + server.start() +---- + +*Jetty* + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpHandler handler = ... + Servlet servlet = new JettyHttpHandlerAdapter(handler); + + Server server = new Server(); + ServletContextHandler contextHandler = new ServletContextHandler(server, ""); + contextHandler.addServlet(new ServletHolder(servlet), "/"); + contextHandler.start(); + + ServerConnector connector = new ServerConnector(server); + connector.setHost(host); + connector.setPort(port); + server.addConnector(connector); + server.start(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val handler: HttpHandler = ... + val servlet = JettyHttpHandlerAdapter(handler) + + val server = Server() + val contextHandler = ServletContextHandler(server, "") + contextHandler.addServlet(ServletHolder(servlet), "/") + contextHandler.start(); + + val connector = ServerConnector(server) + connector.host = host + connector.port = port + server.addConnector(connector) + server.start() +---- + +*Servlet Container* + +To deploy as a WAR to any Servlet container, you can extend and include +{api-spring-framework}/web/server/adapter/AbstractReactiveWebInitializer.html[`AbstractReactiveWebInitializer`] +in the WAR. That class wraps an `HttpHandler` with `ServletHttpHandlerAdapter` and registers +that as a `Servlet`. + + + +[[webflux-web-handler-api]] +== `WebHandler` API + +The `org.springframework.web.server` package builds on the <<webflux-httphandler>> contract +to provide a general-purpose web API for processing requests through a chain of multiple +{api-spring-framework}/web/server/WebExceptionHandler.html[`WebExceptionHandler`], multiple +{api-spring-framework}/web/server/WebFilter.html[`WebFilter`], and a single +{api-spring-framework}/web/server/WebHandler.html[`WebHandler`] component. The chain can +be put together with `WebHttpHandlerBuilder` by simply pointing to a Spring +`ApplicationContext` where components are +<<webflux-web-handler-api-special-beans, auto-detected>>, and/or by registering components +with the builder. + +While `HttpHandler` has a simple goal to abstract the use of different HTTP servers, the +`WebHandler` API aims to provide a broader set of features commonly used in web applications +such as: + +* User session with attributes. +* Request attributes. +* Resolved `Locale` or `Principal` for the request. +* Access to parsed and cached form data. +* Abstractions for multipart data. +* and more.. + +[[webflux-web-handler-api-special-beans]] +=== Special bean types + +The table below lists the components that `WebHttpHandlerBuilder` can auto-detect in a +Spring ApplicationContext, or that can be registered directly with it: + +[cols="2,2,1,3", options="header"] +|=== +| Bean name | Bean type | Count | Description + +| <any> +| `WebExceptionHandler` +| 0..N +| Provide handling for exceptions from the chain of `WebFilter` instances and the target + `WebHandler`. For more details, see <<webflux-exception-handler>>. + +| <any> +| `WebFilter` +| 0..N +| Apply interception style logic to before and after the rest of the filter chain and + the target `WebHandler`. For more details, see <<webflux-filters>>. + +| `webHandler` +| `WebHandler` +| 1 +| The handler for the request. + +| `webSessionManager` +| `WebSessionManager` +| 0..1 +| The manager for `WebSession` instances exposed through a method on `ServerWebExchange`. + `DefaultWebSessionManager` by default. + +| `serverCodecConfigurer` +| `ServerCodecConfigurer` +| 0..1 +| For access to `HttpMessageReader` instances for parsing form data and multipart data that is then + exposed through methods on `ServerWebExchange`. `ServerCodecConfigurer.create()` by default. + +| `localeContextResolver` +| `LocaleContextResolver` +| 0..1 +| The resolver for `LocaleContext` exposed through a method on `ServerWebExchange`. + `AcceptHeaderLocaleContextResolver` by default. + +| `forwardedHeaderTransformer` +| `ForwardedHeaderTransformer` +| 0..1 +| For processing forwarded type headers, either by extracting and removing them or by removing them only. + Not used by default. +|=== + + +[[webflux-form-data]] +=== Form Data + +`ServerWebExchange` exposes the following method for accessing form data: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<MultiValueMap<String, String>> getFormData(); +---- +[source,Kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + suspend fun getFormData(): MultiValueMap<String, String> +---- + +The `DefaultServerWebExchange` uses the configured `HttpMessageReader` to parse form data +(`application/x-www-form-urlencoded`) into a `MultiValueMap`. By default, +`FormHttpMessageReader` is configured for use by the `ServerCodecConfigurer` bean +(see the <<webflux-web-handler-api, Web Handler API>>). + + +[[webflux-multipart]] +=== Multipart Data +[.small]#<<web.adoc#mvc-multipart, See equivalent in the Servlet stack>># + +`ServerWebExchange` exposes the following method for accessing multipart data: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Mono<MultiValueMap<String, Part>> getMultipartData(); +---- +[source,Kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + suspend fun getMultipartData(): MultiValueMap<String, Part> +---- + +The `DefaultServerWebExchange` uses the configured +`HttpMessageReader<MultiValueMap<String, Part>>` to parse `multipart/form-data`, +`multipart/mixed`, and `multipart/related` content into a `MultiValueMap`. +By default, this is the `DefaultPartHttpMessageReader`, which does not have any third-party +dependencies. +Alternatively, the `SynchronossPartHttpMessageReader` can be used, which is based on the +https://github.com/synchronoss/nio-multipart[Synchronoss NIO Multipart] library. +Both are configured through the `ServerCodecConfigurer` bean +(see the <<webflux-web-handler-api, Web Handler API>>). + +To parse multipart data in streaming fashion, you can use the `Flux<PartEvent>` returned from the +`PartEventHttpMessageReader` instead of using `@RequestPart`, as that implies `Map`-like access +to individual parts by name and, hence, requires parsing multipart data in full. +By contrast, you can use `@RequestBody` to decode the content to `Flux<PartEvent>` without +collecting to a `MultiValueMap`. + + +[[webflux-forwarded-headers]] +=== Forwarded Headers +[.small]#<<web.adoc#filters-forwarded-headers, See equivalent in the Servlet stack>># + +As a request goes through proxies (such as load balancers), the host, port, and +scheme may change. That makes it a challenge, from a client perspective, to create links that point to the correct +host, port, and scheme. + +https://tools.ietf.org/html/rfc7239[RFC 7239] defines the `Forwarded` HTTP header +that proxies can use to provide information about the original request. There are other +non-standard headers, too, including `X-Forwarded-Host`, `X-Forwarded-Port`, +`X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`. + +`ForwardedHeaderTransformer` is a component that modifies the host, port, and scheme of +the request, based on forwarded headers, and then removes those headers. If you declare +it as a bean with the name `forwardedHeaderTransformer`, it will be +<<webflux-web-handler-api-special-beans, detected>> and used. + +There are security considerations for forwarded headers, since an application cannot know +if the headers were added by a proxy, as intended, or by a malicious client. This is why +a proxy at the boundary of trust should be configured to remove untrusted forwarded traffic coming +from the outside. You can also configure the `ForwardedHeaderTransformer` with +`removeOnly=true`, in which case it removes but does not use the headers. + +NOTE: In 5.1 `ForwardedHeaderFilter` was deprecated and superseded by +`ForwardedHeaderTransformer` so forwarded headers can be processed earlier, before the +exchange is created. If the filter is configured anyway, it is taken out of the list of +filters, and `ForwardedHeaderTransformer` is used instead. + + + +[[webflux-filters]] +== Filters +[.small]#<<web.adoc#filters, See equivalent in the Servlet stack>># + +In the <<webflux-web-handler-api>>, you can use a `WebFilter` to apply interception-style +logic before and after the rest of the processing chain of filters and the target +`WebHandler`. When using the <<webflux-config>>, registering a `WebFilter` is as simple +as declaring it as a Spring bean and (optionally) expressing precedence by using `@Order` on +the bean declaration or by implementing `Ordered`. + + +[[webflux-filters-cors]] +=== CORS +[.small]#<<web.adoc#filters-cors, See equivalent in the Servlet stack>># + +Spring WebFlux provides fine-grained support for CORS configuration through annotations on +controllers. However, when you use it with Spring Security, we advise relying on the built-in +`CorsFilter`, which must be ordered ahead of Spring Security's chain of filters. + +See the section on <<webflux-cors>> and the <<webflux-cors-webfilter>> for more details. + + +[[webflux-exception-handler]] +== Exceptions +[.small]#<<web.adoc#mvc-ann-customer-servlet-container-error-page, See equivalent in the Servlet stack>># + +In the <<webflux-web-handler-api>>, you can use a `WebExceptionHandler` to handle +exceptions from the chain of `WebFilter` instances and the target `WebHandler`. When using the +<<webflux-config>>, registering a `WebExceptionHandler` is as simple as declaring it as a +Spring bean and (optionally) expressing precedence by using `@Order` on the bean declaration or +by implementing `Ordered`. + +The following table describes the available `WebExceptionHandler` implementations: + +[cols="1,2", options="header"] +|=== +| Exception Handler | Description + +| `ResponseStatusExceptionHandler` +| Provides handling for exceptions of type + {api-spring-framework}/web/server/ResponseStatusException.html[`ResponseStatusException`] + by setting the response to the HTTP status code of the exception. + +| `WebFluxResponseStatusExceptionHandler` +| Extension of `ResponseStatusExceptionHandler` that can also determine the HTTP status + code of a `@ResponseStatus` annotation on any exception. + + This handler is declared in the <<webflux-config>>. + +|=== + + + +[[webflux-codecs]] +== Codecs +[.small]#<<integration.adoc#rest-message-conversion, See equivalent in the Servlet stack>># + +The `spring-web` and `spring-core` modules provide support for serializing and +deserializing byte content to and from higher level objects through non-blocking I/O with +Reactive Streams back pressure. The following describes this support: + +* {api-spring-framework}/core/codec/Encoder.html[`Encoder`] and +{api-spring-framework}/core/codec/Decoder.html[`Decoder`] are low level contracts to +encode and decode content independent of HTTP. +* {api-spring-framework}/http/codec/HttpMessageReader.html[`HttpMessageReader`] and +{api-spring-framework}/http/codec/HttpMessageWriter.html[`HttpMessageWriter`] are contracts +to encode and decode HTTP message content. +* An `Encoder` can be wrapped with `EncoderHttpMessageWriter` to adapt it for use in a web +application, while a `Decoder` can be wrapped with `DecoderHttpMessageReader`. +* {api-spring-framework}/core/io/buffer/DataBuffer.html[`DataBuffer`] abstracts different +byte buffer representations (e.g. Netty `ByteBuf`, `java.nio.ByteBuffer`, etc.) and is +what all codecs work on. See <<core#databuffers,Data Buffers and Codecs>> in the +"Spring Core" section for more on this topic. + +The `spring-core` module provides `byte[]`, `ByteBuffer`, `DataBuffer`, `Resource`, and +`String` encoder and decoder implementations. The `spring-web` module provides Jackson +JSON, Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders along with +web-only HTTP message reader and writer implementations for form data, multipart content, +server-sent events, and others. + +`ClientCodecConfigurer` and `ServerCodecConfigurer` are typically used to configure and +customize the codecs to use in an application. See the section on configuring +<<webflux-config-message-codecs>>. + +[[webflux-codecs-jackson]] +=== Jackson JSON + +JSON and binary JSON (https://github.com/FasterXML/smile-format-specification[Smile]) are +both supported when the Jackson library is present. + +The `Jackson2Decoder` works as follows: + +* Jackson's asynchronous, non-blocking parser is used to aggregate a stream of byte chunks +into ``TokenBuffer``'s each representing a JSON object. +* Each `TokenBuffer` is passed to Jackson's `ObjectMapper` to create a higher level object. +* When decoding to a single-value publisher (e.g. `Mono`), there is one `TokenBuffer`. +* When decoding to a multi-value publisher (e.g. `Flux`), each `TokenBuffer` is passed to +the `ObjectMapper` as soon as enough bytes are received for a fully formed object. The +input content can be a JSON array, or any +https://en.wikipedia.org/wiki/JSON_streaming[line-delimited JSON] format such as NDJSON, +JSON Lines, or JSON Text Sequences. + +The `Jackson2Encoder` works as follows: + +* For a single value publisher (e.g. `Mono`), simply serialize it through the +`ObjectMapper`. +* For a multi-value publisher with `application/json`, by default collect the values with +`Flux#collectToList()` and then serialize the resulting collection. +* For a multi-value publisher with a streaming media type such as +`application/x-ndjson` or `application/stream+x-jackson-smile`, encode, write, and +flush each value individually using a +https://en.wikipedia.org/wiki/JSON_streaming[line-delimited JSON] format. Other +streaming media types may be registered with the encoder. +* For SSE the `Jackson2Encoder` is invoked per event and the output is flushed to ensure +delivery without delay. + +[NOTE] +==== +By default both `Jackson2Encoder` and `Jackson2Decoder` do not support elements of type +`String`. Instead the default assumption is that a string or a sequence of strings +represent serialized JSON content, to be rendered by the `CharSequenceEncoder`. If what +you need is to render a JSON array from `Flux<String>`, use `Flux#collectToList()` and +encode a `Mono<List<String>>`. +==== + +[[webflux-codecs-forms]] +=== Form Data + +`FormHttpMessageReader` and `FormHttpMessageWriter` support decoding and encoding +`application/x-www-form-urlencoded` content. + +On the server side where form content often needs to be accessed from multiple places, +`ServerWebExchange` provides a dedicated `getFormData()` method that parses the content +through `FormHttpMessageReader` and then caches the result for repeated access. +See <<webflux-form-data>> in the <<webflux-web-handler-api>> section. + +Once `getFormData()` is used, the original raw content can no longer be read from the +request body. For this reason, applications are expected to go through `ServerWebExchange` +consistently for access to the cached form data versus reading from the raw request body. + + +[[webflux-codecs-multipart]] +=== Multipart + +`MultipartHttpMessageReader` and `MultipartHttpMessageWriter` support decoding and +encoding "multipart/form-data", "multipart/mixed", and "multipart/related" content. +In turn `MultipartHttpMessageReader` delegates to another `HttpMessageReader` +for the actual parsing to a `Flux<Part>` and then simply collects the parts into a `MultiValueMap`. +By default, the `DefaultPartHttpMessageReader` is used, but this can be changed through the +`ServerCodecConfigurer`. +For more information about the `DefaultPartHttpMessageReader`, refer to the +{api-spring-framework}/http/codec/multipart/DefaultPartHttpMessageReader.html[javadoc of `DefaultPartHttpMessageReader`]. + +On the server side where multipart form content may need to be accessed from multiple +places, `ServerWebExchange` provides a dedicated `getMultipartData()` method that parses +the content through `MultipartHttpMessageReader` and then caches the result for repeated access. +See <<webflux-multipart>> in the <<webflux-web-handler-api>> section. + +Once `getMultipartData()` is used, the original raw content can no longer be read from the +request body. For this reason applications have to consistently use `getMultipartData()` +for repeated, map-like access to parts, or otherwise rely on the +`SynchronossPartHttpMessageReader` for a one-time access to `Flux<Part>`. + + +[[webflux-codecs-limits]] +=== Limits + +`Decoder` and `HttpMessageReader` implementations that buffer some or all of the input +stream can be configured with a limit on the maximum number of bytes to buffer in memory. +In some cases buffering occurs because input is aggregated and represented as a single +object — for example, a controller method with `@RequestBody byte[]`, +`x-www-form-urlencoded` data, and so on. Buffering can also occur with streaming, when +splitting the input stream — for example, delimited text, a stream of JSON objects, and +so on. For those streaming cases, the limit applies to the number of bytes associated +with one object in the stream. + +To configure buffer sizes, you can check if a given `Decoder` or `HttpMessageReader` +exposes a `maxInMemorySize` property and if so the Javadoc will have details about default +values. On the server side, `ServerCodecConfigurer` provides a single place from where to +set all codecs, see <<webflux-config-message-codecs>>. On the client side, the limit for +all codecs can be changed in +<<web-reactive.adoc#webflux-client-builder-maxinmemorysize, WebClient.Builder>>. + +For <<webflux-codecs-multipart,Multipart parsing>> the `maxInMemorySize` property limits +the size of non-file parts. For file parts, it determines the threshold at which the part +is written to disk. For file parts written to disk, there is an additional +`maxDiskUsagePerPart` property to limit the amount of disk space per part. There is also +a `maxParts` property to limit the overall number of parts in a multipart request. +To configure all three in WebFlux, you'll need to supply a pre-configured instance of +`MultipartHttpMessageReader` to `ServerCodecConfigurer`. + + + +[[webflux-codecs-streaming]] +=== Streaming +[.small]#<<web.adoc#mvc-ann-async-http-streaming, See equivalent in the Servlet stack>># + +When streaming to the HTTP response (for example, `text/event-stream`, +`application/x-ndjson`), it is important to send data periodically, in order to +reliably detect a disconnected client sooner rather than later. Such a send could be a +comment-only, empty SSE event or any other "no-op" data that would effectively serve as +a heartbeat. + + +[[webflux-codecs-buffers]] +=== `DataBuffer` + +`DataBuffer` is the representation for a byte buffer in WebFlux. The Spring Core part of +this reference has more on that in the section on +<<core#databuffers, Data Buffers and Codecs>>. The key point to understand is that on some +servers like Netty, byte buffers are pooled and reference counted, and must be released +when consumed to avoid memory leaks. + +WebFlux applications generally do not need to be concerned with such issues, unless they +consume or produce data buffers directly, as opposed to relying on codecs to convert to +and from higher level objects, or unless they choose to create custom codecs. For such +cases please review the information in <<core#databuffers, Data Buffers and Codecs>>, +especially the section on <<core#databuffers-using, Using DataBuffer>>. + + + +[[webflux-logging]] +== Logging +[.small]#<<web.adoc#mvc-logging, See equivalent in the Servlet stack>># + +`DEBUG` level logging in Spring WebFlux is designed to be compact, minimal, and +human-friendly. It focuses on high value bits of information that are useful over and +over again vs others that are useful only when debugging a specific issue. + +`TRACE` level logging generally follows the same principles as `DEBUG` (and for example also +should not be a firehose) but can be used for debugging any issue. In addition, some log +messages may show a different level of detail at `TRACE` vs `DEBUG`. + +Good logging comes from the experience of using the logs. If you spot anything that does +not meet the stated goals, please let us know. + + +[[webflux-logging-id]] +=== Log Id + +In WebFlux, a single request can be run over multiple threads and the thread ID +is not useful for correlating log messages that belong to a specific request. This is why +WebFlux log messages are prefixed with a request-specific ID by default. + +On the server side, the log ID is stored in the `ServerWebExchange` attribute +({api-spring-framework}/web/server/ServerWebExchange.html#LOG_ID_ATTRIBUTE[`LOG_ID_ATTRIBUTE`]), +while a fully formatted prefix based on that ID is available from +`ServerWebExchange#getLogPrefix()`. On the `WebClient` side, the log ID is stored in the +`ClientRequest` attribute +({api-spring-framework}/web/reactive/function/client/ClientRequest.html#LOG_ID_ATTRIBUTE[`LOG_ID_ATTRIBUTE`]) +,while a fully formatted prefix is available from `ClientRequest#logPrefix()`. + + +[[webflux-logging-sensitive-data]] +=== Sensitive Data +[.small]#<<web.adoc#mvc-logging-sensitive-data, See equivalent in the Servlet stack>># + +`DEBUG` and `TRACE` logging can log sensitive information. This is why form parameters and +headers are masked by default and you must explicitly enable their logging in full. + +The following example shows how to do so for server-side requests: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebFlux + class MyConfig implements WebFluxConfigurer { + + @Override + public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) { + configurer.defaultCodecs().enableLoggingRequestDetails(true); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebFlux + class MyConfig : WebFluxConfigurer { + + override fun configureHttpMessageCodecs(configurer: ServerCodecConfigurer) { + configurer.defaultCodecs().enableLoggingRequestDetails(true) + } + } +---- + +The following example shows how to do so for client-side requests: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + Consumer<ClientCodecConfigurer> consumer = configurer -> + configurer.defaultCodecs().enableLoggingRequestDetails(true); + + WebClient webClient = WebClient.builder() + .exchangeStrategies(strategies -> strategies.codecs(consumer)) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val consumer: (ClientCodecConfigurer) -> Unit = { configurer -> configurer.defaultCodecs().enableLoggingRequestDetails(true) } + + val webClient = WebClient.builder() + .exchangeStrategies({ strategies -> strategies.codecs(consumer) }) + .build() +---- + + +[[webflux-logging-appenders]] +=== Appenders + +Logging libraries such as SLF4J and Log4J 2 provide asynchronous loggers that avoid +blocking. While those have their own drawbacks such as potentially dropping messages +that could not be queued for logging, they are the best available options currently +for use in a reactive, non-blocking application. + + + +[[webflux-codecs-custom]] +=== Custom codecs + +Applications can register custom codecs for supporting additional media types, +or specific behaviors that are not supported by the default codecs. + +Some configuration options expressed by developers are enforced on default codecs. +Custom codecs might want to get a chance to align with those preferences, +like <<webflux-codecs-limits, enforcing buffering limits>> +or <<webflux-logging-sensitive-data, logging sensitive data>>. + +The following example shows how to do so for client-side requests: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + WebClient webClient = WebClient.builder() + .codecs(configurer -> { + CustomDecoder decoder = new CustomDecoder(); + configurer.customCodecs().registerWithDefaultConfig(decoder); + }) + .build(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val webClient = WebClient.builder() + .codecs({ configurer -> + val decoder = CustomDecoder() + configurer.customCodecs().registerWithDefaultConfig(decoder) + }) + .build() +---- + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/security.adoc b/framework-docs/modules/ROOT/pages/web/webflux/security.adoc new file mode 100644 index 000000000000..c198e3540c07 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/security.adoc @@ -0,0 +1,17 @@ +[[webflux-web-security]] += Web Security + +[.small]#<<web.adoc#mvc-web-security, See equivalent in the Servlet stack>># + +The https://spring.io/projects/spring-security[Spring Security] project provides support +for protecting web applications from malicious exploits. See the Spring Security +reference documentation, including: + +* {docs-spring-security}/reactive/configuration/webflux.html[WebFlux Security] +* {docs-spring-security}/reactive/test/index.html[WebFlux Testing Support] +* {docs-spring-security}/features/exploits/csrf.html#csrf-protection[CSRF protection] +* {docs-spring-security}/features/exploits/headers.html[Security Response Headers] + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc new file mode 100644 index 000000000000..92f579e974f3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc @@ -0,0 +1,12 @@ +[[webflux-uri-building]] += URI Links + +[.small]#<<web.adoc#mvc-uri-building, See equivalent in the Servlet stack>># + +This section describes various options available in the Spring Framework to prepare URIs. + +include:../:web-uris.adoc[leveloffset=+2] + +include:../:webflux-cors.adoc[leveloffset=+1] + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc index 855774b39897..0017d91c4e3f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc @@ -12,2063 +12,3 @@ of that application. Views have access to all the beans of your application cont such, it is not recommended to use Spring MVC's template support in applications where the templates are editable by external sources, since this can have security implications. -[[mvc-view-thymeleaf]] -== Thymeleaf -[.small]#<<web-reactive.adoc#webflux-view-thymeleaf, See equivalent in the Reactive stack>># - -Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML -templates that can be previewed in a browser by double-clicking, which is very helpful -for independent work on UI templates (for example, by a designer) without the need for -a running server. If you want to replace JSPs, Thymeleaf offers one of the most -extensive sets of features to make such a transition easier. Thymeleaf is actively -developed and maintained. For a more complete introduction, see the -https://www.thymeleaf.org/[Thymeleaf] project home page. - -The Thymeleaf integration with Spring MVC is managed by the Thymeleaf project. -The configuration involves a few bean declarations, such as -`ServletContextTemplateResolver`, `SpringTemplateEngine`, and `ThymeleafViewResolver`. -See https://www.thymeleaf.org/documentation.html[Thymeleaf+Spring] for more details. - - - - -[[mvc-view-freemarker]] -== FreeMarker -[.small]#<<web-reactive.adoc#webflux-view-freemarker, See equivalent in the Reactive stack>># - -https://freemarker.apache.org/[Apache FreeMarker] is a template engine for generating any -kind of text output from HTML to email and others. The Spring Framework has built-in -integration for using Spring MVC with FreeMarker templates. - - - -[[mvc-view-freemarker-contextconfig]] -=== View Configuration -[.small]#<<web-reactive.adoc#webflux-view-freemarker-contextconfig, See equivalent in the Reactive stack>># - -The following example shows how to configure FreeMarker as a view technology: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - registry.freeMarker(); - } - - // Configure FreeMarker... - - @Bean - public FreeMarkerConfigurer freeMarkerConfigurer() { - FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); - configurer.setTemplateLoaderPath("/WEB-INF/freemarker"); - return configurer; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - registry.freeMarker() - } - - // Configure FreeMarker... - - @Bean - fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply { - setTemplateLoaderPath("/WEB-INF/freemarker") - } - } ----- - -The following example shows how to configure the same in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <mvc:annotation-driven/> - - <mvc:view-resolvers> - <mvc:freemarker/> - </mvc:view-resolvers> - - <!-- Configure FreeMarker... --> - <mvc:freemarker-configurer> - <mvc:template-loader-path location="/WEB-INF/freemarker"/> - </mvc:freemarker-configurer> ----- - -Alternatively, you can also declare the `FreeMarkerConfigurer` bean for full control over all -properties, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer"> - <property name="templateLoaderPath" value="/WEB-INF/freemarker/"/> - </bean> ----- - -Your templates need to be stored in the directory specified by the `FreeMarkerConfigurer` -shown in the preceding example. Given the preceding configuration, if your controller -returns a view name of `welcome`, the resolver looks for the -`/WEB-INF/freemarker/welcome.ftl` template. - - - -[[mvc-views-freemarker]] -=== FreeMarker Configuration -[.small]#<<web-reactive.adoc#webflux-views-freemarker, See equivalent in the Reactive stack>># - -You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker -`Configuration` object (which is managed by Spring) by setting the appropriate bean -properties on the `FreeMarkerConfigurer` bean. The `freemarkerSettings` property requires -a `java.util.Properties` object, and the `freemarkerVariables` property requires a -`java.util.Map`. The following example shows how to use a `FreeMarkerConfigurer`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer"> - <property name="templateLoaderPath" value="/WEB-INF/freemarker/"/> - <property name="freemarkerVariables"> - <map> - <entry key="xml_escape" value-ref="fmXmlEscape"/> - </map> - </property> - </bean> - - <bean id="fmXmlEscape" class="freemarker.template.utility.XmlEscape"/> ----- - -See the FreeMarker documentation for details of settings and variables as they apply to -the `Configuration` object. - - - -[[mvc-view-freemarker-forms]] -=== Form Handling - -Spring provides a tag library for use in JSPs that contains, among others, a -`<spring:bind/>` element. This element primarily lets forms display values from -form-backing objects and show the results of failed validations from a `Validator` in the -web or business tier. Spring also has support for the same functionality in FreeMarker, -with additional convenience macros for generating form input elements themselves. - - -[[mvc-view-bind-macros]] -==== The Bind Macros -[.small]#<<web-reactive.adoc#webflux-view-bind-macros, See equivalent in the Reactive stack>># - -A standard set of macros are maintained within the `spring-webmvc.jar` file for -FreeMarker, so they are always available to a suitably configured application. - -Some of the macros defined in the Spring templating libraries are considered internal -(private), but no such scoping exists in the macro definitions, making all macros visible -to calling code and user templates. The following sections concentrate only on the macros -you need to directly call from within your templates. If you wish to view the macro code -directly, the file is called `spring.ftl` and is in the -`org.springframework.web.servlet.view.freemarker` package. - - -[[mvc-view-simple-binding]] -==== Simple Binding - -In your HTML forms based on FreeMarker templates that act as a form view for a Spring MVC -controller, you can use code similar to the next example to bind to field values and -display error messages for each input field in similar fashion to the JSP equivalent. The -following example shows a `personForm` view: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <!-- FreeMarker macros have to be imported into a namespace. - We strongly recommend sticking to 'spring'. --> - <#import "/spring.ftl" as spring/> - <html> - ... - <form action="" method="POST"> - Name: - <@spring.bind "personForm.name"/> - <input type="text" - name="${spring.status.expression}" - value="${spring.status.value?html}"/><br /> - <#list spring.status.errorMessages as error> <b>${error}</b> <br /> </#list> - <br /> - ... - <input type="submit" value="submit"/> - </form> - ... - </html> ----- - -`<@spring.bind>` requires a 'path' argument, which consists of the name of your command -object (it is 'command', unless you changed it in your controller configuration) followed -by a period and the name of the field on the command object to which you wish to bind. You -can also use nested fields, such as `command.address.street`. The `bind` macro assumes the -default HTML escaping behavior specified by the `ServletContext` parameter -`defaultHtmlEscape` in `web.xml`. - -An alternative form of the macro called `<@spring.bindEscaped>` takes a second argument -that explicitly specifies whether HTML escaping should be used in the status error -messages or values. You can set it to `true` or `false` as required. Additional form -handling macros simplify the use of HTML escaping, and you should use these macros -wherever possible. They are explained in the next section. - - -[[mvc-views-form-macros]] -==== Input Macros - -Additional convenience macros for FreeMarker simplify both binding and form generation -(including validation error display). It is never necessary to use these macros to -generate form input fields, and you can mix and match them with simple HTML or direct -calls to the Spring bind macros that we highlighted previously. - -The following table of available macros shows the FreeMarker Template (FTL) definitions -and the parameter list that each takes: - -[[views-macros-defs-tbl]] -.Table of macro definitions -[cols="3,1"] -|=== -| macro | FTL definition - -| `message` (output a string from a resource bundle based on the code parameter) -| <@spring.message code/> - -| `messageText` (output a string from a resource bundle based on the code parameter, - falling back to the value of the default parameter) -| <@spring.messageText code, text/> - -| `url` (prefix a relative URL with the application's context root) -| <@spring.url relativeUrl/> - -| `formInput` (standard input field for gathering user input) -| <@spring.formInput path, attributes, fieldType/> - -| `formHiddenInput` (hidden input field for submitting non-user input) -| <@spring.formHiddenInput path, attributes/> - -| `formPasswordInput` (standard input field for gathering passwords. Note that no - value is ever populated in fields of this type.) -| <@spring.formPasswordInput path, attributes/> - -| `formTextarea` (large text field for gathering long, freeform text input) -| <@spring.formTextarea path, attributes/> - -| `formSingleSelect` (drop down box of options that let a single required value be - selected) -| <@spring.formSingleSelect path, options, attributes/> - -| `formMultiSelect` (a list box of options that let the user select 0 or more values) -| <@spring.formMultiSelect path, options, attributes/> - -| `formRadioButtons` (a set of radio buttons that let a single selection be made - from the available choices) -| <@spring.formRadioButtons path, options separator, attributes/> - -| `formCheckboxes` (a set of checkboxes that let 0 or more values be selected) -| <@spring.formCheckboxes path, options, separator, attributes/> - -| `formCheckbox` (a single checkbox) -| <@spring.formCheckbox path, attributes/> - -| `showErrors` (simplify display of validation errors for the bound field) -| <@spring.showErrors separator, classOrStyle/> -|=== - -NOTE: In FreeMarker templates, `formHiddenInput` and `formPasswordInput` are not actually -required, as you can use the normal `formInput` macro, specifying `hidden` or `password` -as the value for the `fieldType` parameter. - -The parameters to any of the above macros have consistent meanings: - -* `path`: The name of the field to bind to (for example, "command.name") -* `options`: A `Map` of all the available values that can be selected from in the input - field. The keys to the map represent the values that are POSTed back from the form - and bound to the command object. Map objects stored against the keys are the labels - displayed on the form to the user and may be different from the corresponding values - posted back by the form. Usually, such a map is supplied as reference data by the - controller. You can use any `Map` implementation, depending on required behavior. - For strictly sorted maps, you can use a `SortedMap` (such as a `TreeMap`) with a - suitable `Comparator` and, for arbitrary Maps that should return values in insertion - order, use a `LinkedHashMap` or a `LinkedMap` from `commons-collections`. -* `separator`: Where multiple options are available as discreet elements (radio buttons - or checkboxes), the sequence of characters used to separate each one in the list - (such as `<br>`). -* `attributes`: An additional string of arbitrary tags or text to be included within - the HTML tag itself. This string is echoed literally by the macro. For example, in a - `textarea` field, you may supply attributes (such as 'rows="5" cols="60"'), or you - could pass style information such as 'style="border:1px solid silver"'. -* `classOrStyle`: For the `showErrors` macro, the name of the CSS class that the `span` - element that wraps each error uses. If no information is supplied (or the value is - empty), the errors are wrapped in `<b></b>` tags. - -The following sections outline examples of the macros. - -[[mvc-views-form-macros-input]] -===== Input Fields - -The `formInput` macro takes the `path` parameter (`command.name`) and an additional `attributes` -parameter (which is empty in the upcoming example). The macro, along with all other form -generation macros, performs an implicit Spring bind on the path parameter. The binding -remains valid until a new bind occurs, so the `showErrors` macro does not need to pass the -path parameter again -- it operates on the field for which a binding was last created. - -The `showErrors` macro takes a separator parameter (the characters that are used to -separate multiple errors on a given field) and also accepts a second parameter -- this -time, a class name or style attribute. Note that FreeMarker can specify default -values for the attributes parameter. The following example shows how to use the `formInput` -and `showErrors` macros: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <@spring.formInput "command.name"/> - <@spring.showErrors "<br>"/> ----- - -The next example shows the output of the form fragment, generating the name field and displaying a -validation error after the form was submitted with no value in the field. Validation -occurs through Spring's Validation framework. - -The generated HTML resembles the following example: - -[source,jsp,indent=0,subs="verbatim,quotes"] ----- - Name: - <input type="text" name="name" value=""> - <br> - <b>required</b> - <br> - <br> ----- - -The `formTextarea` macro works the same way as the `formInput` macro and accepts the same -parameter list. Commonly, the second parameter (`attributes`) is used to pass style -information or `rows` and `cols` attributes for the `textarea`. - -[[mvc-views-form-macros-select]] -===== Selection Fields - -You can use four selection field macros to generate common UI value selection inputs in -your HTML forms: - -* `formSingleSelect` -* `formMultiSelect` -* `formRadioButtons` -* `formCheckboxes` - -Each of the four macros accepts a `Map` of options that contains the value for the form -field and the label that corresponds to that value. The value and the label can be the -same. - -The next example is for radio buttons in FTL. The form-backing object specifies a default -value of 'London' for this field, so no validation is necessary. When the form is -rendered, the entire list of cities to choose from is supplied as reference data in the -model under the name 'cityMap'. The following listing shows the example: - -[source,jsp,indent=0,subs="verbatim,quotes"] ----- - ... - Town: - <@spring.formRadioButtons "command.address.town", cityMap, ""/><br><br> ----- - -The preceding listing renders a line of radio buttons, one for each value in `cityMap`, and uses a -separator of `""`. No additional attributes are supplied (the last parameter to the macro is -missing). The `cityMap` uses the same `String` for each key-value pair in the map. The map's -keys are what the form actually submits as `POST` request parameters. The map values are the -labels that the user sees. In the preceding example, given a list of three well known cities -and a default value in the form backing object, the HTML resembles the following: - -[source,jsp,indent=0,subs="verbatim,quotes"] ----- - Town: - <input type="radio" name="address.town" value="London">London</input> - <input type="radio" name="address.town" value="Paris" checked="checked">Paris</input> - <input type="radio" name="address.town" value="New York">New York</input> ----- - -If your application expects to handle cities by internal codes (for example), you can create the map of -codes with suitable keys, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - protected Map<String, ?> referenceData(HttpServletRequest request) throws Exception { - Map<String, String> cityMap = new LinkedHashMap<>(); - cityMap.put("LDN", "London"); - cityMap.put("PRS", "Paris"); - cityMap.put("NYC", "New York"); - - Map<String, Object> model = new HashMap<>(); - model.put("cityMap", cityMap); - return model; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - protected fun referenceData(request: HttpServletRequest): Map<String, *> { - val cityMap = linkedMapOf( - "LDN" to "London", - "PRS" to "Paris", - "NYC" to "New York" - ) - return hashMapOf("cityMap" to cityMap) - } ----- - -The code now produces output where the radio values are the relevant codes, but the -user still sees the more user-friendly city names, as follows: - -[source,jsp,indent=0,subs="verbatim,quotes"] ----- - Town: - <input type="radio" name="address.town" value="LDN">London</input> - <input type="radio" name="address.town" value="PRS" checked="checked">Paris</input> - <input type="radio" name="address.town" value="NYC">New York</input> ----- - - -[[mvc-views-form-macros-html-escaping]] -==== HTML Escaping - -Default usage of the form macros described earlier results in HTML elements that are HTML 4.01 -compliant and that use the default value for HTML escaping defined in your `web.xml` file, as -used by Spring's bind support. To make the elements be XHTML compliant or to override -the default HTML escaping value, you can specify two variables in your template (or in -your model, where they are visible to your templates). The advantage of specifying -them in the templates is that they can be changed to different values later in the -template processing to provide different behavior for different fields in your form. - -To switch to XHTML compliance for your tags, specify a value of `true` for a -model or context variable named `xhtmlCompliant`, as the following example shows: - -[source,jsp,indent=0,subs="verbatim,quotes"] ----- - <#-- for FreeMarker --> - <#assign xhtmlCompliant = true> ----- - -After processing this directive, any elements generated by the Spring macros are now XHTML -compliant. - -In similar fashion, you can specify HTML escaping per field, as the following example shows: - -[source,jsp,indent=0,subs="verbatim,quotes"] ----- - <#-- until this point, default HTML escaping is used --> - - <#assign htmlEscape = true> - <#-- next field will use HTML escaping --> - <@spring.formInput "command.name"/> - - <#assign htmlEscape = false in spring> - <#-- all future fields will be bound with HTML escaping off --> ----- - - - - -[[mvc-view-groovymarkup]] -== Groovy Markup - -The https://groovy-lang.org/templating.html#_the_markuptemplateengine[Groovy Markup Template Engine] -is primarily aimed at generating XML-like markup (XML, XHTML, HTML5, and others), but you can -use it to generate any text-based content. The Spring Framework has a built-in -integration for using Spring MVC with Groovy Markup. - -NOTE: The Groovy Markup Template engine requires Groovy 2.3.1+. - - - -[[mvc-view-groovymarkup-configuration]] -=== Configuration - -The following example shows how to configure the Groovy Markup Template Engine: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - registry.groovy(); - } - - // Configure the Groovy Markup Template Engine... - - @Bean - public GroovyMarkupConfigurer groovyMarkupConfigurer() { - GroovyMarkupConfigurer configurer = new GroovyMarkupConfigurer(); - configurer.setResourceLoaderPath("/WEB-INF/"); - return configurer; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - registry.groovy() - } - - // Configure the Groovy Markup Template Engine... - - @Bean - fun groovyMarkupConfigurer() = GroovyMarkupConfigurer().apply { - resourceLoaderPath = "/WEB-INF/" - } - } ----- - -The following example shows how to configure the same in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <mvc:annotation-driven/> - - <mvc:view-resolvers> - <mvc:groovy/> - </mvc:view-resolvers> - - <!-- Configure the Groovy Markup Template Engine... --> - <mvc:groovy-configurer resource-loader-path="/WEB-INF/"/> ----- - - - -[[mvc-view-groovymarkup-example]] -=== Example - -Unlike traditional template engines, Groovy Markup relies on a DSL that uses a builder -syntax. The following example shows a sample template for an HTML page: - -[source,groovy,indent=0,subs="verbatim,quotes"] ----- - yieldUnescaped '<!DOCTYPE html>' - html(lang:'en') { - head { - meta('http-equiv':'"Content-Type" content="text/html; charset=utf-8"') - title('My page') - } - body { - p('This is an example of HTML contents') - } - } ----- - - - - -[[mvc-view-script]] -== Script Views -[.small]#<<web-reactive.adoc#webflux-view-script, See equivalent in the Reactive stack>># - -The Spring Framework has a built-in integration for using Spring MVC with any -templating library that can run on top of the -https://www.jcp.org/en/jsr/detail?id=223[JSR-223] Java scripting engine. We have tested the following -templating libraries on different script engines: - -[%header] -|=== -|Scripting Library |Scripting Engine -|https://handlebarsjs.com/[Handlebars] |https://openjdk.java.net/projects/nashorn/[Nashorn] -|https://mustache.github.io/[Mustache] |https://openjdk.java.net/projects/nashorn/[Nashorn] -|https://facebook.github.io/react/[React] |https://openjdk.java.net/projects/nashorn/[Nashorn] -|https://www.embeddedjs.com/[EJS] |https://openjdk.java.net/projects/nashorn/[Nashorn] -|https://www.stuartellis.name/articles/erb/[ERB] |https://www.jruby.org[JRuby] -|https://docs.python.org/2/library/string.html#template-strings[String templates] |https://www.jython.org/[Jython] -|https://github.com/sdeleuze/kotlin-script-templating[Kotlin Script templating] |https://kotlinlang.org/[Kotlin] -|=== - -TIP: The basic rule for integrating any other script engine is that it must implement the -`ScriptEngine` and `Invocable` interfaces. - - - -[[mvc-view-script-dependencies]] -=== Requirements -[.small]#<<web-reactive.adoc#webflux-view-script-dependencies, See equivalent in the Reactive stack>># - -You need to have the script engine on your classpath, the details of which vary by script engine: - -* The https://openjdk.java.net/projects/nashorn/[Nashorn] JavaScript engine is provided with -Java 8+. Using the latest update release available is highly recommended. -* https://www.jruby.org[JRuby] should be added as a dependency for Ruby support. -* https://www.jython.org[Jython] should be added as a dependency for Python support. -* `org.jetbrains.kotlin:kotlin-script-util` dependency and a `META-INF/services/javax.script.ScriptEngineFactory` - file containing a `org.jetbrains.kotlin.script.jsr223.KotlinJsr223JvmLocalScriptEngineFactory` - line should be added for Kotlin script support. See - https://github.com/sdeleuze/kotlin-script-templating[this example] for more details. - -You need to have the script templating library. One way to do that for JavaScript is -through https://www.webjars.org/[WebJars]. - - - -[[mvc-view-script-integrate]] -=== Script Templates -[.small]#<<web-reactive.adoc#webflux-view-script, See equivalent in the Reactive stack>># - -You can declare a `ScriptTemplateConfigurer` bean to specify the script engine to use, -the script files to load, what function to call to render templates, and so on. -The following example uses Mustache templates and the Nashorn JavaScript engine: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - registry.scriptTemplate(); - } - - @Bean - public ScriptTemplateConfigurer configurer() { - ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer(); - configurer.setEngineName("nashorn"); - configurer.setScripts("mustache.js"); - configurer.setRenderObject("Mustache"); - configurer.setRenderFunction("render"); - return configurer; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - registry.scriptTemplate() - } - - @Bean - fun configurer() = ScriptTemplateConfigurer().apply { - engineName = "nashorn" - setScripts("mustache.js") - renderObject = "Mustache" - renderFunction = "render" - } - } ----- - -The following example shows the same arrangement in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <mvc:annotation-driven/> - - <mvc:view-resolvers> - <mvc:script-template/> - </mvc:view-resolvers> - - <mvc:script-template-configurer engine-name="nashorn" render-object="Mustache" render-function="render"> - <mvc:script location="mustache.js"/> - </mvc:script-template-configurer> ----- - -The controller would look no different for the Java and XML configurations, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class SampleController { - - @GetMapping("/sample") - public String test(Model model) { - model.addAttribute("title", "Sample title"); - model.addAttribute("body", "Sample body"); - return "template"; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class SampleController { - - @GetMapping("/sample") - fun test(model: Model): String { - model["title"] = "Sample title" - model["body"] = "Sample body" - return "template" - } - } ----- - -The following example shows the Mustache template: - -[source,html,indent=0,subs="verbatim,quotes"] ----- - <html> - <head> - <title>{{title}} - - -

{{body}}

- - ----- - -The render function is called with the following parameters: - -* `String template`: The template content -* `Map model`: The view model -* `RenderingContext renderingContext`: The - {api-spring-framework}/web/servlet/view/script/RenderingContext.html[`RenderingContext`] - that gives access to the application context, the locale, the template loader, and the - URL (since 5.0) - -`Mustache.render()` is natively compatible with this signature, so you can call it directly. - -If your templating technology requires some customization, you can provide a script that -implements a custom render function. For example, https://handlebarsjs.com[Handlerbars] -needs to compile templates before using them and requires a -https://en.wikipedia.org/wiki/Polyfill[polyfill] to emulate some -browser facilities that are not available in the server-side script engine. - -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - registry.scriptTemplate(); - } - - @Bean - public ScriptTemplateConfigurer configurer() { - ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer(); - configurer.setEngineName("nashorn"); - configurer.setScripts("polyfill.js", "handlebars.js", "render.js"); - configurer.setRenderFunction("render"); - configurer.setSharedEngine(false); - return configurer; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - registry.scriptTemplate() - } - - @Bean - fun configurer() = ScriptTemplateConfigurer().apply { - engineName = "nashorn" - setScripts("polyfill.js", "handlebars.js", "render.js") - renderFunction = "render" - isSharedEngine = false - } - } ----- - -NOTE: Setting the `sharedEngine` property to `false` is required when using non-thread-safe -script engines with templating libraries not designed for concurrency, such as Handlebars or -React running on Nashorn. In that case, Java SE 8 update 60 is required, due to -https://bugs.openjdk.java.net/browse/JDK-8076099[this bug], but it is generally -recommended to use a recent Java SE patch release in any case. - -`polyfill.js` defines only the `window` object needed by Handlebars to run properly, as follows: - -[source,javascript,indent=0,subs="verbatim,quotes"] ----- - var window = {}; ----- - -This basic `render.js` implementation compiles the template before using it. A production-ready -implementation should also store any reused cached templates or pre-compiled templates. -You can do so on the script side (and handle any customization you need -- managing -template engine configuration, for example). The following example shows how to do so: - -[source,javascript,indent=0,subs="verbatim,quotes"] ----- - function render(template, model) { - var compiledTemplate = Handlebars.compile(template); - return compiledTemplate(model); - } ----- - -Check out the Spring Framework unit tests, -{spring-framework-main-code}/spring-webmvc/src/test/java/org/springframework/web/servlet/view/script[Java], and -{spring-framework-main-code}/spring-webmvc/src/test/resources/org/springframework/web/servlet/view/script[resources], -for more configuration examples. - - - - -[[mvc-view-jsp]] -== JSP and JSTL - -The Spring Framework has a built-in integration for using Spring MVC with JSP and JSTL. - - - -[[mvc-view-jsp-resolver]] -=== View Resolvers - -When developing with JSPs, you typically declare an `InternalResourceViewResolver` bean. - -`InternalResourceViewResolver` can be used for dispatching to any Servlet resource but in -particular for JSPs. As a best practice, we strongly encourage placing your JSP files in -a directory under the `'WEB-INF'` directory so there can be no direct access by clients. - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - ----- - - - -[[mvc-view-jsp-jstl]] -=== JSPs versus JSTL - -When using the JSP Standard Tag Library (JSTL) you must use a special view class, the -`JstlView`, as JSTL needs some preparation before things such as the I18N features can -work. - - - -[[mvc-view-jsp-tags]] -=== Spring's JSP Tag Library - -Spring provides data binding of request parameters to command objects, as described in -earlier chapters. To facilitate the development of JSP pages in combination with those -data binding features, Spring provides a few tags that make things even easier. All -Spring tags have HTML escaping features to enable or disable escaping of characters. - -The `spring.tld` tag library descriptor (TLD) is included in the `spring-webmvc.jar`. -For a comprehensive reference on individual tags, browse the -{api-spring-framework}/web/servlet/tags/package-summary.html#package.description[API reference] -or see the tag library description. - - -[[mvc-view-jsp-formtaglib]] -=== Spring's form tag library - -As of version 2.0, Spring provides a comprehensive set of data binding-aware tags for -handling form elements when using JSP and Spring Web MVC. Each tag provides support for -the set of attributes of its corresponding HTML tag counterpart, making the tags -familiar and intuitive to use. The tag-generated HTML is HTML 4.01/XHTML 1.0 compliant. - -Unlike other form/input tag libraries, Spring's form tag library is integrated with -Spring Web MVC, giving the tags access to the command object and reference data your -controller deals with. As we show in the following examples, the form tags make -JSPs easier to develop, read, and maintain. - -We go through the form tags and look at an example of how each tag is used. We have -included generated HTML snippets where certain tags require further commentary. - - -[[mvc-view-jsp-formtaglib-configuration]] -==== Configuration - -The form tag library comes bundled in `spring-webmvc.jar`. The library descriptor is -called `spring-form.tld`. - -To use the tags from this library, add the following directive to the top of your JSP -page: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %> ----- -where `form` is the tag name prefix you want to use for the tags from this library. - - -[[mvc-view-jsp-formtaglib-formtag]] -==== The Form Tag - -This tag renders an HTML 'form' element and exposes a binding path to inner tags for -binding. It puts the command object in the `PageContext` so that the command object can -be accessed by inner tags. All the other tags in this library are nested tags of the -`form` tag. - -Assume that we have a domain object called `User`. It is a JavaBean with properties -such as `firstName` and `lastName`. We can use it as the form-backing object of our -form controller, which returns `form.jsp`. The following example shows what `form.jsp` could -look like: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - -
First Name:
Last Name:
- -
- ----- - -The `firstName` and `lastName` values are retrieved from the command object placed in -the `PageContext` by the page controller. Keep reading to see more complex examples of -how inner tags are used with the `form` tag. - -The following listing shows the generated HTML, which looks like a standard form: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- -
- - - - - - - - - - - - -
First Name:
Last Name:
- -
-
----- - -The preceding JSP assumes that the variable name of the form-backing object is -`command`. If you have put the form-backing object into the model under another name -(definitely a best practice), you can bind the form to the named variable, as the -following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - -
First Name:
Last Name:
- -
- ----- - - -[[mvc-view-jsp-formtaglib-inputtag]] -==== The `input` Tag - -This tag renders an HTML `input` element with the bound value and `type='text'` by default. -For an example of this tag, see <>. You can also use -HTML5-specific types, such as `email`, `tel`, `date`, and others. - - -[[mvc-view-jsp-formtaglib-checkboxtag]] -==== The `checkbox` Tag - -This tag renders an HTML `input` tag with the `type` set to `checkbox`. - -Assume that our `User` has preferences such as newsletter subscription and a list of -hobbies. The following example shows the `Preferences` class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class Preferences { - - private boolean receiveNewsletter; - private String[] interests; - private String favouriteWord; - - public boolean isReceiveNewsletter() { - return receiveNewsletter; - } - - public void setReceiveNewsletter(boolean receiveNewsletter) { - this.receiveNewsletter = receiveNewsletter; - } - - public String[] getInterests() { - return interests; - } - - public void setInterests(String[] interests) { - this.interests = interests; - } - - public String getFavouriteWord() { - return favouriteWord; - } - - public void setFavouriteWord(String favouriteWord) { - this.favouriteWord = favouriteWord; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class Preferences( - var receiveNewsletter: Boolean, - var interests: StringArray, - var favouriteWord: String - ) ----- - -The corresponding `form.jsp` could then resemble the following: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - <%-- Approach 1: Property is of type java.lang.Boolean --%> - - - - - - <%-- Approach 2: Property is of an array or of type java.util.Collection --%> - - - - - - <%-- Approach 3: Property is of type java.lang.Object --%> - - -
Subscribe to newsletter?:
Interests: - Quidditch: - Herbology: - Defence Against the Dark Arts: -
Favourite Word: - Magic: -
- ----- - -There are three approaches to the `checkbox` tag, which should meet all your checkbox needs. - -* Approach One: When the bound value is of type `java.lang.Boolean`, the - `input(checkbox)` is marked as `checked` if the bound value is `true`. The `value` - attribute corresponds to the resolved value of the `setValue(Object)` value property. -* Approach Two: When the bound value is of type `array` or `java.util.Collection`, the - `input(checkbox)` is marked as `checked` if the configured `setValue(Object)` value is - present in the bound `Collection`. -* Approach Three: For any other bound value type, the `input(checkbox)` is marked as - `checked` if the configured `setValue(Object)` is equal to the bound value. - -Note that, regardless of the approach, the same HTML structure is generated. The following -HTML snippet defines some checkboxes: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Interests: - - Quidditch: - - Herbology: - - Defence Against the Dark Arts: - - - ----- - -You might not expect to see the additional hidden field after each checkbox. -When a checkbox in an HTML page is not checked, its value is not sent to the -server as part of the HTTP request parameters once the form is submitted, so we need a -workaround for this quirk in HTML for Spring form data binding to work. The -`checkbox` tag follows the existing Spring convention of including a hidden parameter -prefixed by an underscore (`_`) for each checkbox. By doing this, you are effectively -telling Spring that "`the checkbox was visible in the form, and I want my object to -which the form data binds to reflect the state of the checkbox, no matter what.`" - - -[[mvc-view-jsp-formtaglib-checkboxestag]] -==== The `checkboxes` Tag - -This tag renders multiple HTML `input` tags with the `type` set to `checkbox`. - -This section build on the example from the previous `checkbox` tag section. Sometimes, you prefer -not to have to list all the possible hobbies in your JSP page. You would rather provide -a list at runtime of the available options and pass that in to the tag. That is the -purpose of the `checkboxes` tag. You can pass in an `Array`, a `List`, or a `Map` that contains -the available options in the `items` property. Typically, the bound property is a -collection so that it can hold multiple values selected by the user. The following example -shows a JSP that uses this tag: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - -
Interests: - <%-- Property is of an array or of type java.util.Collection --%> - -
- ----- - -This example assumes that the `interestList` is a `List` available as a model attribute -that contains strings of the values to be selected from. If you use a `Map`, -the map entry key is used as the value, and the map entry's value is used as -the label to be displayed. You can also use a custom object where you can provide the -property names for the value by using `itemValue` and the label by using `itemLabel`. - - - -[[mvc-view-jsp-formtaglib-radiobuttontag]] -==== The `radiobutton` Tag - -This tag renders an HTML `input` element with the `type` set to `radio`. - -A typical usage pattern involves multiple tag instances bound to the same property -but with different values, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Sex: - - Male:
- Female: - - ----- - - -[[mvc-view-jsp-formtaglib-radiobuttonstag]] -==== The `radiobuttons` Tag - -This tag renders multiple HTML `input` elements with the `type` set to `radio`. - -As with the <>, you might want to -pass in the available options as a runtime variable. For this usage, you can use the -`radiobuttons` tag. You pass in an `Array`, a `List`, or a `Map` that contains the -available options in the `items` property. If you use a `Map`, the map entry key is -used as the value and the map entry's value are used as the label to be displayed. -You can also use a custom object where you can provide the property names for the value -by using `itemValue` and the label by using `itemLabel`, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Sex: - - ----- - - -[[mvc-view-jsp-formtaglib-passwordtag]] -==== The `password` Tag - -This tag renders an HTML `input` tag with the type set to `password` with the bound value. - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Password: - - - - ----- - -Note that, by default, the password value is not shown. If you do want the -password value to be shown, you can set the value of the `showPassword` attribute to -`true`, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Password: - - - - ----- - - -[[mvc-view-jsp-formtaglib-selecttag]] -==== The `select` Tag - -This tag renders an HTML 'select' element. It supports data binding to the selected -option as well as the use of nested `option` and `options` tags. - -Assume that a `User` has a list of skills. The corresponding HTML could be as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Skills: - - ----- - -If the `User's` skill are in Herbology, the HTML source of the 'Skills' row could be -as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Skills: - - - - ----- - - -[[mvc-view-jsp-formtaglib-optiontag]] -==== The `option` Tag - -This tag renders an HTML `option` element. It sets `selected`, based on the bound -value. The following HTML shows typical output for it: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - House: - - - - - - - - - ----- - -If the `User's` house was in Gryffindor, the HTML source of the 'House' row would be -as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - House: - - - - ----- -<1> Note the addition of a `selected` attribute. - - -[[mvc-view-jsp-formtaglib-optionstag]] -==== The `options` Tag - -This tag renders a list of HTML `option` elements. It sets the `selected` attribute, -based on the bound value. The following HTML shows typical output for it: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Country: - - - - - - - ----- - -If the `User` lived in the UK, the HTML source of the 'Country' row would be as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Country: - - - - ----- -<1> Note the addition of a `selected` attribute. - -As the preceding example shows, the combined usage of an `option` tag with the `options` tag -generates the same standard HTML but lets you explicitly specify a value in the -JSP that is for display only (where it belongs), such as the default string in the -example: "-- Please Select". - -The `items` attribute is typically populated with a collection or array of item objects. -`itemValue` and `itemLabel` refer to bean properties of those item objects, if -specified. Otherwise, the item objects themselves are turned into strings. Alternatively, -you can specify a `Map` of items, in which case the map keys are interpreted as option -values and the map values correspond to option labels. If `itemValue` or `itemLabel` (or both) -happen to be specified as well, the item value property applies to the map key, and -the item label property applies to the map value. - - -[[mvc-view-jsp-formtaglib-textareatag]] -==== The `textarea` Tag - -This tag renders an HTML `textarea` element. The following HTML shows typical output for it: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - Notes: - - - ----- - - -[[mvc-view-jsp-formtaglib-hiddeninputtag]] -==== The `hidden` Tag - -This tag renders an HTML `input` tag with the `type` set to `hidden` with the bound value. To submit -an unbound hidden value, use the HTML `input` tag with the `type` set to `hidden`. -The following HTML shows typical output for it: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -If we choose to submit the `house` value as a hidden one, the HTML would be as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - ----- - - -[[mvc-view-jsp-formtaglib-errorstag]] -==== The `errors` Tag - -This tag renders field errors in an HTML `span` element. It provides access to the errors -created in your controller or those that were created by any validators associated with -your controller. - -Assume that we want to display all error messages for the `firstName` and `lastName` -fields once we submit the form. We have a validator for instances of the `User` class -called `UserValidator`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class UserValidator implements Validator { - - public boolean supports(Class candidate) { - return User.class.isAssignableFrom(candidate); - } - - public void validate(Object obj, Errors errors) { - ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "required", "Field is required."); - ValidationUtils.rejectIfEmptyOrWhitespace(errors, "lastName", "required", "Field is required."); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class UserValidator : Validator { - - override fun supports(candidate: Class<*>): Boolean { - return User::class.java.isAssignableFrom(candidate) - } - - override fun validate(obj: Any, errors: Errors) { - ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "required", "Field is required.") - ValidationUtils.rejectIfEmptyOrWhitespace(errors, "lastName", "required", "Field is required.") - } - } ----- - -The `form.jsp` could be as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - <%-- Show errors for firstName field --%> - - - - - - - <%-- Show errors for lastName field --%> - - - - - -
First Name:
Last Name:
- -
- ----- - -If we submit a form with empty values in the `firstName` and `lastName` fields, -the HTML would be as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- -
- - - - - <%-- Associated errors to firstName field displayed --%> - - - - - - - <%-- Associated errors to lastName field displayed --%> - - - - - -
First Name:Field is required.
Last Name:Field is required.
- -
-
----- - -What if we want to display the entire list of errors for a given page? The next example -shows that the `errors` tag also supports some basic wildcarding functionality. - -* `path="{asterisk}"`: Displays all errors. -* `path="lastName"`: Displays all errors associated with the `lastName` field. -* If `path` is omitted, only object errors are displayed. - -The following example displays a list of errors at the top of the page, followed by -field-specific errors next to the fields: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - -
First Name:
Last Name:
- -
- ----- - -The HTML would be as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- -
- Field is required.
Field is required. - - - - - - - - - - - - - - - -
First Name:Field is required.
Last Name:Field is required.
- -
-
----- - -The `spring-form.tld` tag library descriptor (TLD) is included in the `spring-webmvc.jar`. -For a comprehensive reference on individual tags, browse the -{api-spring-framework}/web/servlet/tags/form/package-summary.html#package.description[API reference] -or see the tag library description. - - - -[[mvc-rest-method-conversion]] -==== HTTP Method Conversion - -A key principle of REST is the use of the "`Uniform Interface`". This means that all -resources (URLs) can be manipulated by using the same four HTTP methods: GET, PUT, POST, -and DELETE. For each method, the HTTP specification defines the exact semantics. For -instance, a GET should always be a safe operation, meaning that it has no side effects, -and a PUT or DELETE should be idempotent, meaning that you can repeat these operations -over and over again, but the end result should be the same. While HTTP defines these -four methods, HTML only supports two: GET and POST. Fortunately, there are two possible -workarounds: you can either use JavaScript to do your PUT or DELETE, or you can do a POST -with the "`real`" method as an additional parameter (modeled as a hidden input field in an -HTML form). Spring's `HiddenHttpMethodFilter` uses this latter trick. This -filter is a plain Servlet filter and, therefore, it can be used in combination with any -web framework (not just Spring MVC). Add this filter to your web.xml, and a POST -with a hidden `method` parameter is converted into the corresponding HTTP method -request. - -To support HTTP method conversion, the Spring MVC form tag was updated to support setting -the HTTP method. For example, the following snippet comes from the Pet Clinic sample: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - -

- ----- - -The preceding example performs an HTTP POST, with the "`real`" DELETE method hidden behind -a request parameter. It is picked up by the `HiddenHttpMethodFilter`, which is defined in -web.xml, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - httpMethodFilter - org.springframework.web.filter.HiddenHttpMethodFilter - - - - httpMethodFilter - petclinic - ----- - -The following example shows the corresponding `@Controller` method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RequestMapping(method = RequestMethod.DELETE) - public String deletePet(@PathVariable int ownerId, @PathVariable int petId) { - this.clinic.deletePet(petId); - return "redirect:/owners/" + ownerId; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RequestMapping(method = [RequestMethod.DELETE]) - fun deletePet(@PathVariable ownerId: Int, @PathVariable petId: Int): String { - clinic.deletePet(petId) - return "redirect:/owners/$ownerId" - } ----- - -[[mvc-view-jsp-formtaglib-html5]] -==== HTML5 Tags - -The Spring form tag library allows entering dynamic attributes, which means you can -enter any HTML5 specific attributes. - -The form `input` tag supports entering a type attribute other than `text`. This is -intended to allow rendering new HTML5 specific input types, such as `email`, `date`, -`range`, and others. Note that entering `type='text'` is not required, since `text` -is the default type. - - - - -[[mvc-view-feeds]] -== RSS and Atom - -Both `AbstractAtomFeedView` and `AbstractRssFeedView` inherit from the -`AbstractFeedView` base class and are used to provide Atom and RSS Feed views, respectively. They -are based on https://rometools.github.io/rome/[ROME] project and are located in the -package `org.springframework.web.servlet.view.feed`. - -`AbstractAtomFeedView` requires you to implement the `buildFeedEntries()` method and -optionally override the `buildFeedMetadata()` method (the default implementation is -empty). The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SampleContentAtomView extends AbstractAtomFeedView { - - @Override - protected void buildFeedMetadata(Map model, - Feed feed, HttpServletRequest request) { - // implementation omitted - } - - @Override - protected List buildFeedEntries(Map model, - HttpServletRequest request, HttpServletResponse response) throws Exception { - // implementation omitted - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SampleContentAtomView : AbstractAtomFeedView() { - - override fun buildFeedMetadata(model: Map, - feed: Feed, request: HttpServletRequest) { - // implementation omitted - } - - override fun buildFeedEntries(model: Map, - request: HttpServletRequest, response: HttpServletResponse): List { - // implementation omitted - } - } ----- - -Similar requirements apply for implementing `AbstractRssFeedView`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SampleContentRssView extends AbstractRssFeedView { - - @Override - protected void buildFeedMetadata(Map model, - Channel feed, HttpServletRequest request) { - // implementation omitted - } - - @Override - protected List buildFeedItems(Map model, - HttpServletRequest request, HttpServletResponse response) throws Exception { - // implementation omitted - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SampleContentRssView : AbstractRssFeedView() { - - override fun buildFeedMetadata(model: Map, - feed: Channel, request: HttpServletRequest) { - // implementation omitted - } - - override fun buildFeedItems(model: Map, - request: HttpServletRequest, response: HttpServletResponse): List { - // implementation omitted - } - } ----- - - - -The `buildFeedItems()` and `buildFeedEntries()` methods pass in the HTTP request, in case -you need to access the Locale. The HTTP response is passed in only for the setting of -cookies or other HTTP headers. The feed is automatically written to the response -object after the method returns. - -For an example of creating an Atom view, see Alef Arendsen's Spring Team Blog -https://spring.io/blog/2009/03/16/adding-an-atom-view-to-an-application-using-spring-s-rest-support[entry]. - - - - -[[mvc-view-document]] -== PDF and Excel - -Spring offers ways to return output other than HTML, including PDF and Excel spreadsheets. -This section describes how to use those features. - - - -[[mvc-view-document-intro]] -=== Introduction to Document Views - -An HTML page is not always the best way for the user to view the model output, -and Spring makes it simple to generate a PDF document or an Excel spreadsheet -dynamically from the model data. The document is the view and is streamed from the -server with the correct content type, to (hopefully) enable the client PC to run their -spreadsheet or PDF viewer application in response. - -In order to use Excel views, you need to add the Apache POI library to your classpath. -For PDF generation, you need to add (preferably) the OpenPDF library. - -NOTE: You should use the latest versions of the underlying document-generation libraries, -if possible. In particular, we strongly recommend OpenPDF (for example, OpenPDF 1.2.12) -instead of the outdated original iText 2.1.7, since OpenPDF is actively maintained and -fixes an important vulnerability for untrusted PDF content. - - - -[[mvc-view-document-pdf]] -=== PDF Views - -A simple PDF view for a word list could extend -`org.springframework.web.servlet.view.document.AbstractPdfView` and implement the -`buildPdfDocument()` method, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class PdfWordList extends AbstractPdfView { - - protected void buildPdfDocument(Map model, Document doc, PdfWriter writer, - HttpServletRequest request, HttpServletResponse response) throws Exception { - - List words = (List) model.get("wordList"); - for (String word : words) { - doc.add(new Paragraph(word)); - } - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class PdfWordList : AbstractPdfView() { - - override fun buildPdfDocument(model: Map, doc: Document, writer: PdfWriter, - request: HttpServletRequest, response: HttpServletResponse) { - - val words = model["wordList"] as List - for (word in words) { - doc.add(Paragraph(word)) - } - } - } ----- - -A controller can return such a view either from an external view definition -(referencing it by name) or as a `View` instance from the handler method. - - - -[[mvc-view-document-excel]] -=== Excel Views - -Since Spring Framework 4.2, -`org.springframework.web.servlet.view.document.AbstractXlsView` is provided as a base -class for Excel views. It is based on Apache POI, with specialized subclasses (`AbstractXlsxView` -and `AbstractXlsxStreamingView`) that supersede the outdated `AbstractExcelView` class. - -The programming model is similar to `AbstractPdfView`, with `buildExcelDocument()` -as the central template method and controllers being able to return such a view from -an external definition (by name) or as a `View` instance from the handler method. - - - - -[[mvc-view-jackson]] -== Jackson -[.small]#<># - -Spring offers support for the Jackson JSON library. - - - -[[mvc-view-json-mapping]] -=== Jackson-based JSON MVC Views -[.small]#<># - -The `MappingJackson2JsonView` uses the Jackson library's `ObjectMapper` to render the response -content as JSON. By default, the entire contents of the model map (with the exception of -framework-specific classes) are encoded as JSON. For cases where the contents of the -map need to be filtered, you can specify a specific set of model attributes to encode -by using the `modelKeys` property. You can also use the `extractValueFromSingleKeyModel` -property to have the value in single-key models extracted and serialized directly rather -than as a map of model attributes. - -You can customize JSON mapping as needed by using Jackson's provided -annotations. When you need further control, you can inject a custom `ObjectMapper` -through the `ObjectMapper` property, for cases where you need to provide custom JSON -serializers and deserializers for specific types. - - - -[[mvc-view-xml-mapping]] -=== Jackson-based XML Views -[.small]#<># - -`MappingJackson2XmlView` uses the -https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML extension's] `XmlMapper` -to render the response content as XML. If the model contains multiple entries, you should -explicitly set the object to be serialized by using the `modelKey` bean property. If the -model contains a single entry, it is serialized automatically. - -You can customized XML mapping as needed by using JAXB or Jackson's provided -annotations. When you need further control, you can inject a custom `XmlMapper` -through the `ObjectMapper` property, for cases where custom XML -you need to provide serializers and deserializers for specific types. - - - - -[[mvc-view-xml-marshalling]] -== XML Marshalling - -The `MarshallingView` uses an XML `Marshaller` (defined in the `org.springframework.oxm` -package) to render the response content as XML. You can explicitly set the object to be -marshalled by using a `MarshallingView` instance's `modelKey` bean property. Alternatively, -the view iterates over all model properties and marshals the first type that is supported -by the `Marshaller`. For more information on the functionality in the -`org.springframework.oxm` package, see <>. - - - - -[[mvc-view-xslt]] -== XSLT Views - -XSLT is a transformation language for XML and is popular as a view technology within web -applications. XSLT can be a good choice as a view technology if your application -naturally deals with XML or if your model can easily be converted to XML. The following -section shows how to produce an XML document as model data and have it transformed with -XSLT in a Spring Web MVC application. - -This example is a trivial Spring application that creates a list of words in the -`Controller` and adds them to the model map. The map is returned, along with the view -name of our XSLT view. See <> for details of Spring Web MVC's -`Controller` interface. The XSLT controller turns the list of words into a simple XML -document ready for transformation. - - - -[[mvc-view-xslt-beandefs]] -=== Beans - -Configuration is standard for a simple Spring web application: The MVC configuration -has to define an `XsltViewResolver` bean and regular MVC annotation configuration. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @EnableWebMvc - @ComponentScan - @Configuration - public class WebConfig implements WebMvcConfigurer { - - @Bean - public XsltViewResolver xsltViewResolver() { - XsltViewResolver viewResolver = new XsltViewResolver(); - viewResolver.setPrefix("/WEB-INF/xsl/"); - viewResolver.setSuffix(".xslt"); - return viewResolver; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @EnableWebMvc - @ComponentScan - @Configuration - class WebConfig : WebMvcConfigurer { - - @Bean - fun xsltViewResolver() = XsltViewResolver().apply { - setPrefix("/WEB-INF/xsl/") - setSuffix(".xslt") - } - } ----- - - -[[mvc-view-xslt-controllercode]] -=== Controller - -We also need a Controller that encapsulates our word-generation logic. - -The controller logic is encapsulated in a `@Controller` class, with the -handler method being defined as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class XsltController { - - @RequestMapping("/") - public String home(Model model) throws Exception { - Document document = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument(); - Element root = document.createElement("wordList"); - - List words = Arrays.asList("Hello", "Spring", "Framework"); - for (String word : words) { - Element wordNode = document.createElement("word"); - Text textNode = document.createTextNode(word); - wordNode.appendChild(textNode); - root.appendChild(wordNode); - } - - model.addAttribute("wordList", root); - return "home"; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.ui.set - - @Controller - class XsltController { - - @RequestMapping("/") - fun home(model: Model): String { - val document = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument() - val root = document.createElement("wordList") - - val words = listOf("Hello", "Spring", "Framework") - for (word in words) { - val wordNode = document.createElement("word") - val textNode = document.createTextNode(word) - wordNode.appendChild(textNode) - root.appendChild(wordNode) - } - - model["wordList"] = root - return "home" - } - } ----- - -So far, we have only created a DOM document and added it to the Model map. Note that you -can also load an XML file as a `Resource` and use it instead of a custom DOM document. - -There are software packages available that automatically 'domify' -an object graph, but, within Spring, you have complete flexibility to create the DOM -from your model in any way you choose. This prevents the transformation of XML playing -too great a part in the structure of your model data, which is a danger when using tools -to manage the DOMification process. - - - -[[mvc-view-xslt-transforming]] -=== Transformation - -Finally, the `XsltViewResolver` resolves the "`home`" XSLT template file and merges the -DOM document into it to generate our view. As shown in the `XsltViewResolver` -configuration, XSLT templates live in the `war` file in the `WEB-INF/xsl` directory -and end with an `xslt` file extension. - -The following example shows an XSLT transform: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - Hello! - -

My First Words

-
    - -
- - - - - -
    • -     - -     ----- - -The preceding transform is rendered as the following HTML: - -[source,html,indent=0,subs="verbatim,quotes"] ----- - - - - Hello! - - -

    My First Words

    -
      -
    • Hello
      • -
    • Spring
      • -
    • Framework
      • -
    - - ----- diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-document.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-document.adoc new file mode 100644 index 000000000000..627885398d3b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-document.adoc @@ -0,0 +1,85 @@ +[[mvc-view-document]] += PDF and Excel + +Spring offers ways to return output other than HTML, including PDF and Excel spreadsheets. +This section describes how to use those features. + + + +[[mvc-view-document-intro]] +== Introduction to Document Views + +An HTML page is not always the best way for the user to view the model output, +and Spring makes it simple to generate a PDF document or an Excel spreadsheet +dynamically from the model data. The document is the view and is streamed from the +server with the correct content type, to (hopefully) enable the client PC to run their +spreadsheet or PDF viewer application in response. + +In order to use Excel views, you need to add the Apache POI library to your classpath. +For PDF generation, you need to add (preferably) the OpenPDF library. + +NOTE: You should use the latest versions of the underlying document-generation libraries, +if possible. In particular, we strongly recommend OpenPDF (for example, OpenPDF 1.2.12) +instead of the outdated original iText 2.1.7, since OpenPDF is actively maintained and +fixes an important vulnerability for untrusted PDF content. + + + +[[mvc-view-document-pdf]] +== PDF Views + +A simple PDF view for a word list could extend +`org.springframework.web.servlet.view.document.AbstractPdfView` and implement the +`buildPdfDocument()` method, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class PdfWordList extends AbstractPdfView { + + protected void buildPdfDocument(Map model, Document doc, PdfWriter writer, + HttpServletRequest request, HttpServletResponse response) throws Exception { + + List words = (List) model.get("wordList"); + for (String word : words) { + doc.add(new Paragraph(word)); + } + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class PdfWordList : AbstractPdfView() { + + override fun buildPdfDocument(model: Map, doc: Document, writer: PdfWriter, + request: HttpServletRequest, response: HttpServletResponse) { + + val words = model["wordList"] as List + for (word in words) { + doc.add(Paragraph(word)) + } + } + } +---- + +A controller can return such a view either from an external view definition +(referencing it by name) or as a `View` instance from the handler method. + + + +[[mvc-view-document-excel]] +== Excel Views + +Since Spring Framework 4.2, +`org.springframework.web.servlet.view.document.AbstractXlsView` is provided as a base +class for Excel views. It is based on Apache POI, with specialized subclasses (`AbstractXlsxView` +and `AbstractXlsxStreamingView`) that supersede the outdated `AbstractExcelView` class. + +The programming model is similar to `AbstractPdfView`, with `buildExcelDocument()` +as the central template method and controllers being able to return such a view from +an external definition (by name) or as a `View` instance from the handler method. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-feeds.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-feeds.adoc new file mode 100644 index 000000000000..e9cdbfbe3b67 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-feeds.adoc @@ -0,0 +1,97 @@ +[[mvc-view-feeds]] += RSS and Atom + +Both `AbstractAtomFeedView` and `AbstractRssFeedView` inherit from the +`AbstractFeedView` base class and are used to provide Atom and RSS Feed views, respectively. They +are based on https://rometools.github.io/rome/[ROME] project and are located in the +package `org.springframework.web.servlet.view.feed`. + +`AbstractAtomFeedView` requires you to implement the `buildFeedEntries()` method and +optionally override the `buildFeedMetadata()` method (the default implementation is +empty). The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SampleContentAtomView extends AbstractAtomFeedView { + + @Override + protected void buildFeedMetadata(Map model, + Feed feed, HttpServletRequest request) { + // implementation omitted + } + + @Override + protected List buildFeedEntries(Map model, + HttpServletRequest request, HttpServletResponse response) throws Exception { + // implementation omitted + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SampleContentAtomView : AbstractAtomFeedView() { + + override fun buildFeedMetadata(model: Map, + feed: Feed, request: HttpServletRequest) { + // implementation omitted + } + + override fun buildFeedEntries(model: Map, + request: HttpServletRequest, response: HttpServletResponse): List { + // implementation omitted + } + } +---- + +Similar requirements apply for implementing `AbstractRssFeedView`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SampleContentRssView extends AbstractRssFeedView { + + @Override + protected void buildFeedMetadata(Map model, + Channel feed, HttpServletRequest request) { + // implementation omitted + } + + @Override + protected List buildFeedItems(Map model, + HttpServletRequest request, HttpServletResponse response) throws Exception { + // implementation omitted + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SampleContentRssView : AbstractRssFeedView() { + + override fun buildFeedMetadata(model: Map, + feed: Channel, request: HttpServletRequest) { + // implementation omitted + } + + override fun buildFeedItems(model: Map, + request: HttpServletRequest, response: HttpServletResponse): List { + // implementation omitted + } + } +---- + + + +The `buildFeedItems()` and `buildFeedEntries()` methods pass in the HTTP request, in case +you need to access the Locale. The HTTP response is passed in only for the setting of +cookies or other HTTP headers. The feed is automatically written to the response +object after the method returns. + +For an example of creating an Atom view, see Alef Arendsen's Spring Team Blog +https://spring.io/blog/2009/03/16/adding-an-atom-view-to-an-application-using-spring-s-rest-support[entry]. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc new file mode 100644 index 000000000000..38ffb009f4c9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc @@ -0,0 +1,445 @@ +[[mvc-view-freemarker]] += FreeMarker + +[.small]#<># + +https://freemarker.apache.org/[Apache FreeMarker] is a template engine for generating any +kind of text output from HTML to email and others. The Spring Framework has built-in +integration for using Spring MVC with FreeMarker templates. + + + +[[mvc-view-freemarker-contextconfig]] +== View Configuration +[.small]#<># + +The following example shows how to configure FreeMarker as a view technology: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + registry.freeMarker(); + } + + // Configure FreeMarker... + + @Bean + public FreeMarkerConfigurer freeMarkerConfigurer() { + FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); + configurer.setTemplateLoaderPath("/WEB-INF/freemarker"); + return configurer; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + registry.freeMarker() + } + + // Configure FreeMarker... + + @Bean + fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply { + setTemplateLoaderPath("/WEB-INF/freemarker") + } + } +---- + +The following example shows how to configure the same in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + +---- + +Alternatively, you can also declare the `FreeMarkerConfigurer` bean for full control over all +properties, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + +---- + +Your templates need to be stored in the directory specified by the `FreeMarkerConfigurer` +shown in the preceding example. Given the preceding configuration, if your controller +returns a view name of `welcome`, the resolver looks for the +`/WEB-INF/freemarker/welcome.ftl` template. + + + +[[mvc-views-freemarker]] +== FreeMarker Configuration +[.small]#<># + +You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker +`Configuration` object (which is managed by Spring) by setting the appropriate bean +properties on the `FreeMarkerConfigurer` bean. The `freemarkerSettings` property requires +a `java.util.Properties` object, and the `freemarkerVariables` property requires a +`java.util.Map`. The following example shows how to use a `FreeMarkerConfigurer`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + +---- + +See the FreeMarker documentation for details of settings and variables as they apply to +the `Configuration` object. + + + +[[mvc-view-freemarker-forms]] +== Form Handling + +Spring provides a tag library for use in JSPs that contains, among others, a +`` element. This element primarily lets forms display values from +form-backing objects and show the results of failed validations from a `Validator` in the +web or business tier. Spring also has support for the same functionality in FreeMarker, +with additional convenience macros for generating form input elements themselves. + + +[[mvc-view-bind-macros]] +=== The Bind Macros +[.small]#<># + +A standard set of macros are maintained within the `spring-webmvc.jar` file for +FreeMarker, so they are always available to a suitably configured application. + +Some of the macros defined in the Spring templating libraries are considered internal +(private), but no such scoping exists in the macro definitions, making all macros visible +to calling code and user templates. The following sections concentrate only on the macros +you need to directly call from within your templates. If you wish to view the macro code +directly, the file is called `spring.ftl` and is in the +`org.springframework.web.servlet.view.freemarker` package. + + +[[mvc-view-simple-binding]] +=== Simple Binding + +In your HTML forms based on FreeMarker templates that act as a form view for a Spring MVC +controller, you can use code similar to the next example to bind to field values and +display error messages for each input field in similar fashion to the JSP equivalent. The +following example shows a `personForm` view: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + <#import "/spring.ftl" as spring/> + + ... +
    + Name: + <@spring.bind "personForm.name"/> +
    + <#list spring.status.errorMessages as error> ${error}
    +
    + ... + +
    + ... + +---- + +`<@spring.bind>` requires a 'path' argument, which consists of the name of your command +object (it is 'command', unless you changed it in your controller configuration) followed +by a period and the name of the field on the command object to which you wish to bind. You +can also use nested fields, such as `command.address.street`. The `bind` macro assumes the +default HTML escaping behavior specified by the `ServletContext` parameter +`defaultHtmlEscape` in `web.xml`. + +An alternative form of the macro called `<@spring.bindEscaped>` takes a second argument +that explicitly specifies whether HTML escaping should be used in the status error +messages or values. You can set it to `true` or `false` as required. Additional form +handling macros simplify the use of HTML escaping, and you should use these macros +wherever possible. They are explained in the next section. + + +[[mvc-views-form-macros]] +=== Input Macros + +Additional convenience macros for FreeMarker simplify both binding and form generation +(including validation error display). It is never necessary to use these macros to +generate form input fields, and you can mix and match them with simple HTML or direct +calls to the Spring bind macros that we highlighted previously. + +The following table of available macros shows the FreeMarker Template (FTL) definitions +and the parameter list that each takes: + +[[views-macros-defs-tbl]] +.Table of macro definitions +[cols="3,1"] +|=== +| macro | FTL definition + +| `message` (output a string from a resource bundle based on the code parameter) +| <@spring.message code/> + +| `messageText` (output a string from a resource bundle based on the code parameter, + falling back to the value of the default parameter) +| <@spring.messageText code, text/> + +| `url` (prefix a relative URL with the application's context root) +| <@spring.url relativeUrl/> + +| `formInput` (standard input field for gathering user input) +| <@spring.formInput path, attributes, fieldType/> + +| `formHiddenInput` (hidden input field for submitting non-user input) +| <@spring.formHiddenInput path, attributes/> + +| `formPasswordInput` (standard input field for gathering passwords. Note that no + value is ever populated in fields of this type.) +| <@spring.formPasswordInput path, attributes/> + +| `formTextarea` (large text field for gathering long, freeform text input) +| <@spring.formTextarea path, attributes/> + +| `formSingleSelect` (drop down box of options that let a single required value be + selected) +| <@spring.formSingleSelect path, options, attributes/> + +| `formMultiSelect` (a list box of options that let the user select 0 or more values) +| <@spring.formMultiSelect path, options, attributes/> + +| `formRadioButtons` (a set of radio buttons that let a single selection be made + from the available choices) +| <@spring.formRadioButtons path, options separator, attributes/> + +| `formCheckboxes` (a set of checkboxes that let 0 or more values be selected) +| <@spring.formCheckboxes path, options, separator, attributes/> + +| `formCheckbox` (a single checkbox) +| <@spring.formCheckbox path, attributes/> + +| `showErrors` (simplify display of validation errors for the bound field) +| <@spring.showErrors separator, classOrStyle/> +|=== + +NOTE: In FreeMarker templates, `formHiddenInput` and `formPasswordInput` are not actually +required, as you can use the normal `formInput` macro, specifying `hidden` or `password` +as the value for the `fieldType` parameter. + +The parameters to any of the above macros have consistent meanings: + +* `path`: The name of the field to bind to (for example, "command.name") +* `options`: A `Map` of all the available values that can be selected from in the input + field. The keys to the map represent the values that are POSTed back from the form + and bound to the command object. Map objects stored against the keys are the labels + displayed on the form to the user and may be different from the corresponding values + posted back by the form. Usually, such a map is supplied as reference data by the + controller. You can use any `Map` implementation, depending on required behavior. + For strictly sorted maps, you can use a `SortedMap` (such as a `TreeMap`) with a + suitable `Comparator` and, for arbitrary Maps that should return values in insertion + order, use a `LinkedHashMap` or a `LinkedMap` from `commons-collections`. +* `separator`: Where multiple options are available as discreet elements (radio buttons + or checkboxes), the sequence of characters used to separate each one in the list + (such as `
    `). +* `attributes`: An additional string of arbitrary tags or text to be included within + the HTML tag itself. This string is echoed literally by the macro. For example, in a + `textarea` field, you may supply attributes (such as 'rows="5" cols="60"'), or you + could pass style information such as 'style="border:1px solid silver"'. +* `classOrStyle`: For the `showErrors` macro, the name of the CSS class that the `span` + element that wraps each error uses. If no information is supplied (or the value is + empty), the errors are wrapped in `` tags. + +The following sections outline examples of the macros. + +[[mvc-views-form-macros-input]] +==== Input Fields + +The `formInput` macro takes the `path` parameter (`command.name`) and an additional `attributes` +parameter (which is empty in the upcoming example). The macro, along with all other form +generation macros, performs an implicit Spring bind on the path parameter. The binding +remains valid until a new bind occurs, so the `showErrors` macro does not need to pass the +path parameter again -- it operates on the field for which a binding was last created. + +The `showErrors` macro takes a separator parameter (the characters that are used to +separate multiple errors on a given field) and also accepts a second parameter -- this +time, a class name or style attribute. Note that FreeMarker can specify default +values for the attributes parameter. The following example shows how to use the `formInput` +and `showErrors` macros: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <@spring.formInput "command.name"/> + <@spring.showErrors "
    "/> +---- + +The next example shows the output of the form fragment, generating the name field and displaying a +validation error after the form was submitted with no value in the field. Validation +occurs through Spring's Validation framework. + +The generated HTML resembles the following example: + +[source,jsp,indent=0,subs="verbatim,quotes"] +---- + Name: + +
    + required +
    +
    +---- + +The `formTextarea` macro works the same way as the `formInput` macro and accepts the same +parameter list. Commonly, the second parameter (`attributes`) is used to pass style +information or `rows` and `cols` attributes for the `textarea`. + +[[mvc-views-form-macros-select]] +==== Selection Fields + +You can use four selection field macros to generate common UI value selection inputs in +your HTML forms: + +* `formSingleSelect` +* `formMultiSelect` +* `formRadioButtons` +* `formCheckboxes` + +Each of the four macros accepts a `Map` of options that contains the value for the form +field and the label that corresponds to that value. The value and the label can be the +same. + +The next example is for radio buttons in FTL. The form-backing object specifies a default +value of 'London' for this field, so no validation is necessary. When the form is +rendered, the entire list of cities to choose from is supplied as reference data in the +model under the name 'cityMap'. The following listing shows the example: + +[source,jsp,indent=0,subs="verbatim,quotes"] +---- + ... + Town: + <@spring.formRadioButtons "command.address.town", cityMap, ""/>

    +---- + +The preceding listing renders a line of radio buttons, one for each value in `cityMap`, and uses a +separator of `""`. No additional attributes are supplied (the last parameter to the macro is +missing). The `cityMap` uses the same `String` for each key-value pair in the map. The map's +keys are what the form actually submits as `POST` request parameters. The map values are the +labels that the user sees. In the preceding example, given a list of three well known cities +and a default value in the form backing object, the HTML resembles the following: + +[source,jsp,indent=0,subs="verbatim,quotes"] +---- + Town: + London + Paris + New York +---- + +If your application expects to handle cities by internal codes (for example), you can create the map of +codes with suitable keys, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + protected Map referenceData(HttpServletRequest request) throws Exception { + Map cityMap = new LinkedHashMap<>(); + cityMap.put("LDN", "London"); + cityMap.put("PRS", "Paris"); + cityMap.put("NYC", "New York"); + + Map model = new HashMap<>(); + model.put("cityMap", cityMap); + return model; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + protected fun referenceData(request: HttpServletRequest): Map { + val cityMap = linkedMapOf( + "LDN" to "London", + "PRS" to "Paris", + "NYC" to "New York" + ) + return hashMapOf("cityMap" to cityMap) + } +---- + +The code now produces output where the radio values are the relevant codes, but the +user still sees the more user-friendly city names, as follows: + +[source,jsp,indent=0,subs="verbatim,quotes"] +---- + Town: + London + Paris + New York +---- + + +[[mvc-views-form-macros-html-escaping]] +=== HTML Escaping + +Default usage of the form macros described earlier results in HTML elements that are HTML 4.01 +compliant and that use the default value for HTML escaping defined in your `web.xml` file, as +used by Spring's bind support. To make the elements be XHTML compliant or to override +the default HTML escaping value, you can specify two variables in your template (or in +your model, where they are visible to your templates). The advantage of specifying +them in the templates is that they can be changed to different values later in the +template processing to provide different behavior for different fields in your form. + +To switch to XHTML compliance for your tags, specify a value of `true` for a +model or context variable named `xhtmlCompliant`, as the following example shows: + +[source,jsp,indent=0,subs="verbatim,quotes"] +---- + <#-- for FreeMarker --> + <#assign xhtmlCompliant = true> +---- + +After processing this directive, any elements generated by the Spring macros are now XHTML +compliant. + +In similar fashion, you can specify HTML escaping per field, as the following example shows: + +[source,jsp,indent=0,subs="verbatim,quotes"] +---- + <#-- until this point, default HTML escaping is used --> + + <#assign htmlEscape = true> + <#-- next field will use HTML escaping --> + <@spring.formInput "command.name"/> + + <#assign htmlEscape = false in spring> + <#-- all future fields will be bound with HTML escaping off --> +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-groovymarkup.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-groovymarkup.adoc new file mode 100644 index 000000000000..60292b26f090 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-groovymarkup.adoc @@ -0,0 +1,98 @@ +[[mvc-view-groovymarkup]] += Groovy Markup + +The https://groovy-lang.org/templating.html#_the_markuptemplateengine[Groovy Markup Template Engine] +is primarily aimed at generating XML-like markup (XML, XHTML, HTML5, and others), but you can +use it to generate any text-based content. The Spring Framework has a built-in +integration for using Spring MVC with Groovy Markup. + +NOTE: The Groovy Markup Template engine requires Groovy 2.3.1+. + + + +[[mvc-view-groovymarkup-configuration]] +== Configuration + +The following example shows how to configure the Groovy Markup Template Engine: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + registry.groovy(); + } + + // Configure the Groovy Markup Template Engine... + + @Bean + public GroovyMarkupConfigurer groovyMarkupConfigurer() { + GroovyMarkupConfigurer configurer = new GroovyMarkupConfigurer(); + configurer.setResourceLoaderPath("/WEB-INF/"); + return configurer; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + registry.groovy() + } + + // Configure the Groovy Markup Template Engine... + + @Bean + fun groovyMarkupConfigurer() = GroovyMarkupConfigurer().apply { + resourceLoaderPath = "/WEB-INF/" + } + } +---- + +The following example shows how to configure the same in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + +---- + + + +[[mvc-view-groovymarkup-example]] +== Example + +Unlike traditional template engines, Groovy Markup relies on a DSL that uses a builder +syntax. The following example shows a sample template for an HTML page: + +[source,groovy,indent=0,subs="verbatim,quotes"] +---- + yieldUnescaped '' + html(lang:'en') { + head { + meta('http-equiv':'"Content-Type" content="text/html; charset=utf-8"') + title('My page') + } + body { + p('This is an example of HTML contents') + } + } +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc new file mode 100644 index 000000000000..674fc94faec8 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc @@ -0,0 +1,46 @@ +[[mvc-view-jackson]] += Jackson + +[.small]#<># + +Spring offers support for the Jackson JSON library. + + + +[[mvc-view-json-mapping]] +== Jackson-based JSON MVC Views +[.small]#<># + +The `MappingJackson2JsonView` uses the Jackson library's `ObjectMapper` to render the response +content as JSON. By default, the entire contents of the model map (with the exception of +framework-specific classes) are encoded as JSON. For cases where the contents of the +map need to be filtered, you can specify a specific set of model attributes to encode +by using the `modelKeys` property. You can also use the `extractValueFromSingleKeyModel` +property to have the value in single-key models extracted and serialized directly rather +than as a map of model attributes. + +You can customize JSON mapping as needed by using Jackson's provided +annotations. When you need further control, you can inject a custom `ObjectMapper` +through the `ObjectMapper` property, for cases where you need to provide custom JSON +serializers and deserializers for specific types. + + + +[[mvc-view-xml-mapping]] +== Jackson-based XML Views +[.small]#<># + +`MappingJackson2XmlView` uses the +https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML extension's] `XmlMapper` +to render the response content as XML. If the model contains multiple entries, you should +explicitly set the object to be serialized by using the `modelKey` bean property. If the +model contains a single entry, it is serialized automatically. + +You can customized XML mapping as needed by using JAXB or Jackson's provided +annotations. When you need further control, you can inject a custom `XmlMapper` +through the `ObjectMapper` property, for cases where custom XML +you need to provide serializers and deserializers for specific types. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc new file mode 100644 index 000000000000..8c5ec476c086 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc @@ -0,0 +1,820 @@ +[[mvc-view-jsp]] += JSP and JSTL + +The Spring Framework has a built-in integration for using Spring MVC with JSP and JSTL. + + + +[[mvc-view-jsp-resolver]] +== View Resolvers + +When developing with JSPs, you typically declare an `InternalResourceViewResolver` bean. + +`InternalResourceViewResolver` can be used for dispatching to any Servlet resource but in +particular for JSPs. As a best practice, we strongly encourage placing your JSP files in +a directory under the `'WEB-INF'` directory so there can be no direct access by clients. + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + +---- + + + +[[mvc-view-jsp-jstl]] +== JSPs versus JSTL + +When using the JSP Standard Tag Library (JSTL) you must use a special view class, the +`JstlView`, as JSTL needs some preparation before things such as the I18N features can +work. + + + +[[mvc-view-jsp-tags]] +== Spring's JSP Tag Library + +Spring provides data binding of request parameters to command objects, as described in +earlier chapters. To facilitate the development of JSP pages in combination with those +data binding features, Spring provides a few tags that make things even easier. All +Spring tags have HTML escaping features to enable or disable escaping of characters. + +The `spring.tld` tag library descriptor (TLD) is included in the `spring-webmvc.jar`. +For a comprehensive reference on individual tags, browse the +{api-spring-framework}/web/servlet/tags/package-summary.html#package.description[API reference] +or see the tag library description. + + +[[mvc-view-jsp-formtaglib]] +== Spring's form tag library + +As of version 2.0, Spring provides a comprehensive set of data binding-aware tags for +handling form elements when using JSP and Spring Web MVC. Each tag provides support for +the set of attributes of its corresponding HTML tag counterpart, making the tags +familiar and intuitive to use. The tag-generated HTML is HTML 4.01/XHTML 1.0 compliant. + +Unlike other form/input tag libraries, Spring's form tag library is integrated with +Spring Web MVC, giving the tags access to the command object and reference data your +controller deals with. As we show in the following examples, the form tags make +JSPs easier to develop, read, and maintain. + +We go through the form tags and look at an example of how each tag is used. We have +included generated HTML snippets where certain tags require further commentary. + + +[[mvc-view-jsp-formtaglib-configuration]] +=== Configuration + +The form tag library comes bundled in `spring-webmvc.jar`. The library descriptor is +called `spring-form.tld`. + +To use the tags from this library, add the following directive to the top of your JSP +page: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %> +---- +where `form` is the tag name prefix you want to use for the tags from this library. + + +[[mvc-view-jsp-formtaglib-formtag]] +=== The Form Tag + +This tag renders an HTML 'form' element and exposes a binding path to inner tags for +binding. It puts the command object in the `PageContext` so that the command object can +be accessed by inner tags. All the other tags in this library are nested tags of the +`form` tag. + +Assume that we have a domain object called `User`. It is a JavaBean with properties +such as `firstName` and `lastName`. We can use it as the form-backing object of our +form controller, which returns `form.jsp`. The following example shows what `form.jsp` could +look like: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + +
    First Name:
    Last Name:
    + +
    +     +---- + +The `firstName` and `lastName` values are retrieved from the command object placed in +the `PageContext` by the page controller. Keep reading to see more complex examples of +how inner tags are used with the `form` tag. + +The following listing shows the generated HTML, which looks like a standard form: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- +
    + + + + + + + + + + + + +
    First Name:
    Last Name:
    + +
    +
    +---- + +The preceding JSP assumes that the variable name of the form-backing object is +`command`. If you have put the form-backing object into the model under another name +(definitely a best practice), you can bind the form to the named variable, as the +following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + +
    First Name:
    Last Name:
    + +
    +     +---- + + +[[mvc-view-jsp-formtaglib-inputtag]] +=== The `input` Tag + +This tag renders an HTML `input` element with the bound value and `type='text'` by default. +For an example of this tag, see <>. You can also use +HTML5-specific types, such as `email`, `tel`, `date`, and others. + + +[[mvc-view-jsp-formtaglib-checkboxtag]] +=== The `checkbox` Tag + +This tag renders an HTML `input` tag with the `type` set to `checkbox`. + +Assume that our `User` has preferences such as newsletter subscription and a list of +hobbies. The following example shows the `Preferences` class: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class Preferences { + + private boolean receiveNewsletter; + private String[] interests; + private String favouriteWord; + + public boolean isReceiveNewsletter() { + return receiveNewsletter; + } + + public void setReceiveNewsletter(boolean receiveNewsletter) { + this.receiveNewsletter = receiveNewsletter; + } + + public String[] getInterests() { + return interests; + } + + public void setInterests(String[] interests) { + this.interests = interests; + } + + public String getFavouriteWord() { + return favouriteWord; + } + + public void setFavouriteWord(String favouriteWord) { + this.favouriteWord = favouriteWord; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class Preferences( + var receiveNewsletter: Boolean, + var interests: StringArray, + var favouriteWord: String + ) +---- + +The corresponding `form.jsp` could then resemble the following: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + <%-- Approach 1: Property is of type java.lang.Boolean --%> + + + + + + <%-- Approach 2: Property is of an array or of type java.util.Collection --%> + + + + + + <%-- Approach 3: Property is of type java.lang.Object --%> + + +
    Subscribe to newsletter?:
    Interests: + Quidditch: + Herbology: + Defence Against the Dark Arts: +
    Favourite Word: + Magic: +
    +     +---- + +There are three approaches to the `checkbox` tag, which should meet all your checkbox needs. + +* Approach One: When the bound value is of type `java.lang.Boolean`, the + `input(checkbox)` is marked as `checked` if the bound value is `true`. The `value` + attribute corresponds to the resolved value of the `setValue(Object)` value property. +* Approach Two: When the bound value is of type `array` or `java.util.Collection`, the + `input(checkbox)` is marked as `checked` if the configured `setValue(Object)` value is + present in the bound `Collection`. +* Approach Three: For any other bound value type, the `input(checkbox)` is marked as + `checked` if the configured `setValue(Object)` is equal to the bound value. + +Note that, regardless of the approach, the same HTML structure is generated. The following +HTML snippet defines some checkboxes: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Interests: + + Quidditch: + + Herbology: + + Defence Against the Dark Arts: + + + +---- + +You might not expect to see the additional hidden field after each checkbox. +When a checkbox in an HTML page is not checked, its value is not sent to the +server as part of the HTTP request parameters once the form is submitted, so we need a +workaround for this quirk in HTML for Spring form data binding to work. The +`checkbox` tag follows the existing Spring convention of including a hidden parameter +prefixed by an underscore (`_`) for each checkbox. By doing this, you are effectively +telling Spring that "`the checkbox was visible in the form, and I want my object to +which the form data binds to reflect the state of the checkbox, no matter what.`" + + +[[mvc-view-jsp-formtaglib-checkboxestag]] +=== The `checkboxes` Tag + +This tag renders multiple HTML `input` tags with the `type` set to `checkbox`. + +This section build on the example from the previous `checkbox` tag section. Sometimes, you prefer +not to have to list all the possible hobbies in your JSP page. You would rather provide +a list at runtime of the available options and pass that in to the tag. That is the +purpose of the `checkboxes` tag. You can pass in an `Array`, a `List`, or a `Map` that contains +the available options in the `items` property. Typically, the bound property is a +collection so that it can hold multiple values selected by the user. The following example +shows a JSP that uses this tag: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +
    Interests: + <%-- Property is of an array or of type java.util.Collection --%> + +
    +     +---- + +This example assumes that the `interestList` is a `List` available as a model attribute +that contains strings of the values to be selected from. If you use a `Map`, +the map entry key is used as the value, and the map entry's value is used as +the label to be displayed. You can also use a custom object where you can provide the +property names for the value by using `itemValue` and the label by using `itemLabel`. + + + +[[mvc-view-jsp-formtaglib-radiobuttontag]] +=== The `radiobutton` Tag + +This tag renders an HTML `input` element with the `type` set to `radio`. + +A typical usage pattern involves multiple tag instances bound to the same property +but with different values, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Sex: + + Male:
    + Female: + + +---- + + +[[mvc-view-jsp-formtaglib-radiobuttonstag]] +=== The `radiobuttons` Tag + +This tag renders multiple HTML `input` elements with the `type` set to `radio`. + +As with the <>, you might want to +pass in the available options as a runtime variable. For this usage, you can use the +`radiobuttons` tag. You pass in an `Array`, a `List`, or a `Map` that contains the +available options in the `items` property. If you use a `Map`, the map entry key is +used as the value and the map entry's value are used as the label to be displayed. +You can also use a custom object where you can provide the property names for the value +by using `itemValue` and the label by using `itemLabel`, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Sex: + + +---- + + +[[mvc-view-jsp-formtaglib-passwordtag]] +=== The `password` Tag + +This tag renders an HTML `input` tag with the type set to `password` with the bound value. + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Password: + + + + +---- + +Note that, by default, the password value is not shown. If you do want the +password value to be shown, you can set the value of the `showPassword` attribute to +`true`, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Password: + + + + +---- + + +[[mvc-view-jsp-formtaglib-selecttag]] +=== The `select` Tag + +This tag renders an HTML 'select' element. It supports data binding to the selected +option as well as the use of nested `option` and `options` tags. + +Assume that a `User` has a list of skills. The corresponding HTML could be as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Skills: + + +---- + +If the `User's` skill are in Herbology, the HTML source of the 'Skills' row could be +as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Skills: + + + + +---- + + +[[mvc-view-jsp-formtaglib-optiontag]] +=== The `option` Tag + +This tag renders an HTML `option` element. It sets `selected`, based on the bound +value. The following HTML shows typical output for it: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + House: + + + + + + + + + +---- + +If the `User's` house was in Gryffindor, the HTML source of the 'House' row would be +as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + House: + + + + +---- +<1> Note the addition of a `selected` attribute. + + +[[mvc-view-jsp-formtaglib-optionstag]] +=== The `options` Tag + +This tag renders a list of HTML `option` elements. It sets the `selected` attribute, +based on the bound value. The following HTML shows typical output for it: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Country: + + + + + + + +---- + +If the `User` lived in the UK, the HTML source of the 'Country' row would be as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Country: + + + + +---- +<1> Note the addition of a `selected` attribute. + +As the preceding example shows, the combined usage of an `option` tag with the `options` tag +generates the same standard HTML but lets you explicitly specify a value in the +JSP that is for display only (where it belongs), such as the default string in the +example: "-- Please Select". + +The `items` attribute is typically populated with a collection or array of item objects. +`itemValue` and `itemLabel` refer to bean properties of those item objects, if +specified. Otherwise, the item objects themselves are turned into strings. Alternatively, +you can specify a `Map` of items, in which case the map keys are interpreted as option +values and the map values correspond to option labels. If `itemValue` or `itemLabel` (or both) +happen to be specified as well, the item value property applies to the map key, and +the item label property applies to the map value. + + +[[mvc-view-jsp-formtaglib-textareatag]] +=== The `textarea` Tag + +This tag renders an HTML `textarea` element. The following HTML shows typical output for it: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + Notes: + + + +---- + + +[[mvc-view-jsp-formtaglib-hiddeninputtag]] +=== The `hidden` Tag + +This tag renders an HTML `input` tag with the `type` set to `hidden` with the bound value. To submit +an unbound hidden value, use the HTML `input` tag with the `type` set to `hidden`. +The following HTML shows typical output for it: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +If we choose to submit the `house` value as a hidden one, the HTML would be as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + +---- + + +[[mvc-view-jsp-formtaglib-errorstag]] +=== The `errors` Tag + +This tag renders field errors in an HTML `span` element. It provides access to the errors +created in your controller or those that were created by any validators associated with +your controller. + +Assume that we want to display all error messages for the `firstName` and `lastName` +fields once we submit the form. We have a validator for instances of the `User` class +called `UserValidator`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class UserValidator implements Validator { + + public boolean supports(Class candidate) { + return User.class.isAssignableFrom(candidate); + } + + public void validate(Object obj, Errors errors) { + ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "required", "Field is required."); + ValidationUtils.rejectIfEmptyOrWhitespace(errors, "lastName", "required", "Field is required."); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class UserValidator : Validator { + + override fun supports(candidate: Class<*>): Boolean { + return User::class.java.isAssignableFrom(candidate) + } + + override fun validate(obj: Any, errors: Errors) { + ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "required", "Field is required.") + ValidationUtils.rejectIfEmptyOrWhitespace(errors, "lastName", "required", "Field is required.") + } + } +---- + +The `form.jsp` could be as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + <%-- Show errors for firstName field --%> + + + + + + + <%-- Show errors for lastName field --%> + + + + + +
    First Name:
    Last Name:
    + +
    +     +---- + +If we submit a form with empty values in the `firstName` and `lastName` fields, +the HTML would be as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- +
    + + + + + <%-- Associated errors to firstName field displayed --%> + + + + + + + <%-- Associated errors to lastName field displayed --%> + + + + + +
    First Name:Field is required.
    Last Name:Field is required.
    + +
    +
    +---- + +What if we want to display the entire list of errors for a given page? The next example +shows that the `errors` tag also supports some basic wildcarding functionality. + +* `path="{asterisk}"`: Displays all errors. +* `path="lastName"`: Displays all errors associated with the `lastName` field. +* If `path` is omitted, only object errors are displayed. + +The following example displays a list of errors at the top of the page, followed by +field-specific errors next to the fields: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + +
    First Name:
    Last Name:
    + +
    +     +---- + +The HTML would be as follows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- +
    + Field is required.
    Field is required.     + + + + + + + + + + + + + + + +
    First Name:Field is required.
    Last Name:Field is required.
    + +
    +
    +---- + +The `spring-form.tld` tag library descriptor (TLD) is included in the `spring-webmvc.jar`. +For a comprehensive reference on individual tags, browse the +{api-spring-framework}/web/servlet/tags/form/package-summary.html#package.description[API reference] +or see the tag library description. + + + +[[mvc-rest-method-conversion]] +=== HTTP Method Conversion + +A key principle of REST is the use of the "`Uniform Interface`". This means that all +resources (URLs) can be manipulated by using the same four HTTP methods: GET, PUT, POST, +and DELETE. For each method, the HTTP specification defines the exact semantics. For +instance, a GET should always be a safe operation, meaning that it has no side effects, +and a PUT or DELETE should be idempotent, meaning that you can repeat these operations +over and over again, but the end result should be the same. While HTTP defines these +four methods, HTML only supports two: GET and POST. Fortunately, there are two possible +workarounds: you can either use JavaScript to do your PUT or DELETE, or you can do a POST +with the "`real`" method as an additional parameter (modeled as a hidden input field in an +HTML form). Spring's `HiddenHttpMethodFilter` uses this latter trick. This +filter is a plain Servlet filter and, therefore, it can be used in combination with any +web framework (not just Spring MVC). Add this filter to your web.xml, and a POST +with a hidden `method` parameter is converted into the corresponding HTTP method +request. + +To support HTTP method conversion, the Spring MVC form tag was updated to support setting +the HTTP method. For example, the following snippet comes from the Pet Clinic sample: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +

    +     +---- + +The preceding example performs an HTTP POST, with the "`real`" DELETE method hidden behind +a request parameter. It is picked up by the `HiddenHttpMethodFilter`, which is defined in +web.xml, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + httpMethodFilter + org.springframework.web.filter.HiddenHttpMethodFilter + + + + httpMethodFilter + petclinic + +---- + +The following example shows the corresponding `@Controller` method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RequestMapping(method = RequestMethod.DELETE) + public String deletePet(@PathVariable int ownerId, @PathVariable int petId) { + this.clinic.deletePet(petId); + return "redirect:/owners/" + ownerId; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RequestMapping(method = [RequestMethod.DELETE]) + fun deletePet(@PathVariable ownerId: Int, @PathVariable petId: Int): String { + clinic.deletePet(petId) + return "redirect:/owners/$ownerId" + } +---- + +[[mvc-view-jsp-formtaglib-html5]] +=== HTML5 Tags + +The Spring form tag library allows entering dynamic attributes, which means you can +enter any HTML5 specific attributes. + +The form `input` tag supports entering a type attribute other than `text`. This is +intended to allow rendering new HTML5 specific input types, such as `email`, `date`, +`range`, and others. Note that entering `type='text'` is not required, since `text` +is the default type. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc new file mode 100644 index 000000000000..9d5c0e0c7236 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc @@ -0,0 +1,256 @@ +[[mvc-view-script]] += Script Views + +[.small]#<># + +The Spring Framework has a built-in integration for using Spring MVC with any +templating library that can run on top of the +https://www.jcp.org/en/jsr/detail?id=223[JSR-223] Java scripting engine. We have tested the following +templating libraries on different script engines: + +[%header] +|=== +|Scripting Library |Scripting Engine +|https://handlebarsjs.com/[Handlebars] |https://openjdk.java.net/projects/nashorn/[Nashorn] +|https://mustache.github.io/[Mustache] |https://openjdk.java.net/projects/nashorn/[Nashorn] +|https://facebook.github.io/react/[React] |https://openjdk.java.net/projects/nashorn/[Nashorn] +|https://www.embeddedjs.com/[EJS] |https://openjdk.java.net/projects/nashorn/[Nashorn] +|https://www.stuartellis.name/articles/erb/[ERB] |https://www.jruby.org[JRuby] +|https://docs.python.org/2/library/string.html#template-strings[String templates] |https://www.jython.org/[Jython] +|https://github.com/sdeleuze/kotlin-script-templating[Kotlin Script templating] |https://kotlinlang.org/[Kotlin] +|=== + +TIP: The basic rule for integrating any other script engine is that it must implement the +`ScriptEngine` and `Invocable` interfaces. + + + +[[mvc-view-script-dependencies]] +== Requirements +[.small]#<># + +You need to have the script engine on your classpath, the details of which vary by script engine: + +* The https://openjdk.java.net/projects/nashorn/[Nashorn] JavaScript engine is provided with +Java 8+. Using the latest update release available is highly recommended. +* https://www.jruby.org[JRuby] should be added as a dependency for Ruby support. +* https://www.jython.org[Jython] should be added as a dependency for Python support. +* `org.jetbrains.kotlin:kotlin-script-util` dependency and a `META-INF/services/javax.script.ScriptEngineFactory` + file containing a `org.jetbrains.kotlin.script.jsr223.KotlinJsr223JvmLocalScriptEngineFactory` + line should be added for Kotlin script support. See + https://github.com/sdeleuze/kotlin-script-templating[this example] for more details. + +You need to have the script templating library. One way to do that for JavaScript is +through https://www.webjars.org/[WebJars]. + + + +[[mvc-view-script-integrate]] +== Script Templates +[.small]#<># + +You can declare a `ScriptTemplateConfigurer` bean to specify the script engine to use, +the script files to load, what function to call to render templates, and so on. +The following example uses Mustache templates and the Nashorn JavaScript engine: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + registry.scriptTemplate(); + } + + @Bean + public ScriptTemplateConfigurer configurer() { + ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer(); + configurer.setEngineName("nashorn"); + configurer.setScripts("mustache.js"); + configurer.setRenderObject("Mustache"); + configurer.setRenderFunction("render"); + return configurer; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + registry.scriptTemplate() + } + + @Bean + fun configurer() = ScriptTemplateConfigurer().apply { + engineName = "nashorn" + setScripts("mustache.js") + renderObject = "Mustache" + renderFunction = "render" + } + } +---- + +The following example shows the same arrangement in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + +---- + +The controller would look no different for the Java and XML configurations, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class SampleController { + + @GetMapping("/sample") + public String test(Model model) { + model.addAttribute("title", "Sample title"); + model.addAttribute("body", "Sample body"); + return "template"; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class SampleController { + + @GetMapping("/sample") + fun test(model: Model): String { + model["title"] = "Sample title" + model["body"] = "Sample body" + return "template" + } + } +---- + +The following example shows the Mustache template: + +[source,html,indent=0,subs="verbatim,quotes"] +---- + + + {{title}} + + +

    {{body}}

    + + +---- + +The render function is called with the following parameters: + +* `String template`: The template content +* `Map model`: The view model +* `RenderingContext renderingContext`: The + {api-spring-framework}/web/servlet/view/script/RenderingContext.html[`RenderingContext`] + that gives access to the application context, the locale, the template loader, and the + URL (since 5.0) + +`Mustache.render()` is natively compatible with this signature, so you can call it directly. + +If your templating technology requires some customization, you can provide a script that +implements a custom render function. For example, https://handlebarsjs.com[Handlerbars] +needs to compile templates before using them and requires a +https://en.wikipedia.org/wiki/Polyfill[polyfill] to emulate some +browser facilities that are not available in the server-side script engine. + +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + registry.scriptTemplate(); + } + + @Bean + public ScriptTemplateConfigurer configurer() { + ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer(); + configurer.setEngineName("nashorn"); + configurer.setScripts("polyfill.js", "handlebars.js", "render.js"); + configurer.setRenderFunction("render"); + configurer.setSharedEngine(false); + return configurer; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + registry.scriptTemplate() + } + + @Bean + fun configurer() = ScriptTemplateConfigurer().apply { + engineName = "nashorn" + setScripts("polyfill.js", "handlebars.js", "render.js") + renderFunction = "render" + isSharedEngine = false + } + } +---- + +NOTE: Setting the `sharedEngine` property to `false` is required when using non-thread-safe +script engines with templating libraries not designed for concurrency, such as Handlebars or +React running on Nashorn. In that case, Java SE 8 update 60 is required, due to +https://bugs.openjdk.java.net/browse/JDK-8076099[this bug], but it is generally +recommended to use a recent Java SE patch release in any case. + +`polyfill.js` defines only the `window` object needed by Handlebars to run properly, as follows: + +[source,javascript,indent=0,subs="verbatim,quotes"] +---- + var window = {}; +---- + +This basic `render.js` implementation compiles the template before using it. A production-ready +implementation should also store any reused cached templates or pre-compiled templates. +You can do so on the script side (and handle any customization you need -- managing +template engine configuration, for example). The following example shows how to do so: + +[source,javascript,indent=0,subs="verbatim,quotes"] +---- + function render(template, model) { + var compiledTemplate = Handlebars.compile(template); + return compiledTemplate(model); + } +---- + +Check out the Spring Framework unit tests, +{spring-framework-main-code}/spring-webmvc/src/test/java/org/springframework/web/servlet/view/script[Java], and +{spring-framework-main-code}/spring-webmvc/src/test/resources/org/springframework/web/servlet/view/script[resources], +for more configuration examples. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc new file mode 100644 index 000000000000..e6ea3d7894d4 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc @@ -0,0 +1,21 @@ +[[mvc-view-thymeleaf]] += Thymeleaf + +[.small]#<># + +Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML +templates that can be previewed in a browser by double-clicking, which is very helpful +for independent work on UI templates (for example, by a designer) without the need for +a running server. If you want to replace JSPs, Thymeleaf offers one of the most +extensive sets of features to make such a transition easier. Thymeleaf is actively +developed and maintained. For a more complete introduction, see the +https://www.thymeleaf.org/[Thymeleaf] project home page. + +The Thymeleaf integration with Spring MVC is managed by the Thymeleaf project. +The configuration involves a few bean declarations, such as +`ServletContextTemplateResolver`, `SpringTemplateEngine`, and `ThymeleafViewResolver`. +See https://www.thymeleaf.org/documentation.html[Thymeleaf+Spring] for more details. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc new file mode 100644 index 000000000000..374172dfdc04 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc @@ -0,0 +1,13 @@ +[[mvc-view-xml-marshalling]] += XML Marshalling + +The `MarshallingView` uses an XML `Marshaller` (defined in the `org.springframework.oxm` +package) to render the response content as XML. You can explicitly set the object to be +marshalled by using a `MarshallingView` instance's `modelKey` bean property. Alternatively, +the view iterates over all model properties and marshals the first type that is supported +by the `Marshaller`. For more information on the functionality in the +`org.springframework.oxm` package, see <>. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc new file mode 100644 index 000000000000..8586a50bbb6d --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc @@ -0,0 +1,183 @@ +[[mvc-view-xslt]] += XSLT Views + +XSLT is a transformation language for XML and is popular as a view technology within web +applications. XSLT can be a good choice as a view technology if your application +naturally deals with XML or if your model can easily be converted to XML. The following +section shows how to produce an XML document as model data and have it transformed with +XSLT in a Spring Web MVC application. + +This example is a trivial Spring application that creates a list of words in the +`Controller` and adds them to the model map. The map is returned, along with the view +name of our XSLT view. See <> for details of Spring Web MVC's +`Controller` interface. The XSLT controller turns the list of words into a simple XML +document ready for transformation. + + + +[[mvc-view-xslt-beandefs]] +== Beans + +Configuration is standard for a simple Spring web application: The MVC configuration +has to define an `XsltViewResolver` bean and regular MVC annotation configuration. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @EnableWebMvc + @ComponentScan + @Configuration + public class WebConfig implements WebMvcConfigurer { + + @Bean + public XsltViewResolver xsltViewResolver() { + XsltViewResolver viewResolver = new XsltViewResolver(); + viewResolver.setPrefix("/WEB-INF/xsl/"); + viewResolver.setSuffix(".xslt"); + return viewResolver; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @EnableWebMvc + @ComponentScan + @Configuration + class WebConfig : WebMvcConfigurer { + + @Bean + fun xsltViewResolver() = XsltViewResolver().apply { + setPrefix("/WEB-INF/xsl/") + setSuffix(".xslt") + } + } +---- + + +[[mvc-view-xslt-controllercode]] +== Controller + +We also need a Controller that encapsulates our word-generation logic. + +The controller logic is encapsulated in a `@Controller` class, with the +handler method being defined as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class XsltController { + + @RequestMapping("/") + public String home(Model model) throws Exception { + Document document = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument(); + Element root = document.createElement("wordList"); + + List words = Arrays.asList("Hello", "Spring", "Framework"); + for (String word : words) { + Element wordNode = document.createElement("word"); + Text textNode = document.createTextNode(word); + wordNode.appendChild(textNode); + root.appendChild(wordNode); + } + + model.addAttribute("wordList", root); + return "home"; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.ui.set + + @Controller + class XsltController { + + @RequestMapping("/") + fun home(model: Model): String { + val document = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument() + val root = document.createElement("wordList") + + val words = listOf("Hello", "Spring", "Framework") + for (word in words) { + val wordNode = document.createElement("word") + val textNode = document.createTextNode(word) + wordNode.appendChild(textNode) + root.appendChild(wordNode) + } + + model["wordList"] = root + return "home" + } + } +---- + +So far, we have only created a DOM document and added it to the Model map. Note that you +can also load an XML file as a `Resource` and use it instead of a custom DOM document. + +There are software packages available that automatically 'domify' +an object graph, but, within Spring, you have complete flexibility to create the DOM +from your model in any way you choose. This prevents the transformation of XML playing +too great a part in the structure of your model data, which is a danger when using tools +to manage the DOMification process. + + + +[[mvc-view-xslt-transforming]] +== Transformation + +Finally, the `XsltViewResolver` resolves the "`home`" XSLT template file and merges the +DOM document into it to generate our view. As shown in the `XsltViewResolver` +configuration, XSLT templates live in the `war` file in the `WEB-INF/xsl` directory +and end with an `xslt` file extension. + +The following example shows an XSLT transform: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + Hello! + +

    My First Words

    +
      + +
    + + +     + + +
    • +     + +     +---- + +The preceding transform is rendered as the following HTML: + +[source,html,indent=0,subs="verbatim,quotes"] +---- + + + + Hello! + + +

    My First Words

    +
      +
    • Hello
      • +
    • Spring
      • +
    • Framework
      • +
    + + +---- diff --git a/framework-docs/modules/ROOT/pages/web/webmvc.adoc b/framework-docs/modules/ROOT/pages/web/webmvc.adoc index 6df553ffb973..8c6fa01c2f33 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc.adoc @@ -22,6324 +22,3 @@ https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Versio -[[mvc-servlet]] -== DispatcherServlet -[.small]#<># - -Spring MVC, as many other web frameworks, is designed around the front controller -pattern where a central `Servlet`, the `DispatcherServlet`, provides a shared algorithm -for request processing, while actual work is performed by configurable delegate components. -This model is flexible and supports diverse workflows. - -The `DispatcherServlet`, as any `Servlet`, needs to be declared and mapped according -to the Servlet specification by using Java configuration or in `web.xml`. -In turn, the `DispatcherServlet` uses Spring configuration to discover -the delegate components it needs for request mapping, view resolution, exception -handling, <>. - -The following example of the Java configuration registers and initializes -the `DispatcherServlet`, which is auto-detected by the Servlet container -(see <>): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MyWebApplicationInitializer implements WebApplicationInitializer { - - @Override - public void onStartup(ServletContext servletContext) { - - // Load Spring web application configuration - AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext(); - context.register(AppConfig.class); - - // Create and register the DispatcherServlet - DispatcherServlet servlet = new DispatcherServlet(context); - ServletRegistration.Dynamic registration = servletContext.addServlet("app", servlet); - registration.setLoadOnStartup(1); - registration.addMapping("/app/*"); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyWebApplicationInitializer : WebApplicationInitializer { - - override fun onStartup(servletContext: ServletContext) { - - // Load Spring web application configuration - val context = AnnotationConfigWebApplicationContext() - context.register(AppConfig::class.java) - - // Create and register the DispatcherServlet - val servlet = DispatcherServlet(context) - val registration = servletContext.addServlet("app", servlet) - registration.setLoadOnStartup(1) - registration.addMapping("/app/*") - } - } ----- - -NOTE: In addition to using the ServletContext API directly, you can also extend -`AbstractAnnotationConfigDispatcherServletInitializer` and override specific methods -(see the example under <>). - -NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an -alternative to `AnnotationConfigWebApplicationContext`. See the -{api-spring-framework}/web/context/support/GenericWebApplicationContext.html[`GenericWebApplicationContext`] -javadoc for details. - -The following example of `web.xml` configuration registers and initializes the `DispatcherServlet`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - org.springframework.web.context.ContextLoaderListener - - - - contextConfigLocation - /WEB-INF/app-context.xml - - - - app - org.springframework.web.servlet.DispatcherServlet - - contextConfigLocation - - - 1 - - - - app - /app/* - - - ----- - -NOTE: Spring Boot follows a different initialization sequence. Rather than hooking into -the lifecycle of the Servlet container, Spring Boot uses Spring configuration to -bootstrap itself and the embedded Servlet container. `Filter` and `Servlet` declarations -are detected in Spring configuration and registered with the Servlet container. -For more details, see the -https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-embedded-container[Spring Boot documentation]. - - - -[[mvc-servlet-context-hierarchy]] -=== Context Hierarchy - -`DispatcherServlet` expects a `WebApplicationContext` (an extension of a plain -`ApplicationContext`) for its own configuration. `WebApplicationContext` has a link to the -`ServletContext` and the `Servlet` with which it is associated. It is also bound to the `ServletContext` -such that applications can use static methods on `RequestContextUtils` to look up the -`WebApplicationContext` if they need access to it. - -For many applications, having a single `WebApplicationContext` is simple and suffices. -It is also possible to have a context hierarchy where one root `WebApplicationContext` -is shared across multiple `DispatcherServlet` (or other `Servlet`) instances, each with -its own child `WebApplicationContext` configuration. -See <> -for more on the context hierarchy feature. - -The root `WebApplicationContext` typically contains infrastructure beans, such as data repositories and -business services that need to be shared across multiple `Servlet` instances. Those beans -are effectively inherited and can be overridden (that is, re-declared) in the Servlet-specific -child `WebApplicationContext`, which typically contains beans local to the given `Servlet`. -The following image shows this relationship: - -image::mvc-context-hierarchy.png[] - -The following example configures a `WebApplicationContext` hierarchy: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { - - @Override - protected Class[] getRootConfigClasses() { - return new Class[] { RootConfig.class }; - } - - @Override - protected Class[] getServletConfigClasses() { - return new Class[] { App1Config.class }; - } - - @Override - protected String[] getServletMappings() { - return new String[] { "/app1/*" }; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { - - override fun getRootConfigClasses(): Array> { - return arrayOf(RootConfig::class.java) - } - - override fun getServletConfigClasses(): Array> { - return arrayOf(App1Config::class.java) - } - - override fun getServletMappings(): Array { - return arrayOf("/app1/*") - } - } ----- - -TIP: If an application context hierarchy is not required, applications can return all -configuration through `getRootConfigClasses()` and `null` from `getServletConfigClasses()`. - -The following example shows the `web.xml` equivalent: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - org.springframework.web.context.ContextLoaderListener - - - - contextConfigLocation - /WEB-INF/root-context.xml - - - - app1 - org.springframework.web.servlet.DispatcherServlet - - contextConfigLocation - /WEB-INF/app1-context.xml - - 1 - - - - app1 - /app1/* - - - ----- - -TIP: If an application context hierarchy is not required, applications may configure a -"`root`" context only and leave the `contextConfigLocation` Servlet parameter empty. - - - -[[mvc-servlet-special-bean-types]] -=== Special Bean Types -[.small]#<># - -The `DispatcherServlet` delegates to special beans to process requests and render the -appropriate responses. By "`special beans`" we mean Spring-managed `Object` instances that -implement framework contracts. Those usually come with built-in contracts, but -you can customize their properties and extend or replace them. - -The following table lists the special beans detected by the `DispatcherServlet`: - -[[mvc-webappctx-special-beans-tbl]] -[cols="1,2", options="header"] -|=== -| Bean type| Explanation - -| `HandlerMapping` -| Map a request to a handler along with a list of - <> for pre- and post-processing. - The mapping is based on some criteria, the details of which vary by `HandlerMapping` - implementation. - - The two main `HandlerMapping` implementations are `RequestMappingHandlerMapping` - (which supports `@RequestMapping` annotated methods) and `SimpleUrlHandlerMapping` - (which maintains explicit registrations of URI path patterns to handlers). - -| `HandlerAdapter` -| Help the `DispatcherServlet` to invoke a handler mapped to a request, regardless of - how the handler is actually invoked. For example, invoking an annotated controller - requires resolving annotations. The main purpose of a `HandlerAdapter` is - to shield the `DispatcherServlet` from such details. - -| <> -| Strategy to resolve exceptions, possibly mapping them to handlers, to HTML error - views, or other targets. See <>. - -| <> -| Resolve logical `String`-based view names returned from a handler to an actual `View` - with which to render to the response. See <> and <>. - -| <>, <> -| Resolve the `Locale` a client is using and possibly their time zone, in order to be able - to offer internationalized views. See <>. - -| <> -| Resolve themes your web application can use -- for example, to offer personalized layouts. - See <>. - -| <> -| Abstraction for parsing a multi-part request (for example, browser form file upload) with - the help of some multipart parsing library. See <>. - -| <> -| Store and retrieve the "`input`" and the "`output`" `FlashMap` that can be used to pass - attributes from one request to another, usually across a redirect. - See <>. -|=== - - - -[[mvc-servlet-config]] -=== Web MVC Config -[.small]#<># - -Applications can declare the infrastructure beans listed in <> -that are required to process requests. The `DispatcherServlet` checks the -`WebApplicationContext` for each special bean. If there are no matching bean types, -it falls back on the default types listed in -{spring-framework-main-code}/spring-webmvc/src/main/resources/org/springframework/web/servlet/DispatcherServlet.properties[`DispatcherServlet.properties`]. - -In most cases, the <> is the best starting point. It declares the required -beans in either Java or XML and provides a higher-level configuration callback API to -customize it. - -NOTE: Spring Boot relies on the MVC Java configuration to configure Spring MVC and -provides many extra convenient options. - - - -[[mvc-container-config]] -=== Servlet Config - -In a Servlet environment, you have the option of configuring the Servlet container -programmatically as an alternative or in combination with a `web.xml` file. -The following example registers a `DispatcherServlet`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import org.springframework.web.WebApplicationInitializer; - - public class MyWebApplicationInitializer implements WebApplicationInitializer { - - @Override - public void onStartup(ServletContext container) { - XmlWebApplicationContext appContext = new XmlWebApplicationContext(); - appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml"); - - ServletRegistration.Dynamic registration = container.addServlet("dispatcher", new DispatcherServlet(appContext)); - registration.setLoadOnStartup(1); - registration.addMapping("/"); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.web.WebApplicationInitializer - - class MyWebApplicationInitializer : WebApplicationInitializer { - - override fun onStartup(container: ServletContext) { - val appContext = XmlWebApplicationContext() - appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml") - - val registration = container.addServlet("dispatcher", DispatcherServlet(appContext)) - registration.setLoadOnStartup(1) - registration.addMapping("/") - } - } ----- - - -`WebApplicationInitializer` is an interface provided by Spring MVC that ensures your -implementation is detected and automatically used to initialize any Servlet 3 container. -An abstract base class implementation of `WebApplicationInitializer` named -`AbstractDispatcherServletInitializer` makes it even easier to register the -`DispatcherServlet` by overriding methods to specify the servlet mapping and the -location of the `DispatcherServlet` configuration. - -This is recommended for applications that use Java-based Spring configuration, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { - - @Override - protected Class[] getRootConfigClasses() { - return null; - } - - @Override - protected Class[] getServletConfigClasses() { - return new Class[] { MyWebConfig.class }; - } - - @Override - protected String[] getServletMappings() { - return new String[] { "/" }; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { - - override fun getRootConfigClasses(): Array>? { - return null - } - - override fun getServletConfigClasses(): Array>? { - return arrayOf(MyWebConfig::class.java) - } - - override fun getServletMappings(): Array { - return arrayOf("/") - } - } ----- - -If you use XML-based Spring configuration, you should extend directly from -`AbstractDispatcherServletInitializer`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MyWebAppInitializer extends AbstractDispatcherServletInitializer { - - @Override - protected WebApplicationContext createRootApplicationContext() { - return null; - } - - @Override - protected WebApplicationContext createServletApplicationContext() { - XmlWebApplicationContext cxt = new XmlWebApplicationContext(); - cxt.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml"); - return cxt; - } - - @Override - protected String[] getServletMappings() { - return new String[] { "/" }; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyWebAppInitializer : AbstractDispatcherServletInitializer() { - - override fun createRootApplicationContext(): WebApplicationContext? { - return null - } - - override fun createServletApplicationContext(): WebApplicationContext { - return XmlWebApplicationContext().apply { - setConfigLocation("/WEB-INF/spring/dispatcher-config.xml") - } - } - - override fun getServletMappings(): Array { - return arrayOf("/") - } - } ----- - -`AbstractDispatcherServletInitializer` also provides a convenient way to add `Filter` -instances and have them be automatically mapped to the `DispatcherServlet`, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class MyWebAppInitializer extends AbstractDispatcherServletInitializer { - - // ... - - @Override - protected Filter[] getServletFilters() { - return new Filter[] { - new HiddenHttpMethodFilter(), new CharacterEncodingFilter() }; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyWebAppInitializer : AbstractDispatcherServletInitializer() { - - // ... - - override fun getServletFilters(): Array { - return arrayOf(HiddenHttpMethodFilter(), CharacterEncodingFilter()) - } - } ----- - -Each filter is added with a default name based on its concrete type and automatically -mapped to the `DispatcherServlet`. - -The `isAsyncSupported` protected method of `AbstractDispatcherServletInitializer` -provides a single place to enable async support on the `DispatcherServlet` and all -filters mapped to it. By default, this flag is set to `true`. - -Finally, if you need to further customize the `DispatcherServlet` itself, you can -override the `createDispatcherServlet` method. - - - -[[mvc-servlet-sequence]] -=== Processing -[.small]#<># - -The `DispatcherServlet` processes requests as follows: - -* The `WebApplicationContext` is searched for and bound in the request as an attribute - that the controller and other elements in the process can use. It is bound by default - under the `DispatcherServlet.WEB_APPLICATION_CONTEXT_ATTRIBUTE` key. -* The locale resolver is bound to the request to let elements in the process - resolve the locale to use when processing the request (rendering the view, preparing - data, and so on). If you do not need locale resolving, you do not need the locale resolver. -* The theme resolver is bound to the request to let elements such as views determine - which theme to use. If you do not use themes, you can ignore it. -* If you specify a multipart file resolver, the request is inspected for multiparts. If - multiparts are found, the request is wrapped in a `MultipartHttpServletRequest` for - further processing by other elements in the process. See <> for further - information about multipart handling. -* An appropriate handler is searched for. If a handler is found, the execution chain - associated with the handler (preprocessors, postprocessors, and controllers) is - run to prepare a model for rendering. Alternatively, for annotated - controllers, the response can be rendered (within the `HandlerAdapter`) instead of - returning a view. -* If a model is returned, the view is rendered. If no model is returned (maybe due to - a preprocessor or postprocessor intercepting the request, perhaps for security - reasons), no view is rendered, because the request could already have been fulfilled. - -The `HandlerExceptionResolver` beans declared in the `WebApplicationContext` are used to -resolve exceptions thrown during request processing. Those exception resolvers allow -customizing the logic to address exceptions. See <> for more details. - -For HTTP caching support, handlers can use the `checkNotModified` methods of `WebRequest`, -along with further options for annotated controllers as described in -<>. - -You can customize individual `DispatcherServlet` instances by adding Servlet -initialization parameters (`init-param` elements) to the Servlet declaration in the -`web.xml` file. The following table lists the supported parameters: - -[[mvc-disp-servlet-init-params-tbl]] -.DispatcherServlet initialization parameters -|=== -| Parameter| Explanation - -| `contextClass` -| Class that implements `ConfigurableWebApplicationContext`, to be instantiated and - locally configured by this Servlet. By default, `XmlWebApplicationContext` is used. - -| `contextConfigLocation` -| String that is passed to the context instance (specified by `contextClass`) to - indicate where contexts can be found. The string consists potentially of multiple - strings (using a comma as a delimiter) to support multiple contexts. In the case of - multiple context locations with beans that are defined twice, the latest location - takes precedence. - -| `namespace` -| Namespace of the `WebApplicationContext`. Defaults to `[servlet-name]-servlet`. - -| `throwExceptionIfNoHandlerFound` -| Whether to throw a `NoHandlerFoundException` when no handler was found for a request. - The exception can then be caught with a `HandlerExceptionResolver` (for example, by using an - `@ExceptionHandler` controller method) and handled as any others. - - By default, this is set to `false`, in which case the `DispatcherServlet` sets the - response status to 404 (NOT_FOUND) without raising an exception. - - Note that, if <> is - also configured, unresolved requests are always forwarded to the default servlet - and a 404 is never raised. -|=== - - - -[[mvc-handlermapping-path]] -=== Path Matching - -The Servlet API exposes the full request path as `requestURI` and further sub-divides it -into `contextPath`, `servletPath`, and `pathInfo` whose values vary depending on how a -Servlet is mapped. From these inputs, Spring MVC needs to determine the lookup path to -use for mapping handlers, which should exclude the `contextPath` and any `servletMapping` -prefix, if applicable. - -The `servletPath` and `pathInfo` are decoded and that makes them impossible to compare -directly to the full `requestURI` in order to derive the lookupPath and that makes it -necessary to decode the `requestURI`. However this introduces its own issues because the -path may contain encoded reserved characters such as `"/"` or `";"` that can in turn -alter the structure of the path after they are decoded which can also lead to security -issues. In addition, Servlet containers may normalize the `servletPath` to varying -degrees which makes it further impossible to perform `startsWith` comparisons against -the `requestURI`. - -This is why it is best to avoid reliance on the `servletPath` which comes with the -prefix-based `servletPath` mapping type. If the `DispatcherServlet` is mapped as the -default Servlet with `"/"` or otherwise without a prefix with `"/*"` and the Servlet -container is 4.0+ then Spring MVC is able to detect the Servlet mapping type and avoid -use of the `servletPath` and `pathInfo` altogether. On a 3.1 Servlet container, -assuming the same Servlet mapping types, the equivalent can be achieved by providing -a `UrlPathHelper` with `alwaysUseFullPath=true` via <> in -the MVC config. - -Fortunately the default Servlet mapping `"/"` is a good choice. However, there is still -an issue in that the `requestURI` needs to be decoded to make it possible to compare to -controller mappings. This is again undesirable because of the potential to decode -reserved characters that alter the path structure. If such characters are not expected, -then you can reject them (like the Spring Security HTTP firewall), or you can configure -`UrlPathHelper` with `urlDecode=false` but controller mappings will need to match to the -encoded path which may not always work well. Furthermore, sometimes the -`DispatcherServlet` needs to share the URL space with another Servlet and may need to -be mapped by prefix. - -The above issues are addressed when using `PathPatternParser` and parsed patterns, as -an alternative to String path matching with `AntPathMatcher`. The `PathPatternParser` has -been available for use in Spring MVC from version 5.3, and is enabled by default from -version 6.0. Unlike `AntPathMatcher` which needs either the lookup path decoded or the -controller mapping encoded, a parsed `PathPattern` matches to a parsed representation -of the path called `RequestPath`, one path segment at a time. This allows decoding and -sanitizing path segment values individually without the risk of altering the structure -of the path. Parsed `PathPattern` also supports the use of `servletPath` prefix mapping -as long as a Servlet path mapping is used and the prefix is kept simple, i.e. it has no -encoded characters. For pattern syntax details and comparison, see -<>. - - - - -[[mvc-handlermapping-interceptor]] -=== Interception - -All `HandlerMapping` implementations support handler interceptors that are useful when -you want to apply specific functionality to certain requests -- for example, checking for -a principal. Interceptors must implement `HandlerInterceptor` from the -`org.springframework.web.servlet` package with three methods that should provide enough -flexibility to do all kinds of pre-processing and post-processing: - -* `preHandle(..)`: Before the actual handler is run -* `postHandle(..)`: After the handler is run -* `afterCompletion(..)`: After the complete request has finished - -The `preHandle(..)` method returns a boolean value. You can use this method to break or -continue the processing of the execution chain. When this method returns `true`, the -handler execution chain continues. When it returns false, the `DispatcherServlet` -assumes the interceptor itself has taken care of requests (and, for example, rendered an -appropriate view) and does not continue executing the other interceptors and the actual -handler in the execution chain. - -See <> in the section on MVC configuration for examples of how to -configure interceptors. You can also register them directly by using setters on individual -`HandlerMapping` implementations. - -`postHandle` method is less useful with `@ResponseBody` and `ResponseEntity` methods for -which the response is written and committed within the `HandlerAdapter` and before -`postHandle`. That means it is too late to make any changes to the response, such as adding -an extra header. For such scenarios, you can implement `ResponseBodyAdvice` and either -declare it as an <> bean or configure it directly on -`RequestMappingHandlerAdapter`. - - - - -[[mvc-exceptionhandlers]] -=== Exceptions -[.small]#<># - -If an exception occurs during request mapping or is thrown from a request handler (such as -a `@Controller`), the `DispatcherServlet` delegates to a chain of `HandlerExceptionResolver` -beans to resolve the exception and provide alternative handling, which is typically an -error response. - -The following table lists the available `HandlerExceptionResolver` implementations: - -[cols="1,2", options="header"] -.HandlerExceptionResolver implementations -|=== -| `HandlerExceptionResolver` | Description - -| `SimpleMappingExceptionResolver` -| A mapping between exception class names and error view names. Useful for rendering - error pages in a browser application. - -| {api-spring-framework}/web/servlet/mvc/support/DefaultHandlerExceptionResolver.html[`DefaultHandlerExceptionResolver`] -| Resolves exceptions raised by Spring MVC and maps them to HTTP status codes. - See also alternative `ResponseEntityExceptionHandler` and <>. - -| `ResponseStatusExceptionResolver` -| Resolves exceptions with the `@ResponseStatus` annotation and maps them to HTTP status - codes based on the value in the annotation. - -| `ExceptionHandlerExceptionResolver` -| Resolves exceptions by invoking an `@ExceptionHandler` method in a `@Controller` or a - `@ControllerAdvice` class. See <>. -|=== - - -[[mvc-exceptionhandlers-handling]] -==== Chain of Resolvers - -You can form an exception resolver chain by declaring multiple `HandlerExceptionResolver` -beans in your Spring configuration and setting their `order` properties as needed. -The higher the order property, the later the exception resolver is positioned. - -The contract of `HandlerExceptionResolver` specifies that it can return: - -* a `ModelAndView` that points to an error view. -* An empty `ModelAndView` if the exception was handled within the resolver. -* `null` if the exception remains unresolved, for subsequent resolvers to try, and, if the -exception remains at the end, it is allowed to bubble up to the Servlet container. - -The <> automatically declares built-in resolvers for default Spring MVC -exceptions, for `@ResponseStatus` annotated exceptions, and for support of -`@ExceptionHandler` methods. You can customize that list or replace it. - - -[[mvc-ann-customer-servlet-container-error-page]] -==== Container Error Page - -If an exception remains unresolved by any `HandlerExceptionResolver` and is, therefore, -left to propagate or if the response status is set to an error status (that is, 4xx, 5xx), -Servlet containers can render a default error page in HTML. To customize the default -error page of the container, you can declare an error page mapping in `web.xml`. -The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - /error - ----- - -Given the preceding example, when an exception bubbles up or the response has an error status, the -Servlet container makes an ERROR dispatch within the container to the configured URL -(for example, `/error`). This is then processed by the `DispatcherServlet`, possibly mapping it -to a `@Controller`, which could be implemented to return an error view name with a model -or to render a JSON response, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RestController - public class ErrorController { - - @RequestMapping(path = "/error") - public Map handle(HttpServletRequest request) { - Map map = new HashMap<>(); - map.put("status", request.getAttribute("jakarta.servlet.error.status_code")); - map.put("reason", request.getAttribute("jakarta.servlet.error.message")); - return map; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RestController - class ErrorController { - - @RequestMapping(path = ["/error"]) - fun handle(request: HttpServletRequest): Map { - val map = HashMap() - map["status"] = request.getAttribute("jakarta.servlet.error.status_code") - map["reason"] = request.getAttribute("jakarta.servlet.error.message") - return map - } - } ----- - -TIP: The Servlet API does not provide a way to create error page mappings in Java. You can, -however, use both a `WebApplicationInitializer` and a minimal `web.xml`. - - - -[[mvc-viewresolver]] -=== View Resolution -[.small]#<># - -Spring MVC defines the `ViewResolver` and `View` interfaces that let you render -models in a browser without tying you to a specific view technology. `ViewResolver` -provides a mapping between view names and actual views. `View` addresses the preparation -of data before handing over to a specific view technology. - -The following table provides more details on the `ViewResolver` hierarchy: - -[[mvc-view-resolvers-tbl]] -.ViewResolver implementations -|=== -| ViewResolver| Description - -| `AbstractCachingViewResolver` -| Subclasses of `AbstractCachingViewResolver` cache view instances that they resolve. - Caching improves performance of certain view technologies. You can turn off the - cache by setting the `cache` property to `false`. Furthermore, if you must refresh - a certain view at runtime (for example, when a FreeMarker template is modified), - you can use the `removeFromCache(String viewName, Locale loc)` method. - -| `UrlBasedViewResolver` -| Simple implementation of the `ViewResolver` interface that effects the direct - resolution of logical view names to URLs without an explicit mapping definition. - This is appropriate if your logical names match the names of your view resources - in a straightforward manner, without the need for arbitrary mappings. - -| `InternalResourceViewResolver` -| Convenient subclass of `UrlBasedViewResolver` that supports `InternalResourceView` (in - effect, Servlets and JSPs) and subclasses such as `JstlView`. You can specify the view - class for all views generated by this resolver by using `setViewClass(..)`. - See the {api-spring-framework}/web/reactive/result/view/UrlBasedViewResolver.html[`UrlBasedViewResolver`] - javadoc for details. - -| `FreeMarkerViewResolver` -| Convenient subclass of `UrlBasedViewResolver` that supports `FreeMarkerView` and - custom subclasses of them. - -| `ContentNegotiatingViewResolver` -| Implementation of the `ViewResolver` interface that resolves a view based on the - request file name or `Accept` header. See <>. - -| `BeanNameViewResolver` -| Implementation of the `ViewResolver` interface that interprets a view name as a - bean name in the current application context. This is a very flexible variant which - allows for mixing and matching different view types based on distinct view names. - Each such `View` can be defined as a bean e.g. in XML or in configuration classes. -|=== - - -[[mvc-viewresolver-handling]] -==== Handling -[.small]#<># - -You can chain view resolvers by declaring more than one resolver bean and, if necessary, by -setting the `order` property to specify ordering. Remember, the higher the order property, -the later the view resolver is positioned in the chain. - -The contract of a `ViewResolver` specifies that it can return null to indicate that the -view could not be found. However, in the case of JSPs and `InternalResourceViewResolver`, -the only way to figure out if a JSP exists is to perform a dispatch through -`RequestDispatcher`. Therefore, you must always configure an `InternalResourceViewResolver` -to be last in the overall order of view resolvers. - -Configuring view resolution is as simple as adding `ViewResolver` beans to your Spring -configuration. The <> provides a dedicated configuration API for -<> and for adding logic-less -<> which are useful for HTML template -rendering without controller logic. - - -[[mvc-redirecting-redirect-prefix]] -==== Redirecting -[.small]#<># - -The special `redirect:` prefix in a view name lets you perform a redirect. The -`UrlBasedViewResolver` (and its subclasses) recognize this as an instruction that a -redirect is needed. The rest of the view name is the redirect URL. - -The net effect is the same as if the controller had returned a `RedirectView`, but now -the controller itself can operate in terms of logical view names. A logical view -name (such as `redirect:/myapp/some/resource`) redirects relative to the current -Servlet context, while a name such as `redirect:https://myhost.com/some/arbitrary/path` -redirects to an absolute URL. - -Note that, if a controller method is annotated with the `@ResponseStatus`, the annotation -value takes precedence over the response status set by `RedirectView`. - - -[[mvc-redirecting-forward-prefix]] -==== Forwarding - -You can also use a special `forward:` prefix for view names that are -ultimately resolved by `UrlBasedViewResolver` and subclasses. This creates an -`InternalResourceView`, which does a `RequestDispatcher.forward()`. -Therefore, this prefix is not useful with `InternalResourceViewResolver` and -`InternalResourceView` (for JSPs), but it can be helpful if you use another view -technology but still want to force a forward of a resource to be handled by the -Servlet/JSP engine. Note that you may also chain multiple view resolvers, instead. - - -[[mvc-multiple-representations]] -==== Content Negotiation -[.small]#<># - -{api-spring-framework}/web/servlet/view/ContentNegotiatingViewResolver.html[`ContentNegotiatingViewResolver`] -does not resolve views itself but rather delegates -to other view resolvers and selects the view that resembles the representation requested -by the client. The representation can be determined from the `Accept` header or from a -query parameter (for example, `"/path?format=pdf"`). - -The `ContentNegotiatingViewResolver` selects an appropriate `View` to handle the request -by comparing the request media types with the media type (also known as -`Content-Type`) supported by the `View` associated with each of its `ViewResolvers`. The -first `View` in the list that has a compatible `Content-Type` returns the representation -to the client. If a compatible view cannot be supplied by the `ViewResolver` chain, -the list of views specified through the `DefaultViews` property is consulted. This -latter option is appropriate for singleton `Views` that can render an appropriate -representation of the current resource regardless of the logical view name. The `Accept` -header can include wildcards (for example `text/{asterisk}`), in which case a `View` whose -`Content-Type` is `text/xml` is a compatible match. - -See <> under <> for configuration details. - - - -[[mvc-localeresolver]] -=== Locale - -Most parts of Spring's architecture support internationalization, as the Spring web -MVC framework does. `DispatcherServlet` lets you automatically resolve messages -by using the client's locale. This is done with `LocaleResolver` objects. - -When a request comes in, the `DispatcherServlet` looks for a locale resolver and, if it -finds one, it tries to use it to set the locale. By using the `RequestContext.getLocale()` -method, you can always retrieve the locale that was resolved by the locale resolver. - -In addition to automatic locale resolution, you can also attach an interceptor to the -handler mapping (see <> for more information on handler -mapping interceptors) to change the locale under specific circumstances (for example, -based on a parameter in the request). - -Locale resolvers and interceptors are defined in the -`org.springframework.web.servlet.i18n` package and are configured in your application -context in the normal way. The following selection of locale resolvers is included in -Spring. - -* <> -* <> -* <> -* <> -* <> - - -[[mvc-timezone]] -==== Time Zone - -In addition to obtaining the client's locale, it is often useful to know its time zone. -The `LocaleContextResolver` interface offers an extension to `LocaleResolver` that lets -resolvers provide a richer `LocaleContext`, which may include time zone information. - -When available, the user's `TimeZone` can be obtained by using the -`RequestContext.getTimeZone()` method. Time zone information is automatically used -by any Date/Time `Converter` and `Formatter` objects that are registered with Spring's -`ConversionService`. - - -[[mvc-localeresolver-acceptheader]] -==== Header Resolver - -This locale resolver inspects the `accept-language` header in the request that was sent -by the client (for example, a web browser). Usually, this header field contains the locale of -the client's operating system. Note that this resolver does not support time zone -information. - - -[[mvc-localeresolver-cookie]] -==== Cookie Resolver - -This locale resolver inspects a `Cookie` that might exist on the client to see if a -`Locale` or `TimeZone` is specified. If so, it uses the specified details. By using the -properties of this locale resolver, you can specify the name of the cookie as well as the -maximum age. The following example defines a `CookieLocaleResolver`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -The following table describes the properties `CookieLocaleResolver`: - -[[mvc-cookie-locale-resolver-props-tbl]] -.CookieLocaleResolver properties -[cols="1,1,4"] -|=== -| Property | Default | Description - -| `cookieName` -| class name + LOCALE -| The name of the cookie - -| `cookieMaxAge` -| Servlet container default -| The maximum time a cookie persists on the client. If `-1` is specified, the - cookie will not be persisted. It is available only until the client shuts down - the browser. - -| `cookiePath` -| / -| Limits the visibility of the cookie to a certain part of your site. When `cookiePath` is - specified, the cookie is visible only to that path and the paths below it. -|=== - - -[[mvc-localeresolver-session]] -==== Session Resolver - -The `SessionLocaleResolver` lets you retrieve `Locale` and `TimeZone` from the -session that might be associated with the user's request. In contrast to -`CookieLocaleResolver`, this strategy stores locally chosen locale settings in the -Servlet container's `HttpSession`. As a consequence, those settings are temporary -for each session and are, therefore, lost when each session ends. - -Note that there is no direct relationship with external session management mechanisms, -such as the Spring Session project. This `SessionLocaleResolver` evaluates and -modifies the corresponding `HttpSession` attributes against the current `HttpServletRequest`. - - -[[mvc-localeresolver-interceptor]] -==== Locale Interceptor - -You can enable changing of locales by adding the `LocaleChangeInterceptor` to one of the -`HandlerMapping` definitions. It detects a parameter in the request and changes the locale -accordingly, calling the `setLocale` method on the `LocaleResolver` in the dispatcher's -application context. The next example shows that calls to all `{asterisk}.view` resources -that contain a parameter named `siteLanguage` now changes the locale. So, for example, -a request for the URL, `https://www.sf.net/home.view?siteLanguage=nl`, changes the site -language to Dutch. The following example shows how to intercept the locale: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - /**/*.view=someController - - ----- - - - -[[mvc-themeresolver]] -=== Themes - -You can apply Spring Web MVC framework themes to set the overall look-and-feel of your -application, thereby enhancing user experience. A theme is a collection of static -resources, typically style sheets and images, that affect the visual style of the -application. - -WARNING: as of 6.0 support for themes has been deprecated theme in favor of using CSS, -and without any special support on the server side. - - -[[mvc-themeresolver-defining]] -==== Defining a theme - -To use themes in your web application, you must set up an implementation of the -`org.springframework.ui.context.ThemeSource` interface. The `WebApplicationContext` -interface extends `ThemeSource` but delegates its responsibilities to a dedicated -implementation. By default, the delegate is an -`org.springframework.ui.context.support.ResourceBundleThemeSource` implementation that -loads properties files from the root of the classpath. To use a custom `ThemeSource` -implementation or to configure the base name prefix of the `ResourceBundleThemeSource`, -you can register a bean in the application context with the reserved name, `themeSource`. -The web application context automatically detects a bean with that name and uses it. - -When you use the `ResourceBundleThemeSource`, a theme is defined in a simple properties -file. The properties file lists the resources that make up the theme, as the following example shows: - -[literal,subs="verbatim,quotes"] ----- -styleSheet=/themes/cool/style.css -background=/themes/cool/img/coolBg.jpg ----- - -The keys of the properties are the names that refer to the themed elements from view -code. For a JSP, you typically do this using the `spring:theme` custom tag, which is -very similar to the `spring:message` tag. The following JSP fragment uses the theme -defined in the previous example to customize the look and feel: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - <%@ taglib prefix="spring" uri="http://www.springframework.org/tags"%> - - - - - - ... - - ----- - -By default, the `ResourceBundleThemeSource` uses an empty base name prefix. As a result, -the properties files are loaded from the root of the classpath. Thus, you would put the -`cool.properties` theme definition in a directory at the root of the classpath (for -example, in `/WEB-INF/classes`). The `ResourceBundleThemeSource` uses the standard Java -resource bundle loading mechanism, allowing for full internationalization of themes. For -example, we could have a `/WEB-INF/classes/cool_nl.properties` that references a special -background image with Dutch text on it. - - -[[mvc-themeresolver-resolving]] -==== Resolving Themes - -After you define themes, as described in the <>, -you decide which theme to use. The `DispatcherServlet` looks for a bean named `themeResolver` -to find out which `ThemeResolver` implementation to use. A theme resolver works in much the same -way as a `LocaleResolver`. It detects the theme to use for a particular request and can also -alter the request's theme. The following table describes the theme resolvers provided by Spring: - -[[mvc-theme-resolver-impls-tbl]] -.ThemeResolver implementations -[cols="1,4"] -|=== -| Class | Description - -| `FixedThemeResolver` -| Selects a fixed theme, set by using the `defaultThemeName` property. - -| `SessionThemeResolver` -| The theme is maintained in the user's HTTP session. It needs to be set only once for - each session but is not persisted between sessions. - -| `CookieThemeResolver` -| The selected theme is stored in a cookie on the client. -|=== - -Spring also provides a `ThemeChangeInterceptor` that lets theme changes on every -request with a simple request parameter. - - - -[[mvc-multipart]] -=== Multipart Resolver -[.small]#<># - -`MultipartResolver` from the `org.springframework.web.multipart` package is a strategy -for parsing multipart requests including file uploads. There is a container-based -`StandardServletMultipartResolver` implementation for Servlet multipart request parsing. -Note that the outdated `CommonsMultipartResolver` based on Apache Commons FileUpload is -not available anymore, as of Spring Framework 6.0 with its new Servlet 5.0+ baseline. - -To enable multipart handling, you need to declare a `MultipartResolver` bean in your -`DispatcherServlet` Spring configuration with a name of `multipartResolver`. -The `DispatcherServlet` detects it and applies it to the incoming request. When a POST -with a content type of `multipart/form-data` is received, the resolver parses the -content wraps the current `HttpServletRequest` as a `MultipartHttpServletRequest` to -provide access to resolved files in addition to exposing parts as request parameters. - - -[[mvc-multipart-resolver-standard]] -==== Servlet Multipart Parsing - -Servlet multipart parsing needs to be enabled through Servlet container configuration. -To do so: - -* In Java, set a `MultipartConfigElement` on the Servlet registration. -* In `web.xml`, add a `""` section to the servlet declaration. - -The following example shows how to set a `MultipartConfigElement` on the Servlet registration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class AppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { - - // ... - - @Override - protected void customizeRegistration(ServletRegistration.Dynamic registration) { - - // Optionally also set maxFileSize, maxRequestSize, fileSizeThreshold - registration.setMultipartConfig(new MultipartConfigElement("/tmp")); - } - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class AppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { - - // ... - - override fun customizeRegistration(registration: ServletRegistration.Dynamic) { - - // Optionally also set maxFileSize, maxRequestSize, fileSizeThreshold - registration.setMultipartConfig(MultipartConfigElement("/tmp")) - } - - } ----- - -Once the Servlet multipart configuration is in place, you can add a bean of type -`StandardServletMultipartResolver` with a name of `multipartResolver`. - -[NOTE] -==== -This resolver variant uses your Servlet container's multipart parser as-is, -potentially exposing the application to container implementation differences. -By default, it will try to parse any `multipart/` content type with any HTTP -method but this may not be supported across all Servlet containers. See the -{api-spring-framework}/web/multipart/support/StandardServletMultipartResolver.html[`StandardServletMultipartResolver`] -javadoc for details and configuration options. -==== - - - -[[mvc-logging]] -=== Logging -[.small]#<># - -DEBUG-level logging in Spring MVC is designed to be compact, minimal, and -human-friendly. It focuses on high-value bits of information that are useful over and -over again versus others that are useful only when debugging a specific issue. - -TRACE-level logging generally follows the same principles as DEBUG (and, for example, also -should not be a fire hose) but can be used for debugging any issue. In addition, some log -messages may show a different level of detail at TRACE versus DEBUG. - -Good logging comes from the experience of using the logs. If you spot anything that does -not meet the stated goals, please let us know. - - -[[mvc-logging-sensitive-data]] -==== Sensitive Data -[.small]#<># - -DEBUG and TRACE logging may log sensitive information. This is why request parameters and -headers are masked by default and their logging in full must be enabled explicitly -through the `enableLoggingRequestDetails` property on `DispatcherServlet`. - -The following example shows how to do so by using Java configuration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- -public class MyInitializer - extends AbstractAnnotationConfigDispatcherServletInitializer { - - @Override - protected Class[] getRootConfigClasses() { - return ... ; - } - - @Override - protected Class[] getServletConfigClasses() { - return ... ; - } - - @Override - protected String[] getServletMappings() { - return ... ; - } - - @Override - protected void customizeRegistration(ServletRegistration.Dynamic registration) { - registration.setInitParameter("enableLoggingRequestDetails", "true"); - } - -} ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { - - override fun getRootConfigClasses(): Array>? { - return ... - } - - override fun getServletConfigClasses(): Array>? { - return ... - } - - override fun getServletMappings(): Array { - return ... - } - - override fun customizeRegistration(registration: ServletRegistration.Dynamic) { - registration.setInitParameter("enableLoggingRequestDetails", "true") - } - } ----- - - - - -[[filters]] -== Filters -[.small]#<># - -The `spring-web` module provides some useful filters: - -* <> -* <> -* <> -* <> - - - -[[filters-http-put]] -=== Form Data - -Browsers can submit form data only through HTTP GET or HTTP POST but non-browser clients can also -use HTTP PUT, PATCH, and DELETE. The Servlet API requires `ServletRequest.getParameter{asterisk}()` -methods to support form field access only for HTTP POST. - -The `spring-web` module provides `FormContentFilter` to intercept HTTP PUT, PATCH, and DELETE -requests with a content type of `application/x-www-form-urlencoded`, read the form data from -the body of the request, and wrap the `ServletRequest` to make the form data -available through the `ServletRequest.getParameter{asterisk}()` family of methods. - - - -[[filters-forwarded-headers]] -=== Forwarded Headers -[.small]#<># - -As a request goes through proxies (such as load balancers) the host, port, and -scheme may change, and that makes it a challenge to create links that point to the correct -host, port, and scheme from a client perspective. - -https://tools.ietf.org/html/rfc7239[RFC 7239] defines the `Forwarded` HTTP header -that proxies can use to provide information about the original request. There are other -non-standard headers, too, including `X-Forwarded-Host`, `X-Forwarded-Port`, -`X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`. - -`ForwardedHeaderFilter` is a Servlet filter that modifies the request in order to -a) change the host, port, and scheme based on `Forwarded` headers, and b) to remove those -headers to eliminate further impact. The filter relies on wrapping the request, and -therefore it must be ordered ahead of other filters, such as `RequestContextFilter`, that -should work with the modified and not the original request. - -There are security considerations for forwarded headers since an application cannot know -if the headers were added by a proxy, as intended, or by a malicious client. This is why -a proxy at the boundary of trust should be configured to remove untrusted `Forwarded` -headers that come from the outside. You can also configure the `ForwardedHeaderFilter` -with `removeOnly=true`, in which case it removes but does not use the headers. - -In order to support <> and error dispatches this -filter should be mapped with `DispatcherType.ASYNC` and also `DispatcherType.ERROR`. -If using Spring Framework's `AbstractAnnotationConfigDispatcherServletInitializer` -(see <>) all filters are automatically registered for all dispatch -types. However if registering the filter via `web.xml` or in Spring Boot via a -`FilterRegistrationBean` be sure to include `DispatcherType.ASYNC` and -`DispatcherType.ERROR` in addition to `DispatcherType.REQUEST`. - - - -[[filters-shallow-etag]] -=== Shallow ETag - -The `ShallowEtagHeaderFilter` filter creates a "`shallow`" ETag by caching the content -written to the response and computing an MD5 hash from it. The next time a client sends, -it does the same, but it also compares the computed value against the `If-None-Match` -request header and, if the two are equal, returns a 304 (NOT_MODIFIED). - -This strategy saves network bandwidth but not CPU, as the full response must be computed -for each request. Other strategies at the controller level, described earlier, can avoid -the computation. See <>. - -This filter has a `writeWeakETag` parameter that configures the filter to write weak ETags -similar to the following: `W/"02a2d595e6ed9a0b24f027f2b63b134d6"` (as defined in -https://tools.ietf.org/html/rfc7232#section-2.3[RFC 7232 Section 2.3]). - -In order to support <> this filter must be mapped -with `DispatcherType.ASYNC` so that the filter can delay and successfully generate an -ETag to the end of the last async dispatch. If using Spring Framework's -`AbstractAnnotationConfigDispatcherServletInitializer` (see <>) -all filters are automatically registered for all dispatch types. However if registering -the filter via `web.xml` or in Spring Boot via a `FilterRegistrationBean` be sure to include -`DispatcherType.ASYNC`. - - - -[[filters-cors]] -=== CORS -[.small]#<># - -Spring MVC provides fine-grained support for CORS configuration through annotations on -controllers. However, when used with Spring Security, we advise relying on the built-in -`CorsFilter` that must be ordered ahead of Spring Security's chain of filters. - -See the sections on <> and the <> for more details. - - - - -[[mvc-controller]] -== Annotated Controllers -[.small]#<># - -Spring MVC provides an annotation-based programming model where `@Controller` and -`@RestController` components use annotations to express request mappings, request input, -exception handling, and more. Annotated controllers have flexible method signatures and -do not have to extend base classes nor implement specific interfaces. -The following example shows a controller defined by annotations: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class HelloController { - - @GetMapping("/hello") - public String handle(Model model) { - model.addAttribute("message", "Hello World!"); - return "index"; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.ui.set - - @Controller - class HelloController { - - @GetMapping("/hello") - fun handle(model: Model): String { - model["message"] = "Hello World!" - return "index" - } - } ----- - -In the preceding example, the method accepts a `Model` and returns a view name as a `String`, -but many other options exist and are explained later in this chapter. - -TIP: Guides and tutorials on https://spring.io/guides[spring.io] use the annotation-based -programming model described in this section. - - - -[[mvc-ann-controller]] -=== Declaration -[.small]#<># - -You can define controller beans by using a standard Spring bean definition in the -Servlet's `WebApplicationContext`. The `@Controller` stereotype allows for auto-detection, -aligned with Spring general support for detecting `@Component` classes in the classpath -and auto-registering bean definitions for them. It also acts as a stereotype for the -annotated class, indicating its role as a web component. - -To enable auto-detection of such `@Controller` beans, you can add component scanning to -your Java configuration, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ComponentScan("org.example.web") - public class WebConfig { - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ComponentScan("org.example.web") - class WebConfig { - - // ... - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -`@RestController` is a <> that is -itself meta-annotated with `@Controller` and `@ResponseBody` to indicate a controller whose -every method inherits the type-level `@ResponseBody` annotation and, therefore, writes -directly to the response body versus view resolution and rendering with an HTML template. - - -[[mvc-ann-requestmapping-proxying]] -==== AOP Proxies -[.small]#<># - -In some cases, you may need to decorate a controller with an AOP proxy at runtime. -One example is if you choose to have `@Transactional` annotations directly on the -controller. When this is the case, for controllers specifically, we recommend -using class-based proxying. This is automatically the case with such annotations -directly on the controller. - -If the controller implements an interface, and needs AOP proxying, you may need to -explicitly configure class-based proxying. For example, with `@EnableTransactionManagement` -you can change to `@EnableTransactionManagement(proxyTargetClass = true)`, and with -`` you can change to ``. - -NOTE: Keep in mind that as of 6.0, with interface proxying, Spring MVC no longer detects -controllers based solely on a type-level `@RequestMapping` annotation on the interface. -Please, enable class based proxying, or otherwise the interface must also have an -`@Controller` annotation. - - - -[[mvc-ann-requestmapping]] -=== Request Mapping -[.small]#<># - -You can use the `@RequestMapping` annotation to map requests to controllers methods. It has -various attributes to match by URL, HTTP method, request parameters, headers, and media -types. You can use it at the class level to express shared mappings or at the method level -to narrow down to a specific endpoint mapping. - -There are also HTTP method specific shortcut variants of `@RequestMapping`: - -* `@GetMapping` -* `@PostMapping` -* `@PutMapping` -* `@DeleteMapping` -* `@PatchMapping` - -The shortcuts are <> that are provided because, -arguably, most controller methods should be mapped to a specific HTTP method versus -using `@RequestMapping`, which, by default, matches to all HTTP methods. -A `@RequestMapping` is still needed at the class level to express shared mappings. - -The following example has type and method level mappings: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RestController - @RequestMapping("/persons") - class PersonController { - - @GetMapping("/{id}") - public Person getPerson(@PathVariable Long id) { - // ... - } - - @PostMapping - @ResponseStatus(HttpStatus.CREATED) - public void add(@RequestBody Person person) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RestController - @RequestMapping("/persons") - class PersonController { - - @GetMapping("/{id}") - fun getPerson(@PathVariable id: Long): Person { - // ... - } - - @PostMapping - @ResponseStatus(HttpStatus.CREATED) - fun add(@RequestBody person: Person) { - // ... - } - } ----- - - - -[[mvc-ann-requestmapping-uri-templates]] -==== URI patterns -[.small]#<># - -`@RequestMapping` methods can be mapped using URL patterns. There are two alternatives: - -* `PathPattern` -- a pre-parsed pattern matched against the URL path also pre-parsed as -`PathContainer`. Designed for web use, this solution deals effectively with encoding and -path parameters, and matches efficiently. -* `AntPathMatcher` -- match String patterns against a String path. This is the original -solution also used in Spring configuration to select resources on the classpath, on the -filesystem, and other locations. It is less efficient and the String path input is a -challenge for dealing effectively with encoding and other issues with URLs. - -`PathPattern` is the recommended solution for web applications and it is the only choice in -Spring WebFlux. It was enabled for use in Spring MVC from version 5.3 and is enabled by -default from version 6.0. See <> for -customizations of path matching options. - -`PathPattern` supports the same pattern syntax as `AntPathMatcher`. In addition, it also -supports the capturing pattern, e.g. `+{*spring}+`, for matching 0 or more path segments -at the end of a path. `PathPattern` also restricts the use of `+**+` for matching multiple -path segments such that it's only allowed at the end of a pattern. This eliminates many -cases of ambiguity when choosing the best matching pattern for a given request. -For full pattern syntax please refer to -{api-spring-framework}/web/util/pattern/PathPattern.html[PathPattern] and -{api-spring-framework}/util/AntPathMatcher.html[AntPathMatcher]. - -Some example patterns: - -* `+"/resources/ima?e.png"+` - match one character in a path segment -* `+"/resources/*.png"+` - match zero or more characters in a path segment -* `+"/resources/**"+` - match multiple path segments -* `+"/projects/{project}/versions"+` - match a path segment and capture it as a variable -* `+"/projects/{project:[a-z]+}/versions"+` - match and capture a variable with a regex - -Captured URI variables can be accessed with `@PathVariable`. For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/owners/{ownerId}/pets/{petId}") - public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/owners/{ownerId}/pets/{petId}") - fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { - // ... - } ----- - - -You can declare URI variables at the class and method levels, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - @RequestMapping("/owners/{ownerId}") - public class OwnerController { - - @GetMapping("/pets/{petId}") - public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - @RequestMapping("/owners/{ownerId}") - class OwnerController { - - @GetMapping("/pets/{petId}") - fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { - // ... - } - } ----- - -URI variables are automatically converted to the appropriate type, or `TypeMismatchException` -is raised. Simple types (`int`, `long`, `Date`, and so on) are supported by default and you can -register support for any other data type. -See <> and <>. - -You can explicitly name URI variables (for example, `@PathVariable("customId")`), but you can -leave that detail out if the names are the same and your code is compiled with the `-parameters` -compiler flag. - -The syntax `{varName:regex}` declares a URI variable with a regular expression that has -syntax of `{varName:regex}`. For example, given URL `"/spring-web-3.0.5.jar"`, the following method -extracts the name, version, and file extension: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") - public void handle(@PathVariable String name, @PathVariable String version, @PathVariable String ext) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") - fun handle(@PathVariable name: String, @PathVariable version: String, @PathVariable ext: String) { - // ... - } ----- - -URI path patterns can also have embedded `${...}` placeholders that are resolved on startup -by using `PropertySourcesPlaceholderConfigurer` against local, system, environment, and -other property sources. You can use this, for example, to parameterize a base URL based on -some external configuration. - - - -[[mvc-ann-requestmapping-pattern-comparison]] -==== Pattern Comparison -[.small]#<># - -When multiple patterns match a URL, the best match must be selected. This is done with -one of the following depending on whether use of parsed `PathPattern` is enabled for use or not: - -* {api-spring-framework}/web/util/pattern/PathPattern.html#SPECIFICITY_COMPARATOR[`PathPattern.SPECIFICITY_COMPARATOR`] -* {api-spring-framework}/util/AntPathMatcher.html#getPatternComparator-java.lang.String-[`AntPathMatcher.getPatternComparator(String path)`] - -Both help to sort patterns with more specific ones on top. A pattern is less specific if -it has a lower count of URI variables (counted as 1), single wildcards (counted as 1), -and double wildcards (counted as 2). Given an equal score, the longer pattern is chosen. -Given the same score and length, the pattern with more URI variables than wildcards is -chosen. - -The default mapping pattern (`/{asterisk}{asterisk}`) is excluded from scoring and always -sorted last. Also, prefix patterns (such as `/public/{asterisk}{asterisk}`) are considered less -specific than other pattern that do not have double wildcards. - -For the full details, follow the above links to the pattern Comparators. - - -[[mvc-ann-requestmapping-suffix-pattern-match]] -==== Suffix Match - -Starting in 5.3, by default Spring MVC no longer performs `.{asterisk}` suffix pattern -matching where a controller mapped to `/person` is also implicitly mapped to -`/person.{asterisk}`. As a consequence path extensions are no longer used to interpret -the requested content type for the response -- for example, `/person.pdf`, `/person.xml`, -and so on. - -Using file extensions in this way was necessary when browsers used to send `Accept` headers -that were hard to interpret consistently. At present, that is no longer a necessity and -using the `Accept` header should be the preferred choice. - -Over time, the use of file name extensions has proven problematic in a variety of ways. -It can cause ambiguity when overlain with the use of URI variables, path parameters, and -URI encoding. Reasoning about URL-based authorization -and security (see next section for more details) also becomes more difficult. - -To completely disable the use of path extensions in versions prior to 5.3, set the following: - -* `useSuffixPatternMatching(false)`, see <> -* `favorPathExtension(false)`, see <> - -Having a way to request content types other than through the `"Accept"` header can still -be useful, e.g. when typing a URL in a browser. A safe alternative to path extensions is -to use the query parameter strategy. If you must use file extensions, consider restricting -them to a list of explicitly registered extensions through the `mediaTypes` property of -<>. - - -[[mvc-ann-requestmapping-rfd]] -==== Suffix Match and RFD - -A reflected file download (RFD) attack is similar to XSS in that it relies on request input -(for example, a query parameter and a URI variable) being reflected in the response. However, instead of -inserting JavaScript into HTML, an RFD attack relies on the browser switching to perform a -download and treating the response as an executable script when double-clicked later. - -In Spring MVC, `@ResponseBody` and `ResponseEntity` methods are at risk, because -they can render different content types, which clients can request through URL path extensions. -Disabling suffix pattern matching and using path extensions for content negotiation -lower the risk but are not sufficient to prevent RFD attacks. - -To prevent RFD attacks, prior to rendering the response body, Spring MVC adds a -`Content-Disposition:inline;filename=f.txt` header to suggest a fixed and safe download -file. This is done only if the URL path contains a file extension that is neither -allowed as safe nor explicitly registered for content negotiation. However, it can -potentially have side effects when URLs are typed directly into a browser. - -Many common path extensions are allowed as safe by default. Applications with custom -`HttpMessageConverter` implementations can explicitly register file extensions for content -negotiation to avoid having a `Content-Disposition` header added for those extensions. -See <>. - -See https://pivotal.io/security/cve-2015-5211[CVE-2015-5211] for additional -recommendations related to RFD. - - -[[mvc-ann-requestmapping-consumes]] -==== Consumable Media Types -[.small]#<># - -You can narrow the request mapping based on the `Content-Type` of the request, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping(path = "/pets", consumes = "application/json") // <1> - public void addPet(@RequestBody Pet pet) { - // ... - } ----- -<1> Using a `consumes` attribute to narrow the mapping by the content type. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/pets", consumes = ["application/json"]) // <1> - fun addPet(@RequestBody pet: Pet) { - // ... - } ----- -<1> Using a `consumes` attribute to narrow the mapping by the content type. - -The `consumes` attribute also supports negation expressions -- for example, `!text/plain` means any -content type other than `text/plain`. - -You can declare a shared `consumes` attribute at the class level. Unlike most other -request-mapping attributes, however, when used at the class level, a method-level `consumes` attribute -overrides rather than extends the class-level declaration. - -TIP: `MediaType` provides constants for commonly used media types, such as -`APPLICATION_JSON_VALUE` and `APPLICATION_XML_VALUE`. - - -[[mvc-ann-requestmapping-produces]] -==== Producible Media Types -[.small]#<># - -You can narrow the request mapping based on the `Accept` request header and the list of -content types that a controller method produces, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping(path = "/pets/{petId}", produces = "application/json") // <1> - @ResponseBody - public Pet getPet(@PathVariable String petId) { - // ... - } ----- -<1> Using a `produces` attribute to narrow the mapping by the content type. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/pets/{petId}", produces = ["application/json"]) // <1> - @ResponseBody - fun getPet(@PathVariable petId: String): Pet { - // ... - } ----- -<1> Using a `produces` attribute to narrow the mapping by the content type. - -The media type can specify a character set. Negated expressions are supported -- for example, -`!text/plain` means any content type other than "text/plain". - -You can declare a shared `produces` attribute at the class level. Unlike most other -request-mapping attributes, however, when used at the class level, a method-level `produces` attribute -overrides rather than extends the class-level declaration. - -TIP: `MediaType` provides constants for commonly used media types, such as -`APPLICATION_JSON_VALUE` and `APPLICATION_XML_VALUE`. - - -[[mvc-ann-requestmapping-params-and-headers]] -==== Parameters, headers -[.small]#<># - -You can narrow request mappings based on request parameter conditions. You can test for the -presence of a request parameter (`myParam`), for the absence of one (`!myParam`), or for a -specific value (`myParam=myValue`). The following example shows how to test for a specific value: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping(path = "/pets/{petId}", params = "myParam=myValue") // <1> - public void findPet(@PathVariable String petId) { - // ... - } ----- -<1> Testing whether `myParam` equals `myValue`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/pets/{petId}", params = ["myParam=myValue"]) // <1> - fun findPet(@PathVariable petId: String) { - // ... - } ----- -<1> Testing whether `myParam` equals `myValue`. - -You can also use the same with request header conditions, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") // <1> - public void findPet(@PathVariable String petId) { - // ... - } ----- -<1> Testing whether `myHeader` equals `myValue`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/pets/{petId}", headers = ["myHeader=myValue"]) // <1> - fun findPet(@PathVariable petId: String) { - // ... - } ----- -<1> Testing whether `myHeader` equals `myValue`. - -TIP: You can match `Content-Type` and `Accept` with the headers condition, but it is better to use -<> and <> -instead. - - -[[mvc-ann-requestmapping-head-options]] -==== HTTP HEAD, OPTIONS -[.small]#<># - -`@GetMapping` (and `@RequestMapping(method=HttpMethod.GET)`) support HTTP HEAD -transparently for request mapping. Controller methods do not need to change. -A response wrapper, applied in `jakarta.servlet.http.HttpServlet`, ensures a `Content-Length` -header is set to the number of bytes written (without actually writing to the response). - -`@GetMapping` (and `@RequestMapping(method=HttpMethod.GET)`) are implicitly mapped to -and support HTTP HEAD. An HTTP HEAD request is processed as if it were HTTP GET except -that, instead of writing the body, the number of bytes are counted and the `Content-Length` -header is set. - -By default, HTTP OPTIONS is handled by setting the `Allow` response header to the list of HTTP -methods listed in all `@RequestMapping` methods that have matching URL patterns. - -For a `@RequestMapping` without HTTP method declarations, the `Allow` header is set to -`GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS`. Controller methods should always declare the -supported HTTP methods (for example, by using the HTTP method specific variants: -`@GetMapping`, `@PostMapping`, and others). - -You can explicitly map the `@RequestMapping` method to HTTP HEAD and HTTP OPTIONS, but that -is not necessary in the common case. - - -[[mvc-ann-requestmapping-composed]] -==== Custom Annotations -[.small]#<># - -Spring MVC supports the use of <> -for request mapping. Those are annotations that are themselves meta-annotated with -`@RequestMapping` and composed to redeclare a subset (or all) of the `@RequestMapping` -attributes with a narrower, more specific purpose. - -`@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, and `@PatchMapping` are -examples of composed annotations. They are provided because, arguably, most -controller methods should be mapped to a specific HTTP method versus using `@RequestMapping`, -which, by default, matches to all HTTP methods. If you need an example of composed -annotations, look at how those are declared. - -Spring MVC also supports custom request-mapping attributes with custom request-matching -logic. This is a more advanced option that requires subclassing -`RequestMappingHandlerMapping` and overriding the `getCustomMethodCondition` method, where -you can check the custom attribute and return your own `RequestCondition`. - - -[[mvc-ann-requestmapping-registration]] -==== Explicit Registrations -[.small]#<># - -You can programmatically register handler methods, which you can use for dynamic -registrations or for advanced cases, such as different instances of the same handler -under different URLs. The following example registers a handler method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class MyConfig { - - @Autowired - public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) // <1> - throws NoSuchMethodException { - - RequestMappingInfo info = RequestMappingInfo - .paths("/user/{id}").methods(RequestMethod.GET).build(); // <2> - - Method method = UserHandler.class.getMethod("getUser", Long.class); // <3> - - mapping.registerMapping(info, handler, method); // <4> - } - } ----- -<1> Inject the target handler and the handler mapping for controllers. -<2> Prepare the request mapping meta data. -<3> Get the handler method. -<4> Add the registration. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class MyConfig { - - @Autowired - fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) { // <1> - val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build() // <2> - val method = UserHandler::class.java.getMethod("getUser", Long::class.java) // <3> - mapping.registerMapping(info, handler, method) // <4> - } - } ----- -<1> Inject the target handler and the handler mapping for controllers. -<2> Prepare the request mapping meta data. -<3> Get the handler method. -<4> Add the registration. - - - -[[mvc-ann-methods]] -=== Handler Methods -[.small]#<># - -`@RequestMapping` handler methods have a flexible signature and can choose from a range of -supported controller method arguments and return values. - - -[[mvc-ann-arguments]] -==== Method Arguments -[.small]#<># - -The next table describes the supported controller method arguments. Reactive types are not supported -for any arguments. - -JDK 8's `java.util.Optional` is supported as a method argument in combination with -annotations that have a `required` attribute (for example, `@RequestParam`, `@RequestHeader`, -and others) and is equivalent to `required=false`. - -[cols="1,2", options="header"] -|=== -| Controller method argument | Description - -| `WebRequest`, `NativeWebRequest` -| Generic access to request parameters and request and session attributes, without direct - use of the Servlet API. - -| `jakarta.servlet.ServletRequest`, `jakarta.servlet.ServletResponse` -| Choose any specific request or response type -- for example, `ServletRequest`, `HttpServletRequest`, - or Spring's `MultipartRequest`, `MultipartHttpServletRequest`. - -| `jakarta.servlet.http.HttpSession` -| Enforces the presence of a session. As a consequence, such an argument is never `null`. - Note that session access is not thread-safe. Consider setting the - `RequestMappingHandlerAdapter` instance's `synchronizeOnSession` flag to `true` if multiple - requests are allowed to concurrently access a session. - -| `jakarta.servlet.http.PushBuilder` -| Servlet 4.0 push builder API for programmatic HTTP/2 resource pushes. - Note that, per the Servlet specification, the injected `PushBuilder` instance can be null if the client - does not support that HTTP/2 feature. - -| `java.security.Principal` -| Currently authenticated user -- possibly a specific `Principal` implementation class if known. - - Note that this argument is not resolved eagerly, if it is annotated in order to allow a custom resolver to resolve it - before falling back on default resolution via `HttpServletRequest#getUserPrincipal`. - For example, the Spring Security `Authentication` implements `Principal` and would be injected as such via - `HttpServletRequest#getUserPrincipal`, unless it is also annotated with `@AuthenticationPrincipal` in which case it - is resolved by a custom Spring Security resolver through `Authentication#getPrincipal`. - -| `HttpMethod` -| The HTTP method of the request. - -| `java.util.Locale` -| The current request locale, determined by the most specific `LocaleResolver` available (in - effect, the configured `LocaleResolver` or `LocaleContextResolver`). - -| `java.util.TimeZone` + `java.time.ZoneId` -| The time zone associated with the current request, as determined by a `LocaleContextResolver`. - -| `java.io.InputStream`, `java.io.Reader` -| For access to the raw request body as exposed by the Servlet API. - -| `java.io.OutputStream`, `java.io.Writer` -| For access to the raw response body as exposed by the Servlet API. - -| `@PathVariable` -| For access to URI template variables. See <>. - -| `@MatrixVariable` -| For access to name-value pairs in URI path segments. See <>. - -| `@RequestParam` -| For access to the Servlet request parameters, including multipart files. Parameter values - are converted to the declared method argument type. See <> as well - as <>. - - Note that use of `@RequestParam` is optional for simple parameter values. - See "`Any other argument`", at the end of this table. - -| `@RequestHeader` -| For access to request headers. Header values are converted to the declared method argument - type. See <>. - -| `@CookieValue` -| For access to cookies. Cookies values are converted to the declared method argument - type. See <>. - -| `@RequestBody` -| For access to the HTTP request body. Body content is converted to the declared method - argument type by using `HttpMessageConverter` implementations. See <>. - -| `HttpEntity` -| For access to request headers and body. The body is converted with an `HttpMessageConverter`. - See <>. - -| `@RequestPart` -| For access to a part in a `multipart/form-data` request, converting the part's body - with an `HttpMessageConverter`. See <>. - -| `java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap` -| For access to the model that is used in HTML controllers and exposed to templates as - part of view rendering. - -| `RedirectAttributes` -| Specify attributes to use in case of a redirect (that is, to be appended to the query - string) and flash attributes to be stored temporarily until the request after redirect. - See <> and <>. - -| `@ModelAttribute` -| For access to an existing attribute in the model (instantiated if not present) with - data binding and validation applied. See <> as well as - <> and <>. - - Note that use of `@ModelAttribute` is optional (for example, to set its attributes). - See "`Any other argument`" at the end of this table. - -| `Errors`, `BindingResult` -| For access to errors from validation and data binding for a command object - (that is, a `@ModelAttribute` argument) or errors from the validation of a `@RequestBody` or - `@RequestPart` arguments. You must declare an `Errors`, or `BindingResult` argument - immediately after the validated method argument. - -| `SessionStatus` + class-level `@SessionAttributes` -| For marking form processing complete, which triggers cleanup of session attributes - declared through a class-level `@SessionAttributes` annotation. See - <> for more details. - -| `UriComponentsBuilder` -| For preparing a URL relative to the current request's host, port, scheme, context path, and - the literal part of the servlet mapping. See <>. - -| `@SessionAttribute` -| For access to any session attribute, in contrast to model attributes stored in the session - as a result of a class-level `@SessionAttributes` declaration. See - <> for more details. - -| `@RequestAttribute` -| For access to request attributes. See <> for more details. - -| Any other argument -| If a method argument is not matched to any of the earlier values in this table and it is - a simple type (as determined by - {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]), - it is resolved as a `@RequestParam`. Otherwise, it is resolved as a `@ModelAttribute`. -|=== - - -[[mvc-ann-return-types]] -==== Return Values -[.small]#<># - -The next table describes the supported controller method return values. Reactive types are -supported for all return values. - -[cols="1,2", options="header"] -|=== -| Controller method return value | Description - -| `@ResponseBody` -| The return value is converted through `HttpMessageConverter` implementations and written to the - response. See <>. - -| `HttpEntity`, `ResponseEntity` -| The return value that specifies the full response (including HTTP headers and body) is to be converted - through `HttpMessageConverter` implementations and written to the response. - See <>. - -| `HttpHeaders` -| For returning a response with headers and no body. - -| `ErrorResponse` -| To render an RFC 7807 error response with details in the body, - see <> - -| `ProblemDetail` -| To render an RFC 7807 error response with details in the body, - see <> - -| `String` -| A view name to be resolved with `ViewResolver` implementations and used together with the implicit - model -- determined through command objects and `@ModelAttribute` methods. The handler - method can also programmatically enrich the model by declaring a `Model` argument - (see <>). - -| `View` -| A `View` instance to use for rendering together with the implicit model -- determined - through command objects and `@ModelAttribute` methods. The handler method can also - programmatically enrich the model by declaring a `Model` argument - (see <>). - -| `java.util.Map`, `org.springframework.ui.Model` -| Attributes to be added to the implicit model, with the view name implicitly determined - through a `RequestToViewNameTranslator`. - -| `@ModelAttribute` -| An attribute to be added to the model, with the view name implicitly determined through - a `RequestToViewNameTranslator`. - - Note that `@ModelAttribute` is optional. See "Any other return value" at the end of - this table. - -| `ModelAndView` object -| The view and model attributes to use and, optionally, a response status. - -| `void` -| A method with a `void` return type (or `null` return value) is considered to have fully - handled the response if it also has a `ServletResponse`, an `OutputStream` argument, or - an `@ResponseStatus` annotation. The same is also true if the controller has made a positive - `ETag` or `lastModified` timestamp check (see <> for details). - - If none of the above is true, a `void` return type can also indicate "`no response body`" for - REST controllers or a default view name selection for HTML controllers. - -| `DeferredResult` -| Produce any of the preceding return values asynchronously from any thread -- for example, as a - result of some event or callback. See <> and <>. - -| `Callable` -| Produce any of the above return values asynchronously in a Spring MVC-managed thread. - See <> and <>. - -| `ListenableFuture`, - `java.util.concurrent.CompletionStage`, - `java.util.concurrent.CompletableFuture` -| Alternative to `DeferredResult`, as a convenience (for example, when an underlying service - returns one of those). - -| `ResponseBodyEmitter`, `SseEmitter` -| Emit a stream of objects asynchronously to be written to the response with - `HttpMessageConverter` implementations. Also supported as the body of a `ResponseEntity`. - See <> and <>. - -| `StreamingResponseBody` -| Write to the response `OutputStream` asynchronously. Also supported as the body of a - `ResponseEntity`. See <> and <>. - -| Reactor and other reactive types registered via `ReactiveAdapterRegistry` -| A single value type, e.g. `Mono`, is comparable to returning `DeferredResult`. - A multi-value type, e.g. `Flux`, may be treated as a stream depending on the requested - media type, e.g. "text/event-stream", "application/json+stream", or otherwise is - collected to a List and rendered as a single value. See <> and - <>. - -| Other return values -| If a return value remains unresolved in any other way, it is treated as a model - attribute, unless it is a simple type as determined by - {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], - in which case it remains unresolved. -|=== - - -[[mvc-ann-typeconversion]] -==== Type Conversion -[.small]#<># - -Some annotated controller method arguments that represent `String`-based request input (such as -`@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) -can require type conversion if the argument is declared as something other than `String`. - -For such cases, type conversion is automatically applied based on the configured converters. -By default, simple types (`int`, `long`, `Date`, and others) are supported. You can customize -type conversion through a `WebDataBinder` (see <>) or by registering -`Formatters` with the `FormattingConversionService`. -See <>. - -A practical issue in type conversion is the treatment of an empty String source value. -Such a value is treated as missing if it becomes `null` as a result of type conversion. -This can be the case for `Long`, `UUID`, and other target types. If you want to allow `null` -to be injected, either use the `required` flag on the argument annotation, or declare the -argument as `@Nullable`. - -[NOTE] -==== -As of 5.3, non-null arguments will be enforced even after type conversion. If your handler -method intends to accept a null value as well, either declare your argument as `@Nullable` -or mark it as `required=false` in the corresponding `@RequestParam`, etc. annotation. This is -a best practice and the recommended solution for regressions encountered in a 5.3 upgrade. - -Alternatively, you may specifically handle e.g. the resulting `MissingPathVariableException` -in the case of a required `@PathVariable`. A null value after conversion will be treated like -an empty original value, so the corresponding `Missing...Exception` variants will be thrown. -==== - - -[[mvc-ann-matrix-variables]] -==== Matrix Variables -[.small]#<># - -https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in -path segments. In Spring MVC, we refer to those as "`matrix variables`" based on an -https://www.w3.org/DesignIssues/MatrixURIs.html["`old post`"] by Tim Berners-Lee, but they -can be also be referred to as URI path parameters. - -Matrix variables can appear in any path segment, with each variable separated by a semicolon and -multiple values separated by comma (for example, `/cars;color=red,green;year=2012`). Multiple -values can also be specified through repeated variable names (for example, -`color=red;color=green;color=blue`). - -If a URL is expected to contain matrix variables, the request mapping for a controller -method must use a URI variable to mask that variable content and ensure the request can -be matched successfully independent of matrix variable order and presence. -The following example uses a matrix variable: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // GET /pets/42;q=11;r=22 - - @GetMapping("/pets/{petId}") - public void findPet(@PathVariable String petId, @MatrixVariable int q) { - - // petId == 42 - // q == 11 - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // GET /pets/42;q=11;r=22 - - @GetMapping("/pets/{petId}") - fun findPet(@PathVariable petId: String, @MatrixVariable q: Int) { - - // petId == 42 - // q == 11 - } ----- - -Given that all path segments may contain matrix variables, you may sometimes need to -disambiguate which path variable the matrix variable is expected to be in. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // GET /owners/42;q=11/pets/21;q=22 - - @GetMapping("/owners/{ownerId}/pets/{petId}") - public void findPet( - @MatrixVariable(name="q", pathVar="ownerId") int q1, - @MatrixVariable(name="q", pathVar="petId") int q2) { - - // q1 == 11 - // q2 == 22 - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // GET /owners/42;q=11/pets/21;q=22 - - @GetMapping("/owners/{ownerId}/pets/{petId}") - fun findPet( - @MatrixVariable(name = "q", pathVar = "ownerId") q1: Int, - @MatrixVariable(name = "q", pathVar = "petId") q2: Int) { - - // q1 == 11 - // q2 == 22 - } ----- - -A matrix variable may be defined as optional and a default value specified, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // GET /pets/42 - - @GetMapping("/pets/{petId}") - public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) { - - // q == 1 - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // GET /pets/42 - - @GetMapping("/pets/{petId}") - fun findPet(@MatrixVariable(required = false, defaultValue = "1") q: Int) { - - // q == 1 - } ----- - -To get all matrix variables, you can use a `MultiValueMap`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 - - @GetMapping("/owners/{ownerId}/pets/{petId}") - public void findPet( - @MatrixVariable MultiValueMap matrixVars, - @MatrixVariable(pathVar="petId") MultiValueMap petMatrixVars) { - - // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] - // petMatrixVars: ["q" : 22, "s" : 23] - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 - - @GetMapping("/owners/{ownerId}/pets/{petId}") - fun findPet( - @MatrixVariable matrixVars: MultiValueMap, - @MatrixVariable(pathVar="petId") petMatrixVars: MultiValueMap) { - - // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] - // petMatrixVars: ["q" : 22, "s" : 23] - } ----- - -Note that you need to enable the use of matrix variables. In the MVC Java configuration, -you need to set a `UrlPathHelper` with `removeSemicolonContent=false` through -<>. In the MVC XML namespace, you can set -``. - - -[[mvc-ann-requestparam]] -==== `@RequestParam` -[.small]#<># - -You can use the `@RequestParam` annotation to bind Servlet request parameters (that is, -query parameters or form data) to a method argument in a controller. - -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - @RequestMapping("/pets") - public class EditPetForm { - - // ... - - @GetMapping - public String setupForm(@RequestParam("petId") int petId, Model model) { <1> - Pet pet = this.clinic.loadPet(petId); - model.addAttribute("pet", pet); - return "petForm"; - } - - // ... - - } ----- -<1> Using `@RequestParam` to bind `petId`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.ui.set - - @Controller - @RequestMapping("/pets") - class EditPetForm { - - // ... - - @GetMapping - fun setupForm(@RequestParam("petId") petId: Int, model: Model): String { // <1> - val pet = this.clinic.loadPet(petId); - model["pet"] = pet - return "petForm" - } - - // ... - - } ----- -<1> Using `@RequestParam` to bind `petId`. - -By default, method parameters that use this annotation are required, but you can specify that -a method parameter is optional by setting the `@RequestParam` annotation's `required` flag to -`false` or by declaring the argument with an `java.util.Optional` wrapper. - -Type conversion is automatically applied if the target method parameter type is not -`String`. See <>. - -Declaring the argument type as an array or list allows for resolving multiple parameter -values for the same parameter name. - -When an `@RequestParam` annotation is declared as a `Map` or -`MultiValueMap`, without a parameter name specified in the annotation, -then the map is populated with the request parameter values for each given parameter name. - -Note that use of `@RequestParam` is optional (for example, to set its attributes). -By default, any argument that is a simple value type (as determined by -{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) -and is not resolved by any other argument resolver, is treated as if it were annotated -with `@RequestParam`. - - -[[mvc-ann-requestheader]] -==== `@RequestHeader` -[.small]#<># - -You can use the `@RequestHeader` annotation to bind a request header to a method argument in a -controller. - -Consider the following request, with headers: - -[literal] -[subs="verbatim,quotes"] ----- -Host localhost:8080 -Accept text/html,application/xhtml+xml,application/xml;q=0.9 -Accept-Language fr,en-gb;q=0.7,en;q=0.3 -Accept-Encoding gzip,deflate -Accept-Charset ISO-8859-1,utf-8;q=0.7,*;q=0.7 -Keep-Alive 300 ----- - -The following example gets the value of the `Accept-Encoding` and `Keep-Alive` headers: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/demo") - public void handle( - @RequestHeader("Accept-Encoding") String encoding, // <1> - @RequestHeader("Keep-Alive") long keepAlive) { // <2> - //... - } ----- -<1> Get the value of the `Accept-Encoding` header. -<2> Get the value of the `Keep-Alive` header. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/demo") - fun handle( - @RequestHeader("Accept-Encoding") encoding: String, // <1> - @RequestHeader("Keep-Alive") keepAlive: Long) { // <2> - //... - } ----- -<1> Get the value of the `Accept-Encoding` header. -<2> Get the value of the `Keep-Alive` header. - -If the target method parameter type is not -`String`, type conversion is automatically applied. See <>. - -When an `@RequestHeader` annotation is used on a `Map`, -`MultiValueMap`, or `HttpHeaders` argument, the map is populated -with all header values. - -TIP: Built-in support is available for converting a comma-separated string into an -array or collection of strings or other types known to the type conversion system. For -example, a method parameter annotated with `@RequestHeader("Accept")` can be of type -`String` but also `String[]` or `List`. - - -[[mvc-ann-cookievalue]] -==== `@CookieValue` -[.small]#<># - -You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument -in a controller. - -Consider a request with the following cookie: - -[literal,subs="verbatim,quotes"] ----- -JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84 ----- - -The following example shows how to get the cookie value: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/demo") - public void handle(@CookieValue("JSESSIONID") String cookie) { <1> - //... - } ----- -<1> Get the value of the `JSESSIONID` cookie. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/demo") - fun handle(@CookieValue("JSESSIONID") cookie: String) { // <1> - //... - } ----- -<1> Get the value of the `JSESSIONID` cookie. - -If the target method parameter type is not `String`, type conversion is applied automatically. -See <>. - - -[[mvc-ann-modelattrib-method-args]] -==== `@ModelAttribute` -[.small]#<># - -You can use the `@ModelAttribute` annotation on a method argument to access an attribute from -the model or have it be instantiated if not present. The model attribute is also overlain with -values from HTTP Servlet request parameters whose names match to field names. This is referred -to as data binding, and it saves you from having to deal with parsing and converting individual -query parameters and form fields. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - public String processSubmit(@ModelAttribute Pet pet) { // <1> - // method logic... - } ----- -<1> Bind an instance of `Pet`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -@PostMapping("/owners/{ownerId}/pets/{petId}/edit") -fun processSubmit(@ModelAttribute pet: Pet): String { // <1> - // method logic... -} ----- -<1> Bind an instance of `Pet`. - -The `Pet` instance above is sourced in one of the following ways: - -* Retrieved from the model where it may have been added by a - <>. -* Retrieved from the HTTP session if the model attribute was listed in - the class-level <> annotation. -* Obtained through a `Converter` where the model attribute name matches the name of a - request value such as a path variable or a request parameter (see next example). -* Instantiated using its default constructor. -* Instantiated through a "`primary constructor`" with arguments that match to Servlet - request parameters. Argument names are determined through JavaBeans - `@ConstructorProperties` or through runtime-retained parameter names in the bytecode. - -One alternative to using a <> to -supply it or relying on the framework to create the model attribute, is to have a -`Converter` to provide the instance. This is applied when the model attribute -name matches to the name of a request value such as a path variable or a request -parameter, and there is a `Converter` from `String` to the model attribute type. -In the following example, the model attribute name is `account` which matches the URI -path variable `account`, and there is a registered `Converter` which -could load the `Account` from a data store: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PutMapping("/accounts/{account}") - public String save(@ModelAttribute("account") Account account) { // <1> - // ... - } ----- -<1> Bind an instance of `Account` using an explicit attribute name. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PutMapping("/accounts/{account}") - fun save(@ModelAttribute("account") account: Account): String { // <1> - // ... - } ----- -<1> Bind an instance of `Account` using an explicit attribute name. - -After the model attribute instance is obtained, data binding is applied. The -`WebDataBinder` class matches Servlet request parameter names (query parameters and form -fields) to field names on the target `Object`. Matching fields are populated after type -conversion is applied, where necessary. For more on data binding (and validation), see -<>. For more on customizing data binding, see -<>. - -Data binding can result in errors. By default, a `BindException` is raised. However, to check -for such errors in the controller method, you can add a `BindingResult` argument immediately next -to the `@ModelAttribute`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { // <1> - if (result.hasErrors()) { - return "petForm"; - } - // ... - } ----- -<1> Adding a `BindingResult` next to the `@ModelAttribute`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - fun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { // <1> - if (result.hasErrors()) { - return "petForm" - } - // ... - } ----- -<1> Adding a `BindingResult` next to the `@ModelAttribute`. - -In some cases, you may want access to a model attribute without data binding. For such -cases, you can inject the `Model` into the controller and access it directly or, -alternatively, set `@ModelAttribute(binding=false)`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ModelAttribute - public AccountForm setUpForm() { - return new AccountForm(); - } - - @ModelAttribute - public Account findAccount(@PathVariable String accountId) { - return accountRepository.findOne(accountId); - } - - @PostMapping("update") - public String update(@Valid AccountForm form, BindingResult result, - @ModelAttribute(binding=false) Account account) { // <1> - // ... - } ----- -<1> Setting `@ModelAttribute(binding=false)`. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ModelAttribute - fun setUpForm(): AccountForm { - return AccountForm() - } - - @ModelAttribute - fun findAccount(@PathVariable accountId: String): Account { - return accountRepository.findOne(accountId) - } - - @PostMapping("update") - fun update(@Valid form: AccountForm, result: BindingResult, - @ModelAttribute(binding = false) account: Account): String { // <1> - // ... - } ----- -<1> Setting `@ModelAttribute(binding=false)`. - -You can automatically apply validation after data binding by adding the -`jakarta.validation.Valid` annotation or Spring's `@Validated` annotation -(<> and -<>). The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { // <1> - if (result.hasErrors()) { - return "petForm"; - } - // ... - } ----- -<1> Validate the `Pet` instance. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/owners/{ownerId}/pets/{petId}/edit") - fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { // <1> - if (result.hasErrors()) { - return "petForm" - } - // ... - } ----- -<1> Validate the `Pet` instance. - -Note that using `@ModelAttribute` is optional (for example, to set its attributes). -By default, any argument that is not a simple value type (as determined by -{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) -and is not resolved by any other argument resolver is treated as if it were annotated -with `@ModelAttribute`. - - -[[mvc-ann-sessionattributes]] -==== `@SessionAttributes` -[.small]#<># - -`@SessionAttributes` is used to store model attributes in the HTTP Servlet session between -requests. It is a type-level annotation that declares the session attributes used by a -specific controller. This typically lists the names of model attributes or types of -model attributes that should be transparently stored in the session for subsequent -requests to access. - -The following example uses the `@SessionAttributes` annotation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - @SessionAttributes("pet") // <1> - public class EditPetForm { - // ... - } ----- -<1> Using the `@SessionAttributes` annotation. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - @SessionAttributes("pet") // <1> - class EditPetForm { - // ... - } ----- -<1> Using the `@SessionAttributes` annotation. - -On the first request, when a model attribute with the name, `pet`, is added to the model, -it is automatically promoted to and saved in the HTTP Servlet session. It remains there -until another controller method uses a `SessionStatus` method argument to clear the -storage, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - @SessionAttributes("pet") // <1> - public class EditPetForm { - - // ... - - @PostMapping("/pets/{id}") - public String handle(Pet pet, BindingResult errors, SessionStatus status) { - if (errors.hasErrors) { - // ... - } - status.setComplete(); // <2> - // ... - } - } ----- -<1> Storing the `Pet` value in the Servlet session. -<2> Clearing the `Pet` value from the Servlet session. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -@Controller -@SessionAttributes("pet") // <1> -class EditPetForm { - - // ... - - @PostMapping("/pets/{id}") - fun handle(pet: Pet, errors: BindingResult, status: SessionStatus): String { - if (errors.hasErrors()) { - // ... - } - status.setComplete() // <2> - // ... - } -} ----- -<1> Storing the `Pet` value in the Servlet session. -<2> Clearing the `Pet` value from the Servlet session. - - -[[mvc-ann-sessionattribute]] -==== `@SessionAttribute` -[.small]#<># - -If you need access to pre-existing session attributes that are managed globally -(that is, outside the controller -- for example, by a filter) and may or may not be present, -you can use the `@SessionAttribute` annotation on a method parameter, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RequestMapping("/") - public String handle(@SessionAttribute User user) { <1> - // ... - } ----- -<1> Using a `@SessionAttribute` annotation. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RequestMapping("/") - fun handle(@SessionAttribute user: User): String { // <1> - // ... - } ----- -<1> Using a `@SessionAttribute` annotation. - -For use cases that require adding or removing session attributes, consider injecting -`org.springframework.web.context.request.WebRequest` or -`jakarta.servlet.http.HttpSession` into the controller method. - -For temporary storage of model attributes in the session as part of a controller -workflow, consider using `@SessionAttributes` as described in -<>. - - -[[mvc-ann-requestattrib]] -==== `@RequestAttribute` -[.small]#<># - -Similar to `@SessionAttribute`, you can use the `@RequestAttribute` annotations to -access pre-existing request attributes created earlier (for example, by a Servlet `Filter` -or `HandlerInterceptor`): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/") - public String handle(@RequestAttribute Client client) { // <1> - // ... - } ----- -<1> Using the `@RequestAttribute` annotation. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/") - fun handle(@RequestAttribute client: Client): String { // <1> - // ... - } ----- -<1> Using the `@RequestAttribute` annotation. - - -[[mvc-redirecting-passing-data]] -==== Redirect Attributes - -By default, all model attributes are considered to be exposed as URI template variables in -the redirect URL. Of the remaining attributes, those that are primitive types or -collections or arrays of primitive types are automatically appended as query parameters. - -Appending primitive type attributes as query parameters can be the desired result if a -model instance was prepared specifically for the redirect. However, in annotated -controllers, the model can contain additional attributes added for rendering purposes (for example, -drop-down field values). To avoid the possibility of having such attributes appear in the -URL, a `@RequestMapping` method can declare an argument of type `RedirectAttributes` and -use it to specify the exact attributes to make available to `RedirectView`. If the method -does redirect, the content of `RedirectAttributes` is used. Otherwise, the content of the -model is used. - -The `RequestMappingHandlerAdapter` provides a flag called -`ignoreDefaultModelOnRedirect`, which you can use to indicate that the content of the default -`Model` should never be used if a controller method redirects. Instead, the controller -method should declare an attribute of type `RedirectAttributes` or, if it does not do so, -no attributes should be passed on to `RedirectView`. Both the MVC namespace and the MVC -Java configuration keep this flag set to `false`, to maintain backwards compatibility. -However, for new applications, we recommend setting it to `true`. - -Note that URI template variables from the present request are automatically made -available when expanding a redirect URL, and you don't need to explicitly add them -through `Model` or `RedirectAttributes`. The following example shows how to define a redirect: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/files/{path}") - public String upload(...) { - // ... - return "redirect:files/{path}"; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/files/{path}") - fun upload(...): String { - // ... - return "redirect:files/{path}" - } ----- - -Another way of passing data to the redirect target is by using flash attributes. Unlike -other redirect attributes, flash attributes are saved in the HTTP session (and, hence, do -not appear in the URL). See <> for more information. - - -[[mvc-flash-attributes]] -==== Flash Attributes - -Flash attributes provide a way for one request to store attributes that are intended for use in -another. This is most commonly needed when redirecting -- for example, the -Post-Redirect-Get pattern. Flash attributes are saved temporarily before the -redirect (typically in the session) to be made available to the request after the -redirect and are removed immediately. - -Spring MVC has two main abstractions in support of flash attributes. `FlashMap` is used -to hold flash attributes, while `FlashMapManager` is used to store, retrieve, and manage -`FlashMap` instances. - -Flash attribute support is always "`on`" and does not need to be enabled explicitly. -However, if not used, it never causes HTTP session creation. On each request, there is an -"`input`" `FlashMap` with attributes passed from a previous request (if any) and an -"`output`" `FlashMap` with attributes to save for a subsequent request. Both `FlashMap` -instances are accessible from anywhere in Spring MVC through static methods in -`RequestContextUtils`. - -Annotated controllers typically do not need to work with `FlashMap` directly. Instead, a -`@RequestMapping` method can accept an argument of type `RedirectAttributes` and use it -to add flash attributes for a redirect scenario. Flash attributes added through -`RedirectAttributes` are automatically propagated to the "`output`" FlashMap. Similarly, -after the redirect, attributes from the "`input`" `FlashMap` are automatically added to the -`Model` of the controller that serves the target URL. - -.Matching requests to flash attributes -**** -The concept of flash attributes exists in many other web frameworks and has proven to sometimes -be exposed to concurrency issues. This is because, by definition, flash attributes -are to be stored until the next request. However the very "`next`" request may not be the -intended recipient but another asynchronous request (for example, polling or resource requests), -in which case the flash attributes are removed too early. - -To reduce the possibility of such issues, `RedirectView` automatically "`stamps`" -`FlashMap` instances with the path and query parameters of the target redirect URL. In -turn, the default `FlashMapManager` matches that information to incoming requests when -it looks up the "`input`" `FlashMap`. - -This does not entirely eliminate the possibility of a concurrency issue but -reduces it greatly with information that is already available in the redirect URL. -Therefore, we recommend that you use flash attributes mainly for redirect scenarios. -**** - - -[[mvc-multipart-forms]] -==== Multipart -[.small]#<># - -After a `MultipartResolver` has been <>, the content of POST -requests with `multipart/form-data` is parsed and accessible as regular request -parameters. The following example accesses one regular form field and one uploaded -file: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class FileUploadController { - - @PostMapping("/form") - public String handleFormUpload(@RequestParam("name") String name, - @RequestParam("file") MultipartFile file) { - - if (!file.isEmpty()) { - byte[] bytes = file.getBytes(); - // store the bytes somewhere - return "redirect:uploadSuccess"; - } - return "redirect:uploadFailure"; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class FileUploadController { - - @PostMapping("/form") - fun handleFormUpload(@RequestParam("name") name: String, - @RequestParam("file") file: MultipartFile): String { - - if (!file.isEmpty) { - val bytes = file.bytes - // store the bytes somewhere - return "redirect:uploadSuccess" - } - return "redirect:uploadFailure" - } - } ----- - -Declaring the argument type as a `List` allows for resolving multiple -files for the same parameter name. - -When the `@RequestParam` annotation is declared as a `Map` or -`MultiValueMap`, without a parameter name specified in the annotation, -then the map is populated with the multipart files for each given parameter name. - -NOTE: With Servlet multipart parsing, you may also declare `jakarta.servlet.http.Part` -instead of Spring's `MultipartFile`, as a method argument or collection value type. - -You can also use multipart content as part of data binding to a -<>. For example, the form field -and file from the preceding example could be fields on a form object, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - class MyForm { - - private String name; - - private MultipartFile file; - - // ... - } - - @Controller - public class FileUploadController { - - @PostMapping("/form") - public String handleFormUpload(MyForm form, BindingResult errors) { - if (!form.getFile().isEmpty()) { - byte[] bytes = form.getFile().getBytes(); - // store the bytes somewhere - return "redirect:uploadSuccess"; - } - return "redirect:uploadFailure"; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class MyForm(val name: String, val file: MultipartFile, ...) - - @Controller - class FileUploadController { - - @PostMapping("/form") - fun handleFormUpload(form: MyForm, errors: BindingResult): String { - if (!form.file.isEmpty) { - val bytes = form.file.bytes - // store the bytes somewhere - return "redirect:uploadSuccess" - } - return "redirect:uploadFailure" - } - } ----- - - -Multipart requests can also be submitted from non-browser clients in a RESTful service -scenario. The following example shows a file with JSON: - -[literal,subs="verbatim,quotes"] ----- -POST /someUrl -Content-Type: multipart/mixed - ---edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp -Content-Disposition: form-data; name="meta-data" -Content-Type: application/json; charset=UTF-8 -Content-Transfer-Encoding: 8bit - -{ - "name": "value" -} ---edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp -Content-Disposition: form-data; name="file-data"; filename="file.properties" -Content-Type: text/xml -Content-Transfer-Encoding: 8bit -... File Data ... ----- - -You can access the "meta-data" part with `@RequestParam` as a `String` but you'll -probably want it deserialized from JSON (similar to `@RequestBody`). Use the -`@RequestPart` annotation to access a multipart after converting it with an -<>: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/") - public String handle(@RequestPart("meta-data") MetaData metadata, - @RequestPart("file-data") MultipartFile file) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/") - fun handle(@RequestPart("meta-data") metadata: MetaData, - @RequestPart("file-data") file: MultipartFile): String { - // ... - } ----- - -You can use `@RequestPart` in combination with `jakarta.validation.Valid` or use Spring's -`@Validated` annotation, both of which cause Standard Bean Validation to be applied. -By default, validation errors cause a `MethodArgumentNotValidException`, which is turned -into a 400 (BAD_REQUEST) response. Alternatively, you can handle validation errors locally -within the controller through an `Errors` or `BindingResult` argument, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/") - public String handle(@Valid @RequestPart("meta-data") MetaData metadata, - BindingResult result) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/") - fun handle(@Valid @RequestPart("meta-data") metadata: MetaData, - result: BindingResult): String { - // ... - } ----- - - - -[[mvc-ann-requestbody]] -==== `@RequestBody` -[.small]#<># - -You can use the `@RequestBody` annotation to have the request body read and deserialized into an -`Object` through an <>. -The following example uses a `@RequestBody` argument: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/accounts") - public void handle(@RequestBody Account account) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/accounts") - fun handle(@RequestBody account: Account) { - // ... - } ----- - - -You can use the <> option of the <> to -configure or customize message conversion. - -You can use `@RequestBody` in combination with `jakarta.validation.Valid` or Spring's -`@Validated` annotation, both of which cause Standard Bean Validation to be applied. -By default, validation errors cause a `MethodArgumentNotValidException`, which is turned -into a 400 (BAD_REQUEST) response. Alternatively, you can handle validation errors locally -within the controller through an `Errors` or `BindingResult` argument, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/accounts") - public void handle(@Valid @RequestBody Account account, BindingResult result) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/accounts") - fun handle(@Valid @RequestBody account: Account, result: BindingResult) { - // ... - } ----- - - -[[mvc-ann-httpentity]] -==== HttpEntity -[.small]#<># - -`HttpEntity` is more or less identical to using <> but is based on a -container object that exposes request headers and body. The following listing shows an example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping("/accounts") - public void handle(HttpEntity entity) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping("/accounts") - fun handle(entity: HttpEntity) { - // ... - } ----- - - - -[[mvc-ann-responsebody]] -==== `@ResponseBody` -[.small]#<># - -You can use the `@ResponseBody` annotation on a method to have the return serialized -to the response body through an -<>. -The following listing shows an example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/accounts/{id}") - @ResponseBody - public Account handle() { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/accounts/{id}") - @ResponseBody - fun handle(): Account { - // ... - } ----- - -`@ResponseBody` is also supported at the class level, in which case it is inherited by -all controller methods. This is the effect of `@RestController`, which is nothing more -than a meta-annotation marked with `@Controller` and `@ResponseBody`. - -You can use `@ResponseBody` with reactive types. -See <> and <> for more details. - -You can use the <> option of the <> to -configure or customize message conversion. - -You can combine `@ResponseBody` methods with JSON serialization views. -See <> for details. - - -[[mvc-ann-responseentity]] -==== ResponseEntity -[.small]#<># - -`ResponseEntity` is like <> but with status and headers. For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/something") - public ResponseEntity handle() { - String body = ... ; - String etag = ... ; - return ResponseEntity.ok().eTag(etag).body(body); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/something") - fun handle(): ResponseEntity { - val body = ... - val etag = ... - return ResponseEntity.ok().eTag(etag).build(body) - } ----- - -Spring MVC supports using a single value <> -to produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive -types for the body. This allows the following types of async responses: - -* `ResponseEntity>` or `ResponseEntity>` make the response status and - headers known immediately while the body is provided asynchronously at a later point. - Use `Mono` if the body consists of 0..1 values or `Flux` if it can produce multiple values. -* `Mono>` provides all three -- response status, headers, and body, - asynchronously at a later point. This allows the response status and headers to vary - depending on the outcome of asynchronous request handling. - - -[[mvc-ann-jackson]] -==== Jackson JSON - -Spring offers support for the Jackson JSON library. - -[[mvc-ann-jsonview]] -===== JSON Views -[.small]#<># - -Spring MVC provides built-in support for -https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], -which allow rendering only a subset of all fields in an `Object`. To use it with -`@ResponseBody` or `ResponseEntity` controller methods, you can use Jackson's -`@JsonView` annotation to activate a serialization view class, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RestController - public class UserController { - - @GetMapping("/user") - @JsonView(User.WithoutPasswordView.class) - public User getUser() { - return new User("eric", "7!jd#h23"); - } - } - - public class User { - - public interface WithoutPasswordView {}; - public interface WithPasswordView extends WithoutPasswordView {}; - - private String username; - private String password; - - public User() { - } - - public User(String username, String password) { - this.username = username; - this.password = password; - } - - @JsonView(WithoutPasswordView.class) - public String getUsername() { - return this.username; - } - - @JsonView(WithPasswordView.class) - public String getPassword() { - return this.password; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RestController - class UserController { - - @GetMapping("/user") - @JsonView(User.WithoutPasswordView::class) - fun getUser() = User("eric", "7!jd#h23") - } - - class User( - @JsonView(WithoutPasswordView::class) val username: String, - @JsonView(WithPasswordView::class) val password: String) { - - interface WithoutPasswordView - interface WithPasswordView : WithoutPasswordView - } ----- - -NOTE: `@JsonView` allows an array of view classes, but you can specify only one per -controller method. If you need to activate multiple views, you can use a composite interface. - -If you want to do the above programmatically, instead of declaring an `@JsonView` annotation, -wrap the return value with `MappingJacksonValue` and use it to supply the serialization view: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RestController - public class UserController { - - @GetMapping("/user") - public MappingJacksonValue getUser() { - User user = new User("eric", "7!jd#h23"); - MappingJacksonValue value = new MappingJacksonValue(user); - value.setSerializationView(User.WithoutPasswordView.class); - return value; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RestController - class UserController { - - @GetMapping("/user") - fun getUser(): MappingJacksonValue { - val value = MappingJacksonValue(User("eric", "7!jd#h23")) - value.serializationView = User.WithoutPasswordView::class.java - return value - } - } ----- - -For controllers that rely on view resolution, you can add the serialization view class -to the model, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class UserController extends AbstractController { - - @GetMapping("/user") - public String getUser(Model model) { - model.addAttribute("user", new User("eric", "7!jd#h23")); - model.addAttribute(JsonView.class.getName(), User.WithoutPasswordView.class); - return "userView"; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class UserController : AbstractController() { - - @GetMapping("/user") - fun getUser(model: Model): String { - model["user"] = User("eric", "7!jd#h23") - model[JsonView::class.qualifiedName] = User.WithoutPasswordView::class.java - return "userView" - } - } ----- - - - -[[mvc-ann-modelattrib-methods]] -=== Model -[.small]#<># - -You can use the `@ModelAttribute` annotation: - -* On a <> in `@RequestMapping` methods -to create or access an `Object` from the model and to bind it to the request through a -`WebDataBinder`. -* As a method-level annotation in `@Controller` or `@ControllerAdvice` classes that help -to initialize the model prior to any `@RequestMapping` method invocation. -* On a `@RequestMapping` method to mark its return value is a model attribute. - -This section discusses `@ModelAttribute` methods -- the second item in the preceding list. -A controller can have any number of `@ModelAttribute` methods. All such methods are -invoked before `@RequestMapping` methods in the same controller. A `@ModelAttribute` -method can also be shared across controllers through `@ControllerAdvice`. See the section on -<> for more details. - -`@ModelAttribute` methods have flexible method signatures. They support many of the same -arguments as `@RequestMapping` methods, except for `@ModelAttribute` itself or anything -related to the request body. - -The following example shows a `@ModelAttribute` method: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ModelAttribute - public void populateModel(@RequestParam String number, Model model) { - model.addAttribute(accountRepository.findAccount(number)); - // add more ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ModelAttribute - fun populateModel(@RequestParam number: String, model: Model) { - model.addAttribute(accountRepository.findAccount(number)) - // add more ... - } ----- - -The following example adds only one attribute: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ModelAttribute - public Account addAccount(@RequestParam String number) { - return accountRepository.findAccount(number); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ModelAttribute - fun addAccount(@RequestParam number: String): Account { - return accountRepository.findAccount(number) - } ----- - - -NOTE: When a name is not explicitly specified, a default name is chosen based on the `Object` -type, as explained in the javadoc for {api-spring-framework}/core/Conventions.html[`Conventions`]. -You can always assign an explicit name by using the overloaded `addAttribute` method or -through the `name` attribute on `@ModelAttribute` (for a return value). - -You can also use `@ModelAttribute` as a method-level annotation on `@RequestMapping` methods, -in which case the return value of the `@RequestMapping` method is interpreted as a model -attribute. This is typically not required, as it is the default behavior in HTML controllers, -unless the return value is a `String` that would otherwise be interpreted as a view name. -`@ModelAttribute` can also customize the model attribute name, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/accounts/{id}") - @ModelAttribute("myAccount") - public Account handle() { - // ... - return account; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/accounts/{id}") - @ModelAttribute("myAccount") - fun handle(): Account { - // ... - return account - } ----- - - - -[[mvc-ann-initbinder]] -=== `DataBinder` -[.small]#<># - -`@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods that -initialize instances of `WebDataBinder`, and those, in turn, can: - -* Bind request parameters (that is, form or query data) to a model object. -* Convert String-based request values (such as request parameters, path variables, -headers, cookies, and others) to the target type of controller method arguments. -* Format model object values as `String` values when rendering HTML forms. - -`@InitBinder` methods can register controller-specific `java.beans.PropertyEditor` or -Spring `Converter` and `Formatter` components. In addition, you can use the -<> to register `Converter` and `Formatter` -types in a globally shared `FormattingConversionService`. - -`@InitBinder` methods support many of the same arguments that `@RequestMapping` methods -do, except for `@ModelAttribute` (command object) arguments. Typically, they are declared -with a `WebDataBinder` argument (for registrations) and a `void` return value. -The following listing shows an example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class FormController { - - @InitBinder // <1> - public void initBinder(WebDataBinder binder) { - SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd"); - dateFormat.setLenient(false); - binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false)); - } - - // ... - } ----- -<1> Defining an `@InitBinder` method. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class FormController { - - @InitBinder // <1> - fun initBinder(binder: WebDataBinder) { - val dateFormat = SimpleDateFormat("yyyy-MM-dd") - dateFormat.isLenient = false - binder.registerCustomEditor(Date::class.java, CustomDateEditor(dateFormat, false)) - } - - // ... - } ----- -<1> Defining an `@InitBinder` method. - -Alternatively, when you use a `Formatter`-based setup through a shared -`FormattingConversionService`, you can re-use the same approach and register -controller-specific `Formatter` implementations, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class FormController { - - @InitBinder // <1> - protected void initBinder(WebDataBinder binder) { - binder.addCustomFormatter(new DateFormatter("yyyy-MM-dd")); - } - - // ... - } ----- -<1> Defining an `@InitBinder` method on a custom formatter. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class FormController { - - @InitBinder // <1> - protected fun initBinder(binder: WebDataBinder) { - binder.addCustomFormatter(DateFormatter("yyyy-MM-dd")) - } - - // ... - } ----- -<1> Defining an `@InitBinder` method on a custom formatter. - -[[mvc-ann-initbinder-model-design]] -==== Model Design -[.small]#<># - -include::web-data-binding-model-design.adoc[] - - -[[mvc-ann-exceptionhandler]] -=== Exceptions -[.small]#<># - -`@Controller` and <> classes can have -`@ExceptionHandler` methods to handle exceptions from controller methods, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class SimpleController { - - // ... - - @ExceptionHandler - public ResponseEntity handle(IOException ex) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class SimpleController { - - // ... - - @ExceptionHandler - fun handle(ex: IOException): ResponseEntity { - // ... - } - } ----- - -The exception may match against a top-level exception being propagated (e.g. a direct -`IOException` being thrown) or against a nested cause within a wrapper exception (e.g. -an `IOException` wrapped inside an `IllegalStateException`). As of 5.3, this can match -at arbitrary cause levels, whereas previously only an immediate cause was considered. - -For matching exception types, preferably declare the target exception as a method argument, -as the preceding example shows. When multiple exception methods match, a root exception match is -generally preferred to a cause exception match. More specifically, the `ExceptionDepthComparator` -is used to sort exceptions based on their depth from the thrown exception type. - -Alternatively, the annotation declaration may narrow the exception types to match, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExceptionHandler({FileSystemException.class, RemoteException.class}) - public ResponseEntity handle(IOException ex) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExceptionHandler(FileSystemException::class, RemoteException::class) - fun handle(ex: IOException): ResponseEntity { - // ... - } ----- - -You can even use a list of specific exception types with a very generic argument signature, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @ExceptionHandler({FileSystemException.class, RemoteException.class}) - public ResponseEntity handle(Exception ex) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @ExceptionHandler(FileSystemException::class, RemoteException::class) - fun handle(ex: Exception): ResponseEntity { - // ... - } ----- - -[NOTE] -==== -The distinction between root and cause exception matching can be surprising. - -In the `IOException` variant shown earlier, the method is typically called with -the actual `FileSystemException` or `RemoteException` instance as the argument, -since both of them extend from `IOException`. However, if any such matching -exception is propagated within a wrapper exception which is itself an `IOException`, -the passed-in exception instance is that wrapper exception. - -The behavior is even simpler in the `handle(Exception)` variant. This is -always invoked with the wrapper exception in a wrapping scenario, with the -actually matching exception to be found through `ex.getCause()` in that case. -The passed-in exception is the actual `FileSystemException` or -`RemoteException` instance only when these are thrown as top-level exceptions. -==== - -We generally recommend that you be as specific as possible in the argument signature, -reducing the potential for mismatches between root and cause exception types. -Consider breaking a multi-matching method into individual `@ExceptionHandler` -methods, each matching a single specific exception type through its signature. - -In a multi-`@ControllerAdvice` arrangement, we recommend declaring your primary root exception -mappings on a `@ControllerAdvice` prioritized with a corresponding order. While a root -exception match is preferred to a cause, this is defined among the methods of a given -controller or `@ControllerAdvice` class. This means a cause match on a higher-priority -`@ControllerAdvice` bean is preferred to any match (for example, root) on a lower-priority -`@ControllerAdvice` bean. - -Last but not least, an `@ExceptionHandler` method implementation can choose to back -out of dealing with a given exception instance by rethrowing it in its original form. -This is useful in scenarios where you are interested only in root-level matches or in -matches within a specific context that cannot be statically determined. A rethrown -exception is propagated through the remaining resolution chain, as though -the given `@ExceptionHandler` method would not have matched in the first place. - -Support for `@ExceptionHandler` methods in Spring MVC is built on the `DispatcherServlet` -level, <> mechanism. - - -[[mvc-ann-exceptionhandler-args]] -==== Method Arguments -[.small]#<># - -`@ExceptionHandler` methods support the following arguments: - -[cols="1,2", options="header"] -|=== -| Method argument | Description - -| Exception type -| For access to the raised exception. - -| `HandlerMethod` -| For access to the controller method that raised the exception. - -| `WebRequest`, `NativeWebRequest` -| Generic access to request parameters and request and session attributes without direct - use of the Servlet API. - -| `jakarta.servlet.ServletRequest`, `jakarta.servlet.ServletResponse` -| Choose any specific request or response type (for example, `ServletRequest` or - `HttpServletRequest` or Spring's `MultipartRequest` or `MultipartHttpServletRequest`). - -| `jakarta.servlet.http.HttpSession` -| Enforces the presence of a session. As a consequence, such an argument is never `null`. + - Note that session access is not thread-safe. Consider setting the - `RequestMappingHandlerAdapter` instance's `synchronizeOnSession` flag to `true` if multiple - requests are allowed to access a session concurrently. - -| `java.security.Principal` -| Currently authenticated user -- possibly a specific `Principal` implementation class if known. - -| `HttpMethod` -| The HTTP method of the request. - -| `java.util.Locale` -| The current request locale, determined by the most specific `LocaleResolver` available -- in - effect, the configured `LocaleResolver` or `LocaleContextResolver`. - -| `java.util.TimeZone`, `java.time.ZoneId` -| The time zone associated with the current request, as determined by a `LocaleContextResolver`. - -| `java.io.OutputStream`, `java.io.Writer` -| For access to the raw response body, as exposed by the Servlet API. - -| `java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap` -| For access to the model for an error response. Always empty. - -| `RedirectAttributes` -| Specify attributes to use in case of a redirect -- (that is to be appended to the query - string) and flash attributes to be stored temporarily until the request after the redirect. - See <> and <>. - -| `@SessionAttribute` -| For access to any session attribute, in contrast to model attributes stored in the - session as a result of a class-level `@SessionAttributes` declaration. - See <> for more details. - -| `@RequestAttribute` -| For access to request attributes. See <> for more details. - -|=== - - -[[mvc-ann-exceptionhandler-return-values]] -==== Return Values -[.small]#<># - -`@ExceptionHandler` methods support the following return values: - -[cols="1,2", options="header"] -|=== -| Return value | Description - -| `@ResponseBody` -| The return value is converted through `HttpMessageConverter` instances and written to the - response. See <>. - -| `HttpEntity`, `ResponseEntity` -| The return value specifies that the full response (including the HTTP headers and the body) - be converted through `HttpMessageConverter` instances and written to the response. - See <>. - -| `ErrorResponse` -| To render an RFC 7807 error response with details in the body, -see <> - -| `ProblemDetail` -| To render an RFC 7807 error response with details in the body, -see <> - -| `String` -| A view name to be resolved with `ViewResolver` implementations and used together with the - implicit model -- determined through command objects and `@ModelAttribute` methods. - The handler method can also programmatically enrich the model by declaring a `Model` - argument (described earlier). - -| `View` -| A `View` instance to use for rendering together with the implicit model -- determined - through command objects and `@ModelAttribute` methods. The handler method may also - programmatically enrich the model by declaring a `Model` argument (descried earlier). - -| `java.util.Map`, `org.springframework.ui.Model` -| Attributes to be added to the implicit model with the view name implicitly determined - through a `RequestToViewNameTranslator`. - -| `@ModelAttribute` -| An attribute to be added to the model with the view name implicitly determined through - a `RequestToViewNameTranslator`. - - Note that `@ModelAttribute` is optional. See "`Any other return value`" at the end of - this table. - -| `ModelAndView` object -| The view and model attributes to use and, optionally, a response status. - -| `void` -| A method with a `void` return type (or `null` return value) is considered to have fully - handled the response if it also has a `ServletResponse` an `OutputStream` argument, or - a `@ResponseStatus` annotation. The same is also true if the controller has made a positive - `ETag` or `lastModified` timestamp check (see <> for details). - - If none of the above is true, a `void` return type can also indicate "`no response body`" for - REST controllers or default view name selection for HTML controllers. - -| Any other return value -| If a return value is not matched to any of the above and is not a simple type (as determined by - {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]), - by default, it is treated as a model attribute to be added to the model. If it is a simple type, - it remains unresolved. -|=== - - - -[[mvc-ann-controller-advice]] -=== Controller Advice -[.small]#<># - -`@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply only to the -`@Controller` class, or class hierarchy, in which they are declared. If, instead, they -are declared in an `@ControllerAdvice` or `@RestControllerAdvice` class, then they apply -to any controller. Moreover, as of 5.3, `@ExceptionHandler` methods in `@ControllerAdvice` -can be used to handle exceptions from any `@Controller` or any other handler. - -`@ControllerAdvice` is meta-annotated with `@Component` and therefore can be registered as -a Spring bean through <>. `@RestControllerAdvice` is meta-annotated with `@ControllerAdvice` -and `@ResponseBody`, and that means `@ExceptionHandler` methods will have their return -value rendered via response body message conversion, rather than via HTML views. - -On startup, `RequestMappingHandlerMapping` and `ExceptionHandlerExceptionResolver` detect -controller advice beans and apply them at runtime. Global `@ExceptionHandler` methods, -from an `@ControllerAdvice`, are applied _after_ local ones, from the `@Controller`. -By contrast, global `@ModelAttribute` and `@InitBinder` methods are applied _before_ local ones. - -The `@ControllerAdvice` annotation has attributes that let you narrow the set of controllers -and handlers that they apply to. For example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Target all Controllers annotated with @RestController - @ControllerAdvice(annotations = RestController.class) - public class ExampleAdvice1 {} - - // Target all Controllers within specific packages - @ControllerAdvice("org.example.controllers") - public class ExampleAdvice2 {} - - // Target all Controllers assignable to specific classes - @ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class}) - public class ExampleAdvice3 {} ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Target all Controllers annotated with @RestController - @ControllerAdvice(annotations = [RestController::class]) - class ExampleAdvice1 - - // Target all Controllers within specific packages - @ControllerAdvice("org.example.controllers") - class ExampleAdvice2 - - // Target all Controllers assignable to specific classes - @ControllerAdvice(assignableTypes = [ControllerInterface::class, AbstractController::class]) - class ExampleAdvice3 ----- - -The selectors in the preceding example are evaluated at runtime and may negatively impact -performance if used extensively. See the -{api-spring-framework}/web/bind/annotation/ControllerAdvice.html[`@ControllerAdvice`] -javadoc for more details. - -include::webmvc-functional.adoc[leveloffset=+1] - - - -[[mvc-uri-building]] -== URI Links -[.small]#<># - -This section describes various options available in the Spring Framework to work with URI's. - -include::web-uris.adoc[leveloffset=+2] - - - -[[mvc-servleturicomponentsbuilder]] -=== Relative Servlet Requests - -You can use `ServletUriComponentsBuilder` to create URIs relative to the current request, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpServletRequest request = ... - - // Re-uses scheme, host, port, path, and query string... - - URI uri = ServletUriComponentsBuilder.fromRequest(request) - .replaceQueryParam("accountId", "{id}") - .build("123"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val request: HttpServletRequest = ... - - // Re-uses scheme, host, port, path, and query string... - - val uri = ServletUriComponentsBuilder.fromRequest(request) - .replaceQueryParam("accountId", "{id}") - .build("123") ----- - -You can create URIs relative to the context path, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpServletRequest request = ... - - // Re-uses scheme, host, port, and context path... - - URI uri = ServletUriComponentsBuilder.fromContextPath(request) - .path("/accounts") - .build() - .toUri(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val request: HttpServletRequest = ... - - // Re-uses scheme, host, port, and context path... - - val uri = ServletUriComponentsBuilder.fromContextPath(request) - .path("/accounts") - .build() - .toUri() ----- - -You can create URIs relative to a Servlet (for example, `/main/{asterisk}`), -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - HttpServletRequest request = ... - - // Re-uses scheme, host, port, context path, and Servlet mapping prefix... - - URI uri = ServletUriComponentsBuilder.fromServletMapping(request) - .path("/accounts") - .build() - .toUri(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val request: HttpServletRequest = ... - - // Re-uses scheme, host, port, context path, and Servlet mapping prefix... - - val uri = ServletUriComponentsBuilder.fromServletMapping(request) - .path("/accounts") - .build() - .toUri() ----- - -NOTE: As of 5.1, `ServletUriComponentsBuilder` ignores information from the `Forwarded` and -`X-Forwarded-*` headers, which specify the client-originated address. Consider using the -<> to extract and use or to discard -such headers. - - - -[[mvc-links-to-controllers]] -=== Links to Controllers - -Spring MVC provides a mechanism to prepare links to controller methods. For example, -the following MVC controller allows for link creation: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - @RequestMapping("/hotels/{hotel}") - public class BookingController { - - @GetMapping("/bookings/{booking}") - public ModelAndView getBooking(@PathVariable Long booking) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - @RequestMapping("/hotels/{hotel}") - class BookingController { - - @GetMapping("/bookings/{booking}") - fun getBooking(@PathVariable booking: Long): ModelAndView { - // ... - } - } ----- - -You can prepare a link by referring to the method by name, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - UriComponents uriComponents = MvcUriComponentsBuilder - .fromMethodName(BookingController.class, "getBooking", 21).buildAndExpand(42); - - URI uri = uriComponents.encode().toUri(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val uriComponents = MvcUriComponentsBuilder - .fromMethodName(BookingController::class.java, "getBooking", 21).buildAndExpand(42) - - val uri = uriComponents.encode().toUri() ----- - -In the preceding example, we provide actual method argument values (in this case, the long value: `21`) -to be used as a path variable and inserted into the URL. Furthermore, we provide the -value, `42`, to fill in any remaining URI variables, such as the `hotel` variable inherited -from the type-level request mapping. If the method had more arguments, we could supply null for -arguments not needed for the URL. In general, only `@PathVariable` and `@RequestParam` arguments -are relevant for constructing the URL. - -There are additional ways to use `MvcUriComponentsBuilder`. For example, you can use a technique -akin to mock testing through proxies to avoid referring to the controller method by name, as the following example shows -(the example assumes static import of `MvcUriComponentsBuilder.on`): - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - UriComponents uriComponents = MvcUriComponentsBuilder - .fromMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42); - - URI uri = uriComponents.encode().toUri(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val uriComponents = MvcUriComponentsBuilder - .fromMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42) - - val uri = uriComponents.encode().toUri() ----- - -NOTE: Controller method signatures are limited in their design when they are supposed to be usable for -link creation with `fromMethodCall`. Aside from needing a proper parameter signature, -there is a technical limitation on the return type (namely, generating a runtime proxy -for link builder invocations), so the return type must not be `final`. In particular, -the common `String` return type for view names does not work here. You should use `ModelAndView` -or even plain `Object` (with a `String` return value) instead. - -The earlier examples use static methods in `MvcUriComponentsBuilder`. Internally, they rely -on `ServletUriComponentsBuilder` to prepare a base URL from the scheme, host, port, -context path, and servlet path of the current request. This works well in most cases. -However, sometimes, it can be insufficient. For example, you may be outside the context of -a request (such as a batch process that prepares links) or perhaps you need to insert a path -prefix (such as a locale prefix that was removed from the request path and needs to be -re-inserted into links). - -For such cases, you can use the static `fromXxx` overloaded methods that accept a -`UriComponentsBuilder` to use a base URL. Alternatively, you can create an instance of `MvcUriComponentsBuilder` -with a base URL and then use the instance-based `withXxx` methods. For example, the -following listing uses `withMethodCall`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - UriComponentsBuilder base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en"); - MvcUriComponentsBuilder builder = MvcUriComponentsBuilder.relativeTo(base); - builder.withMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42); - - URI uri = uriComponents.encode().toUri(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en") - val builder = MvcUriComponentsBuilder.relativeTo(base) - builder.withMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42) - - val uri = uriComponents.encode().toUri() ----- - -NOTE: As of 5.1, `MvcUriComponentsBuilder` ignores information from the `Forwarded` and -`X-Forwarded-*` headers, which specify the client-originated address. Consider using the -<> to extract and use or to discard -such headers. - - - -[[mvc-links-to-controllers-from-views]] -=== Links in Views - -In views such as Thymeleaf, FreeMarker, or JSP, you can build links to annotated controllers -by referring to the implicitly or explicitly assigned name for each request mapping. - -Consider the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RequestMapping("/people/{id}/addresses") - public class PersonAddressController { - - @RequestMapping("/{country}") - public HttpEntity getAddress(@PathVariable String country) { ... } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RequestMapping("/people/{id}/addresses") - class PersonAddressController { - - @RequestMapping("/{country}") - fun getAddress(@PathVariable country: String): HttpEntity { ... } - } ----- - -Given the preceding controller, you can prepare a link from a JSP, as follows: - -[source,jsp,indent=0,subs="verbatim,quotes"] ----- -<%@ taglib uri="http://www.springframework.org/tags" prefix="s" %> -... -Get Address ----- - -The preceding example relies on the `mvcUrl` function declared in the Spring tag library -(that is, META-INF/spring.tld), but it is easy to define your own function or prepare a -similar one for other templating technologies. - -Here is how this works. On startup, every `@RequestMapping` is assigned a default name -through `HandlerMethodMappingNamingStrategy`, whose default implementation uses the -capital letters of the class and the method name (for example, the `getThing` method in -`ThingController` becomes "TC#getThing"). If there is a name clash, you can use -`@RequestMapping(name="..")` to assign an explicit name or implement your own -`HandlerMethodMappingNamingStrategy`. - - - - -[[mvc-ann-async]] -== Asynchronous Requests - -Spring MVC has an extensive integration with Servlet asynchronous request -<>: - -* <> and <> -return values in controller methods provide basic support for a single asynchronous -return value. -* Controllers can <> multiple values, including -<> and <>. -* Controllers can use reactive clients and return -<> for response handling. - -For an overview of how this differs from Spring WebFlux, see the <> section below. - -[[mvc-ann-async-deferredresult]] -=== `DeferredResult` - -Once the asynchronous request processing feature is <> -in the Servlet container, controller methods can wrap any supported controller method -return value with `DeferredResult`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/quotes") - @ResponseBody - public DeferredResult quotes() { - DeferredResult deferredResult = new DeferredResult<>(); - // Save the deferredResult somewhere.. - return deferredResult; - } - - // From some other thread... - deferredResult.setResult(result); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/quotes") - @ResponseBody - fun quotes(): DeferredResult { - val deferredResult = DeferredResult() - // Save the deferredResult somewhere.. - return deferredResult - } - - // From some other thread... - deferredResult.setResult(result) ----- - -The controller can produce the return value asynchronously, from a different thread -- for -example, in response to an external event (JMS message), a scheduled task, or other event. - - - -[[mvc-ann-async-callable]] -=== `Callable` - -A controller can wrap any supported return value with `java.util.concurrent.Callable`, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @PostMapping - public Callable processUpload(final MultipartFile file) { - return () -> "someView"; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @PostMapping - fun processUpload(file: MultipartFile) = Callable { - // ... - "someView" - } ----- - -The return value can then be obtained by running the given task through the -<> `TaskExecutor`. - - - -[[mvc-ann-async-processing]] -=== Processing - -Here is a very concise overview of Servlet asynchronous request processing: - -* A `ServletRequest` can be put in asynchronous mode by calling `request.startAsync()`. - The main effect of doing so is that the Servlet (as well as any filters) can exit, but - the response remains open to let processing complete later. -* The call to `request.startAsync()` returns `AsyncContext`, which you can use for - further control over asynchronous processing. For example, it provides the `dispatch` method, - which is similar to a forward from the Servlet API, except that it lets an - application resume request processing on a Servlet container thread. -* The `ServletRequest` provides access to the current `DispatcherType`, which you can - use to distinguish between processing the initial request, an asynchronous - dispatch, a forward, and other dispatcher types. - -`DeferredResult` processing works as follows: - -* The controller returns a `DeferredResult` and saves it in some in-memory - queue or list where it can be accessed. -* Spring MVC calls `request.startAsync()`. -* Meanwhile, the `DispatcherServlet` and all configured filters exit the request - processing thread, but the response remains open. -* The application sets the `DeferredResult` from some thread, and Spring MVC - dispatches the request back to the Servlet container. -* The `DispatcherServlet` is invoked again, and processing resumes with the - asynchronously produced return value. - -`Callable` processing works as follows: - -* The controller returns a `Callable`. -* Spring MVC calls `request.startAsync()` and submits the `Callable` to - a `TaskExecutor` for processing in a separate thread. -* Meanwhile, the `DispatcherServlet` and all filters exit the Servlet container thread, - but the response remains open. -* Eventually the `Callable` produces a result, and Spring MVC dispatches the request back - to the Servlet container to complete processing. -* The `DispatcherServlet` is invoked again, and processing resumes with the - asynchronously produced return value from the `Callable`. - -For further background and context, you can also read -https://spring.io/blog/2012/05/07/spring-mvc-3-2-preview-introducing-servlet-3-async-support[the -blog posts] that introduced asynchronous request processing support in Spring MVC 3.2. - - -[[mvc-ann-async-exceptions]] -==== Exception Handling - -When you use a `DeferredResult`, you can choose whether to call `setResult` or -`setErrorResult` with an exception. In both cases, Spring MVC dispatches the request back -to the Servlet container to complete processing. It is then treated either as if the -controller method returned the given value or as if it produced the given exception. -The exception then goes through the regular exception handling mechanism (for example, invoking -`@ExceptionHandler` methods). - -When you use `Callable`, similar processing logic occurs, the main difference being that -the result is returned from the `Callable` or an exception is raised by it. - - -[[mvc-ann-async-interception]] -==== Interception - -`HandlerInterceptor` instances can be of type `AsyncHandlerInterceptor`, to receive the -`afterConcurrentHandlingStarted` callback on the initial request that starts asynchronous -processing (instead of `postHandle` and `afterCompletion`). - -`HandlerInterceptor` implementations can also register a `CallableProcessingInterceptor` -or a `DeferredResultProcessingInterceptor`, to integrate more deeply with the -lifecycle of an asynchronous request (for example, to handle a timeout event). See -{api-spring-framework}/web/servlet/AsyncHandlerInterceptor.html[`AsyncHandlerInterceptor`] -for more details. - -`DeferredResult` provides `onTimeout(Runnable)` and `onCompletion(Runnable)` callbacks. -See the {api-spring-framework}/web/context/request/async/DeferredResult.html[javadoc of `DeferredResult`] -for more details. `Callable` can be substituted for `WebAsyncTask` that exposes additional -methods for timeout and completion callbacks. - - -[[mvc-ann-async-vs-webflux]] -==== Async Spring MVC compared to WebFlux - -The Servlet API was originally built for making a single pass through the Filter-Servlet -chain. Asynchronous request processing lets applications exit the Filter-Servlet chain -but leave the response open for further processing. The Spring MVC asynchronous support -is built around that mechanism. When a controller returns a `DeferredResult`, the -Filter-Servlet chain is exited, and the Servlet container thread is released. Later, when -the `DeferredResult` is set, an `ASYNC` dispatch (to the same URL) is made, during which the -controller is mapped again but, rather than invoking it, the `DeferredResult` value is used -(as if the controller returned it) to resume processing. - -By contrast, Spring WebFlux is neither built on the Servlet API, nor does it need such an -asynchronous request processing feature, because it is asynchronous by design. Asynchronous -handling is built into all framework contracts and is intrinsically supported through all -stages of request processing. - -From a programming model perspective, both Spring MVC and Spring WebFlux support -asynchronous and <> as return values in controller methods. -Spring MVC even supports streaming, including reactive back pressure. However, individual -writes to the response remain blocking (and are performed on a separate thread), unlike WebFlux, -which relies on non-blocking I/O and does not need an extra thread for each write. - -Another fundamental difference is that Spring MVC does not support asynchronous or reactive -types in controller method arguments (for example, `@RequestBody`, `@RequestPart`, and others), -nor does it have any explicit support for asynchronous and reactive types as model attributes. -Spring WebFlux does support all that. - -Finally, from a configuration perspective the asynchronous request processing feature must be -<>. - - -[[mvc-ann-async-http-streaming]] -=== HTTP Streaming -[.small]#<># - -You can use `DeferredResult` and `Callable` for a single asynchronous return value. -What if you want to produce multiple asynchronous values and have those written to the -response? This section describes how to do so. - - -[[mvc-ann-async-objects]] -==== Objects - -You can use the `ResponseBodyEmitter` return value to produce a stream of objects, where -each object is serialized with an -<> and written to the -response, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/events") - public ResponseBodyEmitter handle() { - ResponseBodyEmitter emitter = new ResponseBodyEmitter(); - // Save the emitter somewhere.. - return emitter; - } - - // In some other thread - emitter.send("Hello once"); - - // and again later on - emitter.send("Hello again"); - - // and done at some point - emitter.complete(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/events") - fun handle() = ResponseBodyEmitter().apply { - // Save the emitter somewhere.. - } - - // In some other thread - emitter.send("Hello once") - - // and again later on - emitter.send("Hello again") - - // and done at some point - emitter.complete() ----- - -You can also use `ResponseBodyEmitter` as the body in a `ResponseEntity`, letting you -customize the status and headers of the response. - -When an `emitter` throws an `IOException` (for example, if the remote client went away), applications -are not responsible for cleaning up the connection and should not invoke `emitter.complete` -or `emitter.completeWithError`. Instead, the servlet container automatically initiates an -`AsyncListener` error notification, in which Spring MVC makes a `completeWithError` call. -This call, in turn, performs one final `ASYNC` dispatch to the application, during which Spring MVC -invokes the configured exception resolvers and completes the request. - - -[[mvc-ann-async-sse]] -==== SSE - -`SseEmitter` (a subclass of `ResponseBodyEmitter`) provides support for -https://www.w3.org/TR/eventsource/[Server-Sent Events], where events sent from the server -are formatted according to the W3C SSE specification. To produce an SSE -stream from a controller, return `SseEmitter`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping(path="/events", produces=MediaType.TEXT_EVENT_STREAM_VALUE) - public SseEmitter handle() { - SseEmitter emitter = new SseEmitter(); - // Save the emitter somewhere.. - return emitter; - } - - // In some other thread - emitter.send("Hello once"); - - // and again later on - emitter.send("Hello again"); - - // and done at some point - emitter.complete(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/events", produces = [MediaType.TEXT_EVENT_STREAM_VALUE]) - fun handle() = SseEmitter().apply { - // Save the emitter somewhere.. - } - - // In some other thread - emitter.send("Hello once") - - // and again later on - emitter.send("Hello again") - - // and done at some point - emitter.complete() ----- - -While SSE is the main option for streaming into browsers, note that Internet Explorer -does not support Server-Sent Events. Consider using Spring's -<> with -<> transports (including SSE) that target -a wide range of browsers. - -See also <> for notes on exception handling. - - -[[mvc-ann-async-output-stream]] -==== Raw Data - -Sometimes, it is useful to bypass message conversion and stream directly to the response -`OutputStream` (for example, for a file download). You can use the `StreamingResponseBody` -return value type to do so, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/download") - public StreamingResponseBody handle() { - return new StreamingResponseBody() { - @Override - public void writeTo(OutputStream outputStream) throws IOException { - // write... - } - }; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/download") - fun handle() = StreamingResponseBody { - // write... - } ----- - -You can use `StreamingResponseBody` as the body in a `ResponseEntity` to -customize the status and headers of the response. - - - -[[mvc-ann-async-reactive-types]] -=== Reactive Types -[.small]#<># - -Spring MVC supports use of reactive client libraries in a controller (also read -<> in the WebFlux section). -This includes the `WebClient` from `spring-webflux` and others, such as Spring Data -reactive data repositories. In such scenarios, it is convenient to be able to return -reactive types from the controller method. - -Reactive return values are handled as follows: - -* A single-value promise is adapted to, similar to using `DeferredResult`. Examples -include `Mono` (Reactor) or `Single` (RxJava). -* A multi-value stream with a streaming media type (such as `application/x-ndjson` -or `text/event-stream`) is adapted to, similar to using `ResponseBodyEmitter` or -`SseEmitter`. Examples include `Flux` (Reactor) or `Observable` (RxJava). -Applications can also return `Flux` or `Observable`. -* A multi-value stream with any other media type (such as `application/json`) is adapted -to, similar to using `DeferredResult>`. - -TIP: Spring MVC supports Reactor and RxJava through the -{api-spring-framework}/core/ReactiveAdapterRegistry.html[`ReactiveAdapterRegistry`] from -`spring-core`, which lets it adapt from multiple reactive libraries. - -For streaming to the response, reactive back pressure is supported, but writes to the -response are still blocking and are run on a separate thread through the -<> `TaskExecutor`, to avoid -blocking the upstream source (such as a `Flux` returned from `WebClient`). -By default, `SimpleAsyncTaskExecutor` is used for the blocking writes, but that is not -suitable under load. If you plan to stream with a reactive type, you should use the -<> to configure a task executor. - - - -[[mvc-ann-async-context-propagation]] -=== Context Propagation - -It is common to propagate context via `java.lang.ThreadLocal`. This works transparently -for handling on the same thread, but requires additional work for asynchronous handling -across multiple threads. The Micrometer -https://github.com/micrometer-metrics/context-propagation#context-propagation-library[Context Propagation] -library simplifies context propagation across threads, and across context mechanisms such -as `ThreadLocal` values, -Reactor https://projectreactor.io/docs/core/release/reference/#context[context], -GraphQL Java https://www.graphql-java.com/documentation/concerns/#context-objects[context], -and others. - -If Micrometer Context Propagation is present on the classpath, when a controller method -returns a <> such as `Flux` or `Mono`, all -`ThreadLocal` values, for which there is a registered `io.micrometer.ThreadLocalAccessor`, -are written to the Reactor `Context` as key-value pairs, using the key assigned by the -`ThreadLocalAccessor`. - -For other asynchronous handling scenarios, you can use the Context Propagation library -directly. For example: - -[source,java,indent=0,subs="verbatim,quotes"] -.Java ----- - // Capture ThreadLocal values from the main thread ... - ContextSnapshot snapshot = ContextSnapshot.captureAll(); - - // On a different thread: restore ThreadLocal values - try (ContextSnapshot.Scope scope = snapshot.setThreadLocals()) { - // ... - } ----- - -For more details, see the -https://micrometer.io/docs/contextPropagation[documentation] of the Micrometer Context -Propagation library. - - - -[[mvc-ann-async-disconnects]] -=== Disconnects -[.small]#<># - -The Servlet API does not provide any notification when a remote client goes away. -Therefore, while streaming to the response, whether through <> -or <>, it is important to send data periodically, -since the write fails if the client has disconnected. The send could take the form of an -empty (comment-only) SSE event or any other data that the other side would have to interpret -as a heartbeat and ignore. - -Alternatively, consider using web messaging solutions (such as -<> or WebSocket with <>) -that have a built-in heartbeat mechanism. - - - -[[mvc-ann-async-configuration]] -=== Configuration - -The asynchronous request processing feature must be enabled at the Servlet container level. -The MVC configuration also exposes several options for asynchronous requests. - - -[[mvc-ann-async-configuration-servlet3]] -==== Servlet Container - -Filter and Servlet declarations have an `asyncSupported` flag that needs to be set to `true` -to enable asynchronous request processing. In addition, Filter mappings should be -declared to handle the `ASYNC` `jakarta.servlet.DispatchType`. - -In Java configuration, when you use `AbstractAnnotationConfigDispatcherServletInitializer` -to initialize the Servlet container, this is done automatically. - -In `web.xml` configuration, you can add `true` to the -`DispatcherServlet` and to `Filter` declarations and add -`ASYNC` to filter mappings. - - -[[mvc-ann-async-configuration-spring-mvc]] -==== Spring MVC - -The MVC configuration exposes the following options related to asynchronous request processing: - -* Java configuration: Use the `configureAsyncSupport` callback on `WebMvcConfigurer`. -* XML namespace: Use the `` element under ``. - -You can configure the following: - -* Default timeout value for async requests, which if not set, depends -on the underlying Servlet container. -* `AsyncTaskExecutor` to use for blocking writes when streaming with -<> and for executing `Callable` instances returned from -controller methods. We highly recommended configuring this property if you -stream with reactive types or have controller methods that return `Callable`, since -by default, it is a `SimpleAsyncTaskExecutor`. -* `DeferredResultProcessingInterceptor` implementations and `CallableProcessingInterceptor` implementations. - -Note that you can also set the default timeout value on a `DeferredResult`, -a `ResponseBodyEmitter`, and an `SseEmitter`. For a `Callable`, you can use -`WebAsyncTask` to provide a timeout value. - - -include::webmvc-cors.adoc[leveloffset=+1] - - -[[mvc-ann-rest-exceptions]] -== Error Responses -[.small]#<># - -A common requirement for REST services is to include details in the body of error -responses. The Spring Framework supports the "Problem Details for HTTP APIs" -specification, https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807]. - -The following are the main abstractions for this support: - -- `ProblemDetail` -- representation for an RFC 7807 problem detail; a simple container -for both standard fields defined in the spec, and for non-standard ones. -- `ErrorResponse` -- contract to expose HTTP error response details including HTTP -status, response headers, and a body in the format of RFC 7807; this allows exceptions to -encapsulate and expose the details of how they map to an HTTP response. All Spring MVC -exceptions implement this. -- `ErrorResponseException` -- basic `ErrorResponse` implementation that others -can use as a convenient base class. -- `ResponseEntityExceptionHandler` -- convenient base class for an -<> that handles all Spring MVC exceptions, -and any `ErrorResponseException`, and renders an error response with a body. - - - -[[mvc-ann-rest-exceptions-render]] -=== Render -[.small]#<># - -You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from -any `@RequestMapping` method to render an RFC 7807 response. This is processed as follows: - -- The `status` property of `ProblemDetail` determines the HTTP status. -- The `instance` property of `ProblemDetail` is set from the current URL path, if not -already set. -- For content negotiation, the Jackson `HttpMessageConverter` prefers -"application/problem+json" over "application/json" when rendering a `ProblemDetail`, -and also falls back on it if no compatible media type is found. - -To enable RFC 7807 responses for Spring WebFlux exceptions and for any -`ErrorResponseException`, extend `ResponseEntityExceptionHandler` and declare it as an -<> in Spring configuration. The handler -has an `@ExceptionHandler` method that handles any `ErrorResponse` exception, which -includes all built-in web exceptions. You can add more exception handling methods, and -use a protected method to map any exception to a `ProblemDetail`. - - - -[[mvc-ann-rest-exceptions-non-standard]] -=== Non-Standard Fields -[.small]#<># - -You can extend an RFC 7807 response with non-standard fields in one of two ways. - -One, insert into the "properties" `Map` of `ProblemDetail`. When using the Jackson -library, the Spring Framework registers `ProblemDetailJacksonMixin` that ensures this -"properties" `Map` is unwrapped and rendered as top level JSON properties in the -response, and likewise any unknown property during deserialization is inserted into -this `Map`. - -You can also extend `ProblemDetail` to add dedicated non-standard properties. -The copy constructor in `ProblemDetail` allows a subclass to make it easy to be created -from an existing `ProblemDetail`. This could be done centrally, e.g. from an -`@ControllerAdvice` such as `ResponseEntityExceptionHandler` that re-creates the -`ProblemDetail` of an exception into a subclass with the additional non-standard fields. - - - -[[mvc-ann-rest-exceptions-i18n]] -=== Internationalization -[.small]#<># - -It is a common requirement to internationalize error response details, and good practice -to customize the problem details for Spring MVC exceptions. This is supported as follows: - -- Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field -through a <>. -The actual message code value is parameterized with placeholders, e.g. -`"HTTP method {0} not supported"` to be expanded from the arguments. -- Each `ErrorResponse` also exposes a message code to resolve the "title" field. -- `ResponseEntityExceptionHandler` uses the message code and arguments to resolve the -"detail" and the "title" fields. - -By default, the message code for the "detail" field is "problemDetail." + the fully -qualified exception class name. Some exceptions may expose additional message codes in -which case a suffix is added to the default message code. The table below lists message -arguments and codes for Spring MVC exceptions: - -[[mvc-ann-rest-exceptions-codes]] -[cols="1,1,2", options="header"] -|=== -| Exception | Message Code | Message Code Arguments - -| `AsyncRequestTimeoutException` -| (default) -| - -| `ConversionNotSupportedException` -| (default) -| `{0}` property name, `{1}` property value - -| `HttpMediaTypeNotAcceptableException` -| (default) -| `{0}` list of supported media types - -| `HttpMediaTypeNotAcceptableException` -| (default) + ".parseError" -| - -| `HttpMediaTypeNotSupportedException` -| (default) -| `{0}` the media type that is not supported, `{1}` list of supported media types - -| `HttpMediaTypeNotSupportedException` -| (default) + ".parseError" -| - -| `HttpMessageNotReadableException` -| (default) -| - -| `HttpMessageNotWritableException` -| (default) -| - -| `HttpRequestMethodNotSupportedException` -| (default) -| `{0}` the current HTTP method, `{1}` the list of supported HTTP methods - -| `MethodArgumentNotValidException` -| (default) -| `{0}` the list of global errors, `{1}` the list of field errors. - Message codes and arguments for each error within the `BindingResult` are also resolved - via `MessageSource`. - -| `MissingRequestHeaderException` -| (default) -| `{0}` the header name - -| `MissingServletRequestParameterException` -| (default) -| `{0}` the request parameter name - -| `MissingMatrixVariableException` -| (default) -| `{0}` the matrix variable name - -| `MissingPathVariableException` -| (default) -| `{0}` the path variable name - -| `MissingRequestCookieException` -| (default) -| `{0}` the cookie name - -| `MissingServletRequestPartException` -| (default) -| `{0}` the part name - -| `NoHandlerFoundException` -| (default) -| - -| `TypeMismatchException` -| (default) -| `{0}` property name, `{1}` property value - -| `UnsatisfiedServletRequestParameterException` -| (default) -| `{0}` the list of parameter conditions - -|=== - -By default, the message code for the "title" field is "problemDetail.title." + the fully -qualified exception class name. - - - -[[mvc-ann-rest-exceptions-client]] -=== Client Handling -[.small]#<># - -A client application can catch `WebClientResponseException`, when using the `WebClient`, -or `RestClientResponseException` when using the `RestTemplate`, and use their -`getResponseBodyAs` methods to decode the error response body to any target type such as -`ProblemDetail`, or a subclass of `ProblemDetail`. - - - -[[mvc-web-security]] -== Web Security -[.small]#<># - -The https://spring.io/projects/spring-security[Spring Security] project provides support -for protecting web applications from malicious exploits. See the Spring Security -reference documentation, including: - -* {docs-spring-security}/servlet/integrations/mvc.html[Spring MVC Security] -* {docs-spring-security}/servlet/test/mockmvc/setup.html[Spring MVC Test Support] -* {docs-spring-security}/features/exploits/csrf.html#csrf-protection[CSRF protection] -* {docs-spring-security}/features/exploits/headers.html[Security Response Headers] - -https://hdiv.org/[HDIV] is another web security framework that integrates with Spring MVC. - - - - -[[mvc-caching]] -== HTTP Caching -[.small]#<># - -HTTP caching can significantly improve the performance of a web application. HTTP caching -revolves around the `Cache-Control` response header and, subsequently, conditional request -headers (such as `Last-Modified` and `ETag`). `Cache-Control` advises private (for example, browser) -and public (for example, proxy) caches on how to cache and re-use responses. An `ETag` header is used -to make a conditional request that may result in a 304 (NOT_MODIFIED) without a body, -if the content has not changed. `ETag` can be seen as a more sophisticated successor to -the `Last-Modified` header. - -This section describes the HTTP caching-related options that are available in Spring Web MVC. - - - -[[mvc-caching-cachecontrol]] -=== `CacheControl` -[.small]#<># - -{api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for -configuring settings related to the `Cache-Control` header and is accepted as an argument -in a number of places: - -* {api-spring-framework}/web/servlet/mvc/WebContentInterceptor.html[`WebContentInterceptor`] -* {api-spring-framework}/web/servlet/support/WebContentGenerator.html[`WebContentGenerator`] -* <> -* <> - -While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all possible -directives for the `Cache-Control` response header, the `CacheControl` type takes a -use case-oriented approach that focuses on the common scenarios: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // Cache for an hour - "Cache-Control: max-age=3600" - CacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS); - - // Prevent caching - "Cache-Control: no-store" - CacheControl ccNoStore = CacheControl.noStore(); - - // Cache for ten days in public and private caches, - // public caches should not transform the response - // "Cache-Control: max-age=864000, public, no-transform" - CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // Cache for an hour - "Cache-Control: max-age=3600" - val ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS) - - // Prevent caching - "Cache-Control: no-store" - val ccNoStore = CacheControl.noStore() - - // Cache for ten days in public and private caches, - // public caches should not transform the response - // "Cache-Control: max-age=864000, public, no-transform" - val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic() ----- - -`WebContentGenerator` also accepts a simpler `cachePeriod` property (defined in seconds) that -works as follows: - -* A `-1` value does not generate a `Cache-Control` response header. -* A `0` value prevents caching by using the `'Cache-Control: no-store'` directive. -* An `n > 0` value caches the given response for `n` seconds by using the -`'Cache-Control: max-age=n'` directive. - - - -[[mvc-caching-etag-lastmodified]] -=== Controllers -[.small]#<># - -Controllers can add explicit support for HTTP caching. We recommended doing so, since the -`lastModified` or `ETag` value for a resource needs to be calculated before it can be compared -against conditional request headers. A controller can add an `ETag` header and `Cache-Control` -settings to a `ResponseEntity`, as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @GetMapping("/book/{id}") - public ResponseEntity showBook(@PathVariable Long id) { - - Book book = findBook(id); - String version = book.getVersion(); - - return ResponseEntity - .ok() - .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS)) - .eTag(version) // lastModified is also available - .body(book); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @GetMapping("/book/{id}") - fun showBook(@PathVariable id: Long): ResponseEntity { - - val book = findBook(id); - val version = book.getVersion() - - return ResponseEntity - .ok() - .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS)) - .eTag(version) // lastModified is also available - .body(book) - } ----- --- - -The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison -to the conditional request headers indicates that the content has not changed. Otherwise, the -`ETag` and `Cache-Control` headers are added to the response. - -You can also make the check against conditional request headers in the controller, -as the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @RequestMapping - public String myHandleMethod(WebRequest request, Model model) { - - long eTag = ... // <1> - - if (request.checkNotModified(eTag)) { - return null; // <2> - } - - model.addAttribute(...); // <3> - return "myViewName"; - } ----- -<1> Application-specific calculation. -<2> The response has been set to 304 (NOT_MODIFIED) -- no further processing. -<3> Continue with the request processing. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @RequestMapping - fun myHandleMethod(request: WebRequest, model: Model): String? { - - val eTag: Long = ... // <1> - - if (request.checkNotModified(eTag)) { - return null // <2> - } - - model[...] = ... // <3> - return "myViewName" - } ----- -<1> Application-specific calculation. -<2> The response has been set to 304 (NOT_MODIFIED) -- no further processing. -<3> Continue with the request processing. --- - - -There are three variants for checking conditional requests against `eTag` values, `lastModified` -values, or both. For conditional `GET` and `HEAD` requests, you can set the response to -304 (NOT_MODIFIED). For conditional `POST`, `PUT`, and `DELETE`, you can instead set the response -to 412 (PRECONDITION_FAILED), to prevent concurrent modification. - - - -[[mvc-caching-static-resources]] -=== Static Resources -[.small]#<># - -You should serve static resources with a `Cache-Control` and conditional response headers -for optimal performance. See the section on configuring <>. - - - -[[mvc-httpcaching-shallowetag]] -=== `ETag` Filter - -You can use the `ShallowEtagHeaderFilter` to add "`shallow`" `eTag` values that are computed from the -response content and, thus, save bandwidth but not CPU time. See <>. - -include::webmvc-view.adoc[leveloffset=+1] - - - - -[[mvc-config]] -== MVC Config -[.small]#<># - -The MVC Java configuration and the MVC XML namespace provide default configuration -suitable for most applications and a configuration API to customize it. - -For more advanced customizations, which are not available in the configuration API, -see <> and <>. - -You do not need to understand the underlying beans created by the MVC Java configuration -and the MVC namespace. If you want to learn more, see <> -and <>. - - - -[[mvc-config-enable]] -=== Enable MVC Configuration -[.small]#<># - -In Java configuration, you can use the `@EnableWebMvc` annotation to enable MVC -configuration, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig { - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig ----- - -In XML configuration, you can use the `` element to enable MVC -configuration, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -The preceding example registers a number of Spring MVC -<> and adapts to dependencies -available on the classpath (for example, payload converters for JSON, XML, and others). - - - -[[mvc-config-customize]] -=== MVC Config API -[.small]#<># - -In Java configuration, you can implement the `WebMvcConfigurer` interface, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - // Implement configuration methods... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - // Implement configuration methods... - } ----- - - -In XML, you can check attributes and sub-elements of ``. You can -view the https://schema.spring.io/mvc/spring-mvc.xsd[Spring MVC XML schema] or use -the code completion feature of your IDE to discover what attributes and -sub-elements are available. - - - -[[mvc-config-conversion]] -=== Type Conversion -[.small]#<># - -By default, formatters for various number and date types are installed, along with support -for customization via `@NumberFormat` and `@DateTimeFormat` on fields. - -To register custom formatters and converters in Java config, use the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void addFormatters(FormatterRegistry registry) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun addFormatters(registry: FormatterRegistry) { - // ... - } - } ----- - -To do the same in XML config, use the following: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - - - - - - - - ----- - -By default Spring MVC considers the request Locale when parsing and formatting date -values. This works for forms where dates are represented as Strings with "input" form -fields. For "date" and "time" form fields, however, browsers use a fixed format defined -in the HTML spec. For such cases date and time formatting can be customized as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void addFormatters(FormatterRegistry registry) { - DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar(); - registrar.setUseIsoFormat(true); - registrar.registerFormatters(registry); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun addFormatters(registry: FormatterRegistry) { - val registrar = DateTimeFormatterRegistrar() - registrar.setUseIsoFormat(true) - registrar.registerFormatters(registry) - } - } ----- - -NOTE: See <> -and the `FormattingConversionServiceFactoryBean` for more information on when to use -FormatterRegistrar implementations. - - - -[[mvc-config-validation]] -=== Validation -[.small]#<># - -By default, if <> is present -on the classpath (for example, Hibernate Validator), the `LocalValidatorFactoryBean` is -registered as a global <> for use with `@Valid` and -`Validated` on controller method arguments. - -In Java configuration, you can customize the global `Validator` instance, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public Validator getValidator() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun getValidator(): Validator { - // ... - } - } ----- - -The following example shows how to achieve the same configuration in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -Note that you can also register `Validator` implementations locally, as the following -example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Controller - public class MyController { - - @InitBinder - protected void initBinder(WebDataBinder binder) { - binder.addValidators(new FooValidator()); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Controller - class MyController { - - @InitBinder - protected fun initBinder(binder: WebDataBinder) { - binder.addValidators(FooValidator()) - } - } ----- - -TIP: If you need to have a `LocalValidatorFactoryBean` injected somewhere, create a bean and -mark it with `@Primary` in order to avoid conflict with the one declared in the MVC configuration. - - - -[[mvc-config-interceptors]] -=== Interceptors - -In Java configuration, you can register interceptors to apply to incoming requests, as -the following example shows: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void addInterceptors(InterceptorRegistry registry) { - registry.addInterceptor(new LocaleChangeInterceptor()); - registry.addInterceptor(new ThemeChangeInterceptor()).addPathPatterns("/**").excludePathPatterns("/admin/**"); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun addInterceptors(registry: InterceptorRegistry) { - registry.addInterceptor(LocaleChangeInterceptor()) - registry.addInterceptor(ThemeChangeInterceptor()).addPathPatterns("/**").excludePathPatterns("/admin/**") - } - } ----- - -The following example shows how to achieve the same configuration in XML: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - ----- - -NOTE: Mapped interceptors are not ideally suited as a security layer due to the potential -for a mismatch with annotated controller path matching, which can also match trailing -slashes and path extensions transparently, along with other path matching options. Many -of these options have been deprecated but the potential for a mismatch remains. -Generally, we recommend using Spring Security which includes a dedicated -https://docs.spring.io/spring-security/reference/servlet/integrations/mvc.html#mvc-requestmatcher[MvcRequestMatcher] -to align with Spring MVC path matching and also has a security firewall that blocks many -unwanted characters in URL paths. - - - - -[[mvc-config-content-negotiation]] -=== Content Types -[.small]#<># - -You can configure how Spring MVC determines the requested media types from the request -(for example, `Accept` header, URL path extension, query parameter, and others). - -By default, only the `Accept` header is checked. - -If you must use URL-based content type resolution, consider using the query parameter -strategy over path extensions. See -<> and <> for -more details. - -In Java configuration, you can customize requested content type resolution, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configureContentNegotiation(ContentNegotiationConfigurer configurer) { - configurer.mediaType("json", MediaType.APPLICATION_JSON); - configurer.mediaType("xml", MediaType.APPLICATION_XML); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configureContentNegotiation(configurer: ContentNegotiationConfigurer) { - configurer.mediaType("json", MediaType.APPLICATION_JSON) - configurer.mediaType("xml", MediaType.APPLICATION_XML) - } - } ----- - - -The following example shows how to achieve the same configuration in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - json=application/json - xml=application/xml - - - ----- - - - -[[mvc-config-message-converters]] -=== Message Converters -[.small]#<># - -You can customize `HttpMessageConverter` in Java configuration by overriding -{api-spring-framework}/web/servlet/config/annotation/WebMvcConfigurer.html#configureMessageConverters-java.util.List-[`configureMessageConverters()`] -(to replace the default converters created by Spring MVC) or by overriding -{api-spring-framework}/web/servlet/config/annotation/WebMvcConfigurer.html#extendMessageConverters-java.util.List-[`extendMessageConverters()`] -(to customize the default converters or add additional converters to the default ones). - -The following example adds XML and Jackson JSON converters with a customized -`ObjectMapper` instead of the default ones: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfiguration implements WebMvcConfigurer { - - @Override - public void configureMessageConverters(List> converters) { - Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder() - .indentOutput(true) - .dateFormat(new SimpleDateFormat("yyyy-MM-dd")) - .modulesToInstall(new ParameterNamesModule()); - converters.add(new MappingJackson2HttpMessageConverter(builder.build())); - converters.add(new MappingJackson2XmlHttpMessageConverter(builder.createXmlMapper(true).build())); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfiguration : WebMvcConfigurer { - - override fun configureMessageConverters(converters: MutableList>) { - val builder = Jackson2ObjectMapperBuilder() - .indentOutput(true) - .dateFormat(SimpleDateFormat("yyyy-MM-dd")) - .modulesToInstall(ParameterNamesModule()) - converters.add(MappingJackson2HttpMessageConverter(builder.build())) - converters.add(MappingJackson2XmlHttpMessageConverter(builder.createXmlMapper(true).build())) ----- - -In the preceding example, -{api-spring-framework}/http/converter/json/Jackson2ObjectMapperBuilder.html[`Jackson2ObjectMapperBuilder`] -is used to create a common configuration for both `MappingJackson2HttpMessageConverter` and -`MappingJackson2XmlHttpMessageConverter` with indentation enabled, a customized date format, -and the registration of -https://github.com/FasterXML/jackson-module-parameter-names[`jackson-module-parameter-names`], -Which adds support for accessing parameter names (a feature added in Java 8). - -This builder customizes Jackson's default properties as follows: - -* https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/DeserializationFeature.html#FAIL_ON_UNKNOWN_PROPERTIES[`DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES`] is disabled. -* https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/MapperFeature.html#DEFAULT_VIEW_INCLUSION[`MapperFeature.DEFAULT_VIEW_INCLUSION`] is disabled. - -It also automatically registers the following well-known modules if they are detected on the classpath: - -* https://github.com/FasterXML/jackson-datatype-joda[jackson-datatype-joda]: Support for Joda-Time types. -* https://github.com/FasterXML/jackson-datatype-jsr310[jackson-datatype-jsr310]: Support for Java 8 Date and Time API types. -* https://github.com/FasterXML/jackson-datatype-jdk8[jackson-datatype-jdk8]: Support for other Java 8 types, such as `Optional`. -* https://github.com/FasterXML/jackson-module-kotlin[`jackson-module-kotlin`]: Support for Kotlin classes and data classes. - -NOTE: Enabling indentation with Jackson XML support requires -https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.codehaus.woodstox%22%20AND%20a%3A%22woodstox-core-asl%22[`woodstox-core-asl`] -dependency in addition to https://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jackson-dataformat-xml%22[`jackson-dataformat-xml`] one. - -Other interesting Jackson modules are available: - -* https://github.com/zalando/jackson-datatype-money[jackson-datatype-money]: Support for `javax.money` types (unofficial module). -* https://github.com/FasterXML/jackson-datatype-hibernate[jackson-datatype-hibernate]: Support for Hibernate-specific types and properties (including lazy-loading aspects). - -The following example shows how to achieve the same configuration in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - ----- - - - -[[mvc-config-view-controller]] -=== View Controllers - -This is a shortcut for defining a `ParameterizableViewController` that immediately -forwards to a view when invoked. You can use it in static cases when there is no Java controller -logic to run before the view generates the response. - -The following example of Java configuration forwards a request for `/` to a view called `home`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void addViewControllers(ViewControllerRegistry registry) { - registry.addViewController("/").setViewName("home"); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun addViewControllers(registry: ViewControllerRegistry) { - registry.addViewController("/").setViewName("home") - } - } ----- - -The following example achieves the same thing as the preceding example, but with XML, by -using the `` element: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -If an `@RequestMapping` method is mapped to a URL for any HTTP method then a view -controller cannot be used to handle the same URL. This is because a match by URL to an -annotated controller is considered a strong enough indication of endpoint ownership so -that a 405 (METHOD_NOT_ALLOWED), a 415 (UNSUPPORTED_MEDIA_TYPE), or similar response can -be sent to the client to help with debugging. For this reason it is recommended to avoid -splitting URL handling across an annotated controller and a view controller. - - - -[[mvc-config-view-resolvers]] -=== View Resolvers -[.small]#<># - -The MVC configuration simplifies the registration of view resolvers. - -The following Java configuration example configures content negotiation view -resolution by using JSP and Jackson as a default `View` for JSON rendering: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - registry.enableContentNegotiation(new MappingJackson2JsonView()); - registry.jsp(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - registry.enableContentNegotiation(MappingJackson2JsonView()) - registry.jsp() - } - } ----- - - -The following example shows how to achieve the same configuration in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -Note, however, that FreeMarker, Groovy Markup, and script templates also require -configuration of the underlying view technology. - -The MVC namespace provides dedicated elements. The following example works with FreeMarker: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - ----- - -In Java configuration, you can add the respective `Configurer` bean, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configureViewResolvers(ViewResolverRegistry registry) { - registry.enableContentNegotiation(new MappingJackson2JsonView()); - registry.freeMarker().cache(false); - } - - @Bean - public FreeMarkerConfigurer freeMarkerConfigurer() { - FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); - configurer.setTemplateLoaderPath("/freemarker"); - return configurer; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configureViewResolvers(registry: ViewResolverRegistry) { - registry.enableContentNegotiation(MappingJackson2JsonView()) - registry.freeMarker().cache(false) - } - - @Bean - fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply { - setTemplateLoaderPath("/freemarker") - } - } ----- - - - -[[mvc-config-static-resources]] -=== Static Resources -[.small]#<># - -This option provides a convenient way to serve static resources from a list of -{api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. - -In the next example, given a request that starts with `/resources`, the relative path is -used to find and serve static resources relative to `/public` under the web application -root or on the classpath under `/static`. The resources are served with a one-year future -expiration to ensure maximum use of the browser cache and a reduction in HTTP requests -made by the browser. The `Last-Modified` information is deduced from `Resource#lastModified` -so that HTTP conditional requests are supported with `"Last-Modified"` headers. - -The following listing shows how to do so with Java configuration: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void addResourceHandlers(ResourceHandlerRegistry registry) { - registry.addResourceHandler("/resources/**") - .addResourceLocations("/public", "classpath:/static/") - .setCacheControl(CacheControl.maxAge(Duration.ofDays(365))); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun addResourceHandlers(registry: ResourceHandlerRegistry) { - registry.addResourceHandler("/resources/**") - .addResourceLocations("/public", "classpath:/static/") - .setCacheControl(CacheControl.maxAge(Duration.ofDays(365))) - } - } ----- - -The following example shows how to achieve the same configuration in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -See also -<>. - -The resource handler also supports a chain of -{api-spring-framework}/web/servlet/resource/ResourceResolver.html[`ResourceResolver`] implementations and -{api-spring-framework}/web/servlet/resource/ResourceTransformer.html[`ResourceTransformer`] implementations, -which you can use to create a toolchain for working with optimized resources. - -You can use the `VersionResourceResolver` for versioned resource URLs based on an MD5 hash -computed from the content, a fixed application version, or other. A -`ContentVersionStrategy` (MD5 hash) is a good choice -- with some notable exceptions, such as -JavaScript resources used with a module loader. - -The following example shows how to use `VersionResourceResolver` in Java configuration: - -[source,java,indent=0,subs="verbatim",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void addResourceHandlers(ResourceHandlerRegistry registry) { - registry.addResourceHandler("/resources/**") - .addResourceLocations("/public/") - .resourceChain(true) - .addResolver(new VersionResourceResolver().addContentVersionStrategy("/**")); - } - } ----- -[source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun addResourceHandlers(registry: ResourceHandlerRegistry) { - registry.addResourceHandler("/resources/**") - .addResourceLocations("/public/") - .resourceChain(true) - .addResolver(VersionResourceResolver().addContentVersionStrategy("/**")) - } - } ----- - -The following example shows how to achieve the same configuration in XML: - -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - ----- - -You can then use `ResourceUrlProvider` to rewrite URLs and apply the full chain of resolvers and -transformers -- for example, to insert versions. The MVC configuration provides a `ResourceUrlProvider` -bean so that it can be injected into others. You can also make the rewrite transparent with the -`ResourceUrlEncodingFilter` for Thymeleaf, JSPs, FreeMarker, and others with URL tags that -rely on `HttpServletResponse#encodeURL`. - -Note that, when using both `EncodedResourceResolver` (for example, for serving gzipped or -brotli-encoded resources) and `VersionResourceResolver`, you must register them in this order. -That ensures content-based versions are always computed reliably, based on the unencoded file. - -For https://www.webjars.org/documentation[WebJars], versioned URLs like -`/webjars/jquery/1.2.0/jquery.min.js` are the recommended and most efficient way to use them. -The related resource location is configured out of the box with Spring Boot (or can be configured -manually via `ResourceHandlerRegistry`) and does not require to add the -`org.webjars:webjars-locator-core` dependency. - -Version-less URLs like `/webjars/jquery/jquery.min.js` are supported through the -`WebJarsResourceResolver` which is automatically registered when the -`org.webjars:webjars-locator-core` library is present on the classpath, at the cost of a -classpath scanning that could slow down application startup. The resolver can re-write URLs to -include the version of the jar and can also match against incoming URLs without versions --- for example, from `/webjars/jquery/jquery.min.js` to `/webjars/jquery/1.2.0/jquery.min.js`. - -TIP: The Java configuration based on `ResourceHandlerRegistry` provides further options -for fine-grained control, e.g. last-modified behavior and optimized resource resolution. - - - -[[mvc-default-servlet-handler]] -=== Default Servlet - -Spring MVC allows for mapping the `DispatcherServlet` to `/` (thus overriding the mapping -of the container's default Servlet), while still allowing static resource requests to be -handled by the container's default Servlet. It configures a -`DefaultServletHttpRequestHandler` with a URL mapping of `/**` and the lowest priority -relative to other URL mappings. - -This handler forwards all requests to the default Servlet. Therefore, it must -remain last in the order of all other URL `HandlerMappings`. That is the -case if you use ``. Alternatively, if you set up your -own customized `HandlerMapping` instance, be sure to set its `order` property to a value -lower than that of the `DefaultServletHttpRequestHandler`, which is `Integer.MAX_VALUE`. - -The following example shows how to enable the feature by using the default setup: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) { - configurer.enable(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configureDefaultServletHandling(configurer: DefaultServletHandlerConfigurer) { - configurer.enable() - } - } ----- - -The following example shows how to achieve the same configuration in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - -The caveat to overriding the `/` Servlet mapping is that the `RequestDispatcher` for the -default Servlet must be retrieved by name rather than by path. The -`DefaultServletHttpRequestHandler` tries to auto-detect the default Servlet for -the container at startup time, using a list of known names for most of the major Servlet -containers (including Tomcat, Jetty, GlassFish, JBoss, Resin, WebLogic, and WebSphere). -If the default Servlet has been custom-configured with a different name, or if a -different Servlet container is being used where the default Servlet name is unknown, -then you must explicitly provide the default Servlet's name, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) { - configurer.enable("myCustomDefaultServlet"); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configureDefaultServletHandling(configurer: DefaultServletHandlerConfigurer) { - configurer.enable("myCustomDefaultServlet") - } - } ----- - - -The following example shows how to achieve the same configuration in XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - ----- - - - -[[mvc-config-path-matching]] -=== Path Matching -[.small]#<># - -You can customize options related to path matching and treatment of the URL. -For details on the individual options, see the -{api-spring-framework}/web/servlet/config/annotation/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc. - -The following example shows how to customize path matching in Java configuration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableWebMvc - public class WebConfig implements WebMvcConfigurer { - - @Override - public void configurePathMatch(PathMatchConfigurer configurer) { - configurer.addPathPrefix("/api", HandlerTypePredicate.forAnnotation(RestController.class)); - } - - private PathPatternParser patternParser() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableWebMvc - class WebConfig : WebMvcConfigurer { - - override fun configurePathMatch(configurer: PathMatchConfigurer) { - configurer.addPathPrefix("/api", HandlerTypePredicate.forAnnotation(RestController::class.java)) - } - - fun patternParser(): PathPatternParser { - //... - } - } ----- - -The following example shows how to customize path matching in XML configuration: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - - - -[[mvc-config-advanced-java]] -=== Advanced Java Config -[.small]#<># - -`@EnableWebMvc` imports `DelegatingWebMvcConfiguration`, which: - -* Provides default Spring configuration for Spring MVC applications -* Detects and delegates to `WebMvcConfigurer` implementations to customize that configuration. - -For advanced mode, you can remove `@EnableWebMvc` and extend directly from -`DelegatingWebMvcConfiguration` instead of implementing `WebMvcConfigurer`, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class WebConfig extends DelegatingWebMvcConfiguration { - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class WebConfig : DelegatingWebMvcConfiguration() { - - // ... - } ----- - -You can keep existing methods in `WebConfig`, but you can now also override bean declarations -from the base class, and you can still have any number of other `WebMvcConfigurer` implementations on -the classpath. - - - -[[mvc-config-advanced-xml]] -=== Advanced XML Config - -The MVC namespace does not have an advanced mode. If you need to customize a property on -a bean that you cannot change otherwise, you can use the `BeanPostProcessor` lifecycle -hook of the Spring `ApplicationContext`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - public class MyPostProcessor implements BeanPostProcessor { - - public Object postProcessBeforeInitialization(Object bean, String name) throws BeansException { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - class MyPostProcessor : BeanPostProcessor { - - override fun postProcessBeforeInitialization(bean: Any, name: String): Any { - // ... - } - } ----- - - -Note that you need to declare `MyPostProcessor` as a bean, either explicitly in XML or -by letting it be detected through a `` declaration. - - - - -[[mvc-http2]] -== HTTP/2 -[.small]#<># - -Servlet 4 containers are required to support HTTP/2, and Spring Framework 5 is compatible -with Servlet API 4. From a programming model perspective, there is nothing specific that -applications need to do. However, there are considerations related to server configuration. -For more details, see the -https://github.com/spring-projects/spring-framework/wiki/HTTP-2-support[HTTP/2 wiki page]. - -The Servlet API does expose one construct related to HTTP/2. You can use the -`jakarta.servlet.http.PushBuilder` to proactively push resources to clients, and it -is supported as a <> to `@RequestMapping` methods. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc new file mode 100644 index 000000000000..b00b961187af --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc @@ -0,0 +1,102 @@ +[[filters]] += Filters + +[.small]#<># + +The `spring-web` module provides some useful filters: + +* <> +* <> +* <> +* <> + + + +[[filters-http-put]] +== Form Data + +Browsers can submit form data only through HTTP GET or HTTP POST but non-browser clients can also +use HTTP PUT, PATCH, and DELETE. The Servlet API requires `ServletRequest.getParameter{asterisk}()` +methods to support form field access only for HTTP POST. + +The `spring-web` module provides `FormContentFilter` to intercept HTTP PUT, PATCH, and DELETE +requests with a content type of `application/x-www-form-urlencoded`, read the form data from +the body of the request, and wrap the `ServletRequest` to make the form data +available through the `ServletRequest.getParameter{asterisk}()` family of methods. + + + +[[filters-forwarded-headers]] +== Forwarded Headers +[.small]#<># + +As a request goes through proxies (such as load balancers) the host, port, and +scheme may change, and that makes it a challenge to create links that point to the correct +host, port, and scheme from a client perspective. + +https://tools.ietf.org/html/rfc7239[RFC 7239] defines the `Forwarded` HTTP header +that proxies can use to provide information about the original request. There are other +non-standard headers, too, including `X-Forwarded-Host`, `X-Forwarded-Port`, +`X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`. + +`ForwardedHeaderFilter` is a Servlet filter that modifies the request in order to +a) change the host, port, and scheme based on `Forwarded` headers, and b) to remove those +headers to eliminate further impact. The filter relies on wrapping the request, and +therefore it must be ordered ahead of other filters, such as `RequestContextFilter`, that +should work with the modified and not the original request. + +There are security considerations for forwarded headers since an application cannot know +if the headers were added by a proxy, as intended, or by a malicious client. This is why +a proxy at the boundary of trust should be configured to remove untrusted `Forwarded` +headers that come from the outside. You can also configure the `ForwardedHeaderFilter` +with `removeOnly=true`, in which case it removes but does not use the headers. + +In order to support <> and error dispatches this +filter should be mapped with `DispatcherType.ASYNC` and also `DispatcherType.ERROR`. +If using Spring Framework's `AbstractAnnotationConfigDispatcherServletInitializer` +(see <>) all filters are automatically registered for all dispatch +types. However if registering the filter via `web.xml` or in Spring Boot via a +`FilterRegistrationBean` be sure to include `DispatcherType.ASYNC` and +`DispatcherType.ERROR` in addition to `DispatcherType.REQUEST`. + + + +[[filters-shallow-etag]] +== Shallow ETag + +The `ShallowEtagHeaderFilter` filter creates a "`shallow`" ETag by caching the content +written to the response and computing an MD5 hash from it. The next time a client sends, +it does the same, but it also compares the computed value against the `If-None-Match` +request header and, if the two are equal, returns a 304 (NOT_MODIFIED). + +This strategy saves network bandwidth but not CPU, as the full response must be computed +for each request. Other strategies at the controller level, described earlier, can avoid +the computation. See <>. + +This filter has a `writeWeakETag` parameter that configures the filter to write weak ETags +similar to the following: `W/"02a2d595e6ed9a0b24f027f2b63b134d6"` (as defined in +https://tools.ietf.org/html/rfc7232#section-2.3[RFC 7232 Section 2.3]). + +In order to support <> this filter must be mapped +with `DispatcherType.ASYNC` so that the filter can delay and successfully generate an +ETag to the end of the last async dispatch. If using Spring Framework's +`AbstractAnnotationConfigDispatcherServletInitializer` (see <>) +all filters are automatically registered for all dispatch types. However if registering +the filter via `web.xml` or in Spring Boot via a `FilterRegistrationBean` be sure to include +`DispatcherType.ASYNC`. + + + +[[filters-cors]] +== CORS +[.small]#<># + +Spring MVC provides fine-grained support for CORS configuration through annotations on +controllers. However, when used with Spring Security, we advise relying on the built-in +`CorsFilter` that must be ordered ahead of Spring Security's chain of filters. + +See the sections on <> and the <> for more details. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc new file mode 100644 index 000000000000..b6e47669799e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc @@ -0,0 +1,490 @@ +[[mvc-ann-async]] += Asynchronous Requests + +Spring MVC has an extensive integration with Servlet asynchronous request +<>: + +* <> and <> +return values in controller methods provide basic support for a single asynchronous +return value. +* Controllers can <> multiple values, including +<> and <>. +* Controllers can use reactive clients and return +<> for response handling. + +For an overview of how this differs from Spring WebFlux, see the <> section below. + +[[mvc-ann-async-deferredresult]] +== `DeferredResult` + +Once the asynchronous request processing feature is <> +in the Servlet container, controller methods can wrap any supported controller method +return value with `DeferredResult`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/quotes") + @ResponseBody + public DeferredResult quotes() { + DeferredResult deferredResult = new DeferredResult<>(); + // Save the deferredResult somewhere.. + return deferredResult; + } + + // From some other thread... + deferredResult.setResult(result); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/quotes") + @ResponseBody + fun quotes(): DeferredResult { + val deferredResult = DeferredResult() + // Save the deferredResult somewhere.. + return deferredResult + } + + // From some other thread... + deferredResult.setResult(result) +---- + +The controller can produce the return value asynchronously, from a different thread -- for +example, in response to an external event (JMS message), a scheduled task, or other event. + + + +[[mvc-ann-async-callable]] +== `Callable` + +A controller can wrap any supported return value with `java.util.concurrent.Callable`, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping + public Callable processUpload(final MultipartFile file) { + return () -> "someView"; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping + fun processUpload(file: MultipartFile) = Callable { + // ... + "someView" + } +---- + +The return value can then be obtained by running the given task through the +<> `TaskExecutor`. + + + +[[mvc-ann-async-processing]] +== Processing + +Here is a very concise overview of Servlet asynchronous request processing: + +* A `ServletRequest` can be put in asynchronous mode by calling `request.startAsync()`. + The main effect of doing so is that the Servlet (as well as any filters) can exit, but + the response remains open to let processing complete later. +* The call to `request.startAsync()` returns `AsyncContext`, which you can use for + further control over asynchronous processing. For example, it provides the `dispatch` method, + which is similar to a forward from the Servlet API, except that it lets an + application resume request processing on a Servlet container thread. +* The `ServletRequest` provides access to the current `DispatcherType`, which you can + use to distinguish between processing the initial request, an asynchronous + dispatch, a forward, and other dispatcher types. + +`DeferredResult` processing works as follows: + +* The controller returns a `DeferredResult` and saves it in some in-memory + queue or list where it can be accessed. +* Spring MVC calls `request.startAsync()`. +* Meanwhile, the `DispatcherServlet` and all configured filters exit the request + processing thread, but the response remains open. +* The application sets the `DeferredResult` from some thread, and Spring MVC + dispatches the request back to the Servlet container. +* The `DispatcherServlet` is invoked again, and processing resumes with the + asynchronously produced return value. + +`Callable` processing works as follows: + +* The controller returns a `Callable`. +* Spring MVC calls `request.startAsync()` and submits the `Callable` to + a `TaskExecutor` for processing in a separate thread. +* Meanwhile, the `DispatcherServlet` and all filters exit the Servlet container thread, + but the response remains open. +* Eventually the `Callable` produces a result, and Spring MVC dispatches the request back + to the Servlet container to complete processing. +* The `DispatcherServlet` is invoked again, and processing resumes with the + asynchronously produced return value from the `Callable`. + +For further background and context, you can also read +https://spring.io/blog/2012/05/07/spring-mvc-3-2-preview-introducing-servlet-3-async-support[the +blog posts] that introduced asynchronous request processing support in Spring MVC 3.2. + + +[[mvc-ann-async-exceptions]] +=== Exception Handling + +When you use a `DeferredResult`, you can choose whether to call `setResult` or +`setErrorResult` with an exception. In both cases, Spring MVC dispatches the request back +to the Servlet container to complete processing. It is then treated either as if the +controller method returned the given value or as if it produced the given exception. +The exception then goes through the regular exception handling mechanism (for example, invoking +`@ExceptionHandler` methods). + +When you use `Callable`, similar processing logic occurs, the main difference being that +the result is returned from the `Callable` or an exception is raised by it. + + +[[mvc-ann-async-interception]] +=== Interception + +`HandlerInterceptor` instances can be of type `AsyncHandlerInterceptor`, to receive the +`afterConcurrentHandlingStarted` callback on the initial request that starts asynchronous +processing (instead of `postHandle` and `afterCompletion`). + +`HandlerInterceptor` implementations can also register a `CallableProcessingInterceptor` +or a `DeferredResultProcessingInterceptor`, to integrate more deeply with the +lifecycle of an asynchronous request (for example, to handle a timeout event). See +{api-spring-framework}/web/servlet/AsyncHandlerInterceptor.html[`AsyncHandlerInterceptor`] +for more details. + +`DeferredResult` provides `onTimeout(Runnable)` and `onCompletion(Runnable)` callbacks. +See the {api-spring-framework}/web/context/request/async/DeferredResult.html[javadoc of `DeferredResult`] +for more details. `Callable` can be substituted for `WebAsyncTask` that exposes additional +methods for timeout and completion callbacks. + + +[[mvc-ann-async-vs-webflux]] +=== Async Spring MVC compared to WebFlux + +The Servlet API was originally built for making a single pass through the Filter-Servlet +chain. Asynchronous request processing lets applications exit the Filter-Servlet chain +but leave the response open for further processing. The Spring MVC asynchronous support +is built around that mechanism. When a controller returns a `DeferredResult`, the +Filter-Servlet chain is exited, and the Servlet container thread is released. Later, when +the `DeferredResult` is set, an `ASYNC` dispatch (to the same URL) is made, during which the +controller is mapped again but, rather than invoking it, the `DeferredResult` value is used +(as if the controller returned it) to resume processing. + +By contrast, Spring WebFlux is neither built on the Servlet API, nor does it need such an +asynchronous request processing feature, because it is asynchronous by design. Asynchronous +handling is built into all framework contracts and is intrinsically supported through all +stages of request processing. + +From a programming model perspective, both Spring MVC and Spring WebFlux support +asynchronous and <> as return values in controller methods. +Spring MVC even supports streaming, including reactive back pressure. However, individual +writes to the response remain blocking (and are performed on a separate thread), unlike WebFlux, +which relies on non-blocking I/O and does not need an extra thread for each write. + +Another fundamental difference is that Spring MVC does not support asynchronous or reactive +types in controller method arguments (for example, `@RequestBody`, `@RequestPart`, and others), +nor does it have any explicit support for asynchronous and reactive types as model attributes. +Spring WebFlux does support all that. + +Finally, from a configuration perspective the asynchronous request processing feature must be +<>. + + +[[mvc-ann-async-http-streaming]] +== HTTP Streaming +[.small]#<># + +You can use `DeferredResult` and `Callable` for a single asynchronous return value. +What if you want to produce multiple asynchronous values and have those written to the +response? This section describes how to do so. + + +[[mvc-ann-async-objects]] +=== Objects + +You can use the `ResponseBodyEmitter` return value to produce a stream of objects, where +each object is serialized with an +<> and written to the +response, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/events") + public ResponseBodyEmitter handle() { + ResponseBodyEmitter emitter = new ResponseBodyEmitter(); + // Save the emitter somewhere.. + return emitter; + } + + // In some other thread + emitter.send("Hello once"); + + // and again later on + emitter.send("Hello again"); + + // and done at some point + emitter.complete(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/events") + fun handle() = ResponseBodyEmitter().apply { + // Save the emitter somewhere.. + } + + // In some other thread + emitter.send("Hello once") + + // and again later on + emitter.send("Hello again") + + // and done at some point + emitter.complete() +---- + +You can also use `ResponseBodyEmitter` as the body in a `ResponseEntity`, letting you +customize the status and headers of the response. + +When an `emitter` throws an `IOException` (for example, if the remote client went away), applications +are not responsible for cleaning up the connection and should not invoke `emitter.complete` +or `emitter.completeWithError`. Instead, the servlet container automatically initiates an +`AsyncListener` error notification, in which Spring MVC makes a `completeWithError` call. +This call, in turn, performs one final `ASYNC` dispatch to the application, during which Spring MVC +invokes the configured exception resolvers and completes the request. + + +[[mvc-ann-async-sse]] +=== SSE + +`SseEmitter` (a subclass of `ResponseBodyEmitter`) provides support for +https://www.w3.org/TR/eventsource/[Server-Sent Events], where events sent from the server +are formatted according to the W3C SSE specification. To produce an SSE +stream from a controller, return `SseEmitter`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping(path="/events", produces=MediaType.TEXT_EVENT_STREAM_VALUE) + public SseEmitter handle() { + SseEmitter emitter = new SseEmitter(); + // Save the emitter somewhere.. + return emitter; + } + + // In some other thread + emitter.send("Hello once"); + + // and again later on + emitter.send("Hello again"); + + // and done at some point + emitter.complete(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/events", produces = [MediaType.TEXT_EVENT_STREAM_VALUE]) + fun handle() = SseEmitter().apply { + // Save the emitter somewhere.. + } + + // In some other thread + emitter.send("Hello once") + + // and again later on + emitter.send("Hello again") + + // and done at some point + emitter.complete() +---- + +While SSE is the main option for streaming into browsers, note that Internet Explorer +does not support Server-Sent Events. Consider using Spring's +<> with +<> transports (including SSE) that target +a wide range of browsers. + +See also <> for notes on exception handling. + + +[[mvc-ann-async-output-stream]] +=== Raw Data + +Sometimes, it is useful to bypass message conversion and stream directly to the response +`OutputStream` (for example, for a file download). You can use the `StreamingResponseBody` +return value type to do so, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/download") + public StreamingResponseBody handle() { + return new StreamingResponseBody() { + @Override + public void writeTo(OutputStream outputStream) throws IOException { + // write... + } + }; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/download") + fun handle() = StreamingResponseBody { + // write... + } +---- + +You can use `StreamingResponseBody` as the body in a `ResponseEntity` to +customize the status and headers of the response. + + + +[[mvc-ann-async-reactive-types]] +== Reactive Types +[.small]#<># + +Spring MVC supports use of reactive client libraries in a controller (also read +<> in the WebFlux section). +This includes the `WebClient` from `spring-webflux` and others, such as Spring Data +reactive data repositories. In such scenarios, it is convenient to be able to return +reactive types from the controller method. + +Reactive return values are handled as follows: + +* A single-value promise is adapted to, similar to using `DeferredResult`. Examples +include `Mono` (Reactor) or `Single` (RxJava). +* A multi-value stream with a streaming media type (such as `application/x-ndjson` +or `text/event-stream`) is adapted to, similar to using `ResponseBodyEmitter` or +`SseEmitter`. Examples include `Flux` (Reactor) or `Observable` (RxJava). +Applications can also return `Flux` or `Observable`. +* A multi-value stream with any other media type (such as `application/json`) is adapted +to, similar to using `DeferredResult>`. + +TIP: Spring MVC supports Reactor and RxJava through the +{api-spring-framework}/core/ReactiveAdapterRegistry.html[`ReactiveAdapterRegistry`] from +`spring-core`, which lets it adapt from multiple reactive libraries. + +For streaming to the response, reactive back pressure is supported, but writes to the +response are still blocking and are run on a separate thread through the +<> `TaskExecutor`, to avoid +blocking the upstream source (such as a `Flux` returned from `WebClient`). +By default, `SimpleAsyncTaskExecutor` is used for the blocking writes, but that is not +suitable under load. If you plan to stream with a reactive type, you should use the +<> to configure a task executor. + + + +[[mvc-ann-async-context-propagation]] +== Context Propagation + +It is common to propagate context via `java.lang.ThreadLocal`. This works transparently +for handling on the same thread, but requires additional work for asynchronous handling +across multiple threads. The Micrometer +https://github.com/micrometer-metrics/context-propagation#context-propagation-library[Context Propagation] +library simplifies context propagation across threads, and across context mechanisms such +as `ThreadLocal` values, +Reactor https://projectreactor.io/docs/core/release/reference/#context[context], +GraphQL Java https://www.graphql-java.com/documentation/concerns/#context-objects[context], +and others. + +If Micrometer Context Propagation is present on the classpath, when a controller method +returns a <> such as `Flux` or `Mono`, all +`ThreadLocal` values, for which there is a registered `io.micrometer.ThreadLocalAccessor`, +are written to the Reactor `Context` as key-value pairs, using the key assigned by the +`ThreadLocalAccessor`. + +For other asynchronous handling scenarios, you can use the Context Propagation library +directly. For example: + +[source,java,indent=0,subs="verbatim,quotes"] +.Java +---- + // Capture ThreadLocal values from the main thread ... + ContextSnapshot snapshot = ContextSnapshot.captureAll(); + + // On a different thread: restore ThreadLocal values + try (ContextSnapshot.Scope scope = snapshot.setThreadLocals()) { + // ... + } +---- + +For more details, see the +https://micrometer.io/docs/contextPropagation[documentation] of the Micrometer Context +Propagation library. + + + +[[mvc-ann-async-disconnects]] +== Disconnects +[.small]#<># + +The Servlet API does not provide any notification when a remote client goes away. +Therefore, while streaming to the response, whether through <> +or <>, it is important to send data periodically, +since the write fails if the client has disconnected. The send could take the form of an +empty (comment-only) SSE event or any other data that the other side would have to interpret +as a heartbeat and ignore. + +Alternatively, consider using web messaging solutions (such as +<> or WebSocket with <>) +that have a built-in heartbeat mechanism. + + + +[[mvc-ann-async-configuration]] +== Configuration + +The asynchronous request processing feature must be enabled at the Servlet container level. +The MVC configuration also exposes several options for asynchronous requests. + + +[[mvc-ann-async-configuration-servlet3]] +=== Servlet Container + +Filter and Servlet declarations have an `asyncSupported` flag that needs to be set to `true` +to enable asynchronous request processing. In addition, Filter mappings should be +declared to handle the `ASYNC` `jakarta.servlet.DispatchType`. + +In Java configuration, when you use `AbstractAnnotationConfigDispatcherServletInitializer` +to initialize the Servlet container, this is done automatically. + +In `web.xml` configuration, you can add `true` to the +`DispatcherServlet` and to `Filter` declarations and add +`ASYNC` to filter mappings. + + +[[mvc-ann-async-configuration-spring-mvc]] +=== Spring MVC + +The MVC configuration exposes the following options related to asynchronous request processing: + +* Java configuration: Use the `configureAsyncSupport` callback on `WebMvcConfigurer`. +* XML namespace: Use the `` element under ``. + +You can configure the following: + +* Default timeout value for async requests, which if not set, depends +on the underlying Servlet container. +* `AsyncTaskExecutor` to use for blocking writes when streaming with +<> and for executing `Callable` instances returned from +controller methods. We highly recommended configuring this property if you +stream with reactive types or have controller methods that return `Callable`, since +by default, it is a `SimpleAsyncTaskExecutor`. +* `DeferredResultProcessingInterceptor` implementations and `CallableProcessingInterceptor` implementations. + +Note that you can also set the default timeout value on a `DeferredResult`, +a `ResponseBodyEmitter`, and an `SseEmitter`. For a `Callable`, you can use +`WebAsyncTask` to provide a timeout value. + + +include:../:webmvc-cors.adoc[leveloffset=+1] + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc new file mode 100644 index 000000000000..65bac5f96bec --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc @@ -0,0 +1,189 @@ +[[mvc-ann-rest-exceptions]] += Error Responses + +[.small]#<># + +A common requirement for REST services is to include details in the body of error +responses. The Spring Framework supports the "Problem Details for HTTP APIs" +specification, https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807]. + +The following are the main abstractions for this support: + +- `ProblemDetail` -- representation for an RFC 7807 problem detail; a simple container +for both standard fields defined in the spec, and for non-standard ones. +- `ErrorResponse` -- contract to expose HTTP error response details including HTTP +status, response headers, and a body in the format of RFC 7807; this allows exceptions to +encapsulate and expose the details of how they map to an HTTP response. All Spring MVC +exceptions implement this. +- `ErrorResponseException` -- basic `ErrorResponse` implementation that others +can use as a convenient base class. +- `ResponseEntityExceptionHandler` -- convenient base class for an +<> that handles all Spring MVC exceptions, +and any `ErrorResponseException`, and renders an error response with a body. + + + +[[mvc-ann-rest-exceptions-render]] +== Render +[.small]#<># + +You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from +any `@RequestMapping` method to render an RFC 7807 response. This is processed as follows: + +- The `status` property of `ProblemDetail` determines the HTTP status. +- The `instance` property of `ProblemDetail` is set from the current URL path, if not +already set. +- For content negotiation, the Jackson `HttpMessageConverter` prefers +"application/problem+json" over "application/json" when rendering a `ProblemDetail`, +and also falls back on it if no compatible media type is found. + +To enable RFC 7807 responses for Spring WebFlux exceptions and for any +`ErrorResponseException`, extend `ResponseEntityExceptionHandler` and declare it as an +<> in Spring configuration. The handler +has an `@ExceptionHandler` method that handles any `ErrorResponse` exception, which +includes all built-in web exceptions. You can add more exception handling methods, and +use a protected method to map any exception to a `ProblemDetail`. + + + +[[mvc-ann-rest-exceptions-non-standard]] +== Non-Standard Fields +[.small]#<># + +You can extend an RFC 7807 response with non-standard fields in one of two ways. + +One, insert into the "properties" `Map` of `ProblemDetail`. When using the Jackson +library, the Spring Framework registers `ProblemDetailJacksonMixin` that ensures this +"properties" `Map` is unwrapped and rendered as top level JSON properties in the +response, and likewise any unknown property during deserialization is inserted into +this `Map`. + +You can also extend `ProblemDetail` to add dedicated non-standard properties. +The copy constructor in `ProblemDetail` allows a subclass to make it easy to be created +from an existing `ProblemDetail`. This could be done centrally, e.g. from an +`@ControllerAdvice` such as `ResponseEntityExceptionHandler` that re-creates the +`ProblemDetail` of an exception into a subclass with the additional non-standard fields. + + + +[[mvc-ann-rest-exceptions-i18n]] +== Internationalization +[.small]#<># + +It is a common requirement to internationalize error response details, and good practice +to customize the problem details for Spring MVC exceptions. This is supported as follows: + +- Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field +through a <>. +The actual message code value is parameterized with placeholders, e.g. +`"HTTP method {0} not supported"` to be expanded from the arguments. +- Each `ErrorResponse` also exposes a message code to resolve the "title" field. +- `ResponseEntityExceptionHandler` uses the message code and arguments to resolve the +"detail" and the "title" fields. + +By default, the message code for the "detail" field is "problemDetail." + the fully +qualified exception class name. Some exceptions may expose additional message codes in +which case a suffix is added to the default message code. The table below lists message +arguments and codes for Spring MVC exceptions: + +[[mvc-ann-rest-exceptions-codes]] +[cols="1,1,2", options="header"] +|=== +| Exception | Message Code | Message Code Arguments + +| `AsyncRequestTimeoutException` +| (default) +| + +| `ConversionNotSupportedException` +| (default) +| `{0}` property name, `{1}` property value + +| `HttpMediaTypeNotAcceptableException` +| (default) +| `{0}` list of supported media types + +| `HttpMediaTypeNotAcceptableException` +| (default) + ".parseError" +| + +| `HttpMediaTypeNotSupportedException` +| (default) +| `{0}` the media type that is not supported, `{1}` list of supported media types + +| `HttpMediaTypeNotSupportedException` +| (default) + ".parseError" +| + +| `HttpMessageNotReadableException` +| (default) +| + +| `HttpMessageNotWritableException` +| (default) +| + +| `HttpRequestMethodNotSupportedException` +| (default) +| `{0}` the current HTTP method, `{1}` the list of supported HTTP methods + +| `MethodArgumentNotValidException` +| (default) +| `{0}` the list of global errors, `{1}` the list of field errors. + Message codes and arguments for each error within the `BindingResult` are also resolved + via `MessageSource`. + +| `MissingRequestHeaderException` +| (default) +| `{0}` the header name + +| `MissingServletRequestParameterException` +| (default) +| `{0}` the request parameter name + +| `MissingMatrixVariableException` +| (default) +| `{0}` the matrix variable name + +| `MissingPathVariableException` +| (default) +| `{0}` the path variable name + +| `MissingRequestCookieException` +| (default) +| `{0}` the cookie name + +| `MissingServletRequestPartException` +| (default) +| `{0}` the part name + +| `NoHandlerFoundException` +| (default) +| + +| `TypeMismatchException` +| (default) +| `{0}` property name, `{1}` property value + +| `UnsatisfiedServletRequestParameterException` +| (default) +| `{0}` the list of parameter conditions + +|=== + +By default, the message code for the "title" field is "problemDetail.title." + the fully +qualified exception class name. + + + +[[mvc-ann-rest-exceptions-client]] +== Client Handling +[.small]#<># + +A client application can catch `WebClientResponseException`, when using the `WebClient`, +or `RestClientResponseException` when using the `RestTemplate`, and use their +`getResponseBodyAs` methods to decode the error response body to any target type such as +`ProblemDetail`, or a subclass of `ProblemDetail`. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc new file mode 100644 index 000000000000..35f5ef7add26 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc @@ -0,0 +1,194 @@ +[[mvc-caching]] += HTTP Caching + +[.small]#<># + +HTTP caching can significantly improve the performance of a web application. HTTP caching +revolves around the `Cache-Control` response header and, subsequently, conditional request +headers (such as `Last-Modified` and `ETag`). `Cache-Control` advises private (for example, browser) +and public (for example, proxy) caches on how to cache and re-use responses. An `ETag` header is used +to make a conditional request that may result in a 304 (NOT_MODIFIED) without a body, +if the content has not changed. `ETag` can be seen as a more sophisticated successor to +the `Last-Modified` header. + +This section describes the HTTP caching-related options that are available in Spring Web MVC. + + + +[[mvc-caching-cachecontrol]] +== `CacheControl` +[.small]#<># + +{api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for +configuring settings related to the `Cache-Control` header and is accepted as an argument +in a number of places: + +* {api-spring-framework}/web/servlet/mvc/WebContentInterceptor.html[`WebContentInterceptor`] +* {api-spring-framework}/web/servlet/support/WebContentGenerator.html[`WebContentGenerator`] +* <> +* <> + +While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all possible +directives for the `Cache-Control` response header, the `CacheControl` type takes a +use case-oriented approach that focuses on the common scenarios: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Cache for an hour - "Cache-Control: max-age=3600" + CacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS); + + // Prevent caching - "Cache-Control: no-store" + CacheControl ccNoStore = CacheControl.noStore(); + + // Cache for ten days in public and private caches, + // public caches should not transform the response + // "Cache-Control: max-age=864000, public, no-transform" + CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Cache for an hour - "Cache-Control: max-age=3600" + val ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS) + + // Prevent caching - "Cache-Control: no-store" + val ccNoStore = CacheControl.noStore() + + // Cache for ten days in public and private caches, + // public caches should not transform the response + // "Cache-Control: max-age=864000, public, no-transform" + val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic() +---- + +`WebContentGenerator` also accepts a simpler `cachePeriod` property (defined in seconds) that +works as follows: + +* A `-1` value does not generate a `Cache-Control` response header. +* A `0` value prevents caching by using the `'Cache-Control: no-store'` directive. +* An `n > 0` value caches the given response for `n` seconds by using the +`'Cache-Control: max-age=n'` directive. + + + +[[mvc-caching-etag-lastmodified]] +== Controllers +[.small]#<># + +Controllers can add explicit support for HTTP caching. We recommended doing so, since the +`lastModified` or `ETag` value for a resource needs to be calculated before it can be compared +against conditional request headers. A controller can add an `ETag` header and `Cache-Control` +settings to a `ResponseEntity`, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/book/{id}") + public ResponseEntity showBook(@PathVariable Long id) { + + Book book = findBook(id); + String version = book.getVersion(); + + return ResponseEntity + .ok() + .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS)) + .eTag(version) // lastModified is also available + .body(book); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/book/{id}") + fun showBook(@PathVariable id: Long): ResponseEntity { + + val book = findBook(id); + val version = book.getVersion() + + return ResponseEntity + .ok() + .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS)) + .eTag(version) // lastModified is also available + .body(book) + } +---- +-- + +The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison +to the conditional request headers indicates that the content has not changed. Otherwise, the +`ETag` and `Cache-Control` headers are added to the response. + +You can also make the check against conditional request headers in the controller, +as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RequestMapping + public String myHandleMethod(WebRequest request, Model model) { + + long eTag = ... // <1> + + if (request.checkNotModified(eTag)) { + return null; // <2> + } + + model.addAttribute(...); // <3> + return "myViewName"; + } +---- +<1> Application-specific calculation. +<2> The response has been set to 304 (NOT_MODIFIED) -- no further processing. +<3> Continue with the request processing. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RequestMapping + fun myHandleMethod(request: WebRequest, model: Model): String? { + + val eTag: Long = ... // <1> + + if (request.checkNotModified(eTag)) { + return null // <2> + } + + model[...] = ... // <3> + return "myViewName" + } +---- +<1> Application-specific calculation. +<2> The response has been set to 304 (NOT_MODIFIED) -- no further processing. +<3> Continue with the request processing. +-- + + +There are three variants for checking conditional requests against `eTag` values, `lastModified` +values, or both. For conditional `GET` and `HEAD` requests, you can set the response to +304 (NOT_MODIFIED). For conditional `POST`, `PUT`, and `DELETE`, you can instead set the response +to 412 (PRECONDITION_FAILED), to prevent concurrent modification. + + + +[[mvc-caching-static-resources]] +== Static Resources +[.small]#<># + +You should serve static resources with a `Cache-Control` and conditional response headers +for optimal performance. See the section on configuring <>. + + + +[[mvc-httpcaching-shallowetag]] +== `ETag` Filter + +You can use the `ShallowEtagHeaderFilter` to add "`shallow`" `eTag` values that are computed from the +response content and, thus, save bandwidth but not CPU time. See <>. + +include:../:webmvc-view.adoc[leveloffset=+1] + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc new file mode 100644 index 000000000000..2b43f6232625 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc @@ -0,0 +1,17 @@ +[[mvc-config]] += MVC Config + +[.small]#<># + +The MVC Java configuration and the MVC XML namespace provide default configuration +suitable for most applications and a configuration API to customize it. + +For more advanced customizations, which are not available in the configuration API, +see <> and <>. + +You do not need to understand the underlying beans created by the MVC Java configuration +and the MVC namespace. If you want to learn more, see <> +and <>. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc new file mode 100644 index 000000000000..e469a02b8f89 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc @@ -0,0 +1,39 @@ +[[mvc-config-advanced-java]] += Advanced Java Config + +[.small]#<># + +`@EnableWebMvc` imports `DelegatingWebMvcConfiguration`, which: + +* Provides default Spring configuration for Spring MVC applications +* Detects and delegates to `WebMvcConfigurer` implementations to customize that configuration. + +For advanced mode, you can remove `@EnableWebMvc` and extend directly from +`DelegatingWebMvcConfiguration` instead of implementing `WebMvcConfigurer`, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class WebConfig extends DelegatingWebMvcConfiguration { + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class WebConfig : DelegatingWebMvcConfiguration() { + + // ... + } +---- + +You can keep existing methods in `WebConfig`, but you can now also override bean declarations +from the base class, and you can still have any number of other `WebMvcConfigurer` implementations on +the classpath. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-xml.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-xml.adoc new file mode 100644 index 000000000000..c203f2ee64dd --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-xml.adoc @@ -0,0 +1,37 @@ +[[mvc-config-advanced-xml]] += Advanced XML Config + +The MVC namespace does not have an advanced mode. If you need to customize a property on +a bean that you cannot change otherwise, you can use the `BeanPostProcessor` lifecycle +hook of the Spring `ApplicationContext`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + public class MyPostProcessor implements BeanPostProcessor { + + public Object postProcessBeforeInitialization(Object bean, String name) throws BeansException { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + class MyPostProcessor : BeanPostProcessor { + + override fun postProcessBeforeInitialization(bean: Any, name: String): Any { + // ... + } + } +---- + + +Note that you need to declare `MyPostProcessor` as a bean, either explicitly in XML or +by letting it be detected through a `` declaration. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc new file mode 100644 index 000000000000..95c139265750 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc @@ -0,0 +1,65 @@ +[[mvc-config-content-negotiation]] += Content Types + +[.small]#<># + +You can configure how Spring MVC determines the requested media types from the request +(for example, `Accept` header, URL path extension, query parameter, and others). + +By default, only the `Accept` header is checked. + +If you must use URL-based content type resolution, consider using the query parameter +strategy over path extensions. See +<> and <> for +more details. + +In Java configuration, you can customize requested content type resolution, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configureContentNegotiation(ContentNegotiationConfigurer configurer) { + configurer.mediaType("json", MediaType.APPLICATION_JSON); + configurer.mediaType("xml", MediaType.APPLICATION_XML); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configureContentNegotiation(configurer: ContentNegotiationConfigurer) { + configurer.mediaType("json", MediaType.APPLICATION_JSON) + configurer.mediaType("xml", MediaType.APPLICATION_XML) + } + } +---- + + +The following example shows how to achieve the same configuration in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + json=application/json + xml=application/xml + + + +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc new file mode 100644 index 000000000000..9ac7ec9ddbbe --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc @@ -0,0 +1,116 @@ +[[mvc-config-conversion]] += Type Conversion + +[.small]#<># + +By default, formatters for various number and date types are installed, along with support +for customization via `@NumberFormat` and `@DateTimeFormat` on fields. + +To register custom formatters and converters in Java config, use the following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void addFormatters(FormatterRegistry registry) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun addFormatters(registry: FormatterRegistry) { + // ... + } + } +---- + +To do the same in XML config, use the following: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + + + + + + + + + + +---- + +By default Spring MVC considers the request Locale when parsing and formatting date +values. This works for forms where dates are represented as Strings with "input" form +fields. For "date" and "time" form fields, however, browsers use a fixed format defined +in the HTML spec. For such cases date and time formatting can be customized as follows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void addFormatters(FormatterRegistry registry) { + DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar(); + registrar.setUseIsoFormat(true); + registrar.registerFormatters(registry); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun addFormatters(registry: FormatterRegistry) { + val registrar = DateTimeFormatterRegistrar() + registrar.setUseIsoFormat(true) + registrar.registerFormatters(registry) + } + } +---- + +NOTE: See <> +and the `FormattingConversionServiceFactoryBean` for more information on when to use +FormatterRegistrar implementations. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc new file mode 100644 index 000000000000..66261c7616e8 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc @@ -0,0 +1,37 @@ +[[mvc-config-customize]] += MVC Config API + +[.small]#<># + +In Java configuration, you can implement the `WebMvcConfigurer` interface, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + // Implement configuration methods... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + // Implement configuration methods... + } +---- + + +In XML, you can check attributes and sub-elements of ``. You can +view the https://schema.spring.io/mvc/spring-mvc.xsd[Spring MVC XML schema] or use +the code completion feature of your IDE to discover what attributes and +sub-elements are available. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/default-servlet-handler.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/default-servlet-handler.adoc new file mode 100644 index 000000000000..1fea95fc8079 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/default-servlet-handler.adoc @@ -0,0 +1,95 @@ +[[mvc-default-servlet-handler]] += Default Servlet + +Spring MVC allows for mapping the `DispatcherServlet` to `/` (thus overriding the mapping +of the container's default Servlet), while still allowing static resource requests to be +handled by the container's default Servlet. It configures a +`DefaultServletHttpRequestHandler` with a URL mapping of `/**` and the lowest priority +relative to other URL mappings. + +This handler forwards all requests to the default Servlet. Therefore, it must +remain last in the order of all other URL `HandlerMappings`. That is the +case if you use ``. Alternatively, if you set up your +own customized `HandlerMapping` instance, be sure to set its `order` property to a value +lower than that of the `DefaultServletHttpRequestHandler`, which is `Integer.MAX_VALUE`. + +The following example shows how to enable the feature by using the default setup: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) { + configurer.enable(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configureDefaultServletHandling(configurer: DefaultServletHandlerConfigurer) { + configurer.enable() + } + } +---- + +The following example shows how to achieve the same configuration in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +The caveat to overriding the `/` Servlet mapping is that the `RequestDispatcher` for the +default Servlet must be retrieved by name rather than by path. The +`DefaultServletHttpRequestHandler` tries to auto-detect the default Servlet for +the container at startup time, using a list of known names for most of the major Servlet +containers (including Tomcat, Jetty, GlassFish, JBoss, Resin, WebLogic, and WebSphere). +If the default Servlet has been custom-configured with a different name, or if a +different Servlet container is being used where the default Servlet name is unknown, +then you must explicitly provide the default Servlet's name, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) { + configurer.enable("myCustomDefaultServlet"); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configureDefaultServletHandling(configurer: DefaultServletHandlerConfigurer) { + configurer.enable("myCustomDefaultServlet") + } + } +---- + + +The following example shows how to achieve the same configuration in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc new file mode 100644 index 000000000000..d1bdaacc48f7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc @@ -0,0 +1,50 @@ +[[mvc-config-enable]] += Enable MVC Configuration + +[.small]#<># + +In Java configuration, you can use the `@EnableWebMvc` annotation to enable MVC +configuration, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig { + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig +---- + +In XML configuration, you can use the `` element to enable MVC +configuration, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + +The preceding example registers a number of Spring MVC +<> and adapts to dependencies +available on the classpath (for example, payload converters for JSON, XML, and others). + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc new file mode 100644 index 000000000000..2bdaf5effb6f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc @@ -0,0 +1,60 @@ +[[mvc-config-interceptors]] += Interceptors + +In Java configuration, you can register interceptors to apply to incoming requests, as +the following example shows: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void addInterceptors(InterceptorRegistry registry) { + registry.addInterceptor(new LocaleChangeInterceptor()); + registry.addInterceptor(new ThemeChangeInterceptor()).addPathPatterns("/**").excludePathPatterns("/admin/**"); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun addInterceptors(registry: InterceptorRegistry) { + registry.addInterceptor(LocaleChangeInterceptor()) + registry.addInterceptor(ThemeChangeInterceptor()).addPathPatterns("/**").excludePathPatterns("/admin/**") + } + } +---- + +The following example shows how to achieve the same configuration in XML: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + +---- + +NOTE: Mapped interceptors are not ideally suited as a security layer due to the potential +for a mismatch with annotated controller path matching, which can also match trailing +slashes and path extensions transparently, along with other path matching options. Many +of these options have been deprecated but the potential for a mismatch remains. +Generally, we recommend using Spring Security which includes a dedicated +https://docs.spring.io/spring-security/reference/servlet/integrations/mvc.html#mvc-requestmatcher[MvcRequestMatcher] +to align with Spring MVC path matching and also has a security firewall that blocks many +unwanted characters in URL paths. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc new file mode 100644 index 000000000000..2182ccdf98df --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc @@ -0,0 +1,102 @@ +[[mvc-config-message-converters]] += Message Converters + +[.small]#<># + +You can customize `HttpMessageConverter` in Java configuration by overriding +{api-spring-framework}/web/servlet/config/annotation/WebMvcConfigurer.html#configureMessageConverters-java.util.List-[`configureMessageConverters()`] +(to replace the default converters created by Spring MVC) or by overriding +{api-spring-framework}/web/servlet/config/annotation/WebMvcConfigurer.html#extendMessageConverters-java.util.List-[`extendMessageConverters()`] +(to customize the default converters or add additional converters to the default ones). + +The following example adds XML and Jackson JSON converters with a customized +`ObjectMapper` instead of the default ones: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfiguration implements WebMvcConfigurer { + + @Override + public void configureMessageConverters(List> converters) { + Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder() + .indentOutput(true) + .dateFormat(new SimpleDateFormat("yyyy-MM-dd")) + .modulesToInstall(new ParameterNamesModule()); + converters.add(new MappingJackson2HttpMessageConverter(builder.build())); + converters.add(new MappingJackson2XmlHttpMessageConverter(builder.createXmlMapper(true).build())); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfiguration : WebMvcConfigurer { + + override fun configureMessageConverters(converters: MutableList>) { + val builder = Jackson2ObjectMapperBuilder() + .indentOutput(true) + .dateFormat(SimpleDateFormat("yyyy-MM-dd")) + .modulesToInstall(ParameterNamesModule()) + converters.add(MappingJackson2HttpMessageConverter(builder.build())) + converters.add(MappingJackson2XmlHttpMessageConverter(builder.createXmlMapper(true).build())) +---- + +In the preceding example, +{api-spring-framework}/http/converter/json/Jackson2ObjectMapperBuilder.html[`Jackson2ObjectMapperBuilder`] +is used to create a common configuration for both `MappingJackson2HttpMessageConverter` and +`MappingJackson2XmlHttpMessageConverter` with indentation enabled, a customized date format, +and the registration of +https://github.com/FasterXML/jackson-module-parameter-names[`jackson-module-parameter-names`], +Which adds support for accessing parameter names (a feature added in Java 8). + +This builder customizes Jackson's default properties as follows: + +* https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/DeserializationFeature.html#FAIL_ON_UNKNOWN_PROPERTIES[`DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES`] is disabled. +* https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/MapperFeature.html#DEFAULT_VIEW_INCLUSION[`MapperFeature.DEFAULT_VIEW_INCLUSION`] is disabled. + +It also automatically registers the following well-known modules if they are detected on the classpath: + +* https://github.com/FasterXML/jackson-datatype-joda[jackson-datatype-joda]: Support for Joda-Time types. +* https://github.com/FasterXML/jackson-datatype-jsr310[jackson-datatype-jsr310]: Support for Java 8 Date and Time API types. +* https://github.com/FasterXML/jackson-datatype-jdk8[jackson-datatype-jdk8]: Support for other Java 8 types, such as `Optional`. +* https://github.com/FasterXML/jackson-module-kotlin[`jackson-module-kotlin`]: Support for Kotlin classes and data classes. + +NOTE: Enabling indentation with Jackson XML support requires +https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.codehaus.woodstox%22%20AND%20a%3A%22woodstox-core-asl%22[`woodstox-core-asl`] +dependency in addition to https://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jackson-dataformat-xml%22[`jackson-dataformat-xml`] one. + +Other interesting Jackson modules are available: + +* https://github.com/zalando/jackson-datatype-money[jackson-datatype-money]: Support for `javax.money` types (unofficial module). +* https://github.com/FasterXML/jackson-datatype-hibernate[jackson-datatype-hibernate]: Support for Hibernate-specific types and properties (including lazy-loading aspects). + +The following example shows how to achieve the same configuration in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc new file mode 100644 index 000000000000..cde874c9ec65 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc @@ -0,0 +1,61 @@ +[[mvc-config-path-matching]] += Path Matching + +[.small]#<># + +You can customize options related to path matching and treatment of the URL. +For details on the individual options, see the +{api-spring-framework}/web/servlet/config/annotation/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc. + +The following example shows how to customize path matching in Java configuration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configurePathMatch(PathMatchConfigurer configurer) { + configurer.addPathPrefix("/api", HandlerTypePredicate.forAnnotation(RestController.class)); + } + + private PathPatternParser patternParser() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configurePathMatch(configurer: PathMatchConfigurer) { + configurer.addPathPrefix("/api", HandlerTypePredicate.forAnnotation(RestController::class.java)) + } + + fun patternParser(): PathPatternParser { + //... + } + } +---- + +The following example shows how to customize path matching in XML configuration: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc new file mode 100644 index 000000000000..e1f162c8734f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc @@ -0,0 +1,146 @@ +[[mvc-config-static-resources]] += Static Resources + +[.small]#<># + +This option provides a convenient way to serve static resources from a list of +{api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. + +In the next example, given a request that starts with `/resources`, the relative path is +used to find and serve static resources relative to `/public` under the web application +root or on the classpath under `/static`. The resources are served with a one-year future +expiration to ensure maximum use of the browser cache and a reduction in HTTP requests +made by the browser. The `Last-Modified` information is deduced from `Resource#lastModified` +so that HTTP conditional requests are supported with `"Last-Modified"` headers. + +The following listing shows how to do so with Java configuration: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void addResourceHandlers(ResourceHandlerRegistry registry) { + registry.addResourceHandler("/resources/**") + .addResourceLocations("/public", "classpath:/static/") + .setCacheControl(CacheControl.maxAge(Duration.ofDays(365))); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun addResourceHandlers(registry: ResourceHandlerRegistry) { + registry.addResourceHandler("/resources/**") + .addResourceLocations("/public", "classpath:/static/") + .setCacheControl(CacheControl.maxAge(Duration.ofDays(365))) + } + } +---- + +The following example shows how to achieve the same configuration in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +See also +<>. + +The resource handler also supports a chain of +{api-spring-framework}/web/servlet/resource/ResourceResolver.html[`ResourceResolver`] implementations and +{api-spring-framework}/web/servlet/resource/ResourceTransformer.html[`ResourceTransformer`] implementations, +which you can use to create a toolchain for working with optimized resources. + +You can use the `VersionResourceResolver` for versioned resource URLs based on an MD5 hash +computed from the content, a fixed application version, or other. A +`ContentVersionStrategy` (MD5 hash) is a good choice -- with some notable exceptions, such as +JavaScript resources used with a module loader. + +The following example shows how to use `VersionResourceResolver` in Java configuration: + +[source,java,indent=0,subs="verbatim",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void addResourceHandlers(ResourceHandlerRegistry registry) { + registry.addResourceHandler("/resources/**") + .addResourceLocations("/public/") + .resourceChain(true) + .addResolver(new VersionResourceResolver().addContentVersionStrategy("/**")); + } + } +---- +[source,kotlin,indent=0,subs="verbatim",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun addResourceHandlers(registry: ResourceHandlerRegistry) { + registry.addResourceHandler("/resources/**") + .addResourceLocations("/public/") + .resourceChain(true) + .addResolver(VersionResourceResolver().addContentVersionStrategy("/**")) + } + } +---- + +The following example shows how to achieve the same configuration in XML: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + +---- + +You can then use `ResourceUrlProvider` to rewrite URLs and apply the full chain of resolvers and +transformers -- for example, to insert versions. The MVC configuration provides a `ResourceUrlProvider` +bean so that it can be injected into others. You can also make the rewrite transparent with the +`ResourceUrlEncodingFilter` for Thymeleaf, JSPs, FreeMarker, and others with URL tags that +rely on `HttpServletResponse#encodeURL`. + +Note that, when using both `EncodedResourceResolver` (for example, for serving gzipped or +brotli-encoded resources) and `VersionResourceResolver`, you must register them in this order. +That ensures content-based versions are always computed reliably, based on the unencoded file. + +For https://www.webjars.org/documentation[WebJars], versioned URLs like +`/webjars/jquery/1.2.0/jquery.min.js` are the recommended and most efficient way to use them. +The related resource location is configured out of the box with Spring Boot (or can be configured +manually via `ResourceHandlerRegistry`) and does not require to add the +`org.webjars:webjars-locator-core` dependency. + +Version-less URLs like `/webjars/jquery/jquery.min.js` are supported through the +`WebJarsResourceResolver` which is automatically registered when the +`org.webjars:webjars-locator-core` library is present on the classpath, at the cost of a +classpath scanning that could slow down application startup. The resolver can re-write URLs to +include the version of the jar and can also match against incoming URLs without versions +-- for example, from `/webjars/jquery/jquery.min.js` to `/webjars/jquery/1.2.0/jquery.min.js`. + +TIP: The Java configuration based on `ResourceHandlerRegistry` provides further options +for fine-grained control, e.g. last-modified behavior and optimized resource resolution. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc new file mode 100644 index 000000000000..d5791c3519da --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc @@ -0,0 +1,91 @@ +[[mvc-config-validation]] += Validation + +[.small]#<># + +By default, if <> is present +on the classpath (for example, Hibernate Validator), the `LocalValidatorFactoryBean` is +registered as a global <> for use with `@Valid` and +`Validated` on controller method arguments. + +In Java configuration, you can customize the global `Validator` instance, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public Validator getValidator() { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun getValidator(): Validator { + // ... + } + } +---- + +The following example shows how to achieve the same configuration in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + +Note that you can also register `Validator` implementations locally, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class MyController { + + @InitBinder + protected void initBinder(WebDataBinder binder) { + binder.addValidators(new FooValidator()); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class MyController { + + @InitBinder + protected fun initBinder(binder: WebDataBinder) { + binder.addValidators(FooValidator()) + } + } +---- + +TIP: If you need to have a `LocalValidatorFactoryBean` injected somewhere, create a bean and +mark it with `@Primary` in order to avoid conflict with the one declared in the MVC configuration. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-controller.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-controller.adoc new file mode 100644 index 000000000000..0df943d14e05 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-controller.adoc @@ -0,0 +1,52 @@ +[[mvc-config-view-controller]] += View Controllers + +This is a shortcut for defining a `ParameterizableViewController` that immediately +forwards to a view when invoked. You can use it in static cases when there is no Java controller +logic to run before the view generates the response. + +The following example of Java configuration forwards a request for `/` to a view called `home`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void addViewControllers(ViewControllerRegistry registry) { + registry.addViewController("/").setViewName("home"); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun addViewControllers(registry: ViewControllerRegistry) { + registry.addViewController("/").setViewName("home") + } + } +---- + +The following example achieves the same thing as the preceding example, but with XML, by +using the `` element: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + +---- + +If an `@RequestMapping` method is mapped to a URL for any HTTP method then a view +controller cannot be used to handle the same URL. This is because a match by URL to an +annotated controller is considered a strong enough indication of endpoint ownership so +that a 405 (METHOD_NOT_ALLOWED), a 415 (UNSUPPORTED_MEDIA_TYPE), or similar response can +be sent to the client to help with debugging. For this reason it is recommended to avoid +splitting URL handling across an annotated controller and a view controller. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc new file mode 100644 index 000000000000..950afe58684b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc @@ -0,0 +1,119 @@ +[[mvc-config-view-resolvers]] += View Resolvers + +[.small]#<># + +The MVC configuration simplifies the registration of view resolvers. + +The following Java configuration example configures content negotiation view +resolution by using JSP and Jackson as a default `View` for JSON rendering: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + registry.enableContentNegotiation(new MappingJackson2JsonView()); + registry.jsp(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + registry.enableContentNegotiation(MappingJackson2JsonView()) + registry.jsp() + } + } +---- + + +The following example shows how to achieve the same configuration in XML: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + +---- + +Note, however, that FreeMarker, Groovy Markup, and script templates also require +configuration of the underlying view technology. + +The MVC namespace provides dedicated elements. The following example works with FreeMarker: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + +---- + +In Java configuration, you can add the respective `Configurer` bean, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @EnableWebMvc + public class WebConfig implements WebMvcConfigurer { + + @Override + public void configureViewResolvers(ViewResolverRegistry registry) { + registry.enableContentNegotiation(new MappingJackson2JsonView()); + registry.freeMarker().cache(false); + } + + @Bean + public FreeMarkerConfigurer freeMarkerConfigurer() { + FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); + configurer.setTemplateLoaderPath("/freemarker"); + return configurer; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @EnableWebMvc + class WebConfig : WebMvcConfigurer { + + override fun configureViewResolvers(registry: ViewResolverRegistry) { + registry.enableContentNegotiation(MappingJackson2JsonView()) + registry.freeMarker().cache(false) + } + + @Bean + fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply { + setTemplateLoaderPath("/freemarker") + } + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc new file mode 100644 index 000000000000..f3363d0aa0dc --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc @@ -0,0 +1,48 @@ +[[mvc-controller]] += Annotated Controllers + +[.small]#<># + +Spring MVC provides an annotation-based programming model where `@Controller` and +`@RestController` components use annotations to express request mappings, request input, +exception handling, and more. Annotated controllers have flexible method signatures and +do not have to extend base classes nor implement specific interfaces. +The following example shows a controller defined by annotations: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class HelloController { + + @GetMapping("/hello") + public String handle(Model model) { + model.addAttribute("message", "Hello World!"); + return "index"; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.ui.set + + @Controller + class HelloController { + + @GetMapping("/hello") + fun handle(model: Model): String { + model["message"] = "Hello World!" + return "index" + } + } +---- + +In the preceding example, the method accepts a `Model` and returns a view name as a `String`, +but many other options exist and are explained later in this chapter. + +TIP: Guides and tutorials on https://spring.io/guides[spring.io] use the annotation-based +programming model described in this section. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc new file mode 100644 index 000000000000..67132df5eff7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc @@ -0,0 +1,65 @@ +[[mvc-ann-controller-advice]] += Controller Advice + +[.small]#<># + +`@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply only to the +`@Controller` class, or class hierarchy, in which they are declared. If, instead, they +are declared in an `@ControllerAdvice` or `@RestControllerAdvice` class, then they apply +to any controller. Moreover, as of 5.3, `@ExceptionHandler` methods in `@ControllerAdvice` +can be used to handle exceptions from any `@Controller` or any other handler. + +`@ControllerAdvice` is meta-annotated with `@Component` and therefore can be registered as +a Spring bean through <>. `@RestControllerAdvice` is meta-annotated with `@ControllerAdvice` +and `@ResponseBody`, and that means `@ExceptionHandler` methods will have their return +value rendered via response body message conversion, rather than via HTML views. + +On startup, `RequestMappingHandlerMapping` and `ExceptionHandlerExceptionResolver` detect +controller advice beans and apply them at runtime. Global `@ExceptionHandler` methods, +from an `@ControllerAdvice`, are applied _after_ local ones, from the `@Controller`. +By contrast, global `@ModelAttribute` and `@InitBinder` methods are applied _before_ local ones. + +The `@ControllerAdvice` annotation has attributes that let you narrow the set of controllers +and handlers that they apply to. For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Target all Controllers annotated with @RestController + @ControllerAdvice(annotations = RestController.class) + public class ExampleAdvice1 {} + + // Target all Controllers within specific packages + @ControllerAdvice("org.example.controllers") + public class ExampleAdvice2 {} + + // Target all Controllers assignable to specific classes + @ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class}) + public class ExampleAdvice3 {} +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Target all Controllers annotated with @RestController + @ControllerAdvice(annotations = [RestController::class]) + class ExampleAdvice1 + + // Target all Controllers within specific packages + @ControllerAdvice("org.example.controllers") + class ExampleAdvice2 + + // Target all Controllers assignable to specific classes + @ControllerAdvice(assignableTypes = [ControllerInterface::class, AbstractController::class]) + class ExampleAdvice3 +---- + +The selectors in the preceding example are evaluated at runtime and may negatively impact +performance if used extensively. See the +{api-spring-framework}/web/bind/annotation/ControllerAdvice.html[`@ControllerAdvice`] +javadoc for more details. + +include:../../:webmvc-functional.adoc[leveloffset=+1] + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc new file mode 100644 index 000000000000..4b3b141ed32c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc @@ -0,0 +1,262 @@ +[[mvc-ann-exceptionhandler]] += Exceptions + +[.small]#<># + +`@Controller` and <> classes can have +`@ExceptionHandler` methods to handle exceptions from controller methods, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class SimpleController { + + // ... + + @ExceptionHandler + public ResponseEntity handle(IOException ex) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class SimpleController { + + // ... + + @ExceptionHandler + fun handle(ex: IOException): ResponseEntity { + // ... + } + } +---- + +The exception may match against a top-level exception being propagated (e.g. a direct +`IOException` being thrown) or against a nested cause within a wrapper exception (e.g. +an `IOException` wrapped inside an `IllegalStateException`). As of 5.3, this can match +at arbitrary cause levels, whereas previously only an immediate cause was considered. + +For matching exception types, preferably declare the target exception as a method argument, +as the preceding example shows. When multiple exception methods match, a root exception match is +generally preferred to a cause exception match. More specifically, the `ExceptionDepthComparator` +is used to sort exceptions based on their depth from the thrown exception type. + +Alternatively, the annotation declaration may narrow the exception types to match, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExceptionHandler({FileSystemException.class, RemoteException.class}) + public ResponseEntity handle(IOException ex) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExceptionHandler(FileSystemException::class, RemoteException::class) + fun handle(ex: IOException): ResponseEntity { + // ... + } +---- + +You can even use a list of specific exception types with a very generic argument signature, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ExceptionHandler({FileSystemException.class, RemoteException.class}) + public ResponseEntity handle(Exception ex) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ExceptionHandler(FileSystemException::class, RemoteException::class) + fun handle(ex: Exception): ResponseEntity { + // ... + } +---- + +[NOTE] +==== +The distinction between root and cause exception matching can be surprising. + +In the `IOException` variant shown earlier, the method is typically called with +the actual `FileSystemException` or `RemoteException` instance as the argument, +since both of them extend from `IOException`. However, if any such matching +exception is propagated within a wrapper exception which is itself an `IOException`, +the passed-in exception instance is that wrapper exception. + +The behavior is even simpler in the `handle(Exception)` variant. This is +always invoked with the wrapper exception in a wrapping scenario, with the +actually matching exception to be found through `ex.getCause()` in that case. +The passed-in exception is the actual `FileSystemException` or +`RemoteException` instance only when these are thrown as top-level exceptions. +==== + +We generally recommend that you be as specific as possible in the argument signature, +reducing the potential for mismatches between root and cause exception types. +Consider breaking a multi-matching method into individual `@ExceptionHandler` +methods, each matching a single specific exception type through its signature. + +In a multi-`@ControllerAdvice` arrangement, we recommend declaring your primary root exception +mappings on a `@ControllerAdvice` prioritized with a corresponding order. While a root +exception match is preferred to a cause, this is defined among the methods of a given +controller or `@ControllerAdvice` class. This means a cause match on a higher-priority +`@ControllerAdvice` bean is preferred to any match (for example, root) on a lower-priority +`@ControllerAdvice` bean. + +Last but not least, an `@ExceptionHandler` method implementation can choose to back +out of dealing with a given exception instance by rethrowing it in its original form. +This is useful in scenarios where you are interested only in root-level matches or in +matches within a specific context that cannot be statically determined. A rethrown +exception is propagated through the remaining resolution chain, as though +the given `@ExceptionHandler` method would not have matched in the first place. + +Support for `@ExceptionHandler` methods in Spring MVC is built on the `DispatcherServlet` +level, <> mechanism. + + +[[mvc-ann-exceptionhandler-args]] +== Method Arguments +[.small]#<># + +`@ExceptionHandler` methods support the following arguments: + +[cols="1,2", options="header"] +|=== +| Method argument | Description + +| Exception type +| For access to the raised exception. + +| `HandlerMethod` +| For access to the controller method that raised the exception. + +| `WebRequest`, `NativeWebRequest` +| Generic access to request parameters and request and session attributes without direct + use of the Servlet API. + +| `jakarta.servlet.ServletRequest`, `jakarta.servlet.ServletResponse` +| Choose any specific request or response type (for example, `ServletRequest` or + `HttpServletRequest` or Spring's `MultipartRequest` or `MultipartHttpServletRequest`). + +| `jakarta.servlet.http.HttpSession` +| Enforces the presence of a session. As a consequence, such an argument is never `null`. + + Note that session access is not thread-safe. Consider setting the + `RequestMappingHandlerAdapter` instance's `synchronizeOnSession` flag to `true` if multiple + requests are allowed to access a session concurrently. + +| `java.security.Principal` +| Currently authenticated user -- possibly a specific `Principal` implementation class if known. + +| `HttpMethod` +| The HTTP method of the request. + +| `java.util.Locale` +| The current request locale, determined by the most specific `LocaleResolver` available -- in + effect, the configured `LocaleResolver` or `LocaleContextResolver`. + +| `java.util.TimeZone`, `java.time.ZoneId` +| The time zone associated with the current request, as determined by a `LocaleContextResolver`. + +| `java.io.OutputStream`, `java.io.Writer` +| For access to the raw response body, as exposed by the Servlet API. + +| `java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap` +| For access to the model for an error response. Always empty. + +| `RedirectAttributes` +| Specify attributes to use in case of a redirect -- (that is to be appended to the query + string) and flash attributes to be stored temporarily until the request after the redirect. + See <> and <>. + +| `@SessionAttribute` +| For access to any session attribute, in contrast to model attributes stored in the + session as a result of a class-level `@SessionAttributes` declaration. + See <> for more details. + +| `@RequestAttribute` +| For access to request attributes. See <> for more details. + +|=== + + +[[mvc-ann-exceptionhandler-return-values]] +== Return Values +[.small]#<># + +`@ExceptionHandler` methods support the following return values: + +[cols="1,2", options="header"] +|=== +| Return value | Description + +| `@ResponseBody` +| The return value is converted through `HttpMessageConverter` instances and written to the + response. See <>. + +| `HttpEntity`, `ResponseEntity` +| The return value specifies that the full response (including the HTTP headers and the body) + be converted through `HttpMessageConverter` instances and written to the response. + See <>. + +| `ErrorResponse` +| To render an RFC 7807 error response with details in the body, +see <> + +| `ProblemDetail` +| To render an RFC 7807 error response with details in the body, +see <> + +| `String` +| A view name to be resolved with `ViewResolver` implementations and used together with the + implicit model -- determined through command objects and `@ModelAttribute` methods. + The handler method can also programmatically enrich the model by declaring a `Model` + argument (described earlier). + +| `View` +| A `View` instance to use for rendering together with the implicit model -- determined + through command objects and `@ModelAttribute` methods. The handler method may also + programmatically enrich the model by declaring a `Model` argument (descried earlier). + +| `java.util.Map`, `org.springframework.ui.Model` +| Attributes to be added to the implicit model with the view name implicitly determined + through a `RequestToViewNameTranslator`. + +| `@ModelAttribute` +| An attribute to be added to the model with the view name implicitly determined through + a `RequestToViewNameTranslator`. + + Note that `@ModelAttribute` is optional. See "`Any other return value`" at the end of + this table. + +| `ModelAndView` object +| The view and model attributes to use and, optionally, a response status. + +| `void` +| A method with a `void` return type (or `null` return value) is considered to have fully + handled the response if it also has a `ServletResponse` an `OutputStream` argument, or + a `@ResponseStatus` annotation. The same is also true if the controller has made a positive + `ETag` or `lastModified` timestamp check (see <> for details). + + If none of the above is true, a `void` return type can also indicate "`no response body`" for + REST controllers or default view name selection for HTML controllers. + +| Any other return value +| If a return value is not matched to any of the above and is not a simple type (as determined by + {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]), + by default, it is treated as a model attribute to be added to the model. If it is a simple type, + it remains unresolved. +|=== + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc new file mode 100644 index 000000000000..6d025b36656d --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc @@ -0,0 +1,102 @@ +[[mvc-ann-initbinder]] += `DataBinder` + +[.small]#<># + +`@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods that +initialize instances of `WebDataBinder`, and those, in turn, can: + +* Bind request parameters (that is, form or query data) to a model object. +* Convert String-based request values (such as request parameters, path variables, +headers, cookies, and others) to the target type of controller method arguments. +* Format model object values as `String` values when rendering HTML forms. + +`@InitBinder` methods can register controller-specific `java.beans.PropertyEditor` or +Spring `Converter` and `Formatter` components. In addition, you can use the +<> to register `Converter` and `Formatter` +types in a globally shared `FormattingConversionService`. + +`@InitBinder` methods support many of the same arguments that `@RequestMapping` methods +do, except for `@ModelAttribute` (command object) arguments. Typically, they are declared +with a `WebDataBinder` argument (for registrations) and a `void` return value. +The following listing shows an example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class FormController { + + @InitBinder // <1> + public void initBinder(WebDataBinder binder) { + SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd"); + dateFormat.setLenient(false); + binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false)); + } + + // ... + } +---- +<1> Defining an `@InitBinder` method. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class FormController { + + @InitBinder // <1> + fun initBinder(binder: WebDataBinder) { + val dateFormat = SimpleDateFormat("yyyy-MM-dd") + dateFormat.isLenient = false + binder.registerCustomEditor(Date::class.java, CustomDateEditor(dateFormat, false)) + } + + // ... + } +---- +<1> Defining an `@InitBinder` method. + +Alternatively, when you use a `Formatter`-based setup through a shared +`FormattingConversionService`, you can re-use the same approach and register +controller-specific `Formatter` implementations, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class FormController { + + @InitBinder // <1> + protected void initBinder(WebDataBinder binder) { + binder.addCustomFormatter(new DateFormatter("yyyy-MM-dd")); + } + + // ... + } +---- +<1> Defining an `@InitBinder` method on a custom formatter. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class FormController { + + @InitBinder // <1> + protected fun initBinder(binder: WebDataBinder) { + binder.addCustomFormatter(DateFormatter("yyyy-MM-dd")) + } + + // ... + } +---- +<1> Defining an `@InitBinder` method on a custom formatter. + +[[mvc-ann-initbinder-model-design]] +== Model Design +[.small]#<># + +include:../../:web-data-binding-model-design.adoc[] + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc new file mode 100644 index 000000000000..ee2178aa14d2 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc @@ -0,0 +1,9 @@ +[[mvc-ann-methods]] += Handler Methods + +[.small]#<># + +`@RequestMapping` handler methods have a flexible signature and can choose from a range of +supported controller method arguments and return values. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc new file mode 100644 index 000000000000..b0fb31911f98 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc @@ -0,0 +1,142 @@ +[[mvc-ann-arguments]] += Method Arguments + +[.small]#<># + +The next table describes the supported controller method arguments. Reactive types are not supported +for any arguments. + +JDK 8's `java.util.Optional` is supported as a method argument in combination with +annotations that have a `required` attribute (for example, `@RequestParam`, `@RequestHeader`, +and others) and is equivalent to `required=false`. + +[cols="1,2", options="header"] +|=== +| Controller method argument | Description + +| `WebRequest`, `NativeWebRequest` +| Generic access to request parameters and request and session attributes, without direct + use of the Servlet API. + +| `jakarta.servlet.ServletRequest`, `jakarta.servlet.ServletResponse` +| Choose any specific request or response type -- for example, `ServletRequest`, `HttpServletRequest`, + or Spring's `MultipartRequest`, `MultipartHttpServletRequest`. + +| `jakarta.servlet.http.HttpSession` +| Enforces the presence of a session. As a consequence, such an argument is never `null`. + Note that session access is not thread-safe. Consider setting the + `RequestMappingHandlerAdapter` instance's `synchronizeOnSession` flag to `true` if multiple + requests are allowed to concurrently access a session. + +| `jakarta.servlet.http.PushBuilder` +| Servlet 4.0 push builder API for programmatic HTTP/2 resource pushes. + Note that, per the Servlet specification, the injected `PushBuilder` instance can be null if the client + does not support that HTTP/2 feature. + +| `java.security.Principal` +| Currently authenticated user -- possibly a specific `Principal` implementation class if known. + + Note that this argument is not resolved eagerly, if it is annotated in order to allow a custom resolver to resolve it + before falling back on default resolution via `HttpServletRequest#getUserPrincipal`. + For example, the Spring Security `Authentication` implements `Principal` and would be injected as such via + `HttpServletRequest#getUserPrincipal`, unless it is also annotated with `@AuthenticationPrincipal` in which case it + is resolved by a custom Spring Security resolver through `Authentication#getPrincipal`. + +| `HttpMethod` +| The HTTP method of the request. + +| `java.util.Locale` +| The current request locale, determined by the most specific `LocaleResolver` available (in + effect, the configured `LocaleResolver` or `LocaleContextResolver`). + +| `java.util.TimeZone` + `java.time.ZoneId` +| The time zone associated with the current request, as determined by a `LocaleContextResolver`. + +| `java.io.InputStream`, `java.io.Reader` +| For access to the raw request body as exposed by the Servlet API. + +| `java.io.OutputStream`, `java.io.Writer` +| For access to the raw response body as exposed by the Servlet API. + +| `@PathVariable` +| For access to URI template variables. See <>. + +| `@MatrixVariable` +| For access to name-value pairs in URI path segments. See <>. + +| `@RequestParam` +| For access to the Servlet request parameters, including multipart files. Parameter values + are converted to the declared method argument type. See <> as well + as <>. + + Note that use of `@RequestParam` is optional for simple parameter values. + See "`Any other argument`", at the end of this table. + +| `@RequestHeader` +| For access to request headers. Header values are converted to the declared method argument + type. See <>. + +| `@CookieValue` +| For access to cookies. Cookies values are converted to the declared method argument + type. See <>. + +| `@RequestBody` +| For access to the HTTP request body. Body content is converted to the declared method + argument type by using `HttpMessageConverter` implementations. See <>. + +| `HttpEntity` +| For access to request headers and body. The body is converted with an `HttpMessageConverter`. + See <>. + +| `@RequestPart` +| For access to a part in a `multipart/form-data` request, converting the part's body + with an `HttpMessageConverter`. See <>. + +| `java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap` +| For access to the model that is used in HTML controllers and exposed to templates as + part of view rendering. + +| `RedirectAttributes` +| Specify attributes to use in case of a redirect (that is, to be appended to the query + string) and flash attributes to be stored temporarily until the request after redirect. + See <> and <>. + +| `@ModelAttribute` +| For access to an existing attribute in the model (instantiated if not present) with + data binding and validation applied. See <> as well as + <> and <>. + + Note that use of `@ModelAttribute` is optional (for example, to set its attributes). + See "`Any other argument`" at the end of this table. + +| `Errors`, `BindingResult` +| For access to errors from validation and data binding for a command object + (that is, a `@ModelAttribute` argument) or errors from the validation of a `@RequestBody` or + `@RequestPart` arguments. You must declare an `Errors`, or `BindingResult` argument + immediately after the validated method argument. + +| `SessionStatus` + class-level `@SessionAttributes` +| For marking form processing complete, which triggers cleanup of session attributes + declared through a class-level `@SessionAttributes` annotation. See + <> for more details. + +| `UriComponentsBuilder` +| For preparing a URL relative to the current request's host, port, scheme, context path, and + the literal part of the servlet mapping. See <>. + +| `@SessionAttribute` +| For access to any session attribute, in contrast to model attributes stored in the session + as a result of a class-level `@SessionAttributes` declaration. See + <> for more details. + +| `@RequestAttribute` +| For access to request attributes. See <> for more details. + +| Any other argument +| If a method argument is not matched to any of the earlier values in this table and it is + a simple type (as determined by + {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]), + it is resolved as a `@RequestParam`. Otherwise, it is resolved as a `@ModelAttribute`. +|=== + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc new file mode 100644 index 000000000000..c66603740752 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc @@ -0,0 +1,41 @@ +[[mvc-ann-cookievalue]] += `@CookieValue` + +[.small]#<># + +You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument +in a controller. + +Consider a request with the following cookie: + +[literal,subs="verbatim,quotes"] +---- +JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84 +---- + +The following example shows how to get the cookie value: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/demo") + public void handle(@CookieValue("JSESSIONID") String cookie) { <1> + //... + } +---- +<1> Get the value of the `JSESSIONID` cookie. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/demo") + fun handle(@CookieValue("JSESSIONID") cookie: String) { // <1> + //... + } +---- +<1> Get the value of the `JSESSIONID` cookie. + +If the target method parameter type is not `String`, type conversion is applied automatically. +See <>. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc new file mode 100644 index 000000000000..b4ecd70d0276 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc @@ -0,0 +1,46 @@ +[[mvc-flash-attributes]] += Flash Attributes + +Flash attributes provide a way for one request to store attributes that are intended for use in +another. This is most commonly needed when redirecting -- for example, the +Post-Redirect-Get pattern. Flash attributes are saved temporarily before the +redirect (typically in the session) to be made available to the request after the +redirect and are removed immediately. + +Spring MVC has two main abstractions in support of flash attributes. `FlashMap` is used +to hold flash attributes, while `FlashMapManager` is used to store, retrieve, and manage +`FlashMap` instances. + +Flash attribute support is always "`on`" and does not need to be enabled explicitly. +However, if not used, it never causes HTTP session creation. On each request, there is an +"`input`" `FlashMap` with attributes passed from a previous request (if any) and an +"`output`" `FlashMap` with attributes to save for a subsequent request. Both `FlashMap` +instances are accessible from anywhere in Spring MVC through static methods in +`RequestContextUtils`. + +Annotated controllers typically do not need to work with `FlashMap` directly. Instead, a +`@RequestMapping` method can accept an argument of type `RedirectAttributes` and use it +to add flash attributes for a redirect scenario. Flash attributes added through +`RedirectAttributes` are automatically propagated to the "`output`" FlashMap. Similarly, +after the redirect, attributes from the "`input`" `FlashMap` are automatically added to the +`Model` of the controller that serves the target URL. + +.Matching requests to flash attributes +**** +The concept of flash attributes exists in many other web frameworks and has proven to sometimes +be exposed to concurrency issues. This is because, by definition, flash attributes +are to be stored until the next request. However the very "`next`" request may not be the +intended recipient but another asynchronous request (for example, polling or resource requests), +in which case the flash attributes are removed too early. + +To reduce the possibility of such issues, `RedirectView` automatically "`stamps`" +`FlashMap` instances with the path and query parameters of the target redirect URL. In +turn, the default `FlashMapManager` matches that information to incoming requests when +it looks up the "`input`" `FlashMap`. + +This does not entirely eliminate the possibility of a concurrency issue but +reduces it greatly with information that is already available in the redirect URL. +Therefore, we recommend that you use flash attributes mainly for redirect scenarios. +**** + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc new file mode 100644 index 000000000000..ae9ffe0d08c1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc @@ -0,0 +1,27 @@ +[[mvc-ann-httpentity]] += HttpEntity + +[.small]#<># + +`HttpEntity` is more or less identical to using <> but is based on a +container object that exposes request headers and body. The following listing shows an example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/accounts") + public void handle(HttpEntity entity) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/accounts") + fun handle(entity: HttpEntity) { + // ... + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc new file mode 100644 index 000000000000..83d9bc3385c5 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc @@ -0,0 +1,145 @@ +[[mvc-ann-jackson]] += Jackson JSON + +Spring offers support for the Jackson JSON library. + +[[mvc-ann-jsonview]] +== JSON Views +[.small]#<># + +Spring MVC provides built-in support for +https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], +which allow rendering only a subset of all fields in an `Object`. To use it with +`@ResponseBody` or `ResponseEntity` controller methods, you can use Jackson's +`@JsonView` annotation to activate a serialization view class, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RestController + public class UserController { + + @GetMapping("/user") + @JsonView(User.WithoutPasswordView.class) + public User getUser() { + return new User("eric", "7!jd#h23"); + } + } + + public class User { + + public interface WithoutPasswordView {}; + public interface WithPasswordView extends WithoutPasswordView {}; + + private String username; + private String password; + + public User() { + } + + public User(String username, String password) { + this.username = username; + this.password = password; + } + + @JsonView(WithoutPasswordView.class) + public String getUsername() { + return this.username; + } + + @JsonView(WithPasswordView.class) + public String getPassword() { + return this.password; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RestController + class UserController { + + @GetMapping("/user") + @JsonView(User.WithoutPasswordView::class) + fun getUser() = User("eric", "7!jd#h23") + } + + class User( + @JsonView(WithoutPasswordView::class) val username: String, + @JsonView(WithPasswordView::class) val password: String) { + + interface WithoutPasswordView + interface WithPasswordView : WithoutPasswordView + } +---- + +NOTE: `@JsonView` allows an array of view classes, but you can specify only one per +controller method. If you need to activate multiple views, you can use a composite interface. + +If you want to do the above programmatically, instead of declaring an `@JsonView` annotation, +wrap the return value with `MappingJacksonValue` and use it to supply the serialization view: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RestController + public class UserController { + + @GetMapping("/user") + public MappingJacksonValue getUser() { + User user = new User("eric", "7!jd#h23"); + MappingJacksonValue value = new MappingJacksonValue(user); + value.setSerializationView(User.WithoutPasswordView.class); + return value; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RestController + class UserController { + + @GetMapping("/user") + fun getUser(): MappingJacksonValue { + val value = MappingJacksonValue(User("eric", "7!jd#h23")) + value.serializationView = User.WithoutPasswordView::class.java + return value + } + } +---- + +For controllers that rely on view resolution, you can add the serialization view class +to the model, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class UserController extends AbstractController { + + @GetMapping("/user") + public String getUser(Model model) { + model.addAttribute("user", new User("eric", "7!jd#h23")); + model.addAttribute(JsonView.class.getName(), User.WithoutPasswordView.class); + return "userView"; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class UserController : AbstractController() { + + @GetMapping("/user") + fun getUser(model: Model): String { + model["user"] = User("eric", "7!jd#h23") + model[JsonView::class.qualifiedName] = User.WithoutPasswordView::class.java + return "userView" + } + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc new file mode 100644 index 000000000000..0fb3135050c6 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc @@ -0,0 +1,141 @@ +[[mvc-ann-matrix-variables]] += Matrix Variables + +[.small]#<># + +https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in +path segments. In Spring MVC, we refer to those as "`matrix variables`" based on an +https://www.w3.org/DesignIssues/MatrixURIs.html["`old post`"] by Tim Berners-Lee, but they +can be also be referred to as URI path parameters. + +Matrix variables can appear in any path segment, with each variable separated by a semicolon and +multiple values separated by comma (for example, `/cars;color=red,green;year=2012`). Multiple +values can also be specified through repeated variable names (for example, +`color=red;color=green;color=blue`). + +If a URL is expected to contain matrix variables, the request mapping for a controller +method must use a URI variable to mask that variable content and ensure the request can +be matched successfully independent of matrix variable order and presence. +The following example uses a matrix variable: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // GET /pets/42;q=11;r=22 + + @GetMapping("/pets/{petId}") + public void findPet(@PathVariable String petId, @MatrixVariable int q) { + + // petId == 42 + // q == 11 + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // GET /pets/42;q=11;r=22 + + @GetMapping("/pets/{petId}") + fun findPet(@PathVariable petId: String, @MatrixVariable q: Int) { + + // petId == 42 + // q == 11 + } +---- + +Given that all path segments may contain matrix variables, you may sometimes need to +disambiguate which path variable the matrix variable is expected to be in. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // GET /owners/42;q=11/pets/21;q=22 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + public void findPet( + @MatrixVariable(name="q", pathVar="ownerId") int q1, + @MatrixVariable(name="q", pathVar="petId") int q2) { + + // q1 == 11 + // q2 == 22 + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // GET /owners/42;q=11/pets/21;q=22 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + fun findPet( + @MatrixVariable(name = "q", pathVar = "ownerId") q1: Int, + @MatrixVariable(name = "q", pathVar = "petId") q2: Int) { + + // q1 == 11 + // q2 == 22 + } +---- + +A matrix variable may be defined as optional and a default value specified, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // GET /pets/42 + + @GetMapping("/pets/{petId}") + public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) { + + // q == 1 + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // GET /pets/42 + + @GetMapping("/pets/{petId}") + fun findPet(@MatrixVariable(required = false, defaultValue = "1") q: Int) { + + // q == 1 + } +---- + +To get all matrix variables, you can use a `MultiValueMap`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + public void findPet( + @MatrixVariable MultiValueMap matrixVars, + @MatrixVariable(pathVar="petId") MultiValueMap petMatrixVars) { + + // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] + // petMatrixVars: ["q" : 22, "s" : 23] + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + fun findPet( + @MatrixVariable matrixVars: MultiValueMap, + @MatrixVariable(pathVar="petId") petMatrixVars: MultiValueMap) { + + // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] + // petMatrixVars: ["q" : 22, "s" : 23] + } +---- + +Note that you need to enable the use of matrix variables. In the MVC Java configuration, +you need to set a `UrlPathHelper` with `removeSemicolonContent=false` through +<>. In the MVC XML namespace, you can set +``. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc new file mode 100644 index 000000000000..bd26f9a1af7e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc @@ -0,0 +1,194 @@ +[[mvc-ann-modelattrib-method-args]] += `@ModelAttribute` + +[.small]#<># + +You can use the `@ModelAttribute` annotation on a method argument to access an attribute from +the model or have it be instantiated if not present. The model attribute is also overlain with +values from HTTP Servlet request parameters whose names match to field names. This is referred +to as data binding, and it saves you from having to deal with parsing and converting individual +query parameters and form fields. The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + public String processSubmit(@ModelAttribute Pet pet) { // <1> + // method logic... + } +---- +<1> Bind an instance of `Pet`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +@PostMapping("/owners/{ownerId}/pets/{petId}/edit") +fun processSubmit(@ModelAttribute pet: Pet): String { // <1> + // method logic... +} +---- +<1> Bind an instance of `Pet`. + +The `Pet` instance above is sourced in one of the following ways: + +* Retrieved from the model where it may have been added by a + <>. +* Retrieved from the HTTP session if the model attribute was listed in + the class-level <> annotation. +* Obtained through a `Converter` where the model attribute name matches the name of a + request value such as a path variable or a request parameter (see next example). +* Instantiated using its default constructor. +* Instantiated through a "`primary constructor`" with arguments that match to Servlet + request parameters. Argument names are determined through JavaBeans + `@ConstructorProperties` or through runtime-retained parameter names in the bytecode. + +One alternative to using a <> to +supply it or relying on the framework to create the model attribute, is to have a +`Converter` to provide the instance. This is applied when the model attribute +name matches to the name of a request value such as a path variable or a request +parameter, and there is a `Converter` from `String` to the model attribute type. +In the following example, the model attribute name is `account` which matches the URI +path variable `account`, and there is a registered `Converter` which +could load the `Account` from a data store: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PutMapping("/accounts/{account}") + public String save(@ModelAttribute("account") Account account) { // <1> + // ... + } +---- +<1> Bind an instance of `Account` using an explicit attribute name. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PutMapping("/accounts/{account}") + fun save(@ModelAttribute("account") account: Account): String { // <1> + // ... + } +---- +<1> Bind an instance of `Account` using an explicit attribute name. + +After the model attribute instance is obtained, data binding is applied. The +`WebDataBinder` class matches Servlet request parameter names (query parameters and form +fields) to field names on the target `Object`. Matching fields are populated after type +conversion is applied, where necessary. For more on data binding (and validation), see +<>. For more on customizing data binding, see +<>. + +Data binding can result in errors. By default, a `BindException` is raised. However, to check +for such errors in the controller method, you can add a `BindingResult` argument immediately next +to the `@ModelAttribute`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { // <1> + if (result.hasErrors()) { + return "petForm"; + } + // ... + } +---- +<1> Adding a `BindingResult` next to the `@ModelAttribute`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + fun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { // <1> + if (result.hasErrors()) { + return "petForm" + } + // ... + } +---- +<1> Adding a `BindingResult` next to the `@ModelAttribute`. + +In some cases, you may want access to a model attribute without data binding. For such +cases, you can inject the `Model` into the controller and access it directly or, +alternatively, set `@ModelAttribute(binding=false)`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ModelAttribute + public AccountForm setUpForm() { + return new AccountForm(); + } + + @ModelAttribute + public Account findAccount(@PathVariable String accountId) { + return accountRepository.findOne(accountId); + } + + @PostMapping("update") + public String update(@Valid AccountForm form, BindingResult result, + @ModelAttribute(binding=false) Account account) { // <1> + // ... + } +---- +<1> Setting `@ModelAttribute(binding=false)`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ModelAttribute + fun setUpForm(): AccountForm { + return AccountForm() + } + + @ModelAttribute + fun findAccount(@PathVariable accountId: String): Account { + return accountRepository.findOne(accountId) + } + + @PostMapping("update") + fun update(@Valid form: AccountForm, result: BindingResult, + @ModelAttribute(binding = false) account: Account): String { // <1> + // ... + } +---- +<1> Setting `@ModelAttribute(binding=false)`. + +You can automatically apply validation after data binding by adding the +`jakarta.validation.Valid` annotation or Spring's `@Validated` annotation +(<> and +<>). The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { // <1> + if (result.hasErrors()) { + return "petForm"; + } + // ... + } +---- +<1> Validate the `Pet` instance. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/owners/{ownerId}/pets/{petId}/edit") + fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { // <1> + if (result.hasErrors()) { + return "petForm" + } + // ... + } +---- +<1> Validate the `Pet` instance. + +Note that using `@ModelAttribute` is optional (for example, to set its attributes). +By default, any argument that is not a simple value type (as determined by +{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) +and is not resolved by any other argument resolver is treated as if it were annotated +with `@ModelAttribute`. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc new file mode 100644 index 000000000000..59ca68e20e95 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc @@ -0,0 +1,186 @@ +[[mvc-multipart-forms]] += Multipart + +[.small]#<># + +After a `MultipartResolver` has been <>, the content of POST +requests with `multipart/form-data` is parsed and accessible as regular request +parameters. The following example accesses one regular form field and one uploaded +file: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + public class FileUploadController { + + @PostMapping("/form") + public String handleFormUpload(@RequestParam("name") String name, + @RequestParam("file") MultipartFile file) { + + if (!file.isEmpty()) { + byte[] bytes = file.getBytes(); + // store the bytes somewhere + return "redirect:uploadSuccess"; + } + return "redirect:uploadFailure"; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + class FileUploadController { + + @PostMapping("/form") + fun handleFormUpload(@RequestParam("name") name: String, + @RequestParam("file") file: MultipartFile): String { + + if (!file.isEmpty) { + val bytes = file.bytes + // store the bytes somewhere + return "redirect:uploadSuccess" + } + return "redirect:uploadFailure" + } + } +---- + +Declaring the argument type as a `List` allows for resolving multiple +files for the same parameter name. + +When the `@RequestParam` annotation is declared as a `Map` or +`MultiValueMap`, without a parameter name specified in the annotation, +then the map is populated with the multipart files for each given parameter name. + +NOTE: With Servlet multipart parsing, you may also declare `jakarta.servlet.http.Part` +instead of Spring's `MultipartFile`, as a method argument or collection value type. + +You can also use multipart content as part of data binding to a +<>. For example, the form field +and file from the preceding example could be fields on a form object, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + class MyForm { + + private String name; + + private MultipartFile file; + + // ... + } + + @Controller + public class FileUploadController { + + @PostMapping("/form") + public String handleFormUpload(MyForm form, BindingResult errors) { + if (!form.getFile().isEmpty()) { + byte[] bytes = form.getFile().getBytes(); + // store the bytes somewhere + return "redirect:uploadSuccess"; + } + return "redirect:uploadFailure"; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyForm(val name: String, val file: MultipartFile, ...) + + @Controller + class FileUploadController { + + @PostMapping("/form") + fun handleFormUpload(form: MyForm, errors: BindingResult): String { + if (!form.file.isEmpty) { + val bytes = form.file.bytes + // store the bytes somewhere + return "redirect:uploadSuccess" + } + return "redirect:uploadFailure" + } + } +---- + + +Multipart requests can also be submitted from non-browser clients in a RESTful service +scenario. The following example shows a file with JSON: + +[literal,subs="verbatim,quotes"] +---- +POST /someUrl +Content-Type: multipart/mixed + +--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp +Content-Disposition: form-data; name="meta-data" +Content-Type: application/json; charset=UTF-8 +Content-Transfer-Encoding: 8bit + +{ + "name": "value" +} +--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp +Content-Disposition: form-data; name="file-data"; filename="file.properties" +Content-Type: text/xml +Content-Transfer-Encoding: 8bit +... File Data ... +---- + +You can access the "meta-data" part with `@RequestParam` as a `String` but you'll +probably want it deserialized from JSON (similar to `@RequestBody`). Use the +`@RequestPart` annotation to access a multipart after converting it with an +<>: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/") + public String handle(@RequestPart("meta-data") MetaData metadata, + @RequestPart("file-data") MultipartFile file) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/") + fun handle(@RequestPart("meta-data") metadata: MetaData, + @RequestPart("file-data") file: MultipartFile): String { + // ... + } +---- + +You can use `@RequestPart` in combination with `jakarta.validation.Valid` or use Spring's +`@Validated` annotation, both of which cause Standard Bean Validation to be applied. +By default, validation errors cause a `MethodArgumentNotValidException`, which is turned +into a 400 (BAD_REQUEST) response. Alternatively, you can handle validation errors locally +within the controller through an `Errors` or `BindingResult` argument, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/") + public String handle(@Valid @RequestPart("meta-data") MetaData metadata, + BindingResult result) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/") + fun handle(@Valid @RequestPart("meta-data") metadata: MetaData, + result: BindingResult): String { + // ... + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc new file mode 100644 index 000000000000..135e27908786 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc @@ -0,0 +1,52 @@ +[[mvc-redirecting-passing-data]] += Redirect Attributes + +By default, all model attributes are considered to be exposed as URI template variables in +the redirect URL. Of the remaining attributes, those that are primitive types or +collections or arrays of primitive types are automatically appended as query parameters. + +Appending primitive type attributes as query parameters can be the desired result if a +model instance was prepared specifically for the redirect. However, in annotated +controllers, the model can contain additional attributes added for rendering purposes (for example, +drop-down field values). To avoid the possibility of having such attributes appear in the +URL, a `@RequestMapping` method can declare an argument of type `RedirectAttributes` and +use it to specify the exact attributes to make available to `RedirectView`. If the method +does redirect, the content of `RedirectAttributes` is used. Otherwise, the content of the +model is used. + +The `RequestMappingHandlerAdapter` provides a flag called +`ignoreDefaultModelOnRedirect`, which you can use to indicate that the content of the default +`Model` should never be used if a controller method redirects. Instead, the controller +method should declare an attribute of type `RedirectAttributes` or, if it does not do so, +no attributes should be passed on to `RedirectView`. Both the MVC namespace and the MVC +Java configuration keep this flag set to `false`, to maintain backwards compatibility. +However, for new applications, we recommend setting it to `true`. + +Note that URI template variables from the present request are automatically made +available when expanding a redirect URL, and you don't need to explicitly add them +through `Model` or `RedirectAttributes`. The following example shows how to define a redirect: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/files/{path}") + public String upload(...) { + // ... + return "redirect:files/{path}"; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/files/{path}") + fun upload(...): String { + // ... + return "redirect:files/{path}" + } +---- + +Another way of passing data to the redirect target is by using flash attributes. Unlike +other redirect attributes, flash attributes are saved in the HTTP session (and, hence, do +not appear in the URL). See <> for more information. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc new file mode 100644 index 000000000000..35f921cc9179 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc @@ -0,0 +1,30 @@ +[[mvc-ann-requestattrib]] += `@RequestAttribute` + +[.small]#<># + +Similar to `@SessionAttribute`, you can use the `@RequestAttribute` annotations to +access pre-existing request attributes created earlier (for example, by a Servlet `Filter` +or `HandlerInterceptor`): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/") + public String handle(@RequestAttribute Client client) { // <1> + // ... + } +---- +<1> Using the `@RequestAttribute` annotation. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/") + fun handle(@RequestAttribute client: Client): String { // <1> + // ... + } +---- +<1> Using the `@RequestAttribute` annotation. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc new file mode 100644 index 000000000000..e19db56d7dab --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc @@ -0,0 +1,55 @@ +[[mvc-ann-requestbody]] += `@RequestBody` + +[.small]#<># + +You can use the `@RequestBody` annotation to have the request body read and deserialized into an +`Object` through an <>. +The following example uses a `@RequestBody` argument: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/accounts") + public void handle(@RequestBody Account account) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/accounts") + fun handle(@RequestBody account: Account) { + // ... + } +---- + + +You can use the <> option of the <> to +configure or customize message conversion. + +You can use `@RequestBody` in combination with `jakarta.validation.Valid` or Spring's +`@Validated` annotation, both of which cause Standard Bean Validation to be applied. +By default, validation errors cause a `MethodArgumentNotValidException`, which is turned +into a 400 (BAD_REQUEST) response. Alternatively, you can handle validation errors locally +within the controller through an `Errors` or `BindingResult` argument, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping("/accounts") + public void handle(@Valid @RequestBody Account account, BindingResult result) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/accounts") + fun handle(@Valid @RequestBody account: Account, result: BindingResult) { + // ... + } +---- + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc new file mode 100644 index 000000000000..b41391ca5ba9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc @@ -0,0 +1,62 @@ +[[mvc-ann-requestheader]] += `@RequestHeader` + +[.small]#<># + +You can use the `@RequestHeader` annotation to bind a request header to a method argument in a +controller. + +Consider the following request, with headers: + +[literal] +[subs="verbatim,quotes"] +---- +Host localhost:8080 +Accept text/html,application/xhtml+xml,application/xml;q=0.9 +Accept-Language fr,en-gb;q=0.7,en;q=0.3 +Accept-Encoding gzip,deflate +Accept-Charset ISO-8859-1,utf-8;q=0.7,*;q=0.7 +Keep-Alive 300 +---- + +The following example gets the value of the `Accept-Encoding` and `Keep-Alive` headers: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/demo") + public void handle( + @RequestHeader("Accept-Encoding") String encoding, // <1> + @RequestHeader("Keep-Alive") long keepAlive) { // <2> + //... + } +---- +<1> Get the value of the `Accept-Encoding` header. +<2> Get the value of the `Keep-Alive` header. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/demo") + fun handle( + @RequestHeader("Accept-Encoding") encoding: String, // <1> + @RequestHeader("Keep-Alive") keepAlive: Long) { // <2> + //... + } +---- +<1> Get the value of the `Accept-Encoding` header. +<2> Get the value of the `Keep-Alive` header. + +If the target method parameter type is not +`String`, type conversion is automatically applied. See <>. + +When an `@RequestHeader` annotation is used on a `Map`, +`MultiValueMap`, or `HttpHeaders` argument, the map is populated +with all header values. + +TIP: Built-in support is available for converting a comma-separated string into an +array or collection of strings or other types known to the type conversion system. For +example, a method parameter annotated with `@RequestHeader("Accept")` can be of type +`String` but also `String[]` or `List`. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc new file mode 100644 index 000000000000..3d124f4ee0e6 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc @@ -0,0 +1,77 @@ +[[mvc-ann-requestparam]] += `@RequestParam` + +[.small]#<># + +You can use the `@RequestParam` annotation to bind Servlet request parameters (that is, +query parameters or form data) to a method argument in a controller. + +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + @RequestMapping("/pets") + public class EditPetForm { + + // ... + + @GetMapping + public String setupForm(@RequestParam("petId") int petId, Model model) { <1> + Pet pet = this.clinic.loadPet(petId); + model.addAttribute("pet", pet); + return "petForm"; + } + + // ... + + } +---- +<1> Using `@RequestParam` to bind `petId`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.ui.set + + @Controller + @RequestMapping("/pets") + class EditPetForm { + + // ... + + @GetMapping + fun setupForm(@RequestParam("petId") petId: Int, model: Model): String { // <1> + val pet = this.clinic.loadPet(petId); + model["pet"] = pet + return "petForm" + } + + // ... + + } +---- +<1> Using `@RequestParam` to bind `petId`. + +By default, method parameters that use this annotation are required, but you can specify that +a method parameter is optional by setting the `@RequestParam` annotation's `required` flag to +`false` or by declaring the argument with an `java.util.Optional` wrapper. + +Type conversion is automatically applied if the target method parameter type is not +`String`. See <>. + +Declaring the argument type as an array or list allows for resolving multiple parameter +values for the same parameter name. + +When an `@RequestParam` annotation is declared as a `Map` or +`MultiValueMap`, without a parameter name specified in the annotation, +then the map is populated with the request parameter values for each given parameter name. + +Note that use of `@RequestParam` is optional (for example, to set its attributes). +By default, any argument that is a simple value type (as determined by +{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]) +and is not resolved by any other argument resolver, is treated as if it were annotated +with `@RequestParam`. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc new file mode 100644 index 000000000000..9e16a49a1b10 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc @@ -0,0 +1,43 @@ +[[mvc-ann-responsebody]] += `@ResponseBody` + +[.small]#<># + +You can use the `@ResponseBody` annotation on a method to have the return serialized +to the response body through an +<>. +The following listing shows an example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/accounts/{id}") + @ResponseBody + public Account handle() { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/accounts/{id}") + @ResponseBody + fun handle(): Account { + // ... + } +---- + +`@ResponseBody` is also supported at the class level, in which case it is inherited by +all controller methods. This is the effect of `@RestController`, which is nothing more +than a meta-annotation marked with `@Controller` and `@ResponseBody`. + +You can use `@ResponseBody` with reactive types. +See <> and <> for more details. + +You can use the <> option of the <> to +configure or customize message conversion. + +You can combine `@ResponseBody` methods with JSON serialization views. +See <> for details. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc new file mode 100644 index 000000000000..46a78dccd7e3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc @@ -0,0 +1,40 @@ +[[mvc-ann-responseentity]] += ResponseEntity + +[.small]#<># + +`ResponseEntity` is like <> but with status and headers. For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/something") + public ResponseEntity handle() { + String body = ... ; + String etag = ... ; + return ResponseEntity.ok().eTag(etag).body(body); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/something") + fun handle(): ResponseEntity { + val body = ... + val etag = ... + return ResponseEntity.ok().eTag(etag).build(body) + } +---- + +Spring MVC supports using a single value <> +to produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive +types for the body. This allows the following types of async responses: + +* `ResponseEntity>` or `ResponseEntity>` make the response status and + headers known immediately while the body is provided asynchronously at a later point. + Use `Mono` if the body consists of 0..1 values or `Flux` if it can produce multiple values. +* `Mono>` provides all three -- response status, headers, and body, + asynchronously at a later point. This allows the response status and headers to vary + depending on the outcome of asynchronous request handling. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc new file mode 100644 index 000000000000..4ac29378d55f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc @@ -0,0 +1,105 @@ +[[mvc-ann-return-types]] += Return Values + +[.small]#<># + +The next table describes the supported controller method return values. Reactive types are +supported for all return values. + +[cols="1,2", options="header"] +|=== +| Controller method return value | Description + +| `@ResponseBody` +| The return value is converted through `HttpMessageConverter` implementations and written to the + response. See <>. + +| `HttpEntity`, `ResponseEntity` +| The return value that specifies the full response (including HTTP headers and body) is to be converted + through `HttpMessageConverter` implementations and written to the response. + See <>. + +| `HttpHeaders` +| For returning a response with headers and no body. + +| `ErrorResponse` +| To render an RFC 7807 error response with details in the body, + see <> + +| `ProblemDetail` +| To render an RFC 7807 error response with details in the body, + see <> + +| `String` +| A view name to be resolved with `ViewResolver` implementations and used together with the implicit + model -- determined through command objects and `@ModelAttribute` methods. The handler + method can also programmatically enrich the model by declaring a `Model` argument + (see <>). + +| `View` +| A `View` instance to use for rendering together with the implicit model -- determined + through command objects and `@ModelAttribute` methods. The handler method can also + programmatically enrich the model by declaring a `Model` argument + (see <>). + +| `java.util.Map`, `org.springframework.ui.Model` +| Attributes to be added to the implicit model, with the view name implicitly determined + through a `RequestToViewNameTranslator`. + +| `@ModelAttribute` +| An attribute to be added to the model, with the view name implicitly determined through + a `RequestToViewNameTranslator`. + + Note that `@ModelAttribute` is optional. See "Any other return value" at the end of + this table. + +| `ModelAndView` object +| The view and model attributes to use and, optionally, a response status. + +| `void` +| A method with a `void` return type (or `null` return value) is considered to have fully + handled the response if it also has a `ServletResponse`, an `OutputStream` argument, or + an `@ResponseStatus` annotation. The same is also true if the controller has made a positive + `ETag` or `lastModified` timestamp check (see <> for details). + + If none of the above is true, a `void` return type can also indicate "`no response body`" for + REST controllers or a default view name selection for HTML controllers. + +| `DeferredResult` +| Produce any of the preceding return values asynchronously from any thread -- for example, as a + result of some event or callback. See <> and <>. + +| `Callable` +| Produce any of the above return values asynchronously in a Spring MVC-managed thread. + See <> and <>. + +| `ListenableFuture`, + `java.util.concurrent.CompletionStage`, + `java.util.concurrent.CompletableFuture` +| Alternative to `DeferredResult`, as a convenience (for example, when an underlying service + returns one of those). + +| `ResponseBodyEmitter`, `SseEmitter` +| Emit a stream of objects asynchronously to be written to the response with + `HttpMessageConverter` implementations. Also supported as the body of a `ResponseEntity`. + See <> and <>. + +| `StreamingResponseBody` +| Write to the response `OutputStream` asynchronously. Also supported as the body of a + `ResponseEntity`. See <> and <>. + +| Reactor and other reactive types registered via `ReactiveAdapterRegistry` +| A single value type, e.g. `Mono`, is comparable to returning `DeferredResult`. + A multi-value type, e.g. `Flux`, may be treated as a stream depending on the requested + media type, e.g. "text/event-stream", "application/json+stream", or otherwise is + collected to a List and rendered as a single value. See <> and + <>. + +| Other return values +| If a return value remains unresolved in any other way, it is treated as a model + attribute, unless it is a simple type as determined by + {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], + in which case it remains unresolved. +|=== + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc new file mode 100644 index 000000000000..a205b2ec2ff8 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc @@ -0,0 +1,39 @@ +[[mvc-ann-sessionattribute]] += `@SessionAttribute` + +[.small]#<># + +If you need access to pre-existing session attributes that are managed globally +(that is, outside the controller -- for example, by a filter) and may or may not be present, +you can use the `@SessionAttribute` annotation on a method parameter, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RequestMapping("/") + public String handle(@SessionAttribute User user) { <1> + // ... + } +---- +<1> Using a `@SessionAttribute` annotation. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RequestMapping("/") + fun handle(@SessionAttribute user: User): String { // <1> + // ... + } +---- +<1> Using a `@SessionAttribute` annotation. + +For use cases that require adding or removing session attributes, consider injecting +`org.springframework.web.context.request.WebRequest` or +`jakarta.servlet.http.HttpSession` into the controller method. + +For temporary storage of model attributes in the session as part of a controller +workflow, consider using `@SessionAttributes` as described in +<>. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc new file mode 100644 index 000000000000..1163d77211d7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc @@ -0,0 +1,85 @@ +[[mvc-ann-sessionattributes]] += `@SessionAttributes` + +[.small]#<># + +`@SessionAttributes` is used to store model attributes in the HTTP Servlet session between +requests. It is a type-level annotation that declares the session attributes used by a +specific controller. This typically lists the names of model attributes or types of +model attributes that should be transparently stored in the session for subsequent +requests to access. + +The following example uses the `@SessionAttributes` annotation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + @SessionAttributes("pet") // <1> + public class EditPetForm { + // ... + } +---- +<1> Using the `@SessionAttributes` annotation. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + @SessionAttributes("pet") // <1> + class EditPetForm { + // ... + } +---- +<1> Using the `@SessionAttributes` annotation. + +On the first request, when a model attribute with the name, `pet`, is added to the model, +it is automatically promoted to and saved in the HTTP Servlet session. It remains there +until another controller method uses a `SessionStatus` method argument to clear the +storage, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + @SessionAttributes("pet") // <1> + public class EditPetForm { + + // ... + + @PostMapping("/pets/{id}") + public String handle(Pet pet, BindingResult errors, SessionStatus status) { + if (errors.hasErrors) { + // ... + } + status.setComplete(); // <2> + // ... + } + } +---- +<1> Storing the `Pet` value in the Servlet session. +<2> Clearing the `Pet` value from the Servlet session. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +@Controller +@SessionAttributes("pet") // <1> +class EditPetForm { + + // ... + + @PostMapping("/pets/{id}") + fun handle(pet: Pet, errors: BindingResult, status: SessionStatus): String { + if (errors.hasErrors()) { + // ... + } + status.setComplete() // <2> + // ... + } +} +---- +<1> Storing the `Pet` value in the Servlet session. +<2> Clearing the `Pet` value from the Servlet session. + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc new file mode 100644 index 000000000000..d876bd7e7f11 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc @@ -0,0 +1,34 @@ +[[mvc-ann-typeconversion]] += Type Conversion + +[.small]#<># + +Some annotated controller method arguments that represent `String`-based request input (such as +`@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) +can require type conversion if the argument is declared as something other than `String`. + +For such cases, type conversion is automatically applied based on the configured converters. +By default, simple types (`int`, `long`, `Date`, and others) are supported. You can customize +type conversion through a `WebDataBinder` (see <>) or by registering +`Formatters` with the `FormattingConversionService`. +See <>. + +A practical issue in type conversion is the treatment of an empty String source value. +Such a value is treated as missing if it becomes `null` as a result of type conversion. +This can be the case for `Long`, `UUID`, and other target types. If you want to allow `null` +to be injected, either use the `required` flag on the argument annotation, or declare the +argument as `@Nullable`. + +[NOTE] +==== +As of 5.3, non-null arguments will be enforced even after type conversion. If your handler +method intends to accept a null value as well, either declare your argument as `@Nullable` +or mark it as `required=false` in the corresponding `@RequestParam`, etc. annotation. This is +a best practice and the recommended solution for regressions encountered in a 5.3 upgrade. + +Alternatively, you may specifically handle e.g. the resulting `MissingPathVariableException` +in the case of a required `@PathVariable`. A null value after conversion will be treated like +an empty original value, so the corresponding `Missing...Exception` variants will be thrown. +==== + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc new file mode 100644 index 000000000000..08a54deef469 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc @@ -0,0 +1,99 @@ +[[mvc-ann-modelattrib-methods]] += Model + +[.small]#<># + +You can use the `@ModelAttribute` annotation: + +* On a <> in `@RequestMapping` methods +to create or access an `Object` from the model and to bind it to the request through a +`WebDataBinder`. +* As a method-level annotation in `@Controller` or `@ControllerAdvice` classes that help +to initialize the model prior to any `@RequestMapping` method invocation. +* On a `@RequestMapping` method to mark its return value is a model attribute. + +This section discusses `@ModelAttribute` methods -- the second item in the preceding list. +A controller can have any number of `@ModelAttribute` methods. All such methods are +invoked before `@RequestMapping` methods in the same controller. A `@ModelAttribute` +method can also be shared across controllers through `@ControllerAdvice`. See the section on +<> for more details. + +`@ModelAttribute` methods have flexible method signatures. They support many of the same +arguments as `@RequestMapping` methods, except for `@ModelAttribute` itself or anything +related to the request body. + +The following example shows a `@ModelAttribute` method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ModelAttribute + public void populateModel(@RequestParam String number, Model model) { + model.addAttribute(accountRepository.findAccount(number)); + // add more ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ModelAttribute + fun populateModel(@RequestParam number: String, model: Model) { + model.addAttribute(accountRepository.findAccount(number)) + // add more ... + } +---- + +The following example adds only one attribute: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @ModelAttribute + public Account addAccount(@RequestParam String number) { + return accountRepository.findAccount(number); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @ModelAttribute + fun addAccount(@RequestParam number: String): Account { + return accountRepository.findAccount(number) + } +---- + + +NOTE: When a name is not explicitly specified, a default name is chosen based on the `Object` +type, as explained in the javadoc for {api-spring-framework}/core/Conventions.html[`Conventions`]. +You can always assign an explicit name by using the overloaded `addAttribute` method or +through the `name` attribute on `@ModelAttribute` (for a return value). + +You can also use `@ModelAttribute` as a method-level annotation on `@RequestMapping` methods, +in which case the return value of the `@RequestMapping` method is interpreted as a model +attribute. This is typically not required, as it is the default behavior in HTML controllers, +unless the return value is a `String` that would otherwise be interpreted as a view name. +`@ModelAttribute` can also customize the model attribute name, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/accounts/{id}") + @ModelAttribute("myAccount") + public Account handle() { + // ... + return account; + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/accounts/{id}") + @ModelAttribute("myAccount") + fun handle(): Account { + // ... + return account + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc new file mode 100644 index 000000000000..30969a6a156c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc @@ -0,0 +1,502 @@ +[[mvc-ann-requestmapping]] += Request Mapping + +[.small]#<># + +You can use the `@RequestMapping` annotation to map requests to controllers methods. It has +various attributes to match by URL, HTTP method, request parameters, headers, and media +types. You can use it at the class level to express shared mappings or at the method level +to narrow down to a specific endpoint mapping. + +There are also HTTP method specific shortcut variants of `@RequestMapping`: + +* `@GetMapping` +* `@PostMapping` +* `@PutMapping` +* `@DeleteMapping` +* `@PatchMapping` + +The shortcuts are <> that are provided because, +arguably, most controller methods should be mapped to a specific HTTP method versus +using `@RequestMapping`, which, by default, matches to all HTTP methods. +A `@RequestMapping` is still needed at the class level to express shared mappings. + +The following example has type and method level mappings: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RestController + @RequestMapping("/persons") + class PersonController { + + @GetMapping("/{id}") + public Person getPerson(@PathVariable Long id) { + // ... + } + + @PostMapping + @ResponseStatus(HttpStatus.CREATED) + public void add(@RequestBody Person person) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RestController + @RequestMapping("/persons") + class PersonController { + + @GetMapping("/{id}") + fun getPerson(@PathVariable id: Long): Person { + // ... + } + + @PostMapping + @ResponseStatus(HttpStatus.CREATED) + fun add(@RequestBody person: Person) { + // ... + } + } +---- + + + +[[mvc-ann-requestmapping-uri-templates]] +== URI patterns +[.small]#<># + +`@RequestMapping` methods can be mapped using URL patterns. There are two alternatives: + +* `PathPattern` -- a pre-parsed pattern matched against the URL path also pre-parsed as +`PathContainer`. Designed for web use, this solution deals effectively with encoding and +path parameters, and matches efficiently. +* `AntPathMatcher` -- match String patterns against a String path. This is the original +solution also used in Spring configuration to select resources on the classpath, on the +filesystem, and other locations. It is less efficient and the String path input is a +challenge for dealing effectively with encoding and other issues with URLs. + +`PathPattern` is the recommended solution for web applications and it is the only choice in +Spring WebFlux. It was enabled for use in Spring MVC from version 5.3 and is enabled by +default from version 6.0. See <> for +customizations of path matching options. + +`PathPattern` supports the same pattern syntax as `AntPathMatcher`. In addition, it also +supports the capturing pattern, e.g. `+{*spring}+`, for matching 0 or more path segments +at the end of a path. `PathPattern` also restricts the use of `+**+` for matching multiple +path segments such that it's only allowed at the end of a pattern. This eliminates many +cases of ambiguity when choosing the best matching pattern for a given request. +For full pattern syntax please refer to +{api-spring-framework}/web/util/pattern/PathPattern.html[PathPattern] and +{api-spring-framework}/util/AntPathMatcher.html[AntPathMatcher]. + +Some example patterns: + +* `+"/resources/ima?e.png"+` - match one character in a path segment +* `+"/resources/*.png"+` - match zero or more characters in a path segment +* `+"/resources/**"+` - match multiple path segments +* `+"/projects/{project}/versions"+` - match a path segment and capture it as a variable +* `+"/projects/{project:[a-z]+}/versions"+` - match and capture a variable with a regex + +Captured URI variables can be accessed with `@PathVariable`. For example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/owners/{ownerId}/pets/{petId}") + public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/owners/{ownerId}/pets/{petId}") + fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { + // ... + } +---- + + +You can declare URI variables at the class and method levels, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + @RequestMapping("/owners/{ownerId}") + public class OwnerController { + + @GetMapping("/pets/{petId}") + public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + @RequestMapping("/owners/{ownerId}") + class OwnerController { + + @GetMapping("/pets/{petId}") + fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { + // ... + } + } +---- + +URI variables are automatically converted to the appropriate type, or `TypeMismatchException` +is raised. Simple types (`int`, `long`, `Date`, and so on) are supported by default and you can +register support for any other data type. +See <> and <>. + +You can explicitly name URI variables (for example, `@PathVariable("customId")`), but you can +leave that detail out if the names are the same and your code is compiled with the `-parameters` +compiler flag. + +The syntax `{varName:regex}` declares a URI variable with a regular expression that has +syntax of `{varName:regex}`. For example, given URL `"/spring-web-3.0.5.jar"`, the following method +extracts the name, version, and file extension: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") + public void handle(@PathVariable String name, @PathVariable String version, @PathVariable String ext) { + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") + fun handle(@PathVariable name: String, @PathVariable version: String, @PathVariable ext: String) { + // ... + } +---- + +URI path patterns can also have embedded `${...}` placeholders that are resolved on startup +by using `PropertySourcesPlaceholderConfigurer` against local, system, environment, and +other property sources. You can use this, for example, to parameterize a base URL based on +some external configuration. + + + +[[mvc-ann-requestmapping-pattern-comparison]] +== Pattern Comparison +[.small]#<># + +When multiple patterns match a URL, the best match must be selected. This is done with +one of the following depending on whether use of parsed `PathPattern` is enabled for use or not: + +* {api-spring-framework}/web/util/pattern/PathPattern.html#SPECIFICITY_COMPARATOR[`PathPattern.SPECIFICITY_COMPARATOR`] +* {api-spring-framework}/util/AntPathMatcher.html#getPatternComparator-java.lang.String-[`AntPathMatcher.getPatternComparator(String path)`] + +Both help to sort patterns with more specific ones on top. A pattern is less specific if +it has a lower count of URI variables (counted as 1), single wildcards (counted as 1), +and double wildcards (counted as 2). Given an equal score, the longer pattern is chosen. +Given the same score and length, the pattern with more URI variables than wildcards is +chosen. + +The default mapping pattern (`/{asterisk}{asterisk}`) is excluded from scoring and always +sorted last. Also, prefix patterns (such as `/public/{asterisk}{asterisk}`) are considered less +specific than other pattern that do not have double wildcards. + +For the full details, follow the above links to the pattern Comparators. + + +[[mvc-ann-requestmapping-suffix-pattern-match]] +== Suffix Match + +Starting in 5.3, by default Spring MVC no longer performs `.{asterisk}` suffix pattern +matching where a controller mapped to `/person` is also implicitly mapped to +`/person.{asterisk}`. As a consequence path extensions are no longer used to interpret +the requested content type for the response -- for example, `/person.pdf`, `/person.xml`, +and so on. + +Using file extensions in this way was necessary when browsers used to send `Accept` headers +that were hard to interpret consistently. At present, that is no longer a necessity and +using the `Accept` header should be the preferred choice. + +Over time, the use of file name extensions has proven problematic in a variety of ways. +It can cause ambiguity when overlain with the use of URI variables, path parameters, and +URI encoding. Reasoning about URL-based authorization +and security (see next section for more details) also becomes more difficult. + +To completely disable the use of path extensions in versions prior to 5.3, set the following: + +* `useSuffixPatternMatching(false)`, see <> +* `favorPathExtension(false)`, see <> + +Having a way to request content types other than through the `"Accept"` header can still +be useful, e.g. when typing a URL in a browser. A safe alternative to path extensions is +to use the query parameter strategy. If you must use file extensions, consider restricting +them to a list of explicitly registered extensions through the `mediaTypes` property of +<>. + + +[[mvc-ann-requestmapping-rfd]] +== Suffix Match and RFD + +A reflected file download (RFD) attack is similar to XSS in that it relies on request input +(for example, a query parameter and a URI variable) being reflected in the response. However, instead of +inserting JavaScript into HTML, an RFD attack relies on the browser switching to perform a +download and treating the response as an executable script when double-clicked later. + +In Spring MVC, `@ResponseBody` and `ResponseEntity` methods are at risk, because +they can render different content types, which clients can request through URL path extensions. +Disabling suffix pattern matching and using path extensions for content negotiation +lower the risk but are not sufficient to prevent RFD attacks. + +To prevent RFD attacks, prior to rendering the response body, Spring MVC adds a +`Content-Disposition:inline;filename=f.txt` header to suggest a fixed and safe download +file. This is done only if the URL path contains a file extension that is neither +allowed as safe nor explicitly registered for content negotiation. However, it can +potentially have side effects when URLs are typed directly into a browser. + +Many common path extensions are allowed as safe by default. Applications with custom +`HttpMessageConverter` implementations can explicitly register file extensions for content +negotiation to avoid having a `Content-Disposition` header added for those extensions. +See <>. + +See https://pivotal.io/security/cve-2015-5211[CVE-2015-5211] for additional +recommendations related to RFD. + + +[[mvc-ann-requestmapping-consumes]] +== Consumable Media Types +[.small]#<># + +You can narrow the request mapping based on the `Content-Type` of the request, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @PostMapping(path = "/pets", consumes = "application/json") // <1> + public void addPet(@RequestBody Pet pet) { + // ... + } +---- +<1> Using a `consumes` attribute to narrow the mapping by the content type. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @PostMapping("/pets", consumes = ["application/json"]) // <1> + fun addPet(@RequestBody pet: Pet) { + // ... + } +---- +<1> Using a `consumes` attribute to narrow the mapping by the content type. + +The `consumes` attribute also supports negation expressions -- for example, `!text/plain` means any +content type other than `text/plain`. + +You can declare a shared `consumes` attribute at the class level. Unlike most other +request-mapping attributes, however, when used at the class level, a method-level `consumes` attribute +overrides rather than extends the class-level declaration. + +TIP: `MediaType` provides constants for commonly used media types, such as +`APPLICATION_JSON_VALUE` and `APPLICATION_XML_VALUE`. + + +[[mvc-ann-requestmapping-produces]] +== Producible Media Types +[.small]#<># + +You can narrow the request mapping based on the `Accept` request header and the list of +content types that a controller method produces, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping(path = "/pets/{petId}", produces = "application/json") // <1> + @ResponseBody + public Pet getPet(@PathVariable String petId) { + // ... + } +---- +<1> Using a `produces` attribute to narrow the mapping by the content type. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/pets/{petId}", produces = ["application/json"]) // <1> + @ResponseBody + fun getPet(@PathVariable petId: String): Pet { + // ... + } +---- +<1> Using a `produces` attribute to narrow the mapping by the content type. + +The media type can specify a character set. Negated expressions are supported -- for example, +`!text/plain` means any content type other than "text/plain". + +You can declare a shared `produces` attribute at the class level. Unlike most other +request-mapping attributes, however, when used at the class level, a method-level `produces` attribute +overrides rather than extends the class-level declaration. + +TIP: `MediaType` provides constants for commonly used media types, such as +`APPLICATION_JSON_VALUE` and `APPLICATION_XML_VALUE`. + + +[[mvc-ann-requestmapping-params-and-headers]] +== Parameters, headers +[.small]#<># + +You can narrow request mappings based on request parameter conditions. You can test for the +presence of a request parameter (`myParam`), for the absence of one (`!myParam`), or for a +specific value (`myParam=myValue`). The following example shows how to test for a specific value: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping(path = "/pets/{petId}", params = "myParam=myValue") // <1> + public void findPet(@PathVariable String petId) { + // ... + } +---- +<1> Testing whether `myParam` equals `myValue`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/pets/{petId}", params = ["myParam=myValue"]) // <1> + fun findPet(@PathVariable petId: String) { + // ... + } +---- +<1> Testing whether `myParam` equals `myValue`. + +You can also use the same with request header conditions, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") // <1> + public void findPet(@PathVariable String petId) { + // ... + } +---- +<1> Testing whether `myHeader` equals `myValue`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @GetMapping("/pets/{petId}", headers = ["myHeader=myValue"]) // <1> + fun findPet(@PathVariable petId: String) { + // ... + } +---- +<1> Testing whether `myHeader` equals `myValue`. + +TIP: You can match `Content-Type` and `Accept` with the headers condition, but it is better to use +<> and <> +instead. + + +[[mvc-ann-requestmapping-head-options]] +== HTTP HEAD, OPTIONS +[.small]#<># + +`@GetMapping` (and `@RequestMapping(method=HttpMethod.GET)`) support HTTP HEAD +transparently for request mapping. Controller methods do not need to change. +A response wrapper, applied in `jakarta.servlet.http.HttpServlet`, ensures a `Content-Length` +header is set to the number of bytes written (without actually writing to the response). + +`@GetMapping` (and `@RequestMapping(method=HttpMethod.GET)`) are implicitly mapped to +and support HTTP HEAD. An HTTP HEAD request is processed as if it were HTTP GET except +that, instead of writing the body, the number of bytes are counted and the `Content-Length` +header is set. + +By default, HTTP OPTIONS is handled by setting the `Allow` response header to the list of HTTP +methods listed in all `@RequestMapping` methods that have matching URL patterns. + +For a `@RequestMapping` without HTTP method declarations, the `Allow` header is set to +`GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS`. Controller methods should always declare the +supported HTTP methods (for example, by using the HTTP method specific variants: +`@GetMapping`, `@PostMapping`, and others). + +You can explicitly map the `@RequestMapping` method to HTTP HEAD and HTTP OPTIONS, but that +is not necessary in the common case. + + +[[mvc-ann-requestmapping-composed]] +== Custom Annotations +[.small]#<># + +Spring MVC supports the use of <> +for request mapping. Those are annotations that are themselves meta-annotated with +`@RequestMapping` and composed to redeclare a subset (or all) of the `@RequestMapping` +attributes with a narrower, more specific purpose. + +`@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, and `@PatchMapping` are +examples of composed annotations. They are provided because, arguably, most +controller methods should be mapped to a specific HTTP method versus using `@RequestMapping`, +which, by default, matches to all HTTP methods. If you need an example of composed +annotations, look at how those are declared. + +Spring MVC also supports custom request-mapping attributes with custom request-matching +logic. This is a more advanced option that requires subclassing +`RequestMappingHandlerMapping` and overriding the `getCustomMethodCondition` method, where +you can check the custom attribute and return your own `RequestCondition`. + + +[[mvc-ann-requestmapping-registration]] +== Explicit Registrations +[.small]#<># + +You can programmatically register handler methods, which you can use for dynamic +registrations or for advanced cases, such as different instances of the same handler +under different URLs. The following example registers a handler method: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class MyConfig { + + @Autowired + public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) // <1> + throws NoSuchMethodException { + + RequestMappingInfo info = RequestMappingInfo + .paths("/user/{id}").methods(RequestMethod.GET).build(); // <2> + + Method method = UserHandler.class.getMethod("getUser", Long.class); // <3> + + mapping.registerMapping(info, handler, method); // <4> + } + } +---- +<1> Inject the target handler and the handler mapping for controllers. +<2> Prepare the request mapping meta data. +<3> Get the handler method. +<4> Add the registration. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class MyConfig { + + @Autowired + fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) { // <1> + val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build() // <2> + val method = UserHandler::class.java.getMethod("getUser", Long::class.java) // <3> + mapping.registerMapping(info, handler, method) // <4> + } + } +---- +<1> Inject the target handler and the handler mapping for controllers. +<2> Prepare the request mapping meta data. +<3> Get the handler method. +<4> Add the registration. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc new file mode 100644 index 000000000000..3af293ea7ffd --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc @@ -0,0 +1,85 @@ +[[mvc-ann-controller]] += Declaration + +[.small]#<># + +You can define controller beans by using a standard Spring bean definition in the +Servlet's `WebApplicationContext`. The `@Controller` stereotype allows for auto-detection, +aligned with Spring general support for detecting `@Component` classes in the classpath +and auto-registering bean definitions for them. It also acts as a stereotype for the +annotated class, indicating its role as a web component. + +To enable auto-detection of such `@Controller` beans, you can add component scanning to +your Java configuration, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @ComponentScan("org.example.web") + public class WebConfig { + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @ComponentScan("org.example.web") + class WebConfig { + + // ... + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + +---- + +`@RestController` is a <> that is +itself meta-annotated with `@Controller` and `@ResponseBody` to indicate a controller whose +every method inherits the type-level `@ResponseBody` annotation and, therefore, writes +directly to the response body versus view resolution and rendering with an HTML template. + + +[[mvc-ann-requestmapping-proxying]] +== AOP Proxies +[.small]#<># + +In some cases, you may need to decorate a controller with an AOP proxy at runtime. +One example is if you choose to have `@Transactional` annotations directly on the +controller. When this is the case, for controllers specifically, we recommend +using class-based proxying. This is automatically the case with such annotations +directly on the controller. + +If the controller implements an interface, and needs AOP proxying, you may need to +explicitly configure class-based proxying. For example, with `@EnableTransactionManagement` +you can change to `@EnableTransactionManagement(proxyTargetClass = true)`, and with +`` you can change to ``. + +NOTE: Keep in mind that as of 6.0, with interface proxying, Spring MVC no longer detects +controllers based solely on a type-level `@RequestMapping` annotation on the interface. +Please, enable class based proxying, or otherwise the interface must also have an +`@Controller` annotation. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc new file mode 100644 index 000000000000..2c6f1eb15ae9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc @@ -0,0 +1,14 @@ +[[mvc-http2]] += HTTP/2 + +[.small]#<># + +Servlet 4 containers are required to support HTTP/2, and Spring Framework 5 is compatible +with Servlet API 4. From a programming model perspective, there is nothing specific that +applications need to do. However, there are considerations related to server configuration. +For more details, see the +https://github.com/spring-projects/spring-framework/wiki/HTTP-2-support[HTTP/2 wiki page]. + +The Servlet API does expose one construct related to HTTP/2. You can use the +`jakarta.servlet.http.PushBuilder` to proactively push resources to clients, and it +is supported as a <> to `@RequestMapping` methods. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc new file mode 100644 index 000000000000..d7a43f998812 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc @@ -0,0 +1,19 @@ +[[mvc-web-security]] += Web Security + +[.small]#<># + +The https://spring.io/projects/spring-security[Spring Security] project provides support +for protecting web applications from malicious exploits. See the Spring Security +reference documentation, including: + +* {docs-spring-security}/servlet/integrations/mvc.html[Spring MVC Security] +* {docs-spring-security}/servlet/test/mockmvc/setup.html[Spring MVC Test Support] +* {docs-spring-security}/features/exploits/csrf.html#csrf-protection[CSRF protection] +* {docs-spring-security}/features/exploits/headers.html[Security Response Headers] + +https://hdiv.org/[HDIV] is another web security framework that integrates with Spring MVC. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc new file mode 100644 index 000000000000..4cff137d2671 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc @@ -0,0 +1,111 @@ +[[mvc-servlet]] += DispatcherServlet + +[.small]#<># + +Spring MVC, as many other web frameworks, is designed around the front controller +pattern where a central `Servlet`, the `DispatcherServlet`, provides a shared algorithm +for request processing, while actual work is performed by configurable delegate components. +This model is flexible and supports diverse workflows. + +The `DispatcherServlet`, as any `Servlet`, needs to be declared and mapped according +to the Servlet specification by using Java configuration or in `web.xml`. +In turn, the `DispatcherServlet` uses Spring configuration to discover +the delegate components it needs for request mapping, view resolution, exception +handling, <>. + +The following example of the Java configuration registers and initializes +the `DispatcherServlet`, which is auto-detected by the Servlet container +(see <>): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MyWebApplicationInitializer implements WebApplicationInitializer { + + @Override + public void onStartup(ServletContext servletContext) { + + // Load Spring web application configuration + AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext(); + context.register(AppConfig.class); + + // Create and register the DispatcherServlet + DispatcherServlet servlet = new DispatcherServlet(context); + ServletRegistration.Dynamic registration = servletContext.addServlet("app", servlet); + registration.setLoadOnStartup(1); + registration.addMapping("/app/*"); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyWebApplicationInitializer : WebApplicationInitializer { + + override fun onStartup(servletContext: ServletContext) { + + // Load Spring web application configuration + val context = AnnotationConfigWebApplicationContext() + context.register(AppConfig::class.java) + + // Create and register the DispatcherServlet + val servlet = DispatcherServlet(context) + val registration = servletContext.addServlet("app", servlet) + registration.setLoadOnStartup(1) + registration.addMapping("/app/*") + } + } +---- + +NOTE: In addition to using the ServletContext API directly, you can also extend +`AbstractAnnotationConfigDispatcherServletInitializer` and override specific methods +(see the example under <>). + +NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an +alternative to `AnnotationConfigWebApplicationContext`. See the +{api-spring-framework}/web/context/support/GenericWebApplicationContext.html[`GenericWebApplicationContext`] +javadoc for details. + +The following example of `web.xml` configuration registers and initializes the `DispatcherServlet`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + org.springframework.web.context.ContextLoaderListener + + + + contextConfigLocation + /WEB-INF/app-context.xml + + + + app + org.springframework.web.servlet.DispatcherServlet + + contextConfigLocation + + + 1 + + + + app + /app/* + + + +---- + +NOTE: Spring Boot follows a different initialization sequence. Rather than hooking into +the lifecycle of the Servlet container, Spring Boot uses Spring configuration to +bootstrap itself and the embedded Servlet container. `Filter` and `Servlet` declarations +are detected in Spring configuration and registered with the Servlet container. +For more details, see the +https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-embedded-container[Spring Boot documentation]. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc new file mode 100644 index 000000000000..86f7aaf0d75a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc @@ -0,0 +1,20 @@ +[[mvc-servlet-config]] += Web MVC Config + +[.small]#<># + +Applications can declare the infrastructure beans listed in <> +that are required to process requests. The `DispatcherServlet` checks the +`WebApplicationContext` for each special bean. If there are no matching bean types, +it falls back on the default types listed in +{spring-framework-main-code}/spring-webmvc/src/main/resources/org/springframework/web/servlet/DispatcherServlet.properties[`DispatcherServlet.properties`]. + +In most cases, the <> is the best starting point. It declares the required +beans in either Java or XML and provides a higher-level configuration callback API to +customize it. + +NOTE: Spring Boot relies on the MVC Java configuration to configure Spring MVC and +provides many extra convenient options. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/container-config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/container-config.adoc new file mode 100644 index 000000000000..d5624854e6f0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/container-config.adoc @@ -0,0 +1,184 @@ +[[mvc-container-config]] += Servlet Config + +In a Servlet environment, you have the option of configuring the Servlet container +programmatically as an alternative or in combination with a `web.xml` file. +The following example registers a `DispatcherServlet`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + import org.springframework.web.WebApplicationInitializer; + + public class MyWebApplicationInitializer implements WebApplicationInitializer { + + @Override + public void onStartup(ServletContext container) { + XmlWebApplicationContext appContext = new XmlWebApplicationContext(); + appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml"); + + ServletRegistration.Dynamic registration = container.addServlet("dispatcher", new DispatcherServlet(appContext)); + registration.setLoadOnStartup(1); + registration.addMapping("/"); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + import org.springframework.web.WebApplicationInitializer + + class MyWebApplicationInitializer : WebApplicationInitializer { + + override fun onStartup(container: ServletContext) { + val appContext = XmlWebApplicationContext() + appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml") + + val registration = container.addServlet("dispatcher", DispatcherServlet(appContext)) + registration.setLoadOnStartup(1) + registration.addMapping("/") + } + } +---- + + +`WebApplicationInitializer` is an interface provided by Spring MVC that ensures your +implementation is detected and automatically used to initialize any Servlet 3 container. +An abstract base class implementation of `WebApplicationInitializer` named +`AbstractDispatcherServletInitializer` makes it even easier to register the +`DispatcherServlet` by overriding methods to specify the servlet mapping and the +location of the `DispatcherServlet` configuration. + +This is recommended for applications that use Java-based Spring configuration, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { + + @Override + protected Class[] getRootConfigClasses() { + return null; + } + + @Override + protected Class[] getServletConfigClasses() { + return new Class[] { MyWebConfig.class }; + } + + @Override + protected String[] getServletMappings() { + return new String[] { "/" }; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { + + override fun getRootConfigClasses(): Array>? { + return null + } + + override fun getServletConfigClasses(): Array>? { + return arrayOf(MyWebConfig::class.java) + } + + override fun getServletMappings(): Array { + return arrayOf("/") + } + } +---- + +If you use XML-based Spring configuration, you should extend directly from +`AbstractDispatcherServletInitializer`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MyWebAppInitializer extends AbstractDispatcherServletInitializer { + + @Override + protected WebApplicationContext createRootApplicationContext() { + return null; + } + + @Override + protected WebApplicationContext createServletApplicationContext() { + XmlWebApplicationContext cxt = new XmlWebApplicationContext(); + cxt.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml"); + return cxt; + } + + @Override + protected String[] getServletMappings() { + return new String[] { "/" }; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyWebAppInitializer : AbstractDispatcherServletInitializer() { + + override fun createRootApplicationContext(): WebApplicationContext? { + return null + } + + override fun createServletApplicationContext(): WebApplicationContext { + return XmlWebApplicationContext().apply { + setConfigLocation("/WEB-INF/spring/dispatcher-config.xml") + } + } + + override fun getServletMappings(): Array { + return arrayOf("/") + } + } +---- + +`AbstractDispatcherServletInitializer` also provides a convenient way to add `Filter` +instances and have them be automatically mapped to the `DispatcherServlet`, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MyWebAppInitializer extends AbstractDispatcherServletInitializer { + + // ... + + @Override + protected Filter[] getServletFilters() { + return new Filter[] { + new HiddenHttpMethodFilter(), new CharacterEncodingFilter() }; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyWebAppInitializer : AbstractDispatcherServletInitializer() { + + // ... + + override fun getServletFilters(): Array { + return arrayOf(HiddenHttpMethodFilter(), CharacterEncodingFilter()) + } + } +---- + +Each filter is added with a default name based on its concrete type and automatically +mapped to the `DispatcherServlet`. + +The `isAsyncSupported` protected method of `AbstractDispatcherServletInitializer` +provides a single place to enable async support on the `DispatcherServlet` and all +filters mapped to it. By default, this flag is set to `true`. + +Finally, if you need to further customize the `DispatcherServlet` itself, you can +override the `createDispatcherServlet` method. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc new file mode 100644 index 000000000000..149ab98daf5f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc @@ -0,0 +1,107 @@ +[[mvc-servlet-context-hierarchy]] += Context Hierarchy + +`DispatcherServlet` expects a `WebApplicationContext` (an extension of a plain +`ApplicationContext`) for its own configuration. `WebApplicationContext` has a link to the +`ServletContext` and the `Servlet` with which it is associated. It is also bound to the `ServletContext` +such that applications can use static methods on `RequestContextUtils` to look up the +`WebApplicationContext` if they need access to it. + +For many applications, having a single `WebApplicationContext` is simple and suffices. +It is also possible to have a context hierarchy where one root `WebApplicationContext` +is shared across multiple `DispatcherServlet` (or other `Servlet`) instances, each with +its own child `WebApplicationContext` configuration. +See <> +for more on the context hierarchy feature. + +The root `WebApplicationContext` typically contains infrastructure beans, such as data repositories and +business services that need to be shared across multiple `Servlet` instances. Those beans +are effectively inherited and can be overridden (that is, re-declared) in the Servlet-specific +child `WebApplicationContext`, which typically contains beans local to the given `Servlet`. +The following image shows this relationship: + +image::mvc-context-hierarchy.png[] + +The following example configures a `WebApplicationContext` hierarchy: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { + + @Override + protected Class[] getRootConfigClasses() { + return new Class[] { RootConfig.class }; + } + + @Override + protected Class[] getServletConfigClasses() { + return new Class[] { App1Config.class }; + } + + @Override + protected String[] getServletMappings() { + return new String[] { "/app1/*" }; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { + + override fun getRootConfigClasses(): Array> { + return arrayOf(RootConfig::class.java) + } + + override fun getServletConfigClasses(): Array> { + return arrayOf(App1Config::class.java) + } + + override fun getServletMappings(): Array { + return arrayOf("/app1/*") + } + } +---- + +TIP: If an application context hierarchy is not required, applications can return all +configuration through `getRootConfigClasses()` and `null` from `getServletConfigClasses()`. + +The following example shows the `web.xml` equivalent: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + org.springframework.web.context.ContextLoaderListener + + + + contextConfigLocation + /WEB-INF/root-context.xml + + + + app1 + org.springframework.web.servlet.DispatcherServlet + + contextConfigLocation + /WEB-INF/app1-context.xml + + 1 + + + + app1 + /app1/* + + + +---- + +TIP: If an application context hierarchy is not required, applications may configure a +"`root`" context only and leave the `contextConfigLocation` Servlet parameter empty. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc new file mode 100644 index 000000000000..2c527e974022 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc @@ -0,0 +1,112 @@ +[[mvc-exceptionhandlers]] += Exceptions + +[.small]#<># + +If an exception occurs during request mapping or is thrown from a request handler (such as +a `@Controller`), the `DispatcherServlet` delegates to a chain of `HandlerExceptionResolver` +beans to resolve the exception and provide alternative handling, which is typically an +error response. + +The following table lists the available `HandlerExceptionResolver` implementations: + +[cols="1,2", options="header"] +.HandlerExceptionResolver implementations +|=== +| `HandlerExceptionResolver` | Description + +| `SimpleMappingExceptionResolver` +| A mapping between exception class names and error view names. Useful for rendering + error pages in a browser application. + +| {api-spring-framework}/web/servlet/mvc/support/DefaultHandlerExceptionResolver.html[`DefaultHandlerExceptionResolver`] +| Resolves exceptions raised by Spring MVC and maps them to HTTP status codes. + See also alternative `ResponseEntityExceptionHandler` and <>. + +| `ResponseStatusExceptionResolver` +| Resolves exceptions with the `@ResponseStatus` annotation and maps them to HTTP status + codes based on the value in the annotation. + +| `ExceptionHandlerExceptionResolver` +| Resolves exceptions by invoking an `@ExceptionHandler` method in a `@Controller` or a + `@ControllerAdvice` class. See <>. +|=== + + +[[mvc-exceptionhandlers-handling]] +== Chain of Resolvers + +You can form an exception resolver chain by declaring multiple `HandlerExceptionResolver` +beans in your Spring configuration and setting their `order` properties as needed. +The higher the order property, the later the exception resolver is positioned. + +The contract of `HandlerExceptionResolver` specifies that it can return: + +* a `ModelAndView` that points to an error view. +* An empty `ModelAndView` if the exception was handled within the resolver. +* `null` if the exception remains unresolved, for subsequent resolvers to try, and, if the +exception remains at the end, it is allowed to bubble up to the Servlet container. + +The <> automatically declares built-in resolvers for default Spring MVC +exceptions, for `@ResponseStatus` annotated exceptions, and for support of +`@ExceptionHandler` methods. You can customize that list or replace it. + + +[[mvc-ann-customer-servlet-container-error-page]] +== Container Error Page + +If an exception remains unresolved by any `HandlerExceptionResolver` and is, therefore, +left to propagate or if the response status is set to an error status (that is, 4xx, 5xx), +Servlet containers can render a default error page in HTML. To customize the default +error page of the container, you can declare an error page mapping in `web.xml`. +The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + /error + +---- + +Given the preceding example, when an exception bubbles up or the response has an error status, the +Servlet container makes an ERROR dispatch within the container to the configured URL +(for example, `/error`). This is then processed by the `DispatcherServlet`, possibly mapping it +to a `@Controller`, which could be implemented to return an error view name with a model +or to render a JSON response, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RestController + public class ErrorController { + + @RequestMapping(path = "/error") + public Map handle(HttpServletRequest request) { + Map map = new HashMap<>(); + map.put("status", request.getAttribute("jakarta.servlet.error.status_code")); + map.put("reason", request.getAttribute("jakarta.servlet.error.message")); + return map; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RestController + class ErrorController { + + @RequestMapping(path = ["/error"]) + fun handle(request: HttpServletRequest): Map { + val map = HashMap() + map["status"] = request.getAttribute("jakarta.servlet.error.status_code") + map["reason"] = request.getAttribute("jakarta.servlet.error.message") + return map + } + } +---- + +TIP: The Servlet API does not provide a way to create error page mappings in Java. You can, +however, use both a `WebApplicationInitializer` and a minimal `web.xml`. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc new file mode 100644 index 000000000000..dcf5bc86cdab --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc @@ -0,0 +1,34 @@ +[[mvc-handlermapping-interceptor]] += Interception + +All `HandlerMapping` implementations support handler interceptors that are useful when +you want to apply specific functionality to certain requests -- for example, checking for +a principal. Interceptors must implement `HandlerInterceptor` from the +`org.springframework.web.servlet` package with three methods that should provide enough +flexibility to do all kinds of pre-processing and post-processing: + +* `preHandle(..)`: Before the actual handler is run +* `postHandle(..)`: After the handler is run +* `afterCompletion(..)`: After the complete request has finished + +The `preHandle(..)` method returns a boolean value. You can use this method to break or +continue the processing of the execution chain. When this method returns `true`, the +handler execution chain continues. When it returns false, the `DispatcherServlet` +assumes the interceptor itself has taken care of requests (and, for example, rendered an +appropriate view) and does not continue executing the other interceptors and the actual +handler in the execution chain. + +See <> in the section on MVC configuration for examples of how to +configure interceptors. You can also register them directly by using setters on individual +`HandlerMapping` implementations. + +`postHandle` method is less useful with `@ResponseBody` and `ResponseEntity` methods for +which the response is written and committed within the `HandlerAdapter` and before +`postHandle`. That means it is too late to make any changes to the response, such as adding +an extra header. For such scenarios, you can implement `ResponseBodyAdvice` and either +declare it as an <> bean or configure it directly on +`RequestMappingHandlerAdapter`. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc new file mode 100644 index 000000000000..49b35ffda75c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc @@ -0,0 +1,52 @@ +[[mvc-handlermapping-path]] += Path Matching + +The Servlet API exposes the full request path as `requestURI` and further sub-divides it +into `contextPath`, `servletPath`, and `pathInfo` whose values vary depending on how a +Servlet is mapped. From these inputs, Spring MVC needs to determine the lookup path to +use for mapping handlers, which should exclude the `contextPath` and any `servletMapping` +prefix, if applicable. + +The `servletPath` and `pathInfo` are decoded and that makes them impossible to compare +directly to the full `requestURI` in order to derive the lookupPath and that makes it +necessary to decode the `requestURI`. However this introduces its own issues because the +path may contain encoded reserved characters such as `"/"` or `";"` that can in turn +alter the structure of the path after they are decoded which can also lead to security +issues. In addition, Servlet containers may normalize the `servletPath` to varying +degrees which makes it further impossible to perform `startsWith` comparisons against +the `requestURI`. + +This is why it is best to avoid reliance on the `servletPath` which comes with the +prefix-based `servletPath` mapping type. If the `DispatcherServlet` is mapped as the +default Servlet with `"/"` or otherwise without a prefix with `"/*"` and the Servlet +container is 4.0+ then Spring MVC is able to detect the Servlet mapping type and avoid +use of the `servletPath` and `pathInfo` altogether. On a 3.1 Servlet container, +assuming the same Servlet mapping types, the equivalent can be achieved by providing +a `UrlPathHelper` with `alwaysUseFullPath=true` via <> in +the MVC config. + +Fortunately the default Servlet mapping `"/"` is a good choice. However, there is still +an issue in that the `requestURI` needs to be decoded to make it possible to compare to +controller mappings. This is again undesirable because of the potential to decode +reserved characters that alter the path structure. If such characters are not expected, +then you can reject them (like the Spring Security HTTP firewall), or you can configure +`UrlPathHelper` with `urlDecode=false` but controller mappings will need to match to the +encoded path which may not always work well. Furthermore, sometimes the +`DispatcherServlet` needs to share the URL space with another Servlet and may need to +be mapped by prefix. + +The above issues are addressed when using `PathPatternParser` and parsed patterns, as +an alternative to String path matching with `AntPathMatcher`. The `PathPatternParser` has +been available for use in Spring MVC from version 5.3, and is enabled by default from +version 6.0. Unlike `AntPathMatcher` which needs either the lookup path decoded or the +controller mapping encoded, a parsed `PathPattern` matches to a parsed representation +of the path called `RequestPath`, one path segment at a time. This allows decoding and +sanitizing path segment values individually without the risk of altering the structure +of the path. Parsed `PathPattern` also supports the use of `servletPath` prefix mapping +as long as a Servlet path mapping is used and the prefix is kept simple, i.e. it has no +encoded characters. For pattern syntax details and comparison, see +<>. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc new file mode 100644 index 000000000000..168385e9dc6a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc @@ -0,0 +1,145 @@ +[[mvc-localeresolver]] += Locale + +Most parts of Spring's architecture support internationalization, as the Spring web +MVC framework does. `DispatcherServlet` lets you automatically resolve messages +by using the client's locale. This is done with `LocaleResolver` objects. + +When a request comes in, the `DispatcherServlet` looks for a locale resolver and, if it +finds one, it tries to use it to set the locale. By using the `RequestContext.getLocale()` +method, you can always retrieve the locale that was resolved by the locale resolver. + +In addition to automatic locale resolution, you can also attach an interceptor to the +handler mapping (see <> for more information on handler +mapping interceptors) to change the locale under specific circumstances (for example, +based on a parameter in the request). + +Locale resolvers and interceptors are defined in the +`org.springframework.web.servlet.i18n` package and are configured in your application +context in the normal way. The following selection of locale resolvers is included in +Spring. + +* <> +* <> +* <> +* <> +* <> + + +[[mvc-timezone]] +== Time Zone + +In addition to obtaining the client's locale, it is often useful to know its time zone. +The `LocaleContextResolver` interface offers an extension to `LocaleResolver` that lets +resolvers provide a richer `LocaleContext`, which may include time zone information. + +When available, the user's `TimeZone` can be obtained by using the +`RequestContext.getTimeZone()` method. Time zone information is automatically used +by any Date/Time `Converter` and `Formatter` objects that are registered with Spring's +`ConversionService`. + + +[[mvc-localeresolver-acceptheader]] +== Header Resolver + +This locale resolver inspects the `accept-language` header in the request that was sent +by the client (for example, a web browser). Usually, this header field contains the locale of +the client's operating system. Note that this resolver does not support time zone +information. + + +[[mvc-localeresolver-cookie]] +== Cookie Resolver + +This locale resolver inspects a `Cookie` that might exist on the client to see if a +`Locale` or `TimeZone` is specified. If so, it uses the specified details. By using the +properties of this locale resolver, you can specify the name of the cookie as well as the +maximum age. The following example defines a `CookieLocaleResolver`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + +---- + +The following table describes the properties `CookieLocaleResolver`: + +[[mvc-cookie-locale-resolver-props-tbl]] +.CookieLocaleResolver properties +[cols="1,1,4"] +|=== +| Property | Default | Description + +| `cookieName` +| class name + LOCALE +| The name of the cookie + +| `cookieMaxAge` +| Servlet container default +| The maximum time a cookie persists on the client. If `-1` is specified, the + cookie will not be persisted. It is available only until the client shuts down + the browser. + +| `cookiePath` +| / +| Limits the visibility of the cookie to a certain part of your site. When `cookiePath` is + specified, the cookie is visible only to that path and the paths below it. +|=== + + +[[mvc-localeresolver-session]] +== Session Resolver + +The `SessionLocaleResolver` lets you retrieve `Locale` and `TimeZone` from the +session that might be associated with the user's request. In contrast to +`CookieLocaleResolver`, this strategy stores locally chosen locale settings in the +Servlet container's `HttpSession`. As a consequence, those settings are temporary +for each session and are, therefore, lost when each session ends. + +Note that there is no direct relationship with external session management mechanisms, +such as the Spring Session project. This `SessionLocaleResolver` evaluates and +modifies the corresponding `HttpSession` attributes against the current `HttpServletRequest`. + + +[[mvc-localeresolver-interceptor]] +== Locale Interceptor + +You can enable changing of locales by adding the `LocaleChangeInterceptor` to one of the +`HandlerMapping` definitions. It detects a parameter in the request and changes the locale +accordingly, calling the `setLocale` method on the `LocaleResolver` in the dispatcher's +application context. The next example shows that calls to all `{asterisk}.view` resources +that contain a parameter named `siteLanguage` now changes the locale. So, for example, +a request for the URL, `https://www.sf.net/home.view?siteLanguage=nl`, changes the site +language to Dutch. The following example shows how to intercept the locale: + +[source,xml,indent=0,subs="verbatim"] +---- + + + + + + + + + + + + + + /**/*.view=someController + + +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc new file mode 100644 index 000000000000..d09b90c4dc74 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc @@ -0,0 +1,81 @@ +[[mvc-logging]] += Logging + +[.small]#<># + +DEBUG-level logging in Spring MVC is designed to be compact, minimal, and +human-friendly. It focuses on high-value bits of information that are useful over and +over again versus others that are useful only when debugging a specific issue. + +TRACE-level logging generally follows the same principles as DEBUG (and, for example, also +should not be a fire hose) but can be used for debugging any issue. In addition, some log +messages may show a different level of detail at TRACE versus DEBUG. + +Good logging comes from the experience of using the logs. If you spot anything that does +not meet the stated goals, please let us know. + + +[[mvc-logging-sensitive-data]] +== Sensitive Data +[.small]#<># + +DEBUG and TRACE logging may log sensitive information. This is why request parameters and +headers are masked by default and their logging in full must be enabled explicitly +through the `enableLoggingRequestDetails` property on `DispatcherServlet`. + +The following example shows how to do so by using Java configuration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- +public class MyInitializer + extends AbstractAnnotationConfigDispatcherServletInitializer { + + @Override + protected Class[] getRootConfigClasses() { + return ... ; + } + + @Override + protected Class[] getServletConfigClasses() { + return ... ; + } + + @Override + protected String[] getServletMappings() { + return ... ; + } + + @Override + protected void customizeRegistration(ServletRegistration.Dynamic registration) { + registration.setInitParameter("enableLoggingRequestDetails", "true"); + } + +} +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MyInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { + + override fun getRootConfigClasses(): Array>? { + return ... + } + + override fun getServletConfigClasses(): Array>? { + return ... + } + + override fun getServletMappings(): Array { + return ... + } + + override fun customizeRegistration(registration: ServletRegistration.Dynamic) { + registration.setInitParameter("enableLoggingRequestDetails", "true") + } + } +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc new file mode 100644 index 000000000000..d9eec04f118f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc @@ -0,0 +1,77 @@ +[[mvc-multipart]] += Multipart Resolver + +[.small]#<># + +`MultipartResolver` from the `org.springframework.web.multipart` package is a strategy +for parsing multipart requests including file uploads. There is a container-based +`StandardServletMultipartResolver` implementation for Servlet multipart request parsing. +Note that the outdated `CommonsMultipartResolver` based on Apache Commons FileUpload is +not available anymore, as of Spring Framework 6.0 with its new Servlet 5.0+ baseline. + +To enable multipart handling, you need to declare a `MultipartResolver` bean in your +`DispatcherServlet` Spring configuration with a name of `multipartResolver`. +The `DispatcherServlet` detects it and applies it to the incoming request. When a POST +with a content type of `multipart/form-data` is received, the resolver parses the +content wraps the current `HttpServletRequest` as a `MultipartHttpServletRequest` to +provide access to resolved files in addition to exposing parts as request parameters. + + +[[mvc-multipart-resolver-standard]] +== Servlet Multipart Parsing + +Servlet multipart parsing needs to be enabled through Servlet container configuration. +To do so: + +* In Java, set a `MultipartConfigElement` on the Servlet registration. +* In `web.xml`, add a `""` section to the servlet declaration. + +The following example shows how to set a `MultipartConfigElement` on the Servlet registration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class AppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { + + // ... + + @Override + protected void customizeRegistration(ServletRegistration.Dynamic registration) { + + // Optionally also set maxFileSize, maxRequestSize, fileSizeThreshold + registration.setMultipartConfig(new MultipartConfigElement("/tmp")); + } + + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class AppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { + + // ... + + override fun customizeRegistration(registration: ServletRegistration.Dynamic) { + + // Optionally also set maxFileSize, maxRequestSize, fileSizeThreshold + registration.setMultipartConfig(MultipartConfigElement("/tmp")) + } + + } +---- + +Once the Servlet multipart configuration is in place, you can add a bean of type +`StandardServletMultipartResolver` with a name of `multipartResolver`. + +[NOTE] +==== +This resolver variant uses your Servlet container's multipart parser as-is, +potentially exposing the application to container implementation differences. +By default, it will try to parse any `multipart/` content type with any HTTP +method but this may not be supported across all Servlet containers. See the +{api-spring-framework}/web/multipart/support/StandardServletMultipartResolver.html[`StandardServletMultipartResolver`] +javadoc for details and configuration options. +==== + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc new file mode 100644 index 000000000000..e1577db64538 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc @@ -0,0 +1,74 @@ +[[mvc-servlet-sequence]] += Processing + +[.small]#<># + +The `DispatcherServlet` processes requests as follows: + +* The `WebApplicationContext` is searched for and bound in the request as an attribute + that the controller and other elements in the process can use. It is bound by default + under the `DispatcherServlet.WEB_APPLICATION_CONTEXT_ATTRIBUTE` key. +* The locale resolver is bound to the request to let elements in the process + resolve the locale to use when processing the request (rendering the view, preparing + data, and so on). If you do not need locale resolving, you do not need the locale resolver. +* The theme resolver is bound to the request to let elements such as views determine + which theme to use. If you do not use themes, you can ignore it. +* If you specify a multipart file resolver, the request is inspected for multiparts. If + multiparts are found, the request is wrapped in a `MultipartHttpServletRequest` for + further processing by other elements in the process. See <> for further + information about multipart handling. +* An appropriate handler is searched for. If a handler is found, the execution chain + associated with the handler (preprocessors, postprocessors, and controllers) is + run to prepare a model for rendering. Alternatively, for annotated + controllers, the response can be rendered (within the `HandlerAdapter`) instead of + returning a view. +* If a model is returned, the view is rendered. If no model is returned (maybe due to + a preprocessor or postprocessor intercepting the request, perhaps for security + reasons), no view is rendered, because the request could already have been fulfilled. + +The `HandlerExceptionResolver` beans declared in the `WebApplicationContext` are used to +resolve exceptions thrown during request processing. Those exception resolvers allow +customizing the logic to address exceptions. See <> for more details. + +For HTTP caching support, handlers can use the `checkNotModified` methods of `WebRequest`, +along with further options for annotated controllers as described in +<>. + +You can customize individual `DispatcherServlet` instances by adding Servlet +initialization parameters (`init-param` elements) to the Servlet declaration in the +`web.xml` file. The following table lists the supported parameters: + +[[mvc-disp-servlet-init-params-tbl]] +.DispatcherServlet initialization parameters +|=== +| Parameter| Explanation + +| `contextClass` +| Class that implements `ConfigurableWebApplicationContext`, to be instantiated and + locally configured by this Servlet. By default, `XmlWebApplicationContext` is used. + +| `contextConfigLocation` +| String that is passed to the context instance (specified by `contextClass`) to + indicate where contexts can be found. The string consists potentially of multiple + strings (using a comma as a delimiter) to support multiple contexts. In the case of + multiple context locations with beans that are defined twice, the latest location + takes precedence. + +| `namespace` +| Namespace of the `WebApplicationContext`. Defaults to `[servlet-name]-servlet`. + +| `throwExceptionIfNoHandlerFound` +| Whether to throw a `NoHandlerFoundException` when no handler was found for a request. + The exception can then be caught with a `HandlerExceptionResolver` (for example, by using an + `@ExceptionHandler` controller method) and handled as any others. + + By default, this is set to `false`, in which case the `DispatcherServlet` sets the + response status to 404 (NOT_FOUND) without raising an exception. + + Note that, if <> is + also configured, unresolved requests are always forwarded to the default servlet + and a 404 is never raised. +|=== + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc new file mode 100644 index 000000000000..c9a650490f59 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc @@ -0,0 +1,61 @@ +[[mvc-servlet-special-bean-types]] += Special Bean Types + +[.small]#<># + +The `DispatcherServlet` delegates to special beans to process requests and render the +appropriate responses. By "`special beans`" we mean Spring-managed `Object` instances that +implement framework contracts. Those usually come with built-in contracts, but +you can customize their properties and extend or replace them. + +The following table lists the special beans detected by the `DispatcherServlet`: + +[[mvc-webappctx-special-beans-tbl]] +[cols="1,2", options="header"] +|=== +| Bean type| Explanation + +| `HandlerMapping` +| Map a request to a handler along with a list of + <> for pre- and post-processing. + The mapping is based on some criteria, the details of which vary by `HandlerMapping` + implementation. + + The two main `HandlerMapping` implementations are `RequestMappingHandlerMapping` + (which supports `@RequestMapping` annotated methods) and `SimpleUrlHandlerMapping` + (which maintains explicit registrations of URI path patterns to handlers). + +| `HandlerAdapter` +| Help the `DispatcherServlet` to invoke a handler mapped to a request, regardless of + how the handler is actually invoked. For example, invoking an annotated controller + requires resolving annotations. The main purpose of a `HandlerAdapter` is + to shield the `DispatcherServlet` from such details. + +| <> +| Strategy to resolve exceptions, possibly mapping them to handlers, to HTML error + views, or other targets. See <>. + +| <> +| Resolve logical `String`-based view names returned from a handler to an actual `View` + with which to render to the response. See <> and <>. + +| <>, <> +| Resolve the `Locale` a client is using and possibly their time zone, in order to be able + to offer internationalized views. See <>. + +| <> +| Resolve themes your web application can use -- for example, to offer personalized layouts. + See <>. + +| <> +| Abstraction for parsing a multi-part request (for example, browser form file upload) with + the help of some multipart parsing library. See <>. + +| <> +| Store and retrieve the "`input`" and the "`output`" `FlashMap` that can be used to pass + attributes from one request to another, usually across a redirect. + See <>. +|=== + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc new file mode 100644 index 000000000000..83f9f81a8eba --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc @@ -0,0 +1,92 @@ +[[mvc-themeresolver]] += Themes + +You can apply Spring Web MVC framework themes to set the overall look-and-feel of your +application, thereby enhancing user experience. A theme is a collection of static +resources, typically style sheets and images, that affect the visual style of the +application. + +WARNING: as of 6.0 support for themes has been deprecated theme in favor of using CSS, +and without any special support on the server side. + + +[[mvc-themeresolver-defining]] +== Defining a theme + +To use themes in your web application, you must set up an implementation of the +`org.springframework.ui.context.ThemeSource` interface. The `WebApplicationContext` +interface extends `ThemeSource` but delegates its responsibilities to a dedicated +implementation. By default, the delegate is an +`org.springframework.ui.context.support.ResourceBundleThemeSource` implementation that +loads properties files from the root of the classpath. To use a custom `ThemeSource` +implementation or to configure the base name prefix of the `ResourceBundleThemeSource`, +you can register a bean in the application context with the reserved name, `themeSource`. +The web application context automatically detects a bean with that name and uses it. + +When you use the `ResourceBundleThemeSource`, a theme is defined in a simple properties +file. The properties file lists the resources that make up the theme, as the following example shows: + +[literal,subs="verbatim,quotes"] +---- +styleSheet=/themes/cool/style.css +background=/themes/cool/img/coolBg.jpg +---- + +The keys of the properties are the names that refer to the themed elements from view +code. For a JSP, you typically do this using the `spring:theme` custom tag, which is +very similar to the `spring:message` tag. The following JSP fragment uses the theme +defined in the previous example to customize the look and feel: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + <%@ taglib prefix="spring" uri="http://www.springframework.org/tags"%> + + + + + + ... + + +---- + +By default, the `ResourceBundleThemeSource` uses an empty base name prefix. As a result, +the properties files are loaded from the root of the classpath. Thus, you would put the +`cool.properties` theme definition in a directory at the root of the classpath (for +example, in `/WEB-INF/classes`). The `ResourceBundleThemeSource` uses the standard Java +resource bundle loading mechanism, allowing for full internationalization of themes. For +example, we could have a `/WEB-INF/classes/cool_nl.properties` that references a special +background image with Dutch text on it. + + +[[mvc-themeresolver-resolving]] +== Resolving Themes + +After you define themes, as described in the <>, +you decide which theme to use. The `DispatcherServlet` looks for a bean named `themeResolver` +to find out which `ThemeResolver` implementation to use. A theme resolver works in much the same +way as a `LocaleResolver`. It detects the theme to use for a particular request and can also +alter the request's theme. The following table describes the theme resolvers provided by Spring: + +[[mvc-theme-resolver-impls-tbl]] +.ThemeResolver implementations +[cols="1,4"] +|=== +| Class | Description + +| `FixedThemeResolver` +| Selects a fixed theme, set by using the `defaultThemeName` property. + +| `SessionThemeResolver` +| The theme is maintained in the user's HTTP session. It needs to be set only once for + each session but is not persisted between sessions. + +| `CookieThemeResolver` +| The selected theme is stored in a cookie on the client. +|=== + +Spring also provides a `ThemeChangeInterceptor` that lets theme changes on every +request with a simple request parameter. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc new file mode 100644 index 000000000000..f4bf8270ceb0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc @@ -0,0 +1,129 @@ +[[mvc-viewresolver]] += View Resolution + +[.small]#<># + +Spring MVC defines the `ViewResolver` and `View` interfaces that let you render +models in a browser without tying you to a specific view technology. `ViewResolver` +provides a mapping between view names and actual views. `View` addresses the preparation +of data before handing over to a specific view technology. + +The following table provides more details on the `ViewResolver` hierarchy: + +[[mvc-view-resolvers-tbl]] +.ViewResolver implementations +|=== +| ViewResolver| Description + +| `AbstractCachingViewResolver` +| Subclasses of `AbstractCachingViewResolver` cache view instances that they resolve. + Caching improves performance of certain view technologies. You can turn off the + cache by setting the `cache` property to `false`. Furthermore, if you must refresh + a certain view at runtime (for example, when a FreeMarker template is modified), + you can use the `removeFromCache(String viewName, Locale loc)` method. + +| `UrlBasedViewResolver` +| Simple implementation of the `ViewResolver` interface that effects the direct + resolution of logical view names to URLs without an explicit mapping definition. + This is appropriate if your logical names match the names of your view resources + in a straightforward manner, without the need for arbitrary mappings. + +| `InternalResourceViewResolver` +| Convenient subclass of `UrlBasedViewResolver` that supports `InternalResourceView` (in + effect, Servlets and JSPs) and subclasses such as `JstlView`. You can specify the view + class for all views generated by this resolver by using `setViewClass(..)`. + See the {api-spring-framework}/web/reactive/result/view/UrlBasedViewResolver.html[`UrlBasedViewResolver`] + javadoc for details. + +| `FreeMarkerViewResolver` +| Convenient subclass of `UrlBasedViewResolver` that supports `FreeMarkerView` and + custom subclasses of them. + +| `ContentNegotiatingViewResolver` +| Implementation of the `ViewResolver` interface that resolves a view based on the + request file name or `Accept` header. See <>. + +| `BeanNameViewResolver` +| Implementation of the `ViewResolver` interface that interprets a view name as a + bean name in the current application context. This is a very flexible variant which + allows for mixing and matching different view types based on distinct view names. + Each such `View` can be defined as a bean e.g. in XML or in configuration classes. +|=== + + +[[mvc-viewresolver-handling]] +== Handling +[.small]#<># + +You can chain view resolvers by declaring more than one resolver bean and, if necessary, by +setting the `order` property to specify ordering. Remember, the higher the order property, +the later the view resolver is positioned in the chain. + +The contract of a `ViewResolver` specifies that it can return null to indicate that the +view could not be found. However, in the case of JSPs and `InternalResourceViewResolver`, +the only way to figure out if a JSP exists is to perform a dispatch through +`RequestDispatcher`. Therefore, you must always configure an `InternalResourceViewResolver` +to be last in the overall order of view resolvers. + +Configuring view resolution is as simple as adding `ViewResolver` beans to your Spring +configuration. The <> provides a dedicated configuration API for +<> and for adding logic-less +<> which are useful for HTML template +rendering without controller logic. + + +[[mvc-redirecting-redirect-prefix]] +== Redirecting +[.small]#<># + +The special `redirect:` prefix in a view name lets you perform a redirect. The +`UrlBasedViewResolver` (and its subclasses) recognize this as an instruction that a +redirect is needed. The rest of the view name is the redirect URL. + +The net effect is the same as if the controller had returned a `RedirectView`, but now +the controller itself can operate in terms of logical view names. A logical view +name (such as `redirect:/myapp/some/resource`) redirects relative to the current +Servlet context, while a name such as `redirect:https://myhost.com/some/arbitrary/path` +redirects to an absolute URL. + +Note that, if a controller method is annotated with the `@ResponseStatus`, the annotation +value takes precedence over the response status set by `RedirectView`. + + +[[mvc-redirecting-forward-prefix]] +== Forwarding + +You can also use a special `forward:` prefix for view names that are +ultimately resolved by `UrlBasedViewResolver` and subclasses. This creates an +`InternalResourceView`, which does a `RequestDispatcher.forward()`. +Therefore, this prefix is not useful with `InternalResourceViewResolver` and +`InternalResourceView` (for JSPs), but it can be helpful if you use another view +technology but still want to force a forward of a resource to be handled by the +Servlet/JSP engine. Note that you may also chain multiple view resolvers, instead. + + +[[mvc-multiple-representations]] +== Content Negotiation +[.small]#<># + +{api-spring-framework}/web/servlet/view/ContentNegotiatingViewResolver.html[`ContentNegotiatingViewResolver`] +does not resolve views itself but rather delegates +to other view resolvers and selects the view that resembles the representation requested +by the client. The representation can be determined from the `Accept` header or from a +query parameter (for example, `"/path?format=pdf"`). + +The `ContentNegotiatingViewResolver` selects an appropriate `View` to handle the request +by comparing the request media types with the media type (also known as +`Content-Type`) supported by the `View` associated with each of its `ViewResolvers`. The +first `View` in the list that has a compatible `Content-Type` returns the representation +to the client. If a compatible view cannot be supplied by the `ViewResolver` chain, +the list of views specified through the `DefaultViews` property is consulted. This +latter option is appropriate for singleton `Views` that can render an appropriate +representation of the current resource regardless of the logical view name. The `Accept` +header can include wildcards (for example `text/{asterisk}`), in which case a `View` whose +`Content-Type` is `text/xml` is a compatible match. + +See <> under <> for configuration details. + + + diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc new file mode 100644 index 000000000000..e2cadde805bf --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc @@ -0,0 +1,280 @@ +[[mvc-uri-building]] += URI Links + +[.small]#<># + +This section describes various options available in the Spring Framework to work with URI's. + +include:../:web-uris.adoc[leveloffset=+2] + + + +[[mvc-servleturicomponentsbuilder]] +== Relative Servlet Requests + +You can use `ServletUriComponentsBuilder` to create URIs relative to the current request, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpServletRequest request = ... + + // Re-uses scheme, host, port, path, and query string... + + URI uri = ServletUriComponentsBuilder.fromRequest(request) + .replaceQueryParam("accountId", "{id}") + .build("123"); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val request: HttpServletRequest = ... + + // Re-uses scheme, host, port, path, and query string... + + val uri = ServletUriComponentsBuilder.fromRequest(request) + .replaceQueryParam("accountId", "{id}") + .build("123") +---- + +You can create URIs relative to the context path, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpServletRequest request = ... + + // Re-uses scheme, host, port, and context path... + + URI uri = ServletUriComponentsBuilder.fromContextPath(request) + .path("/accounts") + .build() + .toUri(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val request: HttpServletRequest = ... + + // Re-uses scheme, host, port, and context path... + + val uri = ServletUriComponentsBuilder.fromContextPath(request) + .path("/accounts") + .build() + .toUri() +---- + +You can create URIs relative to a Servlet (for example, `/main/{asterisk}`), +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + HttpServletRequest request = ... + + // Re-uses scheme, host, port, context path, and Servlet mapping prefix... + + URI uri = ServletUriComponentsBuilder.fromServletMapping(request) + .path("/accounts") + .build() + .toUri(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val request: HttpServletRequest = ... + + // Re-uses scheme, host, port, context path, and Servlet mapping prefix... + + val uri = ServletUriComponentsBuilder.fromServletMapping(request) + .path("/accounts") + .build() + .toUri() +---- + +NOTE: As of 5.1, `ServletUriComponentsBuilder` ignores information from the `Forwarded` and +`X-Forwarded-*` headers, which specify the client-originated address. Consider using the +<> to extract and use or to discard +such headers. + + + +[[mvc-links-to-controllers]] +== Links to Controllers + +Spring MVC provides a mechanism to prepare links to controller methods. For example, +the following MVC controller allows for link creation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Controller + @RequestMapping("/hotels/{hotel}") + public class BookingController { + + @GetMapping("/bookings/{booking}") + public ModelAndView getBooking(@PathVariable Long booking) { + // ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Controller + @RequestMapping("/hotels/{hotel}") + class BookingController { + + @GetMapping("/bookings/{booking}") + fun getBooking(@PathVariable booking: Long): ModelAndView { + // ... + } + } +---- + +You can prepare a link by referring to the method by name, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + UriComponents uriComponents = MvcUriComponentsBuilder + .fromMethodName(BookingController.class, "getBooking", 21).buildAndExpand(42); + + URI uri = uriComponents.encode().toUri(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val uriComponents = MvcUriComponentsBuilder + .fromMethodName(BookingController::class.java, "getBooking", 21).buildAndExpand(42) + + val uri = uriComponents.encode().toUri() +---- + +In the preceding example, we provide actual method argument values (in this case, the long value: `21`) +to be used as a path variable and inserted into the URL. Furthermore, we provide the +value, `42`, to fill in any remaining URI variables, such as the `hotel` variable inherited +from the type-level request mapping. If the method had more arguments, we could supply null for +arguments not needed for the URL. In general, only `@PathVariable` and `@RequestParam` arguments +are relevant for constructing the URL. + +There are additional ways to use `MvcUriComponentsBuilder`. For example, you can use a technique +akin to mock testing through proxies to avoid referring to the controller method by name, as the following example shows +(the example assumes static import of `MvcUriComponentsBuilder.on`): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + UriComponents uriComponents = MvcUriComponentsBuilder + .fromMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42); + + URI uri = uriComponents.encode().toUri(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val uriComponents = MvcUriComponentsBuilder + .fromMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42) + + val uri = uriComponents.encode().toUri() +---- + +NOTE: Controller method signatures are limited in their design when they are supposed to be usable for +link creation with `fromMethodCall`. Aside from needing a proper parameter signature, +there is a technical limitation on the return type (namely, generating a runtime proxy +for link builder invocations), so the return type must not be `final`. In particular, +the common `String` return type for view names does not work here. You should use `ModelAndView` +or even plain `Object` (with a `String` return value) instead. + +The earlier examples use static methods in `MvcUriComponentsBuilder`. Internally, they rely +on `ServletUriComponentsBuilder` to prepare a base URL from the scheme, host, port, +context path, and servlet path of the current request. This works well in most cases. +However, sometimes, it can be insufficient. For example, you may be outside the context of +a request (such as a batch process that prepares links) or perhaps you need to insert a path +prefix (such as a locale prefix that was removed from the request path and needs to be +re-inserted into links). + +For such cases, you can use the static `fromXxx` overloaded methods that accept a +`UriComponentsBuilder` to use a base URL. Alternatively, you can create an instance of `MvcUriComponentsBuilder` +with a base URL and then use the instance-based `withXxx` methods. For example, the +following listing uses `withMethodCall`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + UriComponentsBuilder base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en"); + MvcUriComponentsBuilder builder = MvcUriComponentsBuilder.relativeTo(base); + builder.withMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42); + + URI uri = uriComponents.encode().toUri(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en") + val builder = MvcUriComponentsBuilder.relativeTo(base) + builder.withMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42) + + val uri = uriComponents.encode().toUri() +---- + +NOTE: As of 5.1, `MvcUriComponentsBuilder` ignores information from the `Forwarded` and +`X-Forwarded-*` headers, which specify the client-originated address. Consider using the +<> to extract and use or to discard +such headers. + + + +[[mvc-links-to-controllers-from-views]] +== Links in Views + +In views such as Thymeleaf, FreeMarker, or JSP, you can build links to annotated controllers +by referring to the implicitly or explicitly assigned name for each request mapping. + +Consider the following example: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @RequestMapping("/people/{id}/addresses") + public class PersonAddressController { + + @RequestMapping("/{country}") + public HttpEntity getAddress(@PathVariable String country) { ... } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @RequestMapping("/people/{id}/addresses") + class PersonAddressController { + + @RequestMapping("/{country}") + fun getAddress(@PathVariable country: String): HttpEntity { ... } + } +---- + +Given the preceding controller, you can prepare a link from a JSP, as follows: + +[source,jsp,indent=0,subs="verbatim,quotes"] +---- +<%@ taglib uri="http://www.springframework.org/tags" prefix="s" %> +... +Get Address +---- + +The preceding example relies on the `mvcUrl` function declared in the Spring tag library +(that is, META-INF/spring.tld), but it is easy to define your own function or prepare a +similar one for other templating technologies. + +Here is how this works. On startup, every `@RequestMapping` is assigned a default name +through `HandlerMethodMappingNamingStrategy`, whose default implementation uses the +capital letters of the class and the method name (for example, the `getThing` method in +`ThingController` becomes "TC#getThing"). If there is a name clash, you can use +`@RequestMapping(name="..")` to assign an explicit name or implement your own +`HandlerMethodMappingNamingStrategy`. + + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket.adoc b/framework-docs/modules/ROOT/pages/web/websocket.adoc index d584e03fb61f..dec37b4eaeef 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket.adoc @@ -11,2505 +11,3 @@ include::websocket-intro.adoc[leveloffset=+1] -[[websocket-server]] -== WebSocket API -[.small]#<># - -The Spring Framework provides a WebSocket API that you can use to write client- and -server-side applications that handle WebSocket messages. - - - -[[websocket-server-handler]] -=== `WebSocketHandler` -[.small]#<># - -Creating a WebSocket server is as simple as implementing `WebSocketHandler` or, more -likely, extending either `TextWebSocketHandler` or `BinaryWebSocketHandler`. The following -example uses `TextWebSocketHandler`: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - import org.springframework.web.socket.WebSocketHandler; - import org.springframework.web.socket.WebSocketSession; - import org.springframework.web.socket.TextMessage; - - public class MyHandler extends TextWebSocketHandler { - - @Override - public void handleTextMessage(WebSocketSession session, TextMessage message) { - // ... - } - - } ----- - -There is dedicated WebSocket Java configuration and XML namespace support for mapping the preceding -WebSocket handler to a specific URL, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - import org.springframework.web.socket.config.annotation.EnableWebSocket; - import org.springframework.web.socket.config.annotation.WebSocketConfigurer; - import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry; - - @Configuration - @EnableWebSocket - public class WebSocketConfig implements WebSocketConfigurer { - - @Override - public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { - registry.addHandler(myHandler(), "/myHandler"); - } - - @Bean - public WebSocketHandler myHandler() { - return new MyHandler(); - } - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - - ----- - -The preceding example is for use in Spring MVC applications and should be included -in the configuration of a <>. However, Spring's -WebSocket support does not depend on Spring MVC. It is relatively simple to -integrate a `WebSocketHandler` into other HTTP-serving environments with the help of -{api-spring-framework}/web/socket/server/support/WebSocketHttpRequestHandler.html[`WebSocketHttpRequestHandler`]. - -When using the `WebSocketHandler` API directly vs indirectly, e.g. through the -<> messaging, the application must synchronize the sending of messages -since the underlying standard WebSocket session (JSR-356) does not allow concurrent -sending. One option is to wrap the `WebSocketSession` with -{api-spring-framework}/web/socket/handler/ConcurrentWebSocketSessionDecorator.html[`ConcurrentWebSocketSessionDecorator`]. - - - -[[websocket-server-handshake]] -=== WebSocket Handshake -[.small]#<># - -The easiest way to customize the initial HTTP WebSocket handshake request is through -a `HandshakeInterceptor`, which exposes methods for "`before`" and "`after`" the handshake. -You can use such an interceptor to preclude the handshake or to make any attributes -available to the `WebSocketSession`. The following example uses a built-in interceptor -to pass HTTP session attributes to the WebSocket session: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocket - public class WebSocketConfig implements WebSocketConfigurer { - - @Override - public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { - registry.addHandler(new MyHandler(), "/myHandler") - .addInterceptors(new HttpSessionHandshakeInterceptor()); - } - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - - - - - ----- - -A more advanced option is to extend the `DefaultHandshakeHandler` that performs -the steps of the WebSocket handshake, including validating the client origin, -negotiating a sub-protocol, and other details. An application may also need to use this -option if it needs to configure a custom `RequestUpgradeStrategy` in order to -adapt to a WebSocket server engine and version that is not yet supported -(see <> for more on this subject). -Both the Java configuration and XML namespace make it possible to configure a custom -`HandshakeHandler`. - - -TIP: Spring provides a `WebSocketHandlerDecorator` base class that you can use to decorate -a `WebSocketHandler` with additional behavior. Logging and exception handling -implementations are provided and added by default when using the WebSocket Java configuration -or XML namespace. The `ExceptionWebSocketHandlerDecorator` catches all uncaught -exceptions that arise from any `WebSocketHandler` method and closes the WebSocket -session with status `1011`, which indicates a server error. - - - -[[websocket-server-deployment]] -=== Deployment - -The Spring WebSocket API is easy to integrate into a Spring MVC application where -the `DispatcherServlet` serves both HTTP WebSocket handshake and other -HTTP requests. It is also easy to integrate into other HTTP processing scenarios -by invoking `WebSocketHttpRequestHandler`. This is convenient and easy to -understand. However, special considerations apply with regards to JSR-356 runtimes. - -The Jakarta WebSocket API (JSR-356) provides two deployment mechanisms. The first -involves a Servlet container classpath scan (a Servlet 3 feature) at startup. -The other is a registration API to use at Servlet container initialization. -Neither of these mechanism makes it possible to use a single "`front controller`" -for all HTTP processing -- including WebSocket handshake and all other HTTP -requests -- such as Spring MVC's `DispatcherServlet`. - -This is a significant limitation of JSR-356 that Spring's WebSocket support addresses with -server-specific `RequestUpgradeStrategy` implementations even when running in a JSR-356 runtime. -Such strategies currently exist for Tomcat, Jetty, GlassFish, WebLogic, WebSphere, and Undertow -(and WildFly). As of Jakarta WebSocket 2.1, a standard request upgrade strategy is available -which Spring chooses on Jakarta EE 10 based web containers such as Tomcat 10.1 and Jetty 12. - -A secondary consideration is that Servlet containers with JSR-356 support are expected -to perform a `ServletContainerInitializer` (SCI) scan that can slow down application -startup -- in some cases, dramatically. If a significant impact is observed after an -upgrade to a Servlet container version with JSR-356 support, it should -be possible to selectively enable or disable web fragments (and SCI scanning) -through the use of the `` element in `web.xml`, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - ----- - -You can then selectively enable web fragments by name, such as Spring's own -`SpringServletContainerInitializer` that provides support for the Servlet 3 -Java initialization API. The following example shows how to do so: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - spring_web - - - ----- - - - -[[websocket-server-runtime-configuration]] -=== Server Configuration -[.small]#<># - -Each underlying WebSocket engine exposes configuration properties that control -runtime characteristics, such as the size of message buffer sizes, idle timeout, -and others. - -For Tomcat, WildFly, and GlassFish, you can add a `ServletServerContainerFactoryBean` to your -WebSocket Java config, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocket - public class WebSocketConfig implements WebSocketConfigurer { - - @Bean - public ServletServerContainerFactoryBean createWebSocketContainer() { - ServletServerContainerFactoryBean container = new ServletServerContainerFactoryBean(); - container.setMaxTextMessageBufferSize(8192); - container.setMaxBinaryMessageBufferSize(8192); - return container; - } - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - ----- - -NOTE: For client-side WebSocket configuration, you should use `WebSocketContainerFactoryBean` -(XML) or `ContainerProvider.getWebSocketContainer()` (Java configuration). - -For Jetty, you need to supply a pre-configured Jetty `WebSocketServerFactory` and plug -that into Spring's `DefaultHandshakeHandler` through your WebSocket Java config. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocket - public class WebSocketConfig implements WebSocketConfigurer { - - @Override - public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { - registry.addHandler(echoWebSocketHandler(), - "/echo").setHandshakeHandler(handshakeHandler()); - } - - @Bean - public DefaultHandshakeHandler handshakeHandler() { - - WebSocketPolicy policy = new WebSocketPolicy(WebSocketBehavior.SERVER); - policy.setInputBufferSize(8192); - policy.setIdleTimeout(600000); - - return new DefaultHandshakeHandler( - new JettyRequestUpgradeStrategy(new WebSocketServerFactory(policy))); - } - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - - - - - - - - - - - - - - - - - - - ----- - - - -[[websocket-server-allowed-origins]] -=== Allowed Origins -[.small]#<># - -As of Spring Framework 4.1.5, the default behavior for WebSocket and SockJS is to accept -only same-origin requests. It is also possible to allow all or a specified list of origins. -This check is mostly designed for browser clients. Nothing prevents other types -of clients from modifying the `Origin` header value (see -https://tools.ietf.org/html/rfc6454[RFC 6454: The Web Origin Concept] for more details). - -The three possible behaviors are: - - * Allow only same-origin requests (default): In this mode, when SockJS is enabled, the - Iframe HTTP response header `X-Frame-Options` is set to `SAMEORIGIN`, and JSONP - transport is disabled, since it does not allow checking the origin of a request. - As a consequence, IE6 and IE7 are not supported when this mode is enabled. - * Allow a specified list of origins: Each allowed origin must start with `http://` - or `https://`. In this mode, when SockJS is enabled, IFrame transport is disabled. - As a consequence, IE6 through IE9 are not supported when this - mode is enabled. - * Allow all origins: To enable this mode, you should provide `{asterisk}` as the allowed origin - value. In this mode, all transports are available. - -You can configure WebSocket and SockJS allowed origins, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - import org.springframework.web.socket.config.annotation.EnableWebSocket; - import org.springframework.web.socket.config.annotation.WebSocketConfigurer; - import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry; - - @Configuration - @EnableWebSocket - public class WebSocketConfig implements WebSocketConfigurer { - - @Override - public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { - registry.addHandler(myHandler(), "/myHandler").setAllowedOrigins("https://mydomain.com"); - } - - @Bean - public WebSocketHandler myHandler() { - return new MyHandler(); - } - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - - ----- - - - - -[[websocket-fallback]] -== SockJS Fallback - -Over the public Internet, restrictive proxies outside your control may preclude WebSocket -interactions, either because they are not configured to pass on the `Upgrade` header or -because they close long-lived connections that appear to be idle. - -The solution to this problem is WebSocket emulation -- that is, attempting to use WebSocket -first and then falling back on HTTP-based techniques that emulate a WebSocket -interaction and expose the same application-level API. - -On the Servlet stack, the Spring Framework provides both server (and also client) support -for the SockJS protocol. - - - -[[websocket-fallback-sockjs-overview]] -=== Overview - -The goal of SockJS is to let applications use a WebSocket API but fall back to -non-WebSocket alternatives when necessary at runtime, without the need to -change application code. - -SockJS consists of: - -* The https://github.com/sockjs/sockjs-protocol[SockJS protocol] -defined in the form of executable -https://sockjs.github.io/sockjs-protocol/sockjs-protocol-0.3.3.html[narrated tests]. -* The https://github.com/sockjs/sockjs-client/[SockJS JavaScript client] -- a client library for use in browsers. -* SockJS server implementations, including one in the Spring Framework `spring-websocket` module. -* A SockJS Java client in the `spring-websocket` module (since version 4.1). - -SockJS is designed for use in browsers. It uses a variety of techniques -to support a wide range of browser versions. -For the full list of SockJS transport types and browsers, see the -https://github.com/sockjs/sockjs-client/[SockJS client] page. Transports -fall in three general categories: WebSocket, HTTP Streaming, and HTTP Long Polling. -For an overview of these categories, see -https://spring.io/blog/2012/05/08/spring-mvc-3-2-preview-techniques-for-real-time-updates/[this blog post]. - -The SockJS client begins by sending `GET /info` to -obtain basic information from the server. After that, it must decide what transport -to use. If possible, WebSocket is used. If not, in most browsers, -there is at least one HTTP streaming option. If not, then HTTP (long) -polling is used. - -All transport requests have the following URL structure: - ----- -https://host:port/myApp/myEndpoint/{server-id}/{session-id}/{transport} ----- - -where: - -* pass:q[`{server-id}`] is useful for routing requests in a cluster but is not used otherwise. -* pass:q[`{session-id}`] correlates HTTP requests belonging to a SockJS session. -* pass:q[`{transport}`] indicates the transport type (for example, `websocket`, `xhr-streaming`, and others). - -The WebSocket transport needs only a single HTTP request to do the WebSocket handshake. -All messages thereafter are exchanged on that socket. - -HTTP transports require more requests. Ajax/XHR streaming, for example, relies on -one long-running request for server-to-client messages and additional HTTP POST -requests for client-to-server messages. Long polling is similar, except that it -ends the current request after each server-to-client send. - -SockJS adds minimal message framing. For example, the server sends the letter `o` -("`open`" frame) initially, messages are sent as `a["message1","message2"]` -(JSON-encoded array), the letter `h` ("`heartbeat`" frame) if no messages flow -for 25 seconds (by default), and the letter `c` ("`close`" frame) to close the session. - -To learn more, run an example in a browser and watch the HTTP requests. -The SockJS client allows fixing the list of transports, so it is possible to -see each transport one at a time. The SockJS client also provides a debug flag, -which enables helpful messages in the browser console. On the server side, you can enable -`TRACE` logging for `org.springframework.web.socket`. -For even more detail, see the SockJS protocol -https://sockjs.github.io/sockjs-protocol/sockjs-protocol-0.3.3.html[narrated test]. - - - -[[websocket-fallback-sockjs-enable]] -=== Enabling SockJS - -You can enable SockJS through Java configuration, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocket - public class WebSocketConfig implements WebSocketConfigurer { - - @Override - public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { - registry.addHandler(myHandler(), "/myHandler").withSockJS(); - } - - @Bean - public WebSocketHandler myHandler() { - return new MyHandler(); - } - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - - - ----- - -The preceding example is for use in Spring MVC applications and should be included in the -configuration of a <>. However, Spring's WebSocket -and SockJS support does not depend on Spring MVC. It is relatively simple to -integrate into other HTTP serving environments with the help of -{api-spring-framework}/web/socket/sockjs/support/SockJsHttpRequestHandler.html[`SockJsHttpRequestHandler`]. - -On the browser side, applications can use the -https://github.com/sockjs/sockjs-client/[`sockjs-client`] (version 1.0.x). It -emulates the W3C WebSocket API and communicates with the server to select the best -transport option, depending on the browser in which it runs. See the -https://github.com/sockjs/sockjs-client/[sockjs-client] page and the list of -transport types supported by browser. The client also provides several -configuration options -- for example, to specify which transports to include. - - - -[[websocket-fallback-xhr-vs-iframe]] -=== IE 8 and 9 - -Internet Explorer 8 and 9 remain in use. They are -a key reason for having SockJS. This section covers important -considerations about running in those browsers. - -The SockJS client supports Ajax/XHR streaming in IE 8 and 9 by using Microsoft's -https://web.archive.org/web/20160219230343/https://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainrequest-restrictions-limitations-and-workarounds.aspx[`XDomainRequest`]. -That works across domains but does not support sending cookies. -Cookies are often essential for Java applications. -However, since the SockJS client can be used with many server -types (not just Java ones), it needs to know whether cookies matter. -If so, the SockJS client prefers Ajax/XHR for streaming. Otherwise, it -relies on an iframe-based technique. - -The first `/info` request from the SockJS client is a request for -information that can influence the client's choice of transports. -One of those details is whether the server application relies on cookies -(for example, for authentication purposes or clustering with sticky sessions). -Spring's SockJS support includes a property called `sessionCookieNeeded`. -It is enabled by default, since most Java applications rely on the `JSESSIONID` -cookie. If your application does not need it, you can turn off this option, -and SockJS client should then choose `xdr-streaming` in IE 8 and 9. - -If you do use an iframe-based transport, keep in mind -that browsers can be instructed to block the use of IFrames on a given page by -setting the HTTP response header `X-Frame-Options` to `DENY`, -`SAMEORIGIN`, or `ALLOW-FROM `. This is used to prevent -https://www.owasp.org/index.php/Clickjacking[clickjacking]. - -[NOTE] -==== -Spring Security 3.2+ provides support for setting `X-Frame-Options` on every -response. By default, the Spring Security Java configuration sets it to `DENY`. -In 3.2, the Spring Security XML namespace does not set that header by default -but can be configured to do so. In the future, it may set it by default. - -See {docs-spring-security}/features/exploits/headers.html#headers-default[Default Security Headers] -of the Spring Security documentation for details on how to configure the -setting of the `X-Frame-Options` header. You can also see -https://github.com/spring-projects/spring-security/issues/2718[gh-2718] -for additional background. -==== - -If your application adds the `X-Frame-Options` response header (as it should!) -and relies on an iframe-based transport, you need to set the header value to -`SAMEORIGIN` or `ALLOW-FROM `. The Spring SockJS -support also needs to know the location of the SockJS client, because it is loaded -from the iframe. By default, the iframe is set to download the SockJS client -from a CDN location. It is a good idea to configure this option to use -a URL from the same origin as the application. - -The following example shows how to do so in Java configuration: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - @Override - public void registerStompEndpoints(StompEndpointRegistry registry) { - registry.addEndpoint("/portfolio").withSockJS() - .setClientLibraryUrl("http://localhost:8080/myapp/js/sockjs-client.js"); - } - - // ... - - } ----- - -The XML namespace provides a similar option through the `` element. - -NOTE: During initial development, do enable the SockJS client `devel` mode that prevents -the browser from caching SockJS requests (like the iframe) that would otherwise -be cached. For details on how to enable it see the -https://github.com/sockjs/sockjs-client/[SockJS client] page. - - - -[[websocket-fallback-sockjs-heartbeat]] -=== Heartbeats - -The SockJS protocol requires servers to send heartbeat messages to preclude proxies -from concluding that a connection is hung. The Spring SockJS configuration has a property -called `heartbeatTime` that you can use to customize the frequency. By default, a -heartbeat is sent after 25 seconds, assuming no other messages were sent on that -connection. This 25-second value is in line with the following -https://tools.ietf.org/html/rfc6202[IETF recommendation] for public Internet applications. - -NOTE: When using STOMP over WebSocket and SockJS, if the STOMP client and server negotiate -heartbeats to be exchanged, the SockJS heartbeats are disabled. - -The Spring SockJS support also lets you configure the `TaskScheduler` to -schedule heartbeats tasks. The task scheduler is backed by a thread pool, -with default settings based on the number of available processors. Your -should consider customizing the settings according to your specific needs. - - - -[[websocket-fallback-sockjs-servlet3-async]] -=== Client Disconnects - -HTTP streaming and HTTP long polling SockJS transports require a connection to remain -open longer than usual. For an overview of these techniques, see -https://spring.io/blog/2012/05/08/spring-mvc-3-2-preview-techniques-for-real-time-updates/[this blog post]. - -In Servlet containers, this is done through Servlet 3 asynchronous support that -allows exiting the Servlet container thread, processing a request, and continuing -to write to the response from another thread. - -A specific issue is that the Servlet API does not provide notifications for a client -that has gone away. See https://github.com/eclipse-ee4j/servlet-api/issues/44[eclipse-ee4j/servlet-api#44]. -However, Servlet containers raise an exception on subsequent attempts to write -to the response. Since Spring's SockJS Service supports server-sent heartbeats (every -25 seconds by default), that means a client disconnect is usually detected within that -time period (or earlier, if messages are sent more frequently). - -NOTE: As a result, network I/O failures can occur because a client has disconnected, which -can fill the log with unnecessary stack traces. Spring makes a best effort to identify -such network failures that represent client disconnects (specific to each server) and log -a minimal message by using the dedicated log category, `DISCONNECTED_CLIENT_LOG_CATEGORY` -(defined in `AbstractSockJsSession`). If you need to see the stack traces, you can set that -log category to TRACE. - - - -[[websocket-fallback-cors]] -=== SockJS and CORS - -If you allow cross-origin requests (see <>), the SockJS protocol -uses CORS for cross-domain support in the XHR streaming and polling transports. Therefore, -CORS headers are added automatically, unless the presence of CORS headers in the response -is detected. So, if an application is already configured to provide CORS support (for example, -through a Servlet Filter), Spring's `SockJsService` skips this part. - -It is also possible to disable the addition of these CORS headers by setting the -`suppressCors` property in Spring's SockJsService. - -SockJS expects the following headers and values: - -* `Access-Control-Allow-Origin`: Initialized from the value of the `Origin` request header. -* `Access-Control-Allow-Credentials`: Always set to `true`. -* `Access-Control-Request-Headers`: Initialized from values from the equivalent request header. -* `Access-Control-Allow-Methods`: The HTTP methods a transport supports (see `TransportType` enum). -* `Access-Control-Max-Age`: Set to 31536000 (1 year). - -For the exact implementation, see `addCorsHeaders` in `AbstractSockJsService` and -the `TransportType` enum in the source code. - -Alternatively, if the CORS configuration allows it, consider excluding URLs with the -SockJS endpoint prefix, thus letting Spring's `SockJsService` handle it. - - - -[[websocket-fallback-sockjs-client]] -=== `SockJsClient` - -Spring provides a SockJS Java client to connect to remote SockJS endpoints without -using a browser. This can be especially useful when there is a need for bidirectional -communication between two servers over a public network (that is, where network proxies can -preclude the use of the WebSocket protocol). A SockJS Java client is also very useful -for testing purposes (for example, to simulate a large number of concurrent users). - -The SockJS Java client supports the `websocket`, `xhr-streaming`, and `xhr-polling` -transports. The remaining ones only make sense for use in a browser. - -You can configure the `WebSocketTransport` with: - -* `StandardWebSocketClient` in a JSR-356 runtime. -* `JettyWebSocketClient` by using the Jetty 9+ native WebSocket API. -* Any implementation of Spring's `WebSocketClient`. - -An `XhrTransport`, by definition, supports both `xhr-streaming` and `xhr-polling`, since, -from a client perspective, there is no difference other than in the URL used to connect -to the server. At present there are two implementations: - -* `RestTemplateXhrTransport` uses Spring's `RestTemplate` for HTTP requests. -* `JettyXhrTransport` uses Jetty's `HttpClient` for HTTP requests. - -The following example shows how to create a SockJS client and connect to a SockJS endpoint: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - List transports = new ArrayList<>(2); - transports.add(new WebSocketTransport(new StandardWebSocketClient())); - transports.add(new RestTemplateXhrTransport()); - - SockJsClient sockJsClient = new SockJsClient(transports); - sockJsClient.doHandshake(new MyWebSocketHandler(), "ws://example.com:8080/sockjs"); ----- - -NOTE: SockJS uses JSON formatted arrays for messages. By default, Jackson 2 is used and needs -to be on the classpath. Alternatively, you can configure a custom implementation of -`SockJsMessageCodec` and configure it on the `SockJsClient`. - -To use `SockJsClient` to simulate a large number of concurrent users, you -need to configure the underlying HTTP client (for XHR transports) to allow a sufficient -number of connections and threads. The following example shows how to do so with Jetty: - -[source,java,indent=0,subs="verbatim,quotes"] ----- -HttpClient jettyHttpClient = new HttpClient(); -jettyHttpClient.setMaxConnectionsPerDestination(1000); -jettyHttpClient.setExecutor(new QueuedThreadPool(1000)); ----- - -The following example shows the server-side SockJS-related properties (see javadoc for details) -that you should also consider customizing: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - public class WebSocketConfig extends WebSocketMessageBrokerConfigurationSupport { - - @Override - public void registerStompEndpoints(StompEndpointRegistry registry) { - registry.addEndpoint("/sockjs").withSockJS() - .setStreamBytesLimit(512 * 1024) <1> - .setHttpMessageCacheSize(1000) <2> - .setDisconnectDelay(30 * 1000); <3> - } - - // ... - } ----- -<1> Set the `streamBytesLimit` property to 512KB (the default is 128KB -- `128 * 1024`). -<2> Set the `httpMessageCacheSize` property to 1,000 (the default is `100`). -<3> Set the `disconnectDelay` property to 30 property seconds (the default is five seconds --- `5 * 1000`). - - - - -[[websocket-stomp]] -== STOMP - -The WebSocket protocol defines two types of messages (text and binary), but their -content is undefined. The protocol defines a mechanism for client and server to negotiate a -sub-protocol (that is, a higher-level messaging protocol) to use on top of WebSocket to -define what kind of messages each can send, what the format is, the content of each -message, and so on. The use of a sub-protocol is optional but, either way, the client and -the server need to agree on some protocol that defines message content. - - - -[[websocket-stomp-overview]] -=== Overview - -https://stomp.github.io/stomp-specification-1.2.html#Abstract[STOMP] (Simple -Text Oriented Messaging Protocol) was originally created for scripting languages -(such as Ruby, Python, and Perl) to connect to enterprise message brokers. It is -designed to address a minimal subset of commonly used messaging patterns. STOMP can be -used over any reliable two-way streaming network protocol, such as TCP and WebSocket. -Although STOMP is a text-oriented protocol, message payloads can be -either text or binary. - -STOMP is a frame-based protocol whose frames are modeled on HTTP. The following listing shows the structure -of a STOMP frame: - ----- -COMMAND -header1:value1 -header2:value2 - -Body^@ ----- - -Clients can use the `SEND` or `SUBSCRIBE` commands to send or subscribe for -messages, along with a `destination` header that describes what the -message is about and who should receive it. This enables a simple -publish-subscribe mechanism that you can use to send messages through the broker -to other connected clients or to send messages to the server to request that -some work be performed. - -When you use Spring's STOMP support, the Spring WebSocket application acts -as the STOMP broker to clients. Messages are routed to `@Controller` message-handling -methods or to a simple in-memory broker that keeps track of subscriptions and -broadcasts messages to subscribed users. You can also configure Spring to work -with a dedicated STOMP broker (such as RabbitMQ, ActiveMQ, and others) for the actual -broadcasting of messages. In that case, Spring maintains -TCP connections to the broker, relays messages to it, and passes messages -from it down to connected WebSocket clients. Thus, Spring web applications can -rely on unified HTTP-based security, common validation, and a familiar programming -model for message handling. - -The following example shows a client subscribing to receive stock quotes, which -the server may emit periodically (for example, via a scheduled task that sends messages -through a `SimpMessagingTemplate` to the broker): - ----- -SUBSCRIBE -id:sub-1 -destination:/topic/price.stock.* - -^@ ----- - -The following example shows a client that sends a trade request, which the server -can handle through an `@MessageMapping` method: - ----- -SEND -destination:/queue/trade -content-type:application/json -content-length:44 - -{"action":"BUY","ticker":"MMM","shares",44}^@ ----- - -After the execution, the server can -broadcast a trade confirmation message and details down to the client. - -The meaning of a destination is intentionally left opaque in the STOMP spec. It can -be any string, and it is entirely up to STOMP servers to define the semantics and -the syntax of the destinations that they support. It is very common, however, for -destinations to be path-like strings where `/topic/..` implies publish-subscribe -(one-to-many) and `/queue/` implies point-to-point (one-to-one) message -exchanges. - -STOMP servers can use the `MESSAGE` command to broadcast messages to all subscribers. -The following example shows a server sending a stock quote to a subscribed client: - ----- -MESSAGE -message-id:nxahklf6-1 -subscription:sub-1 -destination:/topic/price.stock.MMM - -{"ticker":"MMM","price":129.45}^@ ----- - -A server cannot send unsolicited messages. All messages -from a server must be in response to a specific client subscription, and the -`subscription` header of the server message must match the `id` header of the -client subscription. - -The preceding overview is intended to provide the most basic understanding of the -STOMP protocol. We recommended reviewing the protocol -https://stomp.github.io/stomp-specification-1.2.html[specification] in full. - - - -[[websocket-stomp-benefits]] -=== Benefits - -Using STOMP as a sub-protocol lets the Spring Framework and Spring Security -provide a richer programming model versus using raw WebSockets. The same point can be -made about HTTP versus raw TCP and how it lets Spring MVC and other web frameworks -provide rich functionality. The following is a list of benefits: - -* No need to invent a custom messaging protocol and message format. -* STOMP clients, including a <> -in the Spring Framework, are available. -* You can (optionally) use message brokers (such as RabbitMQ, ActiveMQ, and others) to -manage subscriptions and broadcast messages. -* Application logic can be organized in any number of `@Controller` instances and messages can be -routed to them based on the STOMP destination header versus handling raw WebSocket messages -with a single `WebSocketHandler` for a given connection. -* You can use Spring Security to secure messages based on STOMP destinations and message types. - - - -[[websocket-stomp-enable]] -=== Enable STOMP - -STOMP over WebSocket support is available in the `spring-messaging` and -`spring-websocket` modules. Once you have those dependencies, you can expose a STOMP -endpoints, over WebSocket with <>, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker; - import org.springframework.web.socket.config.annotation.StompEndpointRegistry; - - @Configuration - @EnableWebSocketMessageBroker - public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - @Override - public void registerStompEndpoints(StompEndpointRegistry registry) { - registry.addEndpoint("/portfolio").withSockJS(); // <1> - } - - @Override - public void configureMessageBroker(MessageBrokerRegistry config) { - config.setApplicationDestinationPrefixes("/app"); // <2> - config.enableSimpleBroker("/topic", "/queue"); // <3> - } - } ----- - -<1> `/portfolio` is the HTTP URL for the endpoint to which a WebSocket (or SockJS) -client needs to connect for the WebSocket handshake. -<2> STOMP messages whose destination header begins with `/app` are routed to -`@MessageMapping` methods in `@Controller` classes. -<3> Use the built-in message broker for subscriptions and broadcasting and -route messages whose destination header begins with `/topic `or `/queue` to the broker. - - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - - - ----- - -NOTE: For the built-in simple broker, the `/topic` and `/queue` prefixes do not have any special -meaning. They are merely a convention to differentiate between pub-sub versus point-to-point -messaging (that is, many subscribers versus one consumer). When you use an external broker, -check the STOMP page of the broker to understand what kind of STOMP destinations and -prefixes it supports. - -To connect from a browser, for SockJS, you can use the -https://github.com/sockjs/sockjs-client[`sockjs-client`]. For STOMP, many applications have -used the https://github.com/jmesnil/stomp-websocket[jmesnil/stomp-websocket] library -(also known as stomp.js), which is feature-complete and has been used in production for -years but is no longer maintained. At present the -https://github.com/JSteunou/webstomp-client[JSteunou/webstomp-client] is the most -actively maintained and evolving successor of that library. The following example code -is based on it: - -[source,javascript,indent=0,subs="verbatim,quotes"] ----- - var socket = new SockJS("/spring-websocket-portfolio/portfolio"); - var stompClient = webstomp.over(socket); - - stompClient.connect({}, function(frame) { - } ----- - -Alternatively, if you connect through WebSocket (without SockJS), you can use the following code: - -[source,javascript,indent=0,subs="verbatim,quotes"] ----- - var socket = new WebSocket("/spring-websocket-portfolio/portfolio"); - var stompClient = Stomp.over(socket); - - stompClient.connect({}, function(frame) { - } ----- - -Note that `stompClient` in the preceding example does not need to specify `login` -and `passcode` headers. Even if it did, they would be ignored (or, rather, -overridden) on the server side. See <> -and <> for more information on authentication. - -For more example code see: - -* https://spring.io/guides/gs/messaging-stomp-websocket/[Using WebSocket to build an -interactive web application] -- a getting started guide. -* https://github.com/rstoyanchev/spring-websocket-portfolio[Stock Portfolio] -- a sample -application. - - - -[[websocket-stomp-server-config]] -=== WebSocket Server - -To configure the underlying WebSocket server, the information in -<> applies. For Jetty, however you need to set -the `HandshakeHandler` and `WebSocketPolicy` through the `StompEndpointRegistry`: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - @Override - public void registerStompEndpoints(StompEndpointRegistry registry) { - registry.addEndpoint("/portfolio").setHandshakeHandler(handshakeHandler()); - } - - @Bean - public DefaultHandshakeHandler handshakeHandler() { - - WebSocketPolicy policy = new WebSocketPolicy(WebSocketBehavior.SERVER); - policy.setInputBufferSize(8192); - policy.setIdleTimeout(600000); - - return new DefaultHandshakeHandler( - new JettyRequestUpgradeStrategy(new WebSocketServerFactory(policy))); - } - } ----- - - - -[[websocket-stomp-message-flow]] -=== Flow of Messages - -Once a STOMP endpoint is exposed, the Spring application becomes a STOMP broker for -connected clients. This section describes the flow of messages on the server side. - -The `spring-messaging` module contains foundational support for messaging applications -that originated in https://spring.io/spring-integration[Spring Integration] and was -later extracted and incorporated into the Spring Framework for broader use across many -https://spring.io/projects[Spring projects] and application scenarios. -The following list briefly describes a few of the available messaging abstractions: - -* {api-spring-framework}/messaging/Message.html[Message]: -Simple representation for a message, including headers and payload. -* {api-spring-framework}/messaging/MessageHandler.html[MessageHandler]: -Contract for handling a message. -* {api-spring-framework}/messaging/MessageChannel.html[MessageChannel]: -Contract for sending a message that enables loose coupling between producers and consumers. -* {api-spring-framework}/messaging/SubscribableChannel.html[SubscribableChannel]: -`MessageChannel` with `MessageHandler` subscribers. -* {api-spring-framework}/messaging/support/ExecutorSubscribableChannel.html[ExecutorSubscribableChannel]: -`SubscribableChannel` that uses an `Executor` for delivering messages. - -Both the Java configuration (that is, `@EnableWebSocketMessageBroker`) and the XML namespace configuration -(that is, ``) use the preceding components to assemble a message -workflow. The following diagram shows the components used when the simple built-in message -broker is enabled: - -image::message-flow-simple-broker.png[] - -The preceding diagram shows three message channels: - -* `clientInboundChannel`: For passing messages received from WebSocket clients. -* `clientOutboundChannel`: For sending server messages to WebSocket clients. -* `brokerChannel`: For sending messages to the message broker from within -server-side application code. - -The next diagram shows the components used when an external broker (such as RabbitMQ) -is configured for managing subscriptions and broadcasting messages: - -image::message-flow-broker-relay.png[] - -The main difference between the two preceding diagrams is the use of the "`broker relay`" for passing -messages up to the external STOMP broker over TCP and for passing messages down from the -broker to subscribed clients. - -When messages are received from a WebSocket connection, they are decoded to STOMP frames, -turned into a Spring `Message` representation, and sent to the -`clientInboundChannel` for further processing. For example, STOMP messages whose -destination headers start with `/app` may be routed to `@MessageMapping` methods in -annotated controllers, while `/topic` and `/queue` messages may be routed directly -to the message broker. - -An annotated `@Controller` that handles a STOMP message from a client may send a message to -the message broker through the `brokerChannel`, and the broker broadcasts the -message to matching subscribers through the `clientOutboundChannel`. The same -controller can also do the same in response to HTTP requests, so a client can perform an -HTTP POST, and then a `@PostMapping` method can send a message to the message broker -to broadcast to subscribed clients. - -We can trace the flow through a simple example. Consider the following example, which sets up a server: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - @Override - public void registerStompEndpoints(StompEndpointRegistry registry) { - registry.addEndpoint("/portfolio"); - } - - @Override - public void configureMessageBroker(MessageBrokerRegistry registry) { - registry.setApplicationDestinationPrefixes("/app"); - registry.enableSimpleBroker("/topic"); - } - } - - @Controller - public class GreetingController { - - @MessageMapping("/greeting") - public String handle(String greeting) { - return "[" + getTimestamp() + ": " + greeting; - } - } ----- - -The preceding example supports the following flow: - -. The client connects to `http://localhost:8080/portfolio` and, once a WebSocket connection -is established, STOMP frames begin to flow on it. -. The client sends a SUBSCRIBE frame with a destination header of `/topic/greeting`. Once received -and decoded, the message is sent to the `clientInboundChannel` and is then routed to the -message broker, which stores the client subscription. -. The client sends a SEND frame to `/app/greeting`. The `/app` prefix helps to route it to -annotated controllers. After the `/app` prefix is stripped, the remaining `/greeting` -part of the destination is mapped to the `@MessageMapping` method in `GreetingController`. -. The value returned from `GreetingController` is turned into a Spring `Message` with -a payload based on the return value and a default destination header of -`/topic/greeting` (derived from the input destination with `/app` replaced by -`/topic`). The resulting message is sent to the `brokerChannel` and handled -by the message broker. -. The message broker finds all matching subscribers and sends a MESSAGE frame to each one -through the `clientOutboundChannel`, from where messages are encoded as STOMP frames -and sent on the WebSocket connection. - -The next section provides more details on annotated methods, including the -kinds of arguments and return values that are supported. - - - -[[websocket-stomp-handle-annotations]] -=== Annotated Controllers - -Applications can use annotated `@Controller` classes to handle messages from clients. -Such classes can declare `@MessageMapping`, `@SubscribeMapping`, and `@ExceptionHandler` -methods, as described in the following topics: - -* <> -* <> -* <> - - -[[websocket-stomp-message-mapping]] -==== `@MessageMapping` - -You can use `@MessageMapping` to annotate methods that route messages based on their -destination. It is supported at the method level as well as at the type level. At the type -level, `@MessageMapping` is used to express shared mappings across all methods in a -controller. - -By default, the mapping values are Ant-style path patterns (for example `/thing*`, `/thing/**`), -including support for template variables (for example, pass:q[`/thing/{id}`]). The values can be -referenced through `@DestinationVariable` method arguments. Applications can also switch to -a dot-separated destination convention for mappings, as explained in -<>. - -[[supported-method-arguments]] -===== Supported Method Arguments - -The following table describes the method arguments: - -[cols="1,2", options="header"] -|=== -| Method argument | Description - -| `Message` -| For access to the complete message. - -| `MessageHeaders` -| For access to the headers within the `Message`. - -| `MessageHeaderAccessor`, `SimpMessageHeaderAccessor`, and `StompHeaderAccessor` -| For access to the headers through typed accessor methods. - -| `@Payload` -| For access to the payload of the message, converted (for example, from JSON) by a configured -`MessageConverter`. - -The presence of this annotation is not required since it is, by default, assumed if no -other argument is matched. - -You can annotate payload arguments with `@jakarta.validation.Valid` or Spring's `@Validated`, -to have the payload arguments be automatically validated. - -| `@Header` -| For access to a specific header value -- along with type conversion using an -`org.springframework.core.convert.converter.Converter`, if necessary. - -| `@Headers` -| For access to all headers in the message. This argument must be assignable to -`java.util.Map`. - -| `@DestinationVariable` -| For access to template variables extracted from the message destination. -Values are converted to the declared method argument type as necessary. - -| `java.security.Principal` -| Reflects the user logged in at the time of the WebSocket HTTP handshake. - -|=== - -[[return-values]] -===== Return Values - -By default, the return value from a `@MessageMapping` method is serialized to a payload -through a matching `MessageConverter` and sent as a `Message` to the `brokerChannel`, -from where it is broadcast to subscribers. The destination of the outbound message is the -same as that of the inbound message but prefixed with `/topic`. - -You can use the `@SendTo` and `@SendToUser` annotations to customize the destination of -the output message. `@SendTo` is used to customize the target destination or to -specify multiple destinations. `@SendToUser` is used to direct the output message -to only the user associated with the input message. See <>. - -You can use both `@SendTo` and `@SendToUser` at the same time on the same method, and both -are supported at the class level, in which case they act as a default for methods in the -class. However, keep in mind that any method-level `@SendTo` or `@SendToUser` annotations -override any such annotations at the class level. - -Messages can be handled asynchronously and a `@MessageMapping` method can return -`ListenableFuture`, `CompletableFuture`, or `CompletionStage`. - -Note that `@SendTo` and `@SendToUser` are merely a convenience that amounts to using the -`SimpMessagingTemplate` to send messages. If necessary, for more advanced scenarios, -`@MessageMapping` methods can fall back on using the `SimpMessagingTemplate` directly. -This can be done instead of, or possibly in addition to, returning a value. -See <>. - - -[[websocket-stomp-subscribe-mapping]] -==== `@SubscribeMapping` - -`@SubscribeMapping` is similar to `@MessageMapping` but narrows the mapping to -subscription messages only. It supports the same -<> as `@MessageMapping`. However -for the return value, by default, a message is sent directly to the client (through -`clientOutboundChannel`, in response to the subscription) and not to the broker (through -`brokerChannel`, as a broadcast to matching subscriptions). Adding `@SendTo` or -`@SendToUser` overrides this behavior and sends to the broker instead. - -When is this useful? Assume that the broker is mapped to `/topic` and `/queue`, while -application controllers are mapped to `/app`. In this setup, the broker stores all -subscriptions to `/topic` and `/queue` that are intended for repeated broadcasts, and -there is no need for the application to get involved. A client could also subscribe to -some `/app` destination, and a controller could return a value in response to that -subscription without involving the broker without storing or using the subscription again -(effectively a one-time request-reply exchange). One use case for this is populating a UI -with initial data on startup. - -When is this not useful? Do not try to map broker and controllers to the same destination -prefix unless you want both to independently process messages, including subscriptions, -for some reason. Inbound messages are handled in parallel. There are no guarantees whether -a broker or a controller processes a given message first. If the goal is to be notified -when a subscription is stored and ready for broadcasts, a client should ask for a -receipt if the server supports it (simple broker does not). For example, with the Java -<>, you could do the following to add a receipt: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Autowired - private TaskScheduler messageBrokerTaskScheduler; - - // During initialization.. - stompClient.setTaskScheduler(this.messageBrokerTaskScheduler); - - // When subscribing.. - StompHeaders headers = new StompHeaders(); - headers.setDestination("/topic/..."); - headers.setReceipt("r1"); - FrameHandler handler = ...; - stompSession.subscribe(headers, handler).addReceiptTask(receiptHeaders -> { - // Subscription ready... - }); ----- - -A server side option is <> an -`ExecutorChannelInterceptor` on the `brokerChannel` and implement the `afterMessageHandled` -method that is invoked after messages, including subscriptions, have been handled. - - -[[websocket-stomp-exception-handler]] -==== `@MessageExceptionHandler` - -An application can use `@MessageExceptionHandler` methods to handle exceptions from -`@MessageMapping` methods. You can declare exceptions in the annotation -itself or through a method argument if you want to get access to the exception instance. -The following example declares an exception through a method argument: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Controller - public class MyController { - - // ... - - @MessageExceptionHandler - public ApplicationError handleException(MyException exception) { - // ... - return appError; - } - } ----- - -`@MessageExceptionHandler` methods support flexible method signatures and support -the same method argument types and return values as -<> methods. - -Typically, `@MessageExceptionHandler` methods apply within the `@Controller` class -(or class hierarchy) in which they are declared. If you want such methods to apply -more globally (across controllers), you can declare them in a class marked with -`@ControllerAdvice`. This is comparable to the -<> available in Spring MVC. - - - -[[websocket-stomp-handle-send]] -=== Sending Messages - -What if you want to send messages to connected clients from any part of the -application? Any application component can send messages to the `brokerChannel`. -The easiest way to do so is to inject a `SimpMessagingTemplate` and -use it to send messages. Typically, you would inject it by -type, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Controller - public class GreetingController { - - private SimpMessagingTemplate template; - - @Autowired - public GreetingController(SimpMessagingTemplate template) { - this.template = template; - } - - @RequestMapping(path="/greetings", method=POST) - public void greet(String greeting) { - String text = "[" + getTimestamp() + "]:" + greeting; - this.template.convertAndSend("/topic/greetings", text); - } - - } ----- - -However, you can also qualify it by its name (`brokerMessagingTemplate`), if another -bean of the same type exists. - - - -[[websocket-stomp-handle-simple-broker]] -=== Simple Broker - -The built-in simple message broker handles subscription requests from clients, -stores them in memory, and broadcasts messages to connected clients that have matching -destinations. The broker supports path-like destinations, including subscriptions -to Ant-style destination patterns. - -NOTE: Applications can also use dot-separated (rather than slash-separated) destinations. -See <>. - -If configured with a task scheduler, the simple broker supports -https://stomp.github.io/stomp-specification-1.2.html#Heart-beating[STOMP heartbeats]. -To configure a scheduler, you can declare your own `TaskScheduler` bean and set it through -the `MessageBrokerRegistry`. Alternatively, you can use the one that is automatically -declared in the built-in WebSocket configuration, however, you'll' need `@Lazy` to avoid -a cycle between the built-in WebSocket configuration and your -`WebSocketMessageBrokerConfigurer`. For example: - -[source,java,indent=0,subs="verbatim,quotes"] ----- -@Configuration -@EnableWebSocketMessageBroker -public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - private TaskScheduler messageBrokerTaskScheduler; - - @Autowired - public void setMessageBrokerTaskScheduler(@Lazy TaskScheduler taskScheduler) { - this.messageBrokerTaskScheduler = taskScheduler; - } - - @Override - public void configureMessageBroker(MessageBrokerRegistry registry) { - registry.enableSimpleBroker("/queue/", "/topic/") - .setHeartbeatValue(new long[] {10000, 20000}) - .setTaskScheduler(this.messageBrokerTaskScheduler); - - // ... - } -} ----- - - - -[[websocket-stomp-handle-broker-relay]] -=== External Broker - -The simple broker is great for getting started but supports only a subset of -STOMP commands (it does not support acks, receipts, and some other features), -relies on a simple message-sending loop, and is not suitable for clustering. -As an alternative, you can upgrade your applications to use a full-featured -message broker. - -See the STOMP documentation for your message broker of choice (such as -https://www.rabbitmq.com/stomp.html[RabbitMQ], -https://activemq.apache.org/stomp.html[ActiveMQ], and others), install the broker, -and run it with STOMP support enabled. Then you can enable the STOMP broker relay -(instead of the simple broker) in the Spring configuration. - -The following example configuration enables a full-featured broker: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - @Override - public void registerStompEndpoints(StompEndpointRegistry registry) { - registry.addEndpoint("/portfolio").withSockJS(); - } - - @Override - public void configureMessageBroker(MessageBrokerRegistry registry) { - registry.enableStompBrokerRelay("/topic", "/queue"); - registry.setApplicationDestinationPrefixes("/app"); - } - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - - - ----- - -The STOMP broker relay in the preceding configuration is a Spring -{api-spring-framework}/messaging/MessageHandler.html[`MessageHandler`] -that handles messages by forwarding them to an external message broker. -To do so, it establishes TCP connections to the broker, forwards all messages to it, -and then forwards all messages received from the broker to clients through their -WebSocket sessions. Essentially, it acts as a "`relay`" that forwards messages -in both directions. - -NOTE: Add `io.projectreactor.netty:reactor-netty` and `io.netty:netty-all` -dependencies to your project for TCP connection management. - -Furthermore, application components (such as HTTP request handling methods, -business services, and others) can also send messages to the broker relay, as described -in <>, to broadcast messages to subscribed WebSocket clients. - -In effect, the broker relay enables robust and scalable message broadcasting. - - - -[[websocket-stomp-handle-broker-relay-configure]] -=== Connecting to a Broker - -A STOMP broker relay maintains a single "`system`" TCP connection to the broker. -This connection is used for messages originating from the server-side application -only, not for receiving messages. You can configure the STOMP credentials (that is, -the STOMP frame `login` and `passcode` headers) for this connection. This is exposed -in both the XML namespace and Java configuration as the `systemLogin` and -`systemPasscode` properties with default values of `guest` and `guest`. - -The STOMP broker relay also creates a separate TCP connection for every connected -WebSocket client. You can configure the STOMP credentials that are used for all TCP -connections created on behalf of clients. This is exposed in both the XML namespace -and Java configuration as the `clientLogin` and `clientPasscode` properties with default -values of `guest` and `guest`. - -NOTE: The STOMP broker relay always sets the `login` and `passcode` headers on every `CONNECT` -frame that it forwards to the broker on behalf of clients. Therefore, WebSocket clients -need not set those headers. They are ignored. As the <> -section explains, WebSocket clients should instead rely on HTTP authentication to protect -the WebSocket endpoint and establish the client identity. - -The STOMP broker relay also sends and receives heartbeats to and from the message -broker over the "`system`" TCP connection. You can configure the intervals for sending -and receiving heartbeats (10 seconds each by default). If connectivity to the broker -is lost, the broker relay continues to try to reconnect, every 5 seconds, -until it succeeds. - -Any Spring bean can implement `ApplicationListener` -to receive notifications when the "`system`" connection to the broker is lost and -re-established. For example, a Stock Quote service that broadcasts stock quotes can -stop trying to send messages when there is no active "`system`" connection. - -By default, the STOMP broker relay always connects, and reconnects as needed if -connectivity is lost, to the same host and port. If you wish to supply multiple addresses, -on each attempt to connect, you can configure a supplier of addresses, instead of a -fixed host and port. The following example shows how to do that: - -[source,java,indent=0,subs="verbatim,quotes"] ----- -@Configuration -@EnableWebSocketMessageBroker -public class WebSocketConfig extends AbstractWebSocketMessageBrokerConfigurer { - - // ... - - @Override - public void configureMessageBroker(MessageBrokerRegistry registry) { - registry.enableStompBrokerRelay("/queue/", "/topic/").setTcpClient(createTcpClient()); - registry.setApplicationDestinationPrefixes("/app"); - } - - private ReactorNettyTcpClient createTcpClient() { - return new ReactorNettyTcpClient<>( - client -> client.addressSupplier(() -> ... ), - new StompReactorNettyCodec()); - } -} ----- - -You can also configure the STOMP broker relay with a `virtualHost` property. -The value of this property is set as the `host` header of every `CONNECT` frame -and can be useful (for example, in a cloud environment where the actual host to which -the TCP connection is established differs from the host that provides the -cloud-based STOMP service). - - - -[[websocket-stomp-destination-separator]] -=== Dots as Separators - -When messages are routed to `@MessageMapping` methods, they are matched with -`AntPathMatcher`. By default, patterns are expected to use slash (`/`) as the separator. -This is a good convention in web applications and similar to HTTP URLs. However, if -you are more used to messaging conventions, you can switch to using dot (`.`) as the separator. - -The following example shows how to do so in Java configuration: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - // ... - - @Override - public void configureMessageBroker(MessageBrokerRegistry registry) { - registry.setPathMatcher(new AntPathMatcher(".")); - registry.enableStompBrokerRelay("/queue", "/topic"); - registry.setApplicationDestinationPrefixes("/app"); - } - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - - - - - ----- - -After that, a controller can use a dot (`.`) as the separator in `@MessageMapping` methods, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Controller - @MessageMapping("red") - public class RedController { - - @MessageMapping("blue.{green}") - public void handleGreen(@DestinationVariable String green) { - // ... - } - } ----- - -The client can now send a message to `/app/red.blue.green123`. - -In the preceding example, we did not change the prefixes on the "`broker relay`", because those -depend entirely on the external message broker. See the STOMP documentation pages for -the broker you use to see what conventions it supports for the destination header. - -The "`simple broker`", on the other hand, does rely on the configured `PathMatcher`, so, if -you switch the separator, that change also applies to the broker and the way the broker matches -destinations from a message to patterns in subscriptions. - - - -[[websocket-stomp-authentication]] -=== Authentication - -Every STOMP over WebSocket messaging session begins with an HTTP request. -That can be a request to upgrade to WebSockets (that is, a WebSocket handshake) -or, in the case of SockJS fallbacks, a series of SockJS HTTP transport requests. - -Many web applications already have authentication and authorization in place to -secure HTTP requests. Typically, a user is authenticated through Spring Security -by using some mechanism such as a login page, HTTP basic authentication, or another way. -The security context for the authenticated user is saved in the HTTP session -and is associated with subsequent requests in the same cookie-based session. - -Therefore, for a WebSocket handshake or for SockJS HTTP transport requests, -typically, there is already an authenticated user accessible through -`HttpServletRequest#getUserPrincipal()`. Spring automatically associates that user -with a WebSocket or SockJS session created for them and, subsequently, with all -STOMP messages transported over that session through a user header. - -In short, a typical web application needs to do nothing -beyond what it already does for security. The user is authenticated at -the HTTP request level with a security context that is maintained through a cookie-based -HTTP session (which is then associated with WebSocket or SockJS sessions created -for that user) and results in a user header being stamped on every `Message` flowing -through the application. - -The STOMP protocol does have `login` and `passcode` headers on the `CONNECT` frame. -Those were originally designed for and are needed for STOMP over TCP. However, for STOMP -over WebSocket, by default, Spring ignores authentication headers at the STOMP protocol -level, and assumes that the user is already authenticated at the HTTP transport level. -The expectation is that the WebSocket or SockJS session contain the authenticated user. - - - -[[websocket-stomp-authentication-token-based]] -=== Token Authentication - -https://github.com/spring-projects/spring-security-oauth[Spring Security OAuth] -provides support for token based security, including JSON Web Token (JWT). -You can use this as the authentication mechanism in Web applications, -including STOMP over WebSocket interactions, as described in the previous -section (that is, to maintain identity through a cookie-based session). - -At the same time, cookie-based sessions are not always the best fit (for example, -in applications that do not maintain a server-side session or in -mobile applications where it is common to use headers for authentication). - -The https://tools.ietf.org/html/rfc6455#section-10.5[WebSocket protocol, RFC 6455] -"doesn't prescribe any particular way that servers can authenticate clients during -the WebSocket handshake." In practice, however, browser clients can use only standard -authentication headers (that is, basic HTTP authentication) or cookies and cannot (for example) -provide custom headers. Likewise, the SockJS JavaScript client does not provide -a way to send HTTP headers with SockJS transport requests. See -https://github.com/sockjs/sockjs-client/issues/196[sockjs-client issue 196]. -Instead, it does allow sending query parameters that you can use to send a token, -but that has its own drawbacks (for example, the token may be inadvertently -logged with the URL in server logs). - -NOTE: The preceding limitations are for browser-based clients and do not apply to the -Spring Java-based STOMP client, which does support sending headers with both -WebSocket and SockJS requests. - -Therefore, applications that wish to avoid the use of cookies may not have any good -alternatives for authentication at the HTTP protocol level. Instead of using cookies, -they may prefer to authenticate with headers at the STOMP messaging protocol level. -Doing so requires two simple steps: - -. Use the STOMP client to pass authentication headers at connect time. -. Process the authentication headers with a `ChannelInterceptor`. - -The next example uses server-side configuration to register a custom authentication -interceptor. Note that an interceptor needs only to authenticate and set -the user header on the CONNECT `Message`. Spring notes and saves the authenticated -user and associate it with subsequent STOMP messages on the same session. The following -example shows how register a custom authentication interceptor: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class MyConfig implements WebSocketMessageBrokerConfigurer { - - @Override - public void configureClientInboundChannel(ChannelRegistration registration) { - registration.interceptors(new ChannelInterceptor() { - @Override - public Message preSend(Message message, MessageChannel channel) { - StompHeaderAccessor accessor = - MessageHeaderAccessor.getAccessor(message, StompHeaderAccessor.class); - if (StompCommand.CONNECT.equals(accessor.getCommand())) { - Authentication user = ... ; // access authentication header(s) - accessor.setUser(user); - } - return message; - } - }); - } - } ----- - -Also, note that, when you use Spring Security's authorization for messages, at present, -you need to ensure that the authentication `ChannelInterceptor` config is ordered -ahead of Spring Security's. This is best done by declaring the custom interceptor in -its own implementation of `WebSocketMessageBrokerConfigurer` that is marked with -`@Order(Ordered.HIGHEST_PRECEDENCE + 99)`. - - - -[[websocket-stomp-authorization]] -=== Authorization - -Spring Security provides -{docs-spring-security}/servlet/integrations/websocket.html#websocket-authorization[WebSocket sub-protocol authorization] -that uses a `ChannelInterceptor` to authorize messages based on the user header in them. -Also, Spring Session provides -https://docs.spring.io/spring-session/reference/web-socket.html[WebSocket integration] -that ensures the user's HTTP session does not expire while the WebSocket session is still active. - - - -[[websocket-stomp-user-destination]] -=== User Destinations - -An application can send messages that target a specific user, and Spring's STOMP support -recognizes destinations prefixed with `/user/` for this purpose. -For example, a client might subscribe to the `/user/queue/position-updates` destination. -`UserDestinationMessageHandler` handles this destination and transforms it into a -destination unique to the user session (such as `/queue/position-updates-user123`). -This provides the convenience of subscribing to a generically named destination while, -at the same time, ensuring no collisions with other users who subscribe to the same -destination so that each user can receive unique stock position updates. - -TIP: When working with user destinations, it is important to configure broker and -application destination prefixes as shown in <>, or otherwise the -broker would handle "/user" prefixed messages that should only be handled by -`UserDestinationMessageHandler`. - -On the sending side, messages can be sent to a destination such as -pass:q[`/user/{username}/queue/position-updates`], which in turn is translated -by the `UserDestinationMessageHandler` into one or more destinations, one for each -session associated with the user. This lets any component within the application -send messages that target a specific user without necessarily knowing anything more -than their name and the generic destination. This is also supported through an -annotation and a messaging template. - -A message-handling method can send messages to the user associated with -the message being handled through the `@SendToUser` annotation (also supported on -the class-level to share a common destination), as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Controller - public class PortfolioController { - - @MessageMapping("/trade") - @SendToUser("/queue/position-updates") - public TradeResult executeTrade(Trade trade, Principal principal) { - // ... - return tradeResult; - } - } ----- - -If the user has more than one session, by default, all of the sessions subscribed -to the given destination are targeted. However, sometimes, it may be necessary to -target only the session that sent the message being handled. You can do so by -setting the `broadcast` attribute to false, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Controller - public class MyController { - - @MessageMapping("/action") - public void handleAction() throws Exception{ - // raise MyBusinessException here - } - - @MessageExceptionHandler - @SendToUser(destinations="/queue/errors", broadcast=false) - public ApplicationError handleException(MyBusinessException exception) { - // ... - return appError; - } - } ----- - -NOTE: While user destinations generally imply an authenticated user, it is not strictly required. -A WebSocket session that is not associated with an authenticated user -can subscribe to a user destination. In such cases, the `@SendToUser` annotation -behaves exactly the same as with `broadcast=false` (that is, targeting only the -session that sent the message being handled). - -You can send a message to user destinations from any application -component by, for example, injecting the `SimpMessagingTemplate` created by the Java configuration or -the XML namespace. (The bean name is `brokerMessagingTemplate` if required -for qualification with `@Qualifier`.) The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes"] ----- -@Service -public class TradeServiceImpl implements TradeService { - - private final SimpMessagingTemplate messagingTemplate; - - @Autowired - public TradeServiceImpl(SimpMessagingTemplate messagingTemplate) { - this.messagingTemplate = messagingTemplate; - } - - // ... - - public void afterTradeExecuted(Trade trade) { - this.messagingTemplate.convertAndSendToUser( - trade.getUserName(), "/queue/position-updates", trade.getResult()); - } -} ----- - -NOTE: When you use user destinations with an external message broker, you should check the broker -documentation on how to manage inactive queues, so that, when the user session is -over, all unique user queues are removed. For example, RabbitMQ creates auto-delete -queues when you use destinations such as `/exchange/amq.direct/position-updates`. -So, in that case, the client could subscribe to `/user/exchange/amq.direct/position-updates`. -Similarly, ActiveMQ has -https://activemq.apache.org/delete-inactive-destinations.html[configuration options] -for purging inactive destinations. - -In a multi-application server scenario, a user destination may remain unresolved because -the user is connected to a different server. In such cases, you can configure a -destination to broadcast unresolved messages so that other servers have a chance to try. -This can be done through the `userDestinationBroadcast` property of the -`MessageBrokerRegistry` in Java configuration and the `user-destination-broadcast` attribute -of the `message-broker` element in XML. - - - -[[websocket-stomp-ordered-messages]] -=== Order of Messages - -Messages from the broker are published to the `clientOutboundChannel`, from where they are -written to WebSocket sessions. As the channel is backed by a `ThreadPoolExecutor`, messages -are processed in different threads, and the resulting sequence received by the client may -not match the exact order of publication. - -If this is an issue, enable the `setPreservePublishOrder` flag, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class MyConfig implements WebSocketMessageBrokerConfigurer { - - @Override - protected void configureMessageBroker(MessageBrokerRegistry registry) { - // ... - registry.setPreservePublishOrder(true); - } - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - ----- - -When the flag is set, messages within the same client session are published to the -`clientOutboundChannel` one at a time, so that the order of publication is guaranteed. -Note that this incurs a small performance overhead, so you should enable it only if it is required. - - - -[[websocket-stomp-application-context-events]] -=== Events - -Several `ApplicationContext` events are published and can be -received by implementing Spring's `ApplicationListener` interface: - -* `BrokerAvailabilityEvent`: Indicates when the broker becomes available or unavailable. -While the "`simple`" broker becomes available immediately on startup and remains so while -the application is running, the STOMP "`broker relay`" can lose its connection -to the full featured broker (for example, if the broker is restarted). The broker relay -has reconnect logic and re-establishes the "`system`" connection to the broker -when it comes back. As a result, this event is published whenever the state changes from connected -to disconnected and vice-versa. Components that use the `SimpMessagingTemplate` should -subscribe to this event and avoid sending messages at times when the broker is not -available. In any case, they should be prepared to handle `MessageDeliveryException` -when sending a message. -* `SessionConnectEvent`: Published when a new STOMP CONNECT is received to -indicate the start of a new client session. The event contains the message that represents the -connect, including the session ID, user information (if any), and any custom headers the client -sent. This is useful for tracking client sessions. Components subscribed -to this event can wrap the contained message with `SimpMessageHeaderAccessor` or -`StompMessageHeaderAccessor`. -* `SessionConnectedEvent`: Published shortly after a `SessionConnectEvent` when the -broker has sent a STOMP CONNECTED frame in response to the CONNECT. At this point, the -STOMP session can be considered fully established. -* `SessionSubscribeEvent`: Published when a new STOMP SUBSCRIBE is received. -* `SessionUnsubscribeEvent`: Published when a new STOMP UNSUBSCRIBE is received. -* `SessionDisconnectEvent`: Published when a STOMP session ends. The DISCONNECT may -have been sent from the client or it may be automatically generated when the -WebSocket session is closed. In some cases, this event is published more than once -per session. Components should be idempotent with regard to multiple disconnect events. - -NOTE: When you use a full-featured broker, the STOMP "`broker relay`" automatically reconnects the -"`system`" connection if broker becomes temporarily unavailable. Client connections, -however, are not automatically reconnected. Assuming heartbeats are enabled, the client -typically notices the broker is not responding within 10 seconds. Clients need to -implement their own reconnecting logic. - - - -[[websocket-stomp-interceptors]] -=== Interception - -<> provide notifications for the lifecycle -of a STOMP connection but not for every client message. Applications can also register a -`ChannelInterceptor` to intercept any message and in any part of the processing chain. -The following example shows how to intercept inbound messages from clients: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - @Override - public void configureClientInboundChannel(ChannelRegistration registration) { - registration.interceptors(new MyChannelInterceptor()); - } - } ----- - -A custom `ChannelInterceptor` can use `StompHeaderAccessor` or `SimpMessageHeaderAccessor` -to access information about the message, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public class MyChannelInterceptor implements ChannelInterceptor { - - @Override - public Message preSend(Message message, MessageChannel channel) { - StompHeaderAccessor accessor = StompHeaderAccessor.wrap(message); - StompCommand command = accessor.getStompCommand(); - // ... - return message; - } - } ----- - -Applications can also implement `ExecutorChannelInterceptor`, which is a sub-interface -of `ChannelInterceptor` with callbacks in the thread in which the messages are handled. -While a `ChannelInterceptor` is invoked once for each message sent to a channel, the -`ExecutorChannelInterceptor` provides hooks in the thread of each `MessageHandler` -subscribed to messages from the channel. - -Note that, as with the `SessionDisconnectEvent` described earlier, a DISCONNECT message -can be from the client or it can also be automatically generated when -the WebSocket session is closed. In some cases, an interceptor may intercept this -message more than once for each session. Components should be idempotent with regard to -multiple disconnect events. - - - -[[websocket-stomp-client]] -=== STOMP Client - -Spring provides a STOMP over WebSocket client and a STOMP over TCP client. - -To begin, you can create and configure `WebSocketStompClient`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - WebSocketClient webSocketClient = new StandardWebSocketClient(); - WebSocketStompClient stompClient = new WebSocketStompClient(webSocketClient); - stompClient.setMessageConverter(new StringMessageConverter()); - stompClient.setTaskScheduler(taskScheduler); // for heartbeats ----- - -In the preceding example, you could replace `StandardWebSocketClient` with `SockJsClient`, -since that is also an implementation of `WebSocketClient`. The `SockJsClient` can -use WebSocket or HTTP-based transport as a fallback. For more details, see -<>. - -Next, you can establish a connection and provide a handler for the STOMP session, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - String url = "ws://127.0.0.1:8080/endpoint"; - StompSessionHandler sessionHandler = new MyStompSessionHandler(); - stompClient.connect(url, sessionHandler); ----- - -When the session is ready for use, the handler is notified, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- -public class MyStompSessionHandler extends StompSessionHandlerAdapter { - - @Override - public void afterConnected(StompSession session, StompHeaders connectedHeaders) { - // ... - } -} ----- - -Once the session is established, any payload can be sent and is -serialized with the configured `MessageConverter`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- -session.send("/topic/something", "payload"); ----- - -You can also subscribe to destinations. The `subscribe` methods require a handler -for messages on the subscription and returns a `Subscription` handle that you can -use to unsubscribe. For each received message, the handler can specify the target -`Object` type to which the payload should be deserialized, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- -session.subscribe("/topic/something", new StompFrameHandler() { - - @Override - public Type getPayloadType(StompHeaders headers) { - return String.class; - } - - @Override - public void handleFrame(StompHeaders headers, Object payload) { - // ... - } - -}); ----- - -To enable STOMP heartbeat, you can configure `WebSocketStompClient` with a `TaskScheduler` -and optionally customize the heartbeat intervals (10 seconds for write inactivity, -which causes a heartbeat to be sent, and 10 seconds for read inactivity, which -closes the connection). - -`WebSocketStompClient` sends a heartbeat only in case of inactivity, i.e. when no -other messages are sent. This can present a challenge when using an external broker -since messages with a non-broker destination represent activity but aren't actually -forwarded to the broker. In that case you can configure a `TaskScheduler` -when initializing the <> which ensures a -heartbeat is forwarded to the broker also when only messages with a non-broker -destination are sent. - -NOTE: When you use `WebSocketStompClient` for performance tests to simulate thousands -of clients from the same machine, consider turning off heartbeats, since each -connection schedules its own heartbeat tasks and that is not optimized for -a large number of clients running on the same machine. - -The STOMP protocol also supports receipts, where the client must add a `receipt` -header to which the server responds with a RECEIPT frame after the send or -subscribe are processed. To support this, the `StompSession` offers -`setAutoReceipt(boolean)` that causes a `receipt` header to be -added on every subsequent send or subscribe event. -Alternatively, you can also manually add a receipt header to the `StompHeaders`. -Both send and subscribe return an instance of `Receiptable` -that you can use to register for receipt success and failure callbacks. -For this feature, you must configure the client with a `TaskScheduler` -and the amount of time before a receipt expires (15 seconds by default). - -Note that `StompSessionHandler` itself is a `StompFrameHandler`, which lets -it handle ERROR frames in addition to the `handleException` callback for -exceptions from the handling of messages and `handleTransportError` for -transport-level errors including `ConnectionLostException`. - - - -[[websocket-stomp-websocket-scope]] -=== WebSocket Scope - -Each WebSocket session has a map of attributes. The map is attached as a header to -inbound client messages and may be accessed from a controller method, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- -@Controller -public class MyController { - - @MessageMapping("/action") - public void handle(SimpMessageHeaderAccessor headerAccessor) { - Map attrs = headerAccessor.getSessionAttributes(); - // ... - } -} ----- - -You can declare a Spring-managed bean in the `websocket` scope. -You can inject WebSocket-scoped beans into controllers and any channel interceptors -registered on the `clientInboundChannel`. Those are typically singletons and live -longer than any individual WebSocket session. Therefore, you need to use a -scope proxy mode for WebSocket-scoped beans, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Component - @Scope(scopeName = "websocket", proxyMode = ScopedProxyMode.TARGET_CLASS) - public class MyBean { - - @PostConstruct - public void init() { - // Invoked after dependencies injected - } - - // ... - - @PreDestroy - public void destroy() { - // Invoked when the WebSocket session ends - } - } - - @Controller - public class MyController { - - private final MyBean myBean; - - @Autowired - public MyController(MyBean myBean) { - this.myBean = myBean; - } - - @MessageMapping("/action") - public void handle() { - // this.myBean from the current WebSocket session - } - } ----- - -As with any custom scope, Spring initializes a new `MyBean` instance the first -time it is accessed from the controller and stores the instance in the WebSocket -session attributes. The same instance is subsequently returned until the session -ends. WebSocket-scoped beans have all Spring lifecycle methods invoked, as -shown in the preceding examples. - - - -[[websocket-stomp-configuration-performance]] -=== Performance - -There is no silver bullet when it comes to performance. Many factors -affect it, including the size and volume of messages, whether application -methods perform work that requires blocking, and external factors -(such as network speed and other issues). The goal of this section is to provide -an overview of the available configuration options along with some thoughts -on how to reason about scaling. - -In a messaging application, messages are passed through channels for asynchronous -executions that are backed by thread pools. Configuring such an application requires -good knowledge of the channels and the flow of messages. Therefore, it is -recommended to review <>. - -The obvious place to start is to configure the thread pools that back the -`clientInboundChannel` and the `clientOutboundChannel`. By default, both -are configured at twice the number of available processors. - -If the handling of messages in annotated methods is mainly CPU-bound, the -number of threads for the `clientInboundChannel` should remain close to the -number of processors. If the work they do is more IO-bound and requires blocking -or waiting on a database or other external system, the thread pool size -probably needs to be increased. - -[NOTE] -==== -`ThreadPoolExecutor` has three important properties: the core thread pool size, -the max thread pool size, and the capacity for the queue to store -tasks for which there are no available threads. - -A common point of confusion is that configuring the core pool size (for example, 10) -and max pool size (for example, 20) results in a thread pool with 10 to 20 threads. -In fact, if the capacity is left at its default value of Integer.MAX_VALUE, -the thread pool never increases beyond the core pool size, since -all additional tasks are queued. - -See the javadoc of `ThreadPoolExecutor` to learn how these properties work and -understand the various queuing strategies. -==== - -On the `clientOutboundChannel` side, it is all about sending messages to WebSocket -clients. If clients are on a fast network, the number of threads should -remain close to the number of available processors. If they are slow or on -low bandwidth, they take longer to consume messages and put a burden on the -thread pool. Therefore, increasing the thread pool size becomes necessary. - -While the workload for the `clientInboundChannel` is possible to predict -- -after all, it is based on what the application does -- how to configure the -"clientOutboundChannel" is harder, as it is based on factors beyond -the control of the application. For this reason, two additional -properties relate to the sending of messages: `sendTimeLimit` -and `sendBufferSizeLimit`. You can use those methods to configure how long a -send is allowed to take and how much data can be buffered when sending -messages to a client. - -The general idea is that, at any given time, only a single thread can be used -to send to a client. All additional messages, meanwhile, get buffered, and you -can use these properties to decide how long sending a message is allowed to -take and how much data can be buffered in the meantime. See the javadoc and -documentation of the XML schema for important additional details. - -The following example shows a possible configuration: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - @Override - public void configureWebSocketTransport(WebSocketTransportRegistration registration) { - registration.setSendTimeLimit(15 * 1000).setSendBufferSizeLimit(512 * 1024); - } - - // ... - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - ----- - -You can also use the WebSocket transport configuration shown earlier to configure the -maximum allowed size for incoming STOMP messages. In theory, a WebSocket -message can be almost unlimited in size. In practice, WebSocket servers impose -limits -- for example, 8K on Tomcat and 64K on Jetty. For this reason, STOMP clients -(such as the JavaScript https://github.com/JSteunou/webstomp-client[webstomp-client] -and others) split larger STOMP messages at 16K boundaries and send them as multiple -WebSocket messages, which requires the server to buffer and re-assemble. - -Spring's STOMP-over-WebSocket support does this ,so applications can configure the -maximum size for STOMP messages irrespective of WebSocket server-specific message -sizes. Keep in mind that the WebSocket message size is automatically -adjusted, if necessary, to ensure they can carry 16K WebSocket messages at a -minimum. - -The following example shows one possible configuration: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - @Configuration - @EnableWebSocketMessageBroker - public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - - @Override - public void configureWebSocketTransport(WebSocketTransportRegistration registration) { - registration.setMessageSizeLimit(128 * 1024); - } - - // ... - - } ----- - -The following example shows the XML configuration equivalent of the preceding example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - - - - ----- - -An important point about scaling involves using multiple application instances. -Currently, you cannot do that with the simple broker. -However, when you use a full-featured broker (such as RabbitMQ), each application -instance connects to the broker, and messages broadcast from one application -instance can be broadcast through the broker to WebSocket clients connected -through any other application instances. - - - -[[websocket-stomp-stats]] -=== Monitoring - -When you use `@EnableWebSocketMessageBroker` or ``, key -infrastructure components automatically gather statistics and counters that provide -important insight into the internal state of the application. The configuration -also declares a bean of type `WebSocketMessageBrokerStats` that gathers all -available information in one place and by default logs it at the `INFO` level once -every 30 minutes. This bean can be exported to JMX through Spring's -`MBeanExporter` for viewing at runtime (for example, through JDK's `jconsole`). -The following list summarizes the available information: - -Client WebSocket Sessions:: - Current::: Indicates how many client sessions there are - currently, with the count further broken down by WebSocket versus HTTP - streaming and polling SockJS sessions. - Total::: Indicates how many total sessions have been established. - Abnormally Closed::: - Connect Failures:::: Sessions that got established but were - closed after not having received any messages within 60 seconds. This is - usually an indication of proxy or network issues. - Send Limit Exceeded:::: Sessions closed after exceeding the configured send - timeout or the send buffer limits, which can occur with slow clients - (see previous section). - Transport Errors:::: Sessions closed after a transport error, such as - failure to read or write to a WebSocket connection or - HTTP request or response. - STOMP Frames::: The total number of CONNECT, CONNECTED, and DISCONNECT frames - processed, indicating how many clients connected on the STOMP level. Note that - the DISCONNECT count may be lower when sessions get closed abnormally or when - clients close without sending a DISCONNECT frame. -STOMP Broker Relay:: - TCP Connections::: Indicates how many TCP connections on behalf of client - WebSocket sessions are established to the broker. This should be equal to the - number of client WebSocket sessions + 1 additional shared "`system`" connection - for sending messages from within the application. - STOMP Frames::: The total number of CONNECT, CONNECTED, and DISCONNECT frames - forwarded to or received from the broker on behalf of clients. Note that a - DISCONNECT frame is sent to the broker regardless of how the client WebSocket - session was closed. Therefore, a lower DISCONNECT frame count is an indication - that the broker is pro-actively closing connections (maybe because of a - heartbeat that did not arrive in time, an invalid input frame, or other issue). -Client Inbound Channel:: Statistics from the thread pool that backs the `clientInboundChannel` - that provide insight into the health of incoming message processing. Tasks queueing - up here is an indication that the application may be too slow to handle messages. - If there I/O bound tasks (for example, slow database queries, HTTP requests to third party - REST API, and so on), consider increasing the thread pool size. -Client Outbound Channel:: Statistics from the thread pool that backs the `clientOutboundChannel` - that provides insight into the health of broadcasting messages to clients. Tasks - queueing up here is an indication clients are too slow to consume messages. - One way to address this is to increase the thread pool size to accommodate the - expected number of concurrent slow clients. Another option is to reduce the - send timeout and send buffer size limits (see the previous section). -SockJS Task Scheduler:: Statistics from the thread pool of the SockJS task scheduler that - is used to send heartbeats. Note that, when heartbeats are negotiated on the - STOMP level, the SockJS heartbeats are disabled. - - - -[[websocket-stomp-testing]] -=== Testing - -There are two main approaches to testing applications when you use Spring's STOMP-over-WebSocket -support. The first is to write server-side tests to verify the functionality -of controllers and their annotated message-handling methods. The second is to write -full end-to-end tests that involve running a client and a server. - -The two approaches are not mutually exclusive. On the contrary, each has a place -in an overall test strategy. Server-side tests are more focused and easier to write -and maintain. End-to-end integration tests, on the other hand, are more complete and -test much more, but they are also more involved to write and maintain. - -The simplest form of server-side tests is to write controller unit tests. However, -this is not useful enough, since much of what a controller does depends on its -annotations. Pure unit tests simply cannot test that. - -Ideally, controllers under test should be invoked as they are at runtime, much like -the approach to testing controllers that handle HTTP requests by using the Spring MVC Test -framework -- that is, without running a Servlet container but relying on the Spring Framework -to invoke the annotated controllers. As with Spring MVC Test, you have two -possible alternatives here, either use a "`context-based`" or use a "`standalone`" setup: - -* Load the actual Spring configuration with the help of the -Spring TestContext framework, inject `clientInboundChannel` as a test field, and -use it to send messages to be handled by controller methods. - -* Manually set up the minimum Spring framework infrastructure required to invoke -controllers (namely the `SimpAnnotationMethodMessageHandler`) and pass messages for -controllers directly to it. - -Both of these setup scenarios are demonstrated in the -https://github.com/rstoyanchev/spring-websocket-portfolio/tree/master/src/test/java/org/springframework/samples/portfolio/web[tests for the stock portfolio] -sample application. - -The second approach is to create end-to-end integration tests. For that, you need -to run a WebSocket server in embedded mode and connect to it as a WebSocket client -that sends WebSocket messages containing STOMP frames. -The https://github.com/rstoyanchev/spring-websocket-portfolio/tree/master/src/test/java/org/springframework/samples/portfolio/web[tests for the stock portfolio] -sample application also demonstrate this approach by using Tomcat as the embedded -WebSocket server and a simple STOMP client for test purposes. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc b/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc new file mode 100644 index 000000000000..477f291c6835 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc @@ -0,0 +1,379 @@ +[[websocket-fallback]] += SockJS Fallback + +Over the public Internet, restrictive proxies outside your control may preclude WebSocket +interactions, either because they are not configured to pass on the `Upgrade` header or +because they close long-lived connections that appear to be idle. + +The solution to this problem is WebSocket emulation -- that is, attempting to use WebSocket +first and then falling back on HTTP-based techniques that emulate a WebSocket +interaction and expose the same application-level API. + +On the Servlet stack, the Spring Framework provides both server (and also client) support +for the SockJS protocol. + + + +[[websocket-fallback-sockjs-overview]] +== Overview + +The goal of SockJS is to let applications use a WebSocket API but fall back to +non-WebSocket alternatives when necessary at runtime, without the need to +change application code. + +SockJS consists of: + +* The https://github.com/sockjs/sockjs-protocol[SockJS protocol] +defined in the form of executable +https://sockjs.github.io/sockjs-protocol/sockjs-protocol-0.3.3.html[narrated tests]. +* The https://github.com/sockjs/sockjs-client/[SockJS JavaScript client] -- a client library for use in browsers. +* SockJS server implementations, including one in the Spring Framework `spring-websocket` module. +* A SockJS Java client in the `spring-websocket` module (since version 4.1). + +SockJS is designed for use in browsers. It uses a variety of techniques +to support a wide range of browser versions. +For the full list of SockJS transport types and browsers, see the +https://github.com/sockjs/sockjs-client/[SockJS client] page. Transports +fall in three general categories: WebSocket, HTTP Streaming, and HTTP Long Polling. +For an overview of these categories, see +https://spring.io/blog/2012/05/08/spring-mvc-3-2-preview-techniques-for-real-time-updates/[this blog post]. + +The SockJS client begins by sending `GET /info` to +obtain basic information from the server. After that, it must decide what transport +to use. If possible, WebSocket is used. If not, in most browsers, +there is at least one HTTP streaming option. If not, then HTTP (long) +polling is used. + +All transport requests have the following URL structure: + +---- +https://host:port/myApp/myEndpoint/{server-id}/{session-id}/{transport} +---- + +where: + +* pass:q[`{server-id}`] is useful for routing requests in a cluster but is not used otherwise. +* pass:q[`{session-id}`] correlates HTTP requests belonging to a SockJS session. +* pass:q[`{transport}`] indicates the transport type (for example, `websocket`, `xhr-streaming`, and others). + +The WebSocket transport needs only a single HTTP request to do the WebSocket handshake. +All messages thereafter are exchanged on that socket. + +HTTP transports require more requests. Ajax/XHR streaming, for example, relies on +one long-running request for server-to-client messages and additional HTTP POST +requests for client-to-server messages. Long polling is similar, except that it +ends the current request after each server-to-client send. + +SockJS adds minimal message framing. For example, the server sends the letter `o` +("`open`" frame) initially, messages are sent as `a["message1","message2"]` +(JSON-encoded array), the letter `h` ("`heartbeat`" frame) if no messages flow +for 25 seconds (by default), and the letter `c` ("`close`" frame) to close the session. + +To learn more, run an example in a browser and watch the HTTP requests. +The SockJS client allows fixing the list of transports, so it is possible to +see each transport one at a time. The SockJS client also provides a debug flag, +which enables helpful messages in the browser console. On the server side, you can enable +`TRACE` logging for `org.springframework.web.socket`. +For even more detail, see the SockJS protocol +https://sockjs.github.io/sockjs-protocol/sockjs-protocol-0.3.3.html[narrated test]. + + + +[[websocket-fallback-sockjs-enable]] +== Enabling SockJS + +You can enable SockJS through Java configuration, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocket + public class WebSocketConfig implements WebSocketConfigurer { + + @Override + public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { + registry.addHandler(myHandler(), "/myHandler").withSockJS(); + } + + @Bean + public WebSocketHandler myHandler() { + return new MyHandler(); + } + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + + + +---- + +The preceding example is for use in Spring MVC applications and should be included in the +configuration of a <>. However, Spring's WebSocket +and SockJS support does not depend on Spring MVC. It is relatively simple to +integrate into other HTTP serving environments with the help of +{api-spring-framework}/web/socket/sockjs/support/SockJsHttpRequestHandler.html[`SockJsHttpRequestHandler`]. + +On the browser side, applications can use the +https://github.com/sockjs/sockjs-client/[`sockjs-client`] (version 1.0.x). It +emulates the W3C WebSocket API and communicates with the server to select the best +transport option, depending on the browser in which it runs. See the +https://github.com/sockjs/sockjs-client/[sockjs-client] page and the list of +transport types supported by browser. The client also provides several +configuration options -- for example, to specify which transports to include. + + + +[[websocket-fallback-xhr-vs-iframe]] +== IE 8 and 9 + +Internet Explorer 8 and 9 remain in use. They are +a key reason for having SockJS. This section covers important +considerations about running in those browsers. + +The SockJS client supports Ajax/XHR streaming in IE 8 and 9 by using Microsoft's +https://web.archive.org/web/20160219230343/https://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainrequest-restrictions-limitations-and-workarounds.aspx[`XDomainRequest`]. +That works across domains but does not support sending cookies. +Cookies are often essential for Java applications. +However, since the SockJS client can be used with many server +types (not just Java ones), it needs to know whether cookies matter. +If so, the SockJS client prefers Ajax/XHR for streaming. Otherwise, it +relies on an iframe-based technique. + +The first `/info` request from the SockJS client is a request for +information that can influence the client's choice of transports. +One of those details is whether the server application relies on cookies +(for example, for authentication purposes or clustering with sticky sessions). +Spring's SockJS support includes a property called `sessionCookieNeeded`. +It is enabled by default, since most Java applications rely on the `JSESSIONID` +cookie. If your application does not need it, you can turn off this option, +and SockJS client should then choose `xdr-streaming` in IE 8 and 9. + +If you do use an iframe-based transport, keep in mind +that browsers can be instructed to block the use of IFrames on a given page by +setting the HTTP response header `X-Frame-Options` to `DENY`, +`SAMEORIGIN`, or `ALLOW-FROM `. This is used to prevent +https://www.owasp.org/index.php/Clickjacking[clickjacking]. + +[NOTE] +==== +Spring Security 3.2+ provides support for setting `X-Frame-Options` on every +response. By default, the Spring Security Java configuration sets it to `DENY`. +In 3.2, the Spring Security XML namespace does not set that header by default +but can be configured to do so. In the future, it may set it by default. + +See {docs-spring-security}/features/exploits/headers.html#headers-default[Default Security Headers] +of the Spring Security documentation for details on how to configure the +setting of the `X-Frame-Options` header. You can also see +https://github.com/spring-projects/spring-security/issues/2718[gh-2718] +for additional background. +==== + +If your application adds the `X-Frame-Options` response header (as it should!) +and relies on an iframe-based transport, you need to set the header value to +`SAMEORIGIN` or `ALLOW-FROM `. The Spring SockJS +support also needs to know the location of the SockJS client, because it is loaded +from the iframe. By default, the iframe is set to download the SockJS client +from a CDN location. It is a good idea to configure this option to use +a URL from the same origin as the application. + +The following example shows how to do so in Java configuration: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + @Override + public void registerStompEndpoints(StompEndpointRegistry registry) { + registry.addEndpoint("/portfolio").withSockJS() + .setClientLibraryUrl("http://localhost:8080/myapp/js/sockjs-client.js"); + } + + // ... + + } +---- + +The XML namespace provides a similar option through the `` element. + +NOTE: During initial development, do enable the SockJS client `devel` mode that prevents +the browser from caching SockJS requests (like the iframe) that would otherwise +be cached. For details on how to enable it see the +https://github.com/sockjs/sockjs-client/[SockJS client] page. + + + +[[websocket-fallback-sockjs-heartbeat]] +== Heartbeats + +The SockJS protocol requires servers to send heartbeat messages to preclude proxies +from concluding that a connection is hung. The Spring SockJS configuration has a property +called `heartbeatTime` that you can use to customize the frequency. By default, a +heartbeat is sent after 25 seconds, assuming no other messages were sent on that +connection. This 25-second value is in line with the following +https://tools.ietf.org/html/rfc6202[IETF recommendation] for public Internet applications. + +NOTE: When using STOMP over WebSocket and SockJS, if the STOMP client and server negotiate +heartbeats to be exchanged, the SockJS heartbeats are disabled. + +The Spring SockJS support also lets you configure the `TaskScheduler` to +schedule heartbeats tasks. The task scheduler is backed by a thread pool, +with default settings based on the number of available processors. Your +should consider customizing the settings according to your specific needs. + + + +[[websocket-fallback-sockjs-servlet3-async]] +== Client Disconnects + +HTTP streaming and HTTP long polling SockJS transports require a connection to remain +open longer than usual. For an overview of these techniques, see +https://spring.io/blog/2012/05/08/spring-mvc-3-2-preview-techniques-for-real-time-updates/[this blog post]. + +In Servlet containers, this is done through Servlet 3 asynchronous support that +allows exiting the Servlet container thread, processing a request, and continuing +to write to the response from another thread. + +A specific issue is that the Servlet API does not provide notifications for a client +that has gone away. See https://github.com/eclipse-ee4j/servlet-api/issues/44[eclipse-ee4j/servlet-api#44]. +However, Servlet containers raise an exception on subsequent attempts to write +to the response. Since Spring's SockJS Service supports server-sent heartbeats (every +25 seconds by default), that means a client disconnect is usually detected within that +time period (or earlier, if messages are sent more frequently). + +NOTE: As a result, network I/O failures can occur because a client has disconnected, which +can fill the log with unnecessary stack traces. Spring makes a best effort to identify +such network failures that represent client disconnects (specific to each server) and log +a minimal message by using the dedicated log category, `DISCONNECTED_CLIENT_LOG_CATEGORY` +(defined in `AbstractSockJsSession`). If you need to see the stack traces, you can set that +log category to TRACE. + + + +[[websocket-fallback-cors]] +== SockJS and CORS + +If you allow cross-origin requests (see <>), the SockJS protocol +uses CORS for cross-domain support in the XHR streaming and polling transports. Therefore, +CORS headers are added automatically, unless the presence of CORS headers in the response +is detected. So, if an application is already configured to provide CORS support (for example, +through a Servlet Filter), Spring's `SockJsService` skips this part. + +It is also possible to disable the addition of these CORS headers by setting the +`suppressCors` property in Spring's SockJsService. + +SockJS expects the following headers and values: + +* `Access-Control-Allow-Origin`: Initialized from the value of the `Origin` request header. +* `Access-Control-Allow-Credentials`: Always set to `true`. +* `Access-Control-Request-Headers`: Initialized from values from the equivalent request header. +* `Access-Control-Allow-Methods`: The HTTP methods a transport supports (see `TransportType` enum). +* `Access-Control-Max-Age`: Set to 31536000 (1 year). + +For the exact implementation, see `addCorsHeaders` in `AbstractSockJsService` and +the `TransportType` enum in the source code. + +Alternatively, if the CORS configuration allows it, consider excluding URLs with the +SockJS endpoint prefix, thus letting Spring's `SockJsService` handle it. + + + +[[websocket-fallback-sockjs-client]] +== `SockJsClient` + +Spring provides a SockJS Java client to connect to remote SockJS endpoints without +using a browser. This can be especially useful when there is a need for bidirectional +communication between two servers over a public network (that is, where network proxies can +preclude the use of the WebSocket protocol). A SockJS Java client is also very useful +for testing purposes (for example, to simulate a large number of concurrent users). + +The SockJS Java client supports the `websocket`, `xhr-streaming`, and `xhr-polling` +transports. The remaining ones only make sense for use in a browser. + +You can configure the `WebSocketTransport` with: + +* `StandardWebSocketClient` in a JSR-356 runtime. +* `JettyWebSocketClient` by using the Jetty 9+ native WebSocket API. +* Any implementation of Spring's `WebSocketClient`. + +An `XhrTransport`, by definition, supports both `xhr-streaming` and `xhr-polling`, since, +from a client perspective, there is no difference other than in the URL used to connect +to the server. At present there are two implementations: + +* `RestTemplateXhrTransport` uses Spring's `RestTemplate` for HTTP requests. +* `JettyXhrTransport` uses Jetty's `HttpClient` for HTTP requests. + +The following example shows how to create a SockJS client and connect to a SockJS endpoint: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + List transports = new ArrayList<>(2); + transports.add(new WebSocketTransport(new StandardWebSocketClient())); + transports.add(new RestTemplateXhrTransport()); + + SockJsClient sockJsClient = new SockJsClient(transports); + sockJsClient.doHandshake(new MyWebSocketHandler(), "ws://example.com:8080/sockjs"); +---- + +NOTE: SockJS uses JSON formatted arrays for messages. By default, Jackson 2 is used and needs +to be on the classpath. Alternatively, you can configure a custom implementation of +`SockJsMessageCodec` and configure it on the `SockJsClient`. + +To use `SockJsClient` to simulate a large number of concurrent users, you +need to configure the underlying HTTP client (for XHR transports) to allow a sufficient +number of connections and threads. The following example shows how to do so with Jetty: + +[source,java,indent=0,subs="verbatim,quotes"] +---- +HttpClient jettyHttpClient = new HttpClient(); +jettyHttpClient.setMaxConnectionsPerDestination(1000); +jettyHttpClient.setExecutor(new QueuedThreadPool(1000)); +---- + +The following example shows the server-side SockJS-related properties (see javadoc for details) +that you should also consider customizing: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + public class WebSocketConfig extends WebSocketMessageBrokerConfigurationSupport { + + @Override + public void registerStompEndpoints(StompEndpointRegistry registry) { + registry.addEndpoint("/sockjs").withSockJS() + .setStreamBytesLimit(512 * 1024) <1> + .setHttpMessageCacheSize(1000) <2> + .setDisconnectDelay(30 * 1000); <3> + } + + // ... + } +---- +<1> Set the `streamBytesLimit` property to 512KB (the default is 128KB -- `128 * 1024`). +<2> Set the `httpMessageCacheSize` property to 1,000 (the default is `100`). +<3> Set the `disconnectDelay` property to 30 property seconds (the default is five seconds +-- `5 * 1000`). + + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/server.adoc b/framework-docs/modules/ROOT/pages/web/websocket/server.adoc new file mode 100644 index 000000000000..a67bbac5fa2f --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/server.adoc @@ -0,0 +1,426 @@ +[[websocket-server]] += WebSocket API + +[.small]#<># + +The Spring Framework provides a WebSocket API that you can use to write client- and +server-side applications that handle WebSocket messages. + + + +[[websocket-server-handler]] +== `WebSocketHandler` +[.small]#<># + +Creating a WebSocket server is as simple as implementing `WebSocketHandler` or, more +likely, extending either `TextWebSocketHandler` or `BinaryWebSocketHandler`. The following +example uses `TextWebSocketHandler`: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + import org.springframework.web.socket.WebSocketHandler; + import org.springframework.web.socket.WebSocketSession; + import org.springframework.web.socket.TextMessage; + + public class MyHandler extends TextWebSocketHandler { + + @Override + public void handleTextMessage(WebSocketSession session, TextMessage message) { + // ... + } + + } +---- + +There is dedicated WebSocket Java configuration and XML namespace support for mapping the preceding +WebSocket handler to a specific URL, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + import org.springframework.web.socket.config.annotation.EnableWebSocket; + import org.springframework.web.socket.config.annotation.WebSocketConfigurer; + import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry; + + @Configuration + @EnableWebSocket + public class WebSocketConfig implements WebSocketConfigurer { + + @Override + public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { + registry.addHandler(myHandler(), "/myHandler"); + } + + @Bean + public WebSocketHandler myHandler() { + return new MyHandler(); + } + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + + +---- + +The preceding example is for use in Spring MVC applications and should be included +in the configuration of a <>. However, Spring's +WebSocket support does not depend on Spring MVC. It is relatively simple to +integrate a `WebSocketHandler` into other HTTP-serving environments with the help of +{api-spring-framework}/web/socket/server/support/WebSocketHttpRequestHandler.html[`WebSocketHttpRequestHandler`]. + +When using the `WebSocketHandler` API directly vs indirectly, e.g. through the +<> messaging, the application must synchronize the sending of messages +since the underlying standard WebSocket session (JSR-356) does not allow concurrent +sending. One option is to wrap the `WebSocketSession` with +{api-spring-framework}/web/socket/handler/ConcurrentWebSocketSessionDecorator.html[`ConcurrentWebSocketSessionDecorator`]. + + + +[[websocket-server-handshake]] +== WebSocket Handshake +[.small]#<># + +The easiest way to customize the initial HTTP WebSocket handshake request is through +a `HandshakeInterceptor`, which exposes methods for "`before`" and "`after`" the handshake. +You can use such an interceptor to preclude the handshake or to make any attributes +available to the `WebSocketSession`. The following example uses a built-in interceptor +to pass HTTP session attributes to the WebSocket session: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocket + public class WebSocketConfig implements WebSocketConfigurer { + + @Override + public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { + registry.addHandler(new MyHandler(), "/myHandler") + .addInterceptors(new HttpSessionHandshakeInterceptor()); + } + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + + + + + +---- + +A more advanced option is to extend the `DefaultHandshakeHandler` that performs +the steps of the WebSocket handshake, including validating the client origin, +negotiating a sub-protocol, and other details. An application may also need to use this +option if it needs to configure a custom `RequestUpgradeStrategy` in order to +adapt to a WebSocket server engine and version that is not yet supported +(see <> for more on this subject). +Both the Java configuration and XML namespace make it possible to configure a custom +`HandshakeHandler`. + + +TIP: Spring provides a `WebSocketHandlerDecorator` base class that you can use to decorate +a `WebSocketHandler` with additional behavior. Logging and exception handling +implementations are provided and added by default when using the WebSocket Java configuration +or XML namespace. The `ExceptionWebSocketHandlerDecorator` catches all uncaught +exceptions that arise from any `WebSocketHandler` method and closes the WebSocket +session with status `1011`, which indicates a server error. + + + +[[websocket-server-deployment]] +== Deployment + +The Spring WebSocket API is easy to integrate into a Spring MVC application where +the `DispatcherServlet` serves both HTTP WebSocket handshake and other +HTTP requests. It is also easy to integrate into other HTTP processing scenarios +by invoking `WebSocketHttpRequestHandler`. This is convenient and easy to +understand. However, special considerations apply with regards to JSR-356 runtimes. + +The Jakarta WebSocket API (JSR-356) provides two deployment mechanisms. The first +involves a Servlet container classpath scan (a Servlet 3 feature) at startup. +The other is a registration API to use at Servlet container initialization. +Neither of these mechanism makes it possible to use a single "`front controller`" +for all HTTP processing -- including WebSocket handshake and all other HTTP +requests -- such as Spring MVC's `DispatcherServlet`. + +This is a significant limitation of JSR-356 that Spring's WebSocket support addresses with +server-specific `RequestUpgradeStrategy` implementations even when running in a JSR-356 runtime. +Such strategies currently exist for Tomcat, Jetty, GlassFish, WebLogic, WebSphere, and Undertow +(and WildFly). As of Jakarta WebSocket 2.1, a standard request upgrade strategy is available +which Spring chooses on Jakarta EE 10 based web containers such as Tomcat 10.1 and Jetty 12. + +A secondary consideration is that Servlet containers with JSR-356 support are expected +to perform a `ServletContainerInitializer` (SCI) scan that can slow down application +startup -- in some cases, dramatically. If a significant impact is observed after an +upgrade to a Servlet container version with JSR-356 support, it should +be possible to selectively enable or disable web fragments (and SCI scanning) +through the use of the `` element in `web.xml`, as the following example shows: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + +---- + +You can then selectively enable web fragments by name, such as Spring's own +`SpringServletContainerInitializer` that provides support for the Servlet 3 +Java initialization API. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + spring_web + + + +---- + + + +[[websocket-server-runtime-configuration]] +== Server Configuration +[.small]#<># + +Each underlying WebSocket engine exposes configuration properties that control +runtime characteristics, such as the size of message buffer sizes, idle timeout, +and others. + +For Tomcat, WildFly, and GlassFish, you can add a `ServletServerContainerFactoryBean` to your +WebSocket Java config, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocket + public class WebSocketConfig implements WebSocketConfigurer { + + @Bean + public ServletServerContainerFactoryBean createWebSocketContainer() { + ServletServerContainerFactoryBean container = new ServletServerContainerFactoryBean(); + container.setMaxTextMessageBufferSize(8192); + container.setMaxBinaryMessageBufferSize(8192); + return container; + } + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + +---- + +NOTE: For client-side WebSocket configuration, you should use `WebSocketContainerFactoryBean` +(XML) or `ContainerProvider.getWebSocketContainer()` (Java configuration). + +For Jetty, you need to supply a pre-configured Jetty `WebSocketServerFactory` and plug +that into Spring's `DefaultHandshakeHandler` through your WebSocket Java config. +The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocket + public class WebSocketConfig implements WebSocketConfigurer { + + @Override + public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { + registry.addHandler(echoWebSocketHandler(), + "/echo").setHandshakeHandler(handshakeHandler()); + } + + @Bean + public DefaultHandshakeHandler handshakeHandler() { + + WebSocketPolicy policy = new WebSocketPolicy(WebSocketBehavior.SERVER); + policy.setInputBufferSize(8192); + policy.setIdleTimeout(600000); + + return new DefaultHandshakeHandler( + new JettyRequestUpgradeStrategy(new WebSocketServerFactory(policy))); + } + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + + + + + + + + + + + + + + + + + + + +---- + + + +[[websocket-server-allowed-origins]] +== Allowed Origins +[.small]#<># + +As of Spring Framework 4.1.5, the default behavior for WebSocket and SockJS is to accept +only same-origin requests. It is also possible to allow all or a specified list of origins. +This check is mostly designed for browser clients. Nothing prevents other types +of clients from modifying the `Origin` header value (see +https://tools.ietf.org/html/rfc6454[RFC 6454: The Web Origin Concept] for more details). + +The three possible behaviors are: + + * Allow only same-origin requests (default): In this mode, when SockJS is enabled, the + Iframe HTTP response header `X-Frame-Options` is set to `SAMEORIGIN`, and JSONP + transport is disabled, since it does not allow checking the origin of a request. + As a consequence, IE6 and IE7 are not supported when this mode is enabled. + * Allow a specified list of origins: Each allowed origin must start with `http://` + or `https://`. In this mode, when SockJS is enabled, IFrame transport is disabled. + As a consequence, IE6 through IE9 are not supported when this + mode is enabled. + * Allow all origins: To enable this mode, you should provide `{asterisk}` as the allowed origin + value. In this mode, all transports are available. + +You can configure WebSocket and SockJS allowed origins, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + import org.springframework.web.socket.config.annotation.EnableWebSocket; + import org.springframework.web.socket.config.annotation.WebSocketConfigurer; + import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry; + + @Configuration + @EnableWebSocket + public class WebSocketConfig implements WebSocketConfigurer { + + @Override + public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { + registry.addHandler(myHandler(), "/myHandler").setAllowedOrigins("https://mydomain.com"); + } + + @Bean + public WebSocketHandler myHandler() { + return new MyHandler(); + } + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + + +---- + + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp.adoc new file mode 100644 index 000000000000..cc66fcb400e3 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp.adoc @@ -0,0 +1,12 @@ +[[websocket-stomp]] += STOMP + +The WebSocket protocol defines two types of messages (text and binary), but their +content is undefined. The protocol defines a mechanism for client and server to negotiate a +sub-protocol (that is, a higher-level messaging protocol) to use on top of WebSocket to +define what kind of messages each can send, what the format is, the content of each +message, and so on. The use of a sub-protocol is optional but, either way, the client and +the server need to agree on some protocol that defines message content. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/application-context-events.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/application-context-events.adoc new file mode 100644 index 000000000000..7d59414d2ccd --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/application-context-events.adoc @@ -0,0 +1,40 @@ +[[websocket-stomp-application-context-events]] += Events + +Several `ApplicationContext` events are published and can be +received by implementing Spring's `ApplicationListener` interface: + +* `BrokerAvailabilityEvent`: Indicates when the broker becomes available or unavailable. +While the "`simple`" broker becomes available immediately on startup and remains so while +the application is running, the STOMP "`broker relay`" can lose its connection +to the full featured broker (for example, if the broker is restarted). The broker relay +has reconnect logic and re-establishes the "`system`" connection to the broker +when it comes back. As a result, this event is published whenever the state changes from connected +to disconnected and vice-versa. Components that use the `SimpMessagingTemplate` should +subscribe to this event and avoid sending messages at times when the broker is not +available. In any case, they should be prepared to handle `MessageDeliveryException` +when sending a message. +* `SessionConnectEvent`: Published when a new STOMP CONNECT is received to +indicate the start of a new client session. The event contains the message that represents the +connect, including the session ID, user information (if any), and any custom headers the client +sent. This is useful for tracking client sessions. Components subscribed +to this event can wrap the contained message with `SimpMessageHeaderAccessor` or +`StompMessageHeaderAccessor`. +* `SessionConnectedEvent`: Published shortly after a `SessionConnectEvent` when the +broker has sent a STOMP CONNECTED frame in response to the CONNECT. At this point, the +STOMP session can be considered fully established. +* `SessionSubscribeEvent`: Published when a new STOMP SUBSCRIBE is received. +* `SessionUnsubscribeEvent`: Published when a new STOMP UNSUBSCRIBE is received. +* `SessionDisconnectEvent`: Published when a STOMP session ends. The DISCONNECT may +have been sent from the client or it may be automatically generated when the +WebSocket session is closed. In some cases, this event is published more than once +per session. Components should be idempotent with regard to multiple disconnect events. + +NOTE: When you use a full-featured broker, the STOMP "`broker relay`" automatically reconnects the +"`system`" connection if broker becomes temporarily unavailable. Client connections, +however, are not automatically reconnected. Assuming heartbeats are enabled, the client +typically notices the broker is not responding within 10 seconds. Clients need to +implement their own reconnecting logic. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/authentication-token-based.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/authentication-token-based.adoc new file mode 100644 index 000000000000..3ab57f8c878e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/authentication-token-based.adoc @@ -0,0 +1,74 @@ +[[websocket-stomp-authentication-token-based]] += Token Authentication + +https://github.com/spring-projects/spring-security-oauth[Spring Security OAuth] +provides support for token based security, including JSON Web Token (JWT). +You can use this as the authentication mechanism in Web applications, +including STOMP over WebSocket interactions, as described in the previous +section (that is, to maintain identity through a cookie-based session). + +At the same time, cookie-based sessions are not always the best fit (for example, +in applications that do not maintain a server-side session or in +mobile applications where it is common to use headers for authentication). + +The https://tools.ietf.org/html/rfc6455#section-10.5[WebSocket protocol, RFC 6455] +"doesn't prescribe any particular way that servers can authenticate clients during +the WebSocket handshake." In practice, however, browser clients can use only standard +authentication headers (that is, basic HTTP authentication) or cookies and cannot (for example) +provide custom headers. Likewise, the SockJS JavaScript client does not provide +a way to send HTTP headers with SockJS transport requests. See +https://github.com/sockjs/sockjs-client/issues/196[sockjs-client issue 196]. +Instead, it does allow sending query parameters that you can use to send a token, +but that has its own drawbacks (for example, the token may be inadvertently +logged with the URL in server logs). + +NOTE: The preceding limitations are for browser-based clients and do not apply to the +Spring Java-based STOMP client, which does support sending headers with both +WebSocket and SockJS requests. + +Therefore, applications that wish to avoid the use of cookies may not have any good +alternatives for authentication at the HTTP protocol level. Instead of using cookies, +they may prefer to authenticate with headers at the STOMP messaging protocol level. +Doing so requires two simple steps: + +. Use the STOMP client to pass authentication headers at connect time. +. Process the authentication headers with a `ChannelInterceptor`. + +The next example uses server-side configuration to register a custom authentication +interceptor. Note that an interceptor needs only to authenticate and set +the user header on the CONNECT `Message`. Spring notes and saves the authenticated +user and associate it with subsequent STOMP messages on the same session. The following +example shows how register a custom authentication interceptor: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class MyConfig implements WebSocketMessageBrokerConfigurer { + + @Override + public void configureClientInboundChannel(ChannelRegistration registration) { + registration.interceptors(new ChannelInterceptor() { + @Override + public Message preSend(Message message, MessageChannel channel) { + StompHeaderAccessor accessor = + MessageHeaderAccessor.getAccessor(message, StompHeaderAccessor.class); + if (StompCommand.CONNECT.equals(accessor.getCommand())) { + Authentication user = ... ; // access authentication header(s) + accessor.setUser(user); + } + return message; + } + }); + } + } +---- + +Also, note that, when you use Spring Security's authorization for messages, at present, +you need to ensure that the authentication `ChannelInterceptor` config is ordered +ahead of Spring Security's. This is best done by declaring the custom interceptor in +its own implementation of `WebSocketMessageBrokerConfigurer` that is marked with +`@Order(Ordered.HIGHEST_PRECEDENCE + 99)`. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/authentication.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/authentication.adoc new file mode 100644 index 000000000000..b8dafd67d43d --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/authentication.adoc @@ -0,0 +1,34 @@ +[[websocket-stomp-authentication]] += Authentication + +Every STOMP over WebSocket messaging session begins with an HTTP request. +That can be a request to upgrade to WebSockets (that is, a WebSocket handshake) +or, in the case of SockJS fallbacks, a series of SockJS HTTP transport requests. + +Many web applications already have authentication and authorization in place to +secure HTTP requests. Typically, a user is authenticated through Spring Security +by using some mechanism such as a login page, HTTP basic authentication, or another way. +The security context for the authenticated user is saved in the HTTP session +and is associated with subsequent requests in the same cookie-based session. + +Therefore, for a WebSocket handshake or for SockJS HTTP transport requests, +typically, there is already an authenticated user accessible through +`HttpServletRequest#getUserPrincipal()`. Spring automatically associates that user +with a WebSocket or SockJS session created for them and, subsequently, with all +STOMP messages transported over that session through a user header. + +In short, a typical web application needs to do nothing +beyond what it already does for security. The user is authenticated at +the HTTP request level with a security context that is maintained through a cookie-based +HTTP session (which is then associated with WebSocket or SockJS sessions created +for that user) and results in a user header being stamped on every `Message` flowing +through the application. + +The STOMP protocol does have `login` and `passcode` headers on the `CONNECT` frame. +Those were originally designed for and are needed for STOMP over TCP. However, for STOMP +over WebSocket, by default, Spring ignores authentication headers at the STOMP protocol +level, and assumes that the user is already authenticated at the HTTP transport level. +The expectation is that the WebSocket or SockJS session contain the authenticated user. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/authorization.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/authorization.adoc new file mode 100644 index 000000000000..38ba93b459fc --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/authorization.adoc @@ -0,0 +1,12 @@ +[[websocket-stomp-authorization]] += Authorization + +Spring Security provides +{docs-spring-security}/servlet/integrations/websocket.html#websocket-authorization[WebSocket sub-protocol authorization] +that uses a `ChannelInterceptor` to authorize messages based on the user header in them. +Also, Spring Session provides +https://docs.spring.io/spring-session/reference/web-socket.html[WebSocket integration] +that ensures the user's HTTP session does not expire while the WebSocket session is still active. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc new file mode 100644 index 000000000000..49c95b8f0d89 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc @@ -0,0 +1,20 @@ +[[websocket-stomp-benefits]] += Benefits + +Using STOMP as a sub-protocol lets the Spring Framework and Spring Security +provide a richer programming model versus using raw WebSockets. The same point can be +made about HTTP versus raw TCP and how it lets Spring MVC and other web frameworks +provide rich functionality. The following is a list of benefits: + +* No need to invent a custom messaging protocol and message format. +* STOMP clients, including a <> +in the Spring Framework, are available. +* You can (optionally) use message brokers (such as RabbitMQ, ActiveMQ, and others) to +manage subscriptions and broadcast messages. +* Application logic can be organized in any number of `@Controller` instances and messages can be +routed to them based on the STOMP destination header versus handling raw WebSocket messages +with a single `WebSocketHandler` for a given connection. +* You can use Spring Security to secure messages based on STOMP destinations and message types. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc new file mode 100644 index 000000000000..03b7a0c283d7 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc @@ -0,0 +1,109 @@ +[[websocket-stomp-client]] += STOMP Client + +Spring provides a STOMP over WebSocket client and a STOMP over TCP client. + +To begin, you can create and configure `WebSocketStompClient`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + WebSocketClient webSocketClient = new StandardWebSocketClient(); + WebSocketStompClient stompClient = new WebSocketStompClient(webSocketClient); + stompClient.setMessageConverter(new StringMessageConverter()); + stompClient.setTaskScheduler(taskScheduler); // for heartbeats +---- + +In the preceding example, you could replace `StandardWebSocketClient` with `SockJsClient`, +since that is also an implementation of `WebSocketClient`. The `SockJsClient` can +use WebSocket or HTTP-based transport as a fallback. For more details, see +<>. + +Next, you can establish a connection and provide a handler for the STOMP session, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + String url = "ws://127.0.0.1:8080/endpoint"; + StompSessionHandler sessionHandler = new MyStompSessionHandler(); + stompClient.connect(url, sessionHandler); +---- + +When the session is ready for use, the handler is notified, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- +public class MyStompSessionHandler extends StompSessionHandlerAdapter { + + @Override + public void afterConnected(StompSession session, StompHeaders connectedHeaders) { + // ... + } +} +---- + +Once the session is established, any payload can be sent and is +serialized with the configured `MessageConverter`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- +session.send("/topic/something", "payload"); +---- + +You can also subscribe to destinations. The `subscribe` methods require a handler +for messages on the subscription and returns a `Subscription` handle that you can +use to unsubscribe. For each received message, the handler can specify the target +`Object` type to which the payload should be deserialized, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- +session.subscribe("/topic/something", new StompFrameHandler() { + + @Override + public Type getPayloadType(StompHeaders headers) { + return String.class; + } + + @Override + public void handleFrame(StompHeaders headers, Object payload) { + // ... + } + +}); +---- + +To enable STOMP heartbeat, you can configure `WebSocketStompClient` with a `TaskScheduler` +and optionally customize the heartbeat intervals (10 seconds for write inactivity, +which causes a heartbeat to be sent, and 10 seconds for read inactivity, which +closes the connection). + +`WebSocketStompClient` sends a heartbeat only in case of inactivity, i.e. when no +other messages are sent. This can present a challenge when using an external broker +since messages with a non-broker destination represent activity but aren't actually +forwarded to the broker. In that case you can configure a `TaskScheduler` +when initializing the <> which ensures a +heartbeat is forwarded to the broker also when only messages with a non-broker +destination are sent. + +NOTE: When you use `WebSocketStompClient` for performance tests to simulate thousands +of clients from the same machine, consider turning off heartbeats, since each +connection schedules its own heartbeat tasks and that is not optimized for +a large number of clients running on the same machine. + +The STOMP protocol also supports receipts, where the client must add a `receipt` +header to which the server responds with a RECEIPT frame after the send or +subscribe are processed. To support this, the `StompSession` offers +`setAutoReceipt(boolean)` that causes a `receipt` header to be +added on every subsequent send or subscribe event. +Alternatively, you can also manually add a receipt header to the `StompHeaders`. +Both send and subscribe return an instance of `Receiptable` +that you can use to register for receipt success and failure callbacks. +For this feature, you must configure the client with a `TaskScheduler` +and the amount of time before a receipt expires (15 seconds by default). + +Note that `StompSessionHandler` itself is a `StompFrameHandler`, which lets +it handle ERROR frames in addition to the `handleException` callback for +exceptions from the handling of messages and `handleTransportError` for +transport-level errors including `ConnectionLostException`. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc new file mode 100644 index 000000000000..c15c6c4f4070 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc @@ -0,0 +1,163 @@ +[[websocket-stomp-configuration-performance]] += Performance + +There is no silver bullet when it comes to performance. Many factors +affect it, including the size and volume of messages, whether application +methods perform work that requires blocking, and external factors +(such as network speed and other issues). The goal of this section is to provide +an overview of the available configuration options along with some thoughts +on how to reason about scaling. + +In a messaging application, messages are passed through channels for asynchronous +executions that are backed by thread pools. Configuring such an application requires +good knowledge of the channels and the flow of messages. Therefore, it is +recommended to review <>. + +The obvious place to start is to configure the thread pools that back the +`clientInboundChannel` and the `clientOutboundChannel`. By default, both +are configured at twice the number of available processors. + +If the handling of messages in annotated methods is mainly CPU-bound, the +number of threads for the `clientInboundChannel` should remain close to the +number of processors. If the work they do is more IO-bound and requires blocking +or waiting on a database or other external system, the thread pool size +probably needs to be increased. + +[NOTE] +==== +`ThreadPoolExecutor` has three important properties: the core thread pool size, +the max thread pool size, and the capacity for the queue to store +tasks for which there are no available threads. + +A common point of confusion is that configuring the core pool size (for example, 10) +and max pool size (for example, 20) results in a thread pool with 10 to 20 threads. +In fact, if the capacity is left at its default value of Integer.MAX_VALUE, +the thread pool never increases beyond the core pool size, since +all additional tasks are queued. + +See the javadoc of `ThreadPoolExecutor` to learn how these properties work and +understand the various queuing strategies. +==== + +On the `clientOutboundChannel` side, it is all about sending messages to WebSocket +clients. If clients are on a fast network, the number of threads should +remain close to the number of available processors. If they are slow or on +low bandwidth, they take longer to consume messages and put a burden on the +thread pool. Therefore, increasing the thread pool size becomes necessary. + +While the workload for the `clientInboundChannel` is possible to predict -- +after all, it is based on what the application does -- how to configure the +"clientOutboundChannel" is harder, as it is based on factors beyond +the control of the application. For this reason, two additional +properties relate to the sending of messages: `sendTimeLimit` +and `sendBufferSizeLimit`. You can use those methods to configure how long a +send is allowed to take and how much data can be buffered when sending +messages to a client. + +The general idea is that, at any given time, only a single thread can be used +to send to a client. All additional messages, meanwhile, get buffered, and you +can use these properties to decide how long sending a message is allowed to +take and how much data can be buffered in the meantime. See the javadoc and +documentation of the XML schema for important additional details. + +The following example shows a possible configuration: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + @Override + public void configureWebSocketTransport(WebSocketTransportRegistration registration) { + registration.setSendTimeLimit(15 * 1000).setSendBufferSizeLimit(512 * 1024); + } + + // ... + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + +---- + +You can also use the WebSocket transport configuration shown earlier to configure the +maximum allowed size for incoming STOMP messages. In theory, a WebSocket +message can be almost unlimited in size. In practice, WebSocket servers impose +limits -- for example, 8K on Tomcat and 64K on Jetty. For this reason, STOMP clients +(such as the JavaScript https://github.com/JSteunou/webstomp-client[webstomp-client] +and others) split larger STOMP messages at 16K boundaries and send them as multiple +WebSocket messages, which requires the server to buffer and re-assemble. + +Spring's STOMP-over-WebSocket support does this ,so applications can configure the +maximum size for STOMP messages irrespective of WebSocket server-specific message +sizes. Keep in mind that the WebSocket message size is automatically +adjusted, if necessary, to ensure they can carry 16K WebSocket messages at a +minimum. + +The following example shows one possible configuration: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + @Override + public void configureWebSocketTransport(WebSocketTransportRegistration registration) { + registration.setMessageSizeLimit(128 * 1024); + } + + // ... + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + +---- + +An important point about scaling involves using multiple application instances. +Currently, you cannot do that with the simple broker. +However, when you use a full-featured broker (such as RabbitMQ), each application +instance connects to the broker, and messages broadcast from one application +instance can be broadcast through the broker to WebSocket clients connected +through any other application instances. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/destination-separator.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/destination-separator.adoc new file mode 100644 index 000000000000..866b6d81e07a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/destination-separator.adoc @@ -0,0 +1,80 @@ +[[websocket-stomp-destination-separator]] += Dots as Separators + +When messages are routed to `@MessageMapping` methods, they are matched with +`AntPathMatcher`. By default, patterns are expected to use slash (`/`) as the separator. +This is a good convention in web applications and similar to HTTP URLs. However, if +you are more used to messaging conventions, you can switch to using dot (`.`) as the separator. + +The following example shows how to do so in Java configuration: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + // ... + + @Override + public void configureMessageBroker(MessageBrokerRegistry registry) { + registry.setPathMatcher(new AntPathMatcher(".")); + registry.enableStompBrokerRelay("/queue", "/topic"); + registry.setApplicationDestinationPrefixes("/app"); + } + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + + + + + +---- + +After that, a controller can use a dot (`.`) as the separator in `@MessageMapping` methods, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Controller + @MessageMapping("red") + public class RedController { + + @MessageMapping("blue.{green}") + public void handleGreen(@DestinationVariable String green) { + // ... + } + } +---- + +The client can now send a message to `/app/red.blue.green123`. + +In the preceding example, we did not change the prefixes on the "`broker relay`", because those +depend entirely on the external message broker. See the STOMP documentation pages for +the broker you use to see what conventions it supports for the destination header. + +The "`simple broker`", on the other hand, does rely on the configured `PathMatcher`, so, if +you switch the separator, that change also applies to the broker and the way the broker matches +destinations from a message to patterns in subscriptions. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc new file mode 100644 index 000000000000..10a3dc470f78 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc @@ -0,0 +1,109 @@ +[[websocket-stomp-enable]] += Enable STOMP + +STOMP over WebSocket support is available in the `spring-messaging` and +`spring-websocket` modules. Once you have those dependencies, you can expose a STOMP +endpoints, over WebSocket with <>, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker; + import org.springframework.web.socket.config.annotation.StompEndpointRegistry; + + @Configuration + @EnableWebSocketMessageBroker + public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + @Override + public void registerStompEndpoints(StompEndpointRegistry registry) { + registry.addEndpoint("/portfolio").withSockJS(); // <1> + } + + @Override + public void configureMessageBroker(MessageBrokerRegistry config) { + config.setApplicationDestinationPrefixes("/app"); // <2> + config.enableSimpleBroker("/topic", "/queue"); // <3> + } + } +---- + +<1> `/portfolio` is the HTTP URL for the endpoint to which a WebSocket (or SockJS) +client needs to connect for the WebSocket handshake. +<2> STOMP messages whose destination header begins with `/app` are routed to +`@MessageMapping` methods in `@Controller` classes. +<3> Use the built-in message broker for subscriptions and broadcasting and +route messages whose destination header begins with `/topic `or `/queue` to the broker. + + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + + + +---- + +NOTE: For the built-in simple broker, the `/topic` and `/queue` prefixes do not have any special +meaning. They are merely a convention to differentiate between pub-sub versus point-to-point +messaging (that is, many subscribers versus one consumer). When you use an external broker, +check the STOMP page of the broker to understand what kind of STOMP destinations and +prefixes it supports. + +To connect from a browser, for SockJS, you can use the +https://github.com/sockjs/sockjs-client[`sockjs-client`]. For STOMP, many applications have +used the https://github.com/jmesnil/stomp-websocket[jmesnil/stomp-websocket] library +(also known as stomp.js), which is feature-complete and has been used in production for +years but is no longer maintained. At present the +https://github.com/JSteunou/webstomp-client[JSteunou/webstomp-client] is the most +actively maintained and evolving successor of that library. The following example code +is based on it: + +[source,javascript,indent=0,subs="verbatim,quotes"] +---- + var socket = new SockJS("/spring-websocket-portfolio/portfolio"); + var stompClient = webstomp.over(socket); + + stompClient.connect({}, function(frame) { + } +---- + +Alternatively, if you connect through WebSocket (without SockJS), you can use the following code: + +[source,javascript,indent=0,subs="verbatim,quotes"] +---- + var socket = new WebSocket("/spring-websocket-portfolio/portfolio"); + var stompClient = Stomp.over(socket); + + stompClient.connect({}, function(frame) { + } +---- + +Note that `stompClient` in the preceding example does not need to specify `login` +and `passcode` headers. Even if it did, they would be ignored (or, rather, +overridden) on the server side. See <> +and <> for more information on authentication. + +For more example code see: + +* https://spring.io/guides/gs/messaging-stomp-websocket/[Using WebSocket to build an +interactive web application] -- a getting started guide. +* https://github.com/rstoyanchev/spring-websocket-portfolio[Stock Portfolio] -- a sample +application. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc new file mode 100644 index 000000000000..6eaf09f96bf4 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc @@ -0,0 +1,185 @@ +[[websocket-stomp-handle-annotations]] += Annotated Controllers + +Applications can use annotated `@Controller` classes to handle messages from clients. +Such classes can declare `@MessageMapping`, `@SubscribeMapping`, and `@ExceptionHandler` +methods, as described in the following topics: + +* <> +* <> +* <> + + +[[websocket-stomp-message-mapping]] +== `@MessageMapping` + +You can use `@MessageMapping` to annotate methods that route messages based on their +destination. It is supported at the method level as well as at the type level. At the type +level, `@MessageMapping` is used to express shared mappings across all methods in a +controller. + +By default, the mapping values are Ant-style path patterns (for example `/thing*`, `/thing/**`), +including support for template variables (for example, pass:q[`/thing/{id}`]). The values can be +referenced through `@DestinationVariable` method arguments. Applications can also switch to +a dot-separated destination convention for mappings, as explained in +<>. + +[[supported-method-arguments]] +=== Supported Method Arguments + +The following table describes the method arguments: + +[cols="1,2", options="header"] +|=== +| Method argument | Description + +| `Message` +| For access to the complete message. + +| `MessageHeaders` +| For access to the headers within the `Message`. + +| `MessageHeaderAccessor`, `SimpMessageHeaderAccessor`, and `StompHeaderAccessor` +| For access to the headers through typed accessor methods. + +| `@Payload` +| For access to the payload of the message, converted (for example, from JSON) by a configured +`MessageConverter`. + +The presence of this annotation is not required since it is, by default, assumed if no +other argument is matched. + +You can annotate payload arguments with `@jakarta.validation.Valid` or Spring's `@Validated`, +to have the payload arguments be automatically validated. + +| `@Header` +| For access to a specific header value -- along with type conversion using an +`org.springframework.core.convert.converter.Converter`, if necessary. + +| `@Headers` +| For access to all headers in the message. This argument must be assignable to +`java.util.Map`. + +| `@DestinationVariable` +| For access to template variables extracted from the message destination. +Values are converted to the declared method argument type as necessary. + +| `java.security.Principal` +| Reflects the user logged in at the time of the WebSocket HTTP handshake. + +|=== + +[[return-values]] +=== Return Values + +By default, the return value from a `@MessageMapping` method is serialized to a payload +through a matching `MessageConverter` and sent as a `Message` to the `brokerChannel`, +from where it is broadcast to subscribers. The destination of the outbound message is the +same as that of the inbound message but prefixed with `/topic`. + +You can use the `@SendTo` and `@SendToUser` annotations to customize the destination of +the output message. `@SendTo` is used to customize the target destination or to +specify multiple destinations. `@SendToUser` is used to direct the output message +to only the user associated with the input message. See <>. + +You can use both `@SendTo` and `@SendToUser` at the same time on the same method, and both +are supported at the class level, in which case they act as a default for methods in the +class. However, keep in mind that any method-level `@SendTo` or `@SendToUser` annotations +override any such annotations at the class level. + +Messages can be handled asynchronously and a `@MessageMapping` method can return +`ListenableFuture`, `CompletableFuture`, or `CompletionStage`. + +Note that `@SendTo` and `@SendToUser` are merely a convenience that amounts to using the +`SimpMessagingTemplate` to send messages. If necessary, for more advanced scenarios, +`@MessageMapping` methods can fall back on using the `SimpMessagingTemplate` directly. +This can be done instead of, or possibly in addition to, returning a value. +See <>. + + +[[websocket-stomp-subscribe-mapping]] +== `@SubscribeMapping` + +`@SubscribeMapping` is similar to `@MessageMapping` but narrows the mapping to +subscription messages only. It supports the same +<> as `@MessageMapping`. However +for the return value, by default, a message is sent directly to the client (through +`clientOutboundChannel`, in response to the subscription) and not to the broker (through +`brokerChannel`, as a broadcast to matching subscriptions). Adding `@SendTo` or +`@SendToUser` overrides this behavior and sends to the broker instead. + +When is this useful? Assume that the broker is mapped to `/topic` and `/queue`, while +application controllers are mapped to `/app`. In this setup, the broker stores all +subscriptions to `/topic` and `/queue` that are intended for repeated broadcasts, and +there is no need for the application to get involved. A client could also subscribe to +some `/app` destination, and a controller could return a value in response to that +subscription without involving the broker without storing or using the subscription again +(effectively a one-time request-reply exchange). One use case for this is populating a UI +with initial data on startup. + +When is this not useful? Do not try to map broker and controllers to the same destination +prefix unless you want both to independently process messages, including subscriptions, +for some reason. Inbound messages are handled in parallel. There are no guarantees whether +a broker or a controller processes a given message first. If the goal is to be notified +when a subscription is stored and ready for broadcasts, a client should ask for a +receipt if the server supports it (simple broker does not). For example, with the Java +<>, you could do the following to add a receipt: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Autowired + private TaskScheduler messageBrokerTaskScheduler; + + // During initialization.. + stompClient.setTaskScheduler(this.messageBrokerTaskScheduler); + + // When subscribing.. + StompHeaders headers = new StompHeaders(); + headers.setDestination("/topic/..."); + headers.setReceipt("r1"); + FrameHandler handler = ...; + stompSession.subscribe(headers, handler).addReceiptTask(receiptHeaders -> { + // Subscription ready... + }); +---- + +A server side option is <> an +`ExecutorChannelInterceptor` on the `brokerChannel` and implement the `afterMessageHandled` +method that is invoked after messages, including subscriptions, have been handled. + + +[[websocket-stomp-exception-handler]] +== `@MessageExceptionHandler` + +An application can use `@MessageExceptionHandler` methods to handle exceptions from +`@MessageMapping` methods. You can declare exceptions in the annotation +itself or through a method argument if you want to get access to the exception instance. +The following example declares an exception through a method argument: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Controller + public class MyController { + + // ... + + @MessageExceptionHandler + public ApplicationError handleException(MyException exception) { + // ... + return appError; + } + } +---- + +`@MessageExceptionHandler` methods support flexible method signatures and support +the same method argument types and return values as +<> methods. + +Typically, `@MessageExceptionHandler` methods apply within the `@Controller` class +(or class hierarchy) in which they are declared. If you want such methods to apply +more globally (across controllers), you can declare them in a class marked with +`@ControllerAdvice`. This is comparable to the +<> available in Spring MVC. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc new file mode 100644 index 000000000000..84d61cc03a48 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc @@ -0,0 +1,68 @@ +[[websocket-stomp-handle-broker-relay-configure]] += Connecting to a Broker + +A STOMP broker relay maintains a single "`system`" TCP connection to the broker. +This connection is used for messages originating from the server-side application +only, not for receiving messages. You can configure the STOMP credentials (that is, +the STOMP frame `login` and `passcode` headers) for this connection. This is exposed +in both the XML namespace and Java configuration as the `systemLogin` and +`systemPasscode` properties with default values of `guest` and `guest`. + +The STOMP broker relay also creates a separate TCP connection for every connected +WebSocket client. You can configure the STOMP credentials that are used for all TCP +connections created on behalf of clients. This is exposed in both the XML namespace +and Java configuration as the `clientLogin` and `clientPasscode` properties with default +values of `guest` and `guest`. + +NOTE: The STOMP broker relay always sets the `login` and `passcode` headers on every `CONNECT` +frame that it forwards to the broker on behalf of clients. Therefore, WebSocket clients +need not set those headers. They are ignored. As the <> +section explains, WebSocket clients should instead rely on HTTP authentication to protect +the WebSocket endpoint and establish the client identity. + +The STOMP broker relay also sends and receives heartbeats to and from the message +broker over the "`system`" TCP connection. You can configure the intervals for sending +and receiving heartbeats (10 seconds each by default). If connectivity to the broker +is lost, the broker relay continues to try to reconnect, every 5 seconds, +until it succeeds. + +Any Spring bean can implement `ApplicationListener` +to receive notifications when the "`system`" connection to the broker is lost and +re-established. For example, a Stock Quote service that broadcasts stock quotes can +stop trying to send messages when there is no active "`system`" connection. + +By default, the STOMP broker relay always connects, and reconnects as needed if +connectivity is lost, to the same host and port. If you wish to supply multiple addresses, +on each attempt to connect, you can configure a supplier of addresses, instead of a +fixed host and port. The following example shows how to do that: + +[source,java,indent=0,subs="verbatim,quotes"] +---- +@Configuration +@EnableWebSocketMessageBroker +public class WebSocketConfig extends AbstractWebSocketMessageBrokerConfigurer { + + // ... + + @Override + public void configureMessageBroker(MessageBrokerRegistry registry) { + registry.enableStompBrokerRelay("/queue/", "/topic/").setTcpClient(createTcpClient()); + registry.setApplicationDestinationPrefixes("/app"); + } + + private ReactorNettyTcpClient createTcpClient() { + return new ReactorNettyTcpClient<>( + client -> client.addressSupplier(() -> ... ), + new StompReactorNettyCodec()); + } +} +---- + +You can also configure the STOMP broker relay with a `virtualHost` property. +The value of this property is set as the `host` header of every `CONNECT` frame +and can be useful (for example, in a cloud environment where the actual host to which +the TCP connection is established differs from the host that provides the +cloud-based STOMP service). + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc new file mode 100644 index 000000000000..245c85b5871a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc @@ -0,0 +1,79 @@ +[[websocket-stomp-handle-broker-relay]] += External Broker + +The simple broker is great for getting started but supports only a subset of +STOMP commands (it does not support acks, receipts, and some other features), +relies on a simple message-sending loop, and is not suitable for clustering. +As an alternative, you can upgrade your applications to use a full-featured +message broker. + +See the STOMP documentation for your message broker of choice (such as +https://www.rabbitmq.com/stomp.html[RabbitMQ], +https://activemq.apache.org/stomp.html[ActiveMQ], and others), install the broker, +and run it with STOMP support enabled. Then you can enable the STOMP broker relay +(instead of the simple broker) in the Spring configuration. + +The following example configuration enables a full-featured broker: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + @Override + public void registerStompEndpoints(StompEndpointRegistry registry) { + registry.addEndpoint("/portfolio").withSockJS(); + } + + @Override + public void configureMessageBroker(MessageBrokerRegistry registry) { + registry.enableStompBrokerRelay("/topic", "/queue"); + registry.setApplicationDestinationPrefixes("/app"); + } + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + + + + +---- + +The STOMP broker relay in the preceding configuration is a Spring +{api-spring-framework}/messaging/MessageHandler.html[`MessageHandler`] +that handles messages by forwarding them to an external message broker. +To do so, it establishes TCP connections to the broker, forwards all messages to it, +and then forwards all messages received from the broker to clients through their +WebSocket sessions. Essentially, it acts as a "`relay`" that forwards messages +in both directions. + +NOTE: Add `io.projectreactor.netty:reactor-netty` and `io.netty:netty-all` +dependencies to your project for TCP connection management. + +Furthermore, application components (such as HTTP request handling methods, +business services, and others) can also send messages to the broker relay, as described +in <>, to broadcast messages to subscribed WebSocket clients. + +In effect, the broker relay enables robust and scalable message broadcasting. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-send.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-send.adoc new file mode 100644 index 000000000000..e193522ab0c2 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-send.adoc @@ -0,0 +1,35 @@ +[[websocket-stomp-handle-send]] += Sending Messages + +What if you want to send messages to connected clients from any part of the +application? Any application component can send messages to the `brokerChannel`. +The easiest way to do so is to inject a `SimpMessagingTemplate` and +use it to send messages. Typically, you would inject it by +type, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Controller + public class GreetingController { + + private SimpMessagingTemplate template; + + @Autowired + public GreetingController(SimpMessagingTemplate template) { + this.template = template; + } + + @RequestMapping(path="/greetings", method=POST) + public void greet(String greeting) { + String text = "[" + getTimestamp() + "]:" + greeting; + this.template.convertAndSend("/topic/greetings", text); + } + + } +---- + +However, you can also qualify it by its name (`brokerMessagingTemplate`), if another +bean of the same type exists. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc new file mode 100644 index 000000000000..d8803a980236 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc @@ -0,0 +1,45 @@ +[[websocket-stomp-handle-simple-broker]] += Simple Broker + +The built-in simple message broker handles subscription requests from clients, +stores them in memory, and broadcasts messages to connected clients that have matching +destinations. The broker supports path-like destinations, including subscriptions +to Ant-style destination patterns. + +NOTE: Applications can also use dot-separated (rather than slash-separated) destinations. +See <>. + +If configured with a task scheduler, the simple broker supports +https://stomp.github.io/stomp-specification-1.2.html#Heart-beating[STOMP heartbeats]. +To configure a scheduler, you can declare your own `TaskScheduler` bean and set it through +the `MessageBrokerRegistry`. Alternatively, you can use the one that is automatically +declared in the built-in WebSocket configuration, however, you'll' need `@Lazy` to avoid +a cycle between the built-in WebSocket configuration and your +`WebSocketMessageBrokerConfigurer`. For example: + +[source,java,indent=0,subs="verbatim,quotes"] +---- +@Configuration +@EnableWebSocketMessageBroker +public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + private TaskScheduler messageBrokerTaskScheduler; + + @Autowired + public void setMessageBrokerTaskScheduler(@Lazy TaskScheduler taskScheduler) { + this.messageBrokerTaskScheduler = taskScheduler; + } + + @Override + public void configureMessageBroker(MessageBrokerRegistry registry) { + registry.enableSimpleBroker("/queue/", "/topic/") + .setHeartbeatValue(new long[] {10000, 20000}) + .setTaskScheduler(this.messageBrokerTaskScheduler); + + // ... + } +} +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc new file mode 100644 index 000000000000..8c6d0db145e9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc @@ -0,0 +1,52 @@ +[[websocket-stomp-interceptors]] += Interception + +<> provide notifications for the lifecycle +of a STOMP connection but not for every client message. Applications can also register a +`ChannelInterceptor` to intercept any message and in any part of the processing chain. +The following example shows how to intercept inbound messages from clients: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + @Override + public void configureClientInboundChannel(ChannelRegistration registration) { + registration.interceptors(new MyChannelInterceptor()); + } + } +---- + +A custom `ChannelInterceptor` can use `StompHeaderAccessor` or `SimpMessageHeaderAccessor` +to access information about the message, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public class MyChannelInterceptor implements ChannelInterceptor { + + @Override + public Message preSend(Message message, MessageChannel channel) { + StompHeaderAccessor accessor = StompHeaderAccessor.wrap(message); + StompCommand command = accessor.getStompCommand(); + // ... + return message; + } + } +---- + +Applications can also implement `ExecutorChannelInterceptor`, which is a sub-interface +of `ChannelInterceptor` with callbacks in the thread in which the messages are handled. +While a `ChannelInterceptor` is invoked once for each message sent to a channel, the +`ExecutorChannelInterceptor` provides hooks in the thread of each `MessageHandler` +subscribed to messages from the channel. + +Note that, as with the `SessionDisconnectEvent` described earlier, a DISCONNECT message +can be from the client or it can also be automatically generated when +the WebSocket session is closed. In some cases, an interceptor may intercept this +message more than once for each session. Components should be idempotent with regard to +multiple disconnect events. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/message-flow.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/message-flow.adoc new file mode 100644 index 000000000000..275ab0a27bd0 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/message-flow.adoc @@ -0,0 +1,114 @@ +[[websocket-stomp-message-flow]] += Flow of Messages + +Once a STOMP endpoint is exposed, the Spring application becomes a STOMP broker for +connected clients. This section describes the flow of messages on the server side. + +The `spring-messaging` module contains foundational support for messaging applications +that originated in https://spring.io/spring-integration[Spring Integration] and was +later extracted and incorporated into the Spring Framework for broader use across many +https://spring.io/projects[Spring projects] and application scenarios. +The following list briefly describes a few of the available messaging abstractions: + +* {api-spring-framework}/messaging/Message.html[Message]: +Simple representation for a message, including headers and payload. +* {api-spring-framework}/messaging/MessageHandler.html[MessageHandler]: +Contract for handling a message. +* {api-spring-framework}/messaging/MessageChannel.html[MessageChannel]: +Contract for sending a message that enables loose coupling between producers and consumers. +* {api-spring-framework}/messaging/SubscribableChannel.html[SubscribableChannel]: +`MessageChannel` with `MessageHandler` subscribers. +* {api-spring-framework}/messaging/support/ExecutorSubscribableChannel.html[ExecutorSubscribableChannel]: +`SubscribableChannel` that uses an `Executor` for delivering messages. + +Both the Java configuration (that is, `@EnableWebSocketMessageBroker`) and the XML namespace configuration +(that is, ``) use the preceding components to assemble a message +workflow. The following diagram shows the components used when the simple built-in message +broker is enabled: + +image::message-flow-simple-broker.png[] + +The preceding diagram shows three message channels: + +* `clientInboundChannel`: For passing messages received from WebSocket clients. +* `clientOutboundChannel`: For sending server messages to WebSocket clients. +* `brokerChannel`: For sending messages to the message broker from within +server-side application code. + +The next diagram shows the components used when an external broker (such as RabbitMQ) +is configured for managing subscriptions and broadcasting messages: + +image::message-flow-broker-relay.png[] + +The main difference between the two preceding diagrams is the use of the "`broker relay`" for passing +messages up to the external STOMP broker over TCP and for passing messages down from the +broker to subscribed clients. + +When messages are received from a WebSocket connection, they are decoded to STOMP frames, +turned into a Spring `Message` representation, and sent to the +`clientInboundChannel` for further processing. For example, STOMP messages whose +destination headers start with `/app` may be routed to `@MessageMapping` methods in +annotated controllers, while `/topic` and `/queue` messages may be routed directly +to the message broker. + +An annotated `@Controller` that handles a STOMP message from a client may send a message to +the message broker through the `brokerChannel`, and the broker broadcasts the +message to matching subscribers through the `clientOutboundChannel`. The same +controller can also do the same in response to HTTP requests, so a client can perform an +HTTP POST, and then a `@PostMapping` method can send a message to the message broker +to broadcast to subscribed clients. + +We can trace the flow through a simple example. Consider the following example, which sets up a server: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + @Override + public void registerStompEndpoints(StompEndpointRegistry registry) { + registry.addEndpoint("/portfolio"); + } + + @Override + public void configureMessageBroker(MessageBrokerRegistry registry) { + registry.setApplicationDestinationPrefixes("/app"); + registry.enableSimpleBroker("/topic"); + } + } + + @Controller + public class GreetingController { + + @MessageMapping("/greeting") + public String handle(String greeting) { + return "[" + getTimestamp() + ": " + greeting; + } + } +---- + +The preceding example supports the following flow: + +. The client connects to `http://localhost:8080/portfolio` and, once a WebSocket connection +is established, STOMP frames begin to flow on it. +. The client sends a SUBSCRIBE frame with a destination header of `/topic/greeting`. Once received +and decoded, the message is sent to the `clientInboundChannel` and is then routed to the +message broker, which stores the client subscription. +. The client sends a SEND frame to `/app/greeting`. The `/app` prefix helps to route it to +annotated controllers. After the `/app` prefix is stripped, the remaining `/greeting` +part of the destination is mapped to the `@MessageMapping` method in `GreetingController`. +. The value returned from `GreetingController` is turned into a Spring `Message` with +a payload based on the return value and a default destination header of +`/topic/greeting` (derived from the input destination with `/app` replaced by +`/topic`). The resulting message is sent to the `brokerChannel` and handled +by the message broker. +. The message broker finds all matching subscribers and sends a MESSAGE frame to each one +through the `clientOutboundChannel`, from where messages are encoded as STOMP frames +and sent on the WebSocket connection. + +The next section provides more details on annotated methods, including the +kinds of arguments and return values that are supported. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/ordered-messages.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/ordered-messages.adoc new file mode 100644 index 000000000000..17279a243e21 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/ordered-messages.adoc @@ -0,0 +1,51 @@ +[[websocket-stomp-ordered-messages]] += Order of Messages + +Messages from the broker are published to the `clientOutboundChannel`, from where they are +written to WebSocket sessions. As the channel is backed by a `ThreadPoolExecutor`, messages +are processed in different threads, and the resulting sequence received by the client may +not match the exact order of publication. + +If this is an issue, enable the `setPreservePublishOrder` flag, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class MyConfig implements WebSocketMessageBrokerConfigurer { + + @Override + protected void configureMessageBroker(MessageBrokerRegistry registry) { + // ... + registry.setPreservePublishOrder(true); + } + + } +---- + +The following example shows the XML configuration equivalent of the preceding example: + +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + + + +---- + +When the flag is set, messages within the same client session are published to the +`clientOutboundChannel` one at a time, so that the order of publication is guaranteed. +Note that this incurs a small performance overhead, so you should enable it only if it is required. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/overview.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/overview.adoc new file mode 100644 index 000000000000..cf94589ba1d6 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/overview.adoc @@ -0,0 +1,97 @@ +[[websocket-stomp-overview]] += Overview + +https://stomp.github.io/stomp-specification-1.2.html#Abstract[STOMP] (Simple +Text Oriented Messaging Protocol) was originally created for scripting languages +(such as Ruby, Python, and Perl) to connect to enterprise message brokers. It is +designed to address a minimal subset of commonly used messaging patterns. STOMP can be +used over any reliable two-way streaming network protocol, such as TCP and WebSocket. +Although STOMP is a text-oriented protocol, message payloads can be +either text or binary. + +STOMP is a frame-based protocol whose frames are modeled on HTTP. The following listing shows the structure +of a STOMP frame: + +---- +COMMAND +header1:value1 +header2:value2 + +Body^@ +---- + +Clients can use the `SEND` or `SUBSCRIBE` commands to send or subscribe for +messages, along with a `destination` header that describes what the +message is about and who should receive it. This enables a simple +publish-subscribe mechanism that you can use to send messages through the broker +to other connected clients or to send messages to the server to request that +some work be performed. + +When you use Spring's STOMP support, the Spring WebSocket application acts +as the STOMP broker to clients. Messages are routed to `@Controller` message-handling +methods or to a simple in-memory broker that keeps track of subscriptions and +broadcasts messages to subscribed users. You can also configure Spring to work +with a dedicated STOMP broker (such as RabbitMQ, ActiveMQ, and others) for the actual +broadcasting of messages. In that case, Spring maintains +TCP connections to the broker, relays messages to it, and passes messages +from it down to connected WebSocket clients. Thus, Spring web applications can +rely on unified HTTP-based security, common validation, and a familiar programming +model for message handling. + +The following example shows a client subscribing to receive stock quotes, which +the server may emit periodically (for example, via a scheduled task that sends messages +through a `SimpMessagingTemplate` to the broker): + +---- +SUBSCRIBE +id:sub-1 +destination:/topic/price.stock.* + +^@ +---- + +The following example shows a client that sends a trade request, which the server +can handle through an `@MessageMapping` method: + +---- +SEND +destination:/queue/trade +content-type:application/json +content-length:44 + +{"action":"BUY","ticker":"MMM","shares",44}^@ +---- + +After the execution, the server can +broadcast a trade confirmation message and details down to the client. + +The meaning of a destination is intentionally left opaque in the STOMP spec. It can +be any string, and it is entirely up to STOMP servers to define the semantics and +the syntax of the destinations that they support. It is very common, however, for +destinations to be path-like strings where `/topic/..` implies publish-subscribe +(one-to-many) and `/queue/` implies point-to-point (one-to-one) message +exchanges. + +STOMP servers can use the `MESSAGE` command to broadcast messages to all subscribers. +The following example shows a server sending a stock quote to a subscribed client: + +---- +MESSAGE +message-id:nxahklf6-1 +subscription:sub-1 +destination:/topic/price.stock.MMM + +{"ticker":"MMM","price":129.45}^@ +---- + +A server cannot send unsolicited messages. All messages +from a server must be in response to a specific client subscription, and the +`subscription` header of the server message must match the `id` header of the +client subscription. + +The preceding overview is intended to provide the most basic understanding of the +STOMP protocol. We recommended reviewing the protocol +https://stomp.github.io/stomp-specification-1.2.html[specification] in full. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/scope.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/scope.adoc new file mode 100644 index 000000000000..b4300990abe6 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/scope.adoc @@ -0,0 +1,69 @@ +[[websocket-stomp-websocket-scope]] += WebSocket Scope + +Each WebSocket session has a map of attributes. The map is attached as a header to +inbound client messages and may be accessed from a controller method, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- +@Controller +public class MyController { + + @MessageMapping("/action") + public void handle(SimpMessageHeaderAccessor headerAccessor) { + Map attrs = headerAccessor.getSessionAttributes(); + // ... + } +} +---- + +You can declare a Spring-managed bean in the `websocket` scope. +You can inject WebSocket-scoped beans into controllers and any channel interceptors +registered on the `clientInboundChannel`. Those are typically singletons and live +longer than any individual WebSocket session. Therefore, you need to use a +scope proxy mode for WebSocket-scoped beans, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Component + @Scope(scopeName = "websocket", proxyMode = ScopedProxyMode.TARGET_CLASS) + public class MyBean { + + @PostConstruct + public void init() { + // Invoked after dependencies injected + } + + // ... + + @PreDestroy + public void destroy() { + // Invoked when the WebSocket session ends + } + } + + @Controller + public class MyController { + + private final MyBean myBean; + + @Autowired + public MyController(MyBean myBean) { + this.myBean = myBean; + } + + @MessageMapping("/action") + public void handle() { + // this.myBean from the current WebSocket session + } + } +---- + +As with any custom scope, Spring initializes a new `MyBean` instance the first +time it is accessed from the controller and stores the instance in the WebSocket +session attributes. The same instance is subsequently returned until the session +ends. WebSocket-scoped beans have all Spring lifecycle methods invoked, as +shown in the preceding examples. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc new file mode 100644 index 000000000000..119db2b62b91 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc @@ -0,0 +1,33 @@ +[[websocket-stomp-server-config]] += WebSocket Server + +To configure the underlying WebSocket server, the information in +<> applies. For Jetty, however you need to set +the `HandshakeHandler` and `WebSocketPolicy` through the `StompEndpointRegistry`: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Configuration + @EnableWebSocketMessageBroker + public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { + + @Override + public void registerStompEndpoints(StompEndpointRegistry registry) { + registry.addEndpoint("/portfolio").setHandshakeHandler(handshakeHandler()); + } + + @Bean + public DefaultHandshakeHandler handshakeHandler() { + + WebSocketPolicy policy = new WebSocketPolicy(WebSocketBehavior.SERVER); + policy.setInputBufferSize(8192); + policy.setIdleTimeout(600000); + + return new DefaultHandshakeHandler( + new JettyRequestUpgradeStrategy(new WebSocketServerFactory(policy))); + } + } +---- + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/stats.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/stats.adoc new file mode 100644 index 000000000000..107f353fd425 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/stats.adoc @@ -0,0 +1,59 @@ +[[websocket-stomp-stats]] += Monitoring + +When you use `@EnableWebSocketMessageBroker` or ``, key +infrastructure components automatically gather statistics and counters that provide +important insight into the internal state of the application. The configuration +also declares a bean of type `WebSocketMessageBrokerStats` that gathers all +available information in one place and by default logs it at the `INFO` level once +every 30 minutes. This bean can be exported to JMX through Spring's +`MBeanExporter` for viewing at runtime (for example, through JDK's `jconsole`). +The following list summarizes the available information: + +Client WebSocket Sessions:: + Current::: Indicates how many client sessions there are + currently, with the count further broken down by WebSocket versus HTTP + streaming and polling SockJS sessions. + Total::: Indicates how many total sessions have been established. + Abnormally Closed::: + Connect Failures:::: Sessions that got established but were + closed after not having received any messages within 60 seconds. This is + usually an indication of proxy or network issues. + Send Limit Exceeded:::: Sessions closed after exceeding the configured send + timeout or the send buffer limits, which can occur with slow clients + (see previous section). + Transport Errors:::: Sessions closed after a transport error, such as + failure to read or write to a WebSocket connection or + HTTP request or response. + STOMP Frames::: The total number of CONNECT, CONNECTED, and DISCONNECT frames + processed, indicating how many clients connected on the STOMP level. Note that + the DISCONNECT count may be lower when sessions get closed abnormally or when + clients close without sending a DISCONNECT frame. +STOMP Broker Relay:: + TCP Connections::: Indicates how many TCP connections on behalf of client + WebSocket sessions are established to the broker. This should be equal to the + number of client WebSocket sessions + 1 additional shared "`system`" connection + for sending messages from within the application. + STOMP Frames::: The total number of CONNECT, CONNECTED, and DISCONNECT frames + forwarded to or received from the broker on behalf of clients. Note that a + DISCONNECT frame is sent to the broker regardless of how the client WebSocket + session was closed. Therefore, a lower DISCONNECT frame count is an indication + that the broker is pro-actively closing connections (maybe because of a + heartbeat that did not arrive in time, an invalid input frame, or other issue). +Client Inbound Channel:: Statistics from the thread pool that backs the `clientInboundChannel` + that provide insight into the health of incoming message processing. Tasks queueing + up here is an indication that the application may be too slow to handle messages. + If there I/O bound tasks (for example, slow database queries, HTTP requests to third party + REST API, and so on), consider increasing the thread pool size. +Client Outbound Channel:: Statistics from the thread pool that backs the `clientOutboundChannel` + that provides insight into the health of broadcasting messages to clients. Tasks + queueing up here is an indication clients are too slow to consume messages. + One way to address this is to increase the thread pool size to accommodate the + expected number of concurrent slow clients. Another option is to reduce the + send timeout and send buffer size limits (see the previous section). +SockJS Task Scheduler:: Statistics from the thread pool of the SockJS task scheduler that + is used to send heartbeats. Note that, when heartbeats are negotiated on the + STOMP level, the SockJS heartbeats are disabled. + + + diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/testing.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/testing.adoc new file mode 100644 index 000000000000..33ed3f6a7e0c --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/testing.adoc @@ -0,0 +1,41 @@ +[[websocket-stomp-testing]] += Testing + +There are two main approaches to testing applications when you use Spring's STOMP-over-WebSocket +support. The first is to write server-side tests to verify the functionality +of controllers and their annotated message-handling methods. The second is to write +full end-to-end tests that involve running a client and a server. + +The two approaches are not mutually exclusive. On the contrary, each has a place +in an overall test strategy. Server-side tests are more focused and easier to write +and maintain. End-to-end integration tests, on the other hand, are more complete and +test much more, but they are also more involved to write and maintain. + +The simplest form of server-side tests is to write controller unit tests. However, +this is not useful enough, since much of what a controller does depends on its +annotations. Pure unit tests simply cannot test that. + +Ideally, controllers under test should be invoked as they are at runtime, much like +the approach to testing controllers that handle HTTP requests by using the Spring MVC Test +framework -- that is, without running a Servlet container but relying on the Spring Framework +to invoke the annotated controllers. As with Spring MVC Test, you have two +possible alternatives here, either use a "`context-based`" or use a "`standalone`" setup: + +* Load the actual Spring configuration with the help of the +Spring TestContext framework, inject `clientInboundChannel` as a test field, and +use it to send messages to be handled by controller methods. + +* Manually set up the minimum Spring framework infrastructure required to invoke +controllers (namely the `SimpAnnotationMethodMessageHandler`) and pass messages for +controllers directly to it. + +Both of these setup scenarios are demonstrated in the +https://github.com/rstoyanchev/spring-websocket-portfolio/tree/master/src/test/java/org/springframework/samples/portfolio/web[tests for the stock portfolio] +sample application. + +The second approach is to create end-to-end integration tests. For that, you need +to run a WebSocket server in embedded mode and connect to it as a WebSocket client +that sends WebSocket messages containing STOMP frames. +The https://github.com/rstoyanchev/spring-websocket-portfolio/tree/master/src/test/java/org/springframework/samples/portfolio/web[tests for the stock portfolio] +sample application also demonstrate this approach by using Tomcat as the embedded +WebSocket server and a simple STOMP client for test purposes. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc new file mode 100644 index 000000000000..7dd0ceb1189a --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc @@ -0,0 +1,117 @@ +[[websocket-stomp-user-destination]] += User Destinations + +An application can send messages that target a specific user, and Spring's STOMP support +recognizes destinations prefixed with `/user/` for this purpose. +For example, a client might subscribe to the `/user/queue/position-updates` destination. +`UserDestinationMessageHandler` handles this destination and transforms it into a +destination unique to the user session (such as `/queue/position-updates-user123`). +This provides the convenience of subscribing to a generically named destination while, +at the same time, ensuring no collisions with other users who subscribe to the same +destination so that each user can receive unique stock position updates. + +TIP: When working with user destinations, it is important to configure broker and +application destination prefixes as shown in <>, or otherwise the +broker would handle "/user" prefixed messages that should only be handled by +`UserDestinationMessageHandler`. + +On the sending side, messages can be sent to a destination such as +pass:q[`/user/{username}/queue/position-updates`], which in turn is translated +by the `UserDestinationMessageHandler` into one or more destinations, one for each +session associated with the user. This lets any component within the application +send messages that target a specific user without necessarily knowing anything more +than their name and the generic destination. This is also supported through an +annotation and a messaging template. + +A message-handling method can send messages to the user associated with +the message being handled through the `@SendToUser` annotation (also supported on +the class-level to share a common destination), as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Controller + public class PortfolioController { + + @MessageMapping("/trade") + @SendToUser("/queue/position-updates") + public TradeResult executeTrade(Trade trade, Principal principal) { + // ... + return tradeResult; + } + } +---- + +If the user has more than one session, by default, all of the sessions subscribed +to the given destination are targeted. However, sometimes, it may be necessary to +target only the session that sent the message being handled. You can do so by +setting the `broadcast` attribute to false, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @Controller + public class MyController { + + @MessageMapping("/action") + public void handleAction() throws Exception{ + // raise MyBusinessException here + } + + @MessageExceptionHandler + @SendToUser(destinations="/queue/errors", broadcast=false) + public ApplicationError handleException(MyBusinessException exception) { + // ... + return appError; + } + } +---- + +NOTE: While user destinations generally imply an authenticated user, it is not strictly required. +A WebSocket session that is not associated with an authenticated user +can subscribe to a user destination. In such cases, the `@SendToUser` annotation +behaves exactly the same as with `broadcast=false` (that is, targeting only the +session that sent the message being handled). + +You can send a message to user destinations from any application +component by, for example, injecting the `SimpMessagingTemplate` created by the Java configuration or +the XML namespace. (The bean name is `brokerMessagingTemplate` if required +for qualification with `@Qualifier`.) The following example shows how to do so: + +[source,java,indent=0,subs="verbatim,quotes"] +---- +@Service +public class TradeServiceImpl implements TradeService { + + private final SimpMessagingTemplate messagingTemplate; + + @Autowired + public TradeServiceImpl(SimpMessagingTemplate messagingTemplate) { + this.messagingTemplate = messagingTemplate; + } + + // ... + + public void afterTradeExecuted(Trade trade) { + this.messagingTemplate.convertAndSendToUser( + trade.getUserName(), "/queue/position-updates", trade.getResult()); + } +} +---- + +NOTE: When you use user destinations with an external message broker, you should check the broker +documentation on how to manage inactive queues, so that, when the user session is +over, all unique user queues are removed. For example, RabbitMQ creates auto-delete +queues when you use destinations such as `/exchange/amq.direct/position-updates`. +So, in that case, the client could subscribe to `/user/exchange/amq.direct/position-updates`. +Similarly, ActiveMQ has +https://activemq.apache.org/delete-inactive-destinations.html[configuration options] +for purging inactive destinations. + +In a multi-application server scenario, a user destination may remain unresolved because +the user is connected to a different server. In such cases, you can configure a +destination to broadcast unresolved messages so that other servers have a chance to try. +This can be done through the `userDestinationBroadcast` property of the +`MessageBrokerRegistry` in Java configuration and the `user-destination-broadcast` attribute +of the `message-broker` element in XML. + + + From 385800e250c8b1716573ba0b41fdd4fe03cd8c1c Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:26:16 -0500 Subject: [PATCH 12/31] Generate a default navigation --- framework-docs/modules/ROOT/nav.adoc | 436 +++++++++++++++++++++++++++ 1 file changed, 436 insertions(+) create mode 100644 framework-docs/modules/ROOT/nav.adoc diff --git a/framework-docs/modules/ROOT/nav.adoc b/framework-docs/modules/ROOT/nav.adoc new file mode 100644 index 000000000000..770eb6a3d7fd --- /dev/null +++ b/framework-docs/modules/ROOT/nav.adoc @@ -0,0 +1,436 @@ +* xref:index.adoc[] +* xref:attributes.adoc[] +* xref:overview.adoc[] +* xref:core.adoc[] +* xref:page-layout.adoc[] +** xref:core/beans.adoc[] +*** xref:core/beans/introduction.adoc[] +*** xref:core/beans/basics.adoc[] +*** xref:core/beans/definition.adoc[] +*** xref:core/beans/dependencies.adoc[] +**** xref:core/beans/dependencies/factory-collaborators.adoc[] +**** xref:core/beans/dependencies/factory-properties-detailed.adoc[] +**** xref:core/beans/dependencies/factory-dependson.adoc[] +**** xref:core/beans/dependencies/factory-lazy-init.adoc[] +**** xref:core/beans/dependencies/factory-autowire.adoc[] +**** xref:core/beans/dependencies/factory-method-injection.adoc[] +*** xref:core/beans/factory-scopes.adoc[] +*** xref:core/beans/factory-nature.adoc[] +*** xref:core/beans/child-bean-definitions.adoc[] +*** xref:core/beans/factory-extension.adoc[] +*** xref:core/beans/annotation-config.adoc[] +**** xref:core/beans/annotation-config/autowired.adoc[] +**** xref:core/beans/annotation-config/autowired-primary.adoc[] +**** xref:core/beans/annotation-config/autowired-qualifiers.adoc[] +**** xref:core/beans/annotation-config/generics-as-qualifiers.adoc[] +**** xref:core/beans/annotation-config/custom-autowire-configurer.adoc[] +**** xref:core/beans/annotation-config/resource.adoc[] +**** xref:core/beans/annotation-config/value-annotations.adoc[] +**** xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[] +*** xref:core/beans/classpath-scanning.adoc[] +*** xref:core/beans/standard-annotations.adoc[] +*** xref:core/beans/java.adoc[] +**** xref:core/beans/java/basic-concepts.adoc[] +**** xref:core/beans/java/instantiating-container.adoc[] +**** xref:core/beans/java/bean-annotation.adoc[] +**** xref:core/beans/java/configuration-annotation.adoc[] +**** xref:core/beans/java/composing-configuration-classes.adoc[] +*** xref:core/beans/environment.adoc[] +*** xref:core/beans/context-load-time-weaver.adoc[] +*** xref:core/beans/context-introduction.adoc[] +*** xref:core/beans/beanfactory.adoc[] +** xref:core/resources.adoc[] +** xref:core/validation.adoc[] +*** xref:core/validation/validator.adoc[] +*** xref:core/validation/conversion.adoc[] +*** xref:core/validation/beans-beans.adoc[] +*** xref:core/validation/convert.adoc[] +*** xref:core/validation/format.adoc[] +*** xref:core/validation/format-configuring-formatting-globaldatetimeformat.adoc[] +*** xref:core/validation/beanvalidation.adoc[] +** xref:core/expressions.adoc[] +*** xref:core/expressions/evaluation.adoc[] +*** xref:core/expressions/beandef.adoc[] +*** xref:core/expressions/language-ref.adoc[] +**** xref:core/expressions/language-ref/literal.adoc[] +**** xref:core/expressions/language-ref/properties-arrays.adoc[] +**** xref:core/expressions/language-ref/inline-lists.adoc[] +**** xref:core/expressions/language-ref/inline-maps.adoc[] +**** xref:core/expressions/language-ref/array-construction.adoc[] +**** xref:core/expressions/language-ref/methods.adoc[] +**** xref:core/expressions/language-ref/operators.adoc[] +**** xref:core/expressions/language-ref/types.adoc[] +**** xref:core/expressions/language-ref/constructors.adoc[] +**** xref:core/expressions/language-ref/variables.adoc[] +**** xref:core/expressions/language-ref/functions.adoc[] +**** xref:core/expressions/language-ref/bean-references.adoc[] +**** xref:core/expressions/language-ref/operator-ternary.adoc[] +**** xref:core/expressions/language-ref/operator-elvis.adoc[] +**** xref:core/expressions/language-ref/operator-safe-navigation.adoc[] +**** xref:core/expressions/language-ref/collection-selection.adoc[] +**** xref:core/expressions/language-ref/collection-projection.adoc[] +**** xref:core/expressions/language-ref/templating.adoc[] +*** xref:core/expressions/example-classes.adoc[] +** xref:core/aop.adoc[] +*** xref:core/aop/introduction-defn.adoc[] +*** xref:core/aop/introduction-spring-defn.adoc[] +*** xref:core/aop/introduction-proxies.adoc[] +*** xref:core/aop/ataspectj.adoc[] +**** xref:core/aop/ataspectj/aspectj-support.adoc[] +**** xref:core/aop/ataspectj/at-aspectj.adoc[] +**** xref:core/aop/ataspectj/pointcuts.adoc[] +**** xref:core/aop/ataspectj/advice.adoc[] +**** xref:core/aop/ataspectj/introductions.adoc[] +**** xref:core/aop/ataspectj/instantiation-models.adoc[] +**** xref:core/aop/ataspectj/example.adoc[] +*** xref:core/aop/schema.adoc[] +*** xref:core/aop/choosing.adoc[] +*** xref:core/aop/mixing-styles.adoc[] +*** xref:core/aop/proxying.adoc[] +*** xref:core/aop/aspectj-programmatic.adoc[] +*** xref:core/aop/using-aspectj.adoc[] +*** xref:core/aop/resources.adoc[] +** xref:core/aop-api.adoc[] +*** xref:core/aop-api/pointcuts.adoc[] +*** xref:core/aop-api/advice.adoc[] +*** xref:core/aop-api/advisor.adoc[] +*** xref:core/aop-api/pfb.adoc[] +*** xref:core/aop-api/concise-proxy.adoc[] +*** xref:core/aop-api/prog.adoc[] +*** xref:core/aop-api/advised.adoc[] +*** xref:core/aop-api/autoproxy.adoc[] +*** xref:core/aop-api/targetsource.adoc[] +*** xref:core/aop-api/extensibility.adoc[] +** xref:core/null-safety.adoc[] +** xref:core/databuffer-codec.adoc[] +** xref:core/spring-jcl.adoc[] +** xref:core/aot.adoc[] +** xref:core/appendix.adoc[] +*** xref:core/appendix/xsd-schemas.adoc[] +*** xref:core/appendix/xml-custom.adoc[] +*** xref:core/appendix/application-startup-steps.adoc[] +* xref:testing.adoc[] +** xref:testing/introduction.adoc[] +** xref:testing/unit.adoc[] +** xref:testing/integration.adoc[] +** xref:testing/support-jdbc.adoc[] +** xref:testing/testcontext-framework.adoc[] +*** xref:testing/testcontext-framework/key-abstractions.adoc[] +*** xref:testing/testcontext-framework/bootstrapping.adoc[] +*** xref:testing/testcontext-framework/tel-config.adoc[] +*** xref:testing/testcontext-framework/application-events.adoc[] +*** xref:testing/testcontext-framework/test-execution-events.adoc[] +*** xref:testing/testcontext-framework/ctx-management.adoc[] +**** xref:testing/testcontext-framework/ctx-management/xml.adoc[] +**** xref:testing/testcontext-framework/ctx-management/groovy.adoc[] +**** xref:testing/testcontext-framework/ctx-management/javaconfig.adoc[] +**** xref:testing/testcontext-framework/ctx-management/mixed-config.adoc[] +**** xref:testing/testcontext-framework/ctx-management/initializers.adoc[] +**** xref:testing/testcontext-framework/ctx-management/inheritance.adoc[] +**** xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[] +**** xref:testing/testcontext-framework/ctx-management/property-sources.adoc[] +**** xref:testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc[] +**** xref:testing/testcontext-framework/ctx-management/web.adoc[] +**** xref:testing/testcontext-framework/ctx-management/web-mocks.adoc[] +**** xref:testing/testcontext-framework/ctx-management/caching.adoc[] +**** xref:testing/testcontext-framework/ctx-management/hierarchies.adoc[] +*** xref:testing/testcontext-framework/fixture-di.adoc[] +*** xref:testing/testcontext-framework/web-scoped-beans.adoc[] +*** xref:testing/testcontext-framework/tx.adoc[] +*** xref:testing/testcontext-framework/executing-sql.adoc[] +*** xref:testing/testcontext-framework/parallel-test-execution.adoc[] +*** xref:testing/testcontext-framework/support-classes.adoc[] +*** xref:testing/testcontext-framework/aot.adoc[] +** xref:testing/webtestclient.adoc[] +** xref:testing/spring-mvc-test-framework.adoc[] +*** xref:testing/spring-mvc-test-framework/server.adoc[] +*** xref:testing/spring-mvc-test-framework/server-static-imports.adoc[] +*** xref:testing/spring-mvc-test-framework/server-setup-options.adoc[] +*** xref:testing/spring-mvc-test-framework/server-setup-steps.adoc[] +*** xref:testing/spring-mvc-test-framework/server-performing-requests.adoc[] +*** xref:testing/spring-mvc-test-framework/server-defining-expectations.adoc[] +*** xref:testing/spring-mvc-test-framework/async-requests.adoc[] +*** xref:testing/spring-mvc-test-framework/vs-streaming-response.adoc[] +*** xref:testing/spring-mvc-test-framework/server-filters.adoc[] +*** xref:testing/spring-mvc-test-framework/vs-end-to-end-integration-tests.adoc[] +*** xref:testing/spring-mvc-test-framework/server-resources.adoc[] +*** xref:testing/spring-mvc-test-framework/server-htmlunit.adoc[] +**** xref:testing/spring-mvc-test-framework/server-htmlunit/why.adoc[] +**** xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc[] +**** xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc[] +**** xref:testing/spring-mvc-test-framework/server-htmlunit/geb.adoc[] +** xref:testing/spring-mvc-test-client.adoc[] +** xref:testing/appendix.adoc[] +** xref:testing/annotations.adoc[] +*** xref:testing/annotations/integration-standard.adoc[] +*** xref:testing/annotations/integration-spring.adoc[] +**** xref:testing/annotations/integration-spring/annotation-bootstrapwith.adoc[] +**** xref:testing/annotations/integration-spring/annotation-contextconfiguration.adoc[] +**** xref:testing/annotations/integration-spring/annotation-webappconfiguration.adoc[] +**** xref:testing/annotations/integration-spring/annotation-contexthierarchy.adoc[] +**** xref:testing/annotations/integration-spring/annotation-activeprofiles.adoc[] +**** xref:testing/annotations/integration-spring/annotation-testpropertysource.adoc[] +**** xref:testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc[] +**** xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[] +**** xref:testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc[] +**** xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[] +**** xref:testing/annotations/integration-spring/annotation-commit.adoc[] +**** xref:testing/annotations/integration-spring/annotation-rollback.adoc[] +**** xref:testing/annotations/integration-spring/annotation-beforetransaction.adoc[] +**** xref:testing/annotations/integration-spring/annotation-aftertransaction.adoc[] +**** xref:testing/annotations/integration-spring/annotation-sql.adoc[] +**** xref:testing/annotations/integration-spring/annotation-sqlconfig.adoc[] +**** xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[] +**** xref:testing/annotations/integration-spring/annotation-sqlgroup.adoc[] +*** xref:testing/annotations/integration-junit4.adoc[] +*** xref:testing/annotations/integration-junit-jupiter.adoc[] +*** xref:testing/annotations/integration-meta.adoc[] +** xref:testing/resources.adoc[] +* xref:data-access.adoc[] +** xref:data-access/transaction.adoc[] +*** xref:data-access/transaction/motivation.adoc[] +*** xref:data-access/transaction/strategies.adoc[] +*** xref:data-access/transaction/tx-resource-synchronization.adoc[] +*** xref:data-access/transaction/declarative.adoc[] +**** xref:data-access/transaction/declarative/tx-decl-explained.adoc[] +**** xref:data-access/transaction/declarative/first-example.adoc[] +**** xref:data-access/transaction/declarative/rolling-back.adoc[] +**** xref:data-access/transaction/declarative/diff-tx.adoc[] +**** xref:data-access/transaction/declarative/txadvice-settings.adoc[] +**** xref:data-access/transaction/declarative/annotations.adoc[] +**** xref:data-access/transaction/declarative/tx-propagation.adoc[] +**** xref:data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc[] +**** xref:data-access/transaction/declarative/aspectj.adoc[] +*** xref:data-access/transaction/programmatic.adoc[] +*** xref:data-access/transaction/tx-decl-vs-prog.adoc[] +*** xref:data-access/transaction/event.adoc[] +*** xref:data-access/transaction/application-server-integration.adoc[] +*** xref:data-access/transaction/solutions-to-common-problems.adoc[] +*** xref:data-access/transaction/resources.adoc[] +** xref:data-access/dao.adoc[] +** xref:data-access/jdbc.adoc[] +*** xref:data-access/jdbc/choose-style.adoc[] +*** xref:data-access/jdbc/packages.adoc[] +*** xref:data-access/jdbc/core.adoc[] +*** xref:data-access/jdbc/connections.adoc[] +*** xref:data-access/jdbc/advanced.adoc[] +*** xref:data-access/jdbc/simple.adoc[] +*** xref:data-access/jdbc/object.adoc[] +*** xref:data-access/jdbc/parameter-handling.adoc[] +*** xref:data-access/jdbc/embedded-database-support.adoc[] +*** xref:data-access/jdbc/initializing-datasource.adoc[] +** xref:data-access/r2dbc.adoc[] +** xref:data-access/orm.adoc[] +*** xref:data-access/orm/introduction.adoc[] +*** xref:data-access/orm/general.adoc[] +*** xref:data-access/orm/hibernate.adoc[] +*** xref:data-access/orm/jpa.adoc[] +** xref:data-access/oxm.adoc[] +** xref:data-access/appendix.adoc[] +* xref:web.adoc[] +** xref:web/webmvc.adoc[] +*** xref:web/webmvc/mvc-servlet.adoc[] +**** xref:web/webmvc/mvc-servlet/context-hierarchy.adoc[] +**** xref:web/webmvc/mvc-servlet/special-bean-types.adoc[] +**** xref:web/webmvc/mvc-servlet/config.adoc[] +**** xref:web/webmvc/mvc-servlet/container-config.adoc[] +**** xref:web/webmvc/mvc-servlet/sequence.adoc[] +**** xref:web/webmvc/mvc-servlet/handlermapping-path.adoc[] +**** xref:web/webmvc/mvc-servlet/handlermapping-interceptor.adoc[] +**** xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[] +**** xref:web/webmvc/mvc-servlet/viewresolver.adoc[] +**** xref:web/webmvc/mvc-servlet/localeresolver.adoc[] +**** xref:web/webmvc/mvc-servlet/themeresolver.adoc[] +**** xref:web/webmvc/mvc-servlet/multipart.adoc[] +**** xref:web/webmvc/mvc-servlet/logging.adoc[] +*** xref:web/webmvc/filters.adoc[] +*** xref:web/webmvc/mvc-controller.adoc[] +**** xref:web/webmvc/mvc-controller/ann.adoc[] +**** xref:web/webmvc/mvc-controller/ann-requestmapping.adoc[] +**** xref:web/webmvc/mvc-controller/ann-methods.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/arguments.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/return-types.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/requestparam.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/requestheader.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/cookievalue.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/requestattrib.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/httpentity.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/responseentity.adoc[] +***** xref:web/webmvc/mvc-controller/ann-methods/jackson.adoc[] +**** xref:web/webmvc/mvc-controller/ann-modelattrib-methods.adoc[] +**** xref:web/webmvc/mvc-controller/ann-initbinder.adoc[] +**** xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc[] +**** xref:web/webmvc/mvc-controller/ann-advice.adoc[] +*** xref:web/webmvc/mvc-uri-building.adoc[] +*** xref:web/webmvc/mvc-ann-async.adoc[] +*** xref:web/webmvc/mvc-ann-rest-exceptions.adoc[] +*** xref:web/webmvc/mvc-security.adoc[] +*** xref:web/webmvc/mvc-caching.adoc[] +*** xref:web/webmvc/mvc-config.adoc[] +**** xref:web/webmvc/mvc-config/enable.adoc[] +**** xref:web/webmvc/mvc-config/customize.adoc[] +**** xref:web/webmvc/mvc-config/conversion.adoc[] +**** xref:web/webmvc/mvc-config/validation.adoc[] +**** xref:web/webmvc/mvc-config/interceptors.adoc[] +**** xref:web/webmvc/mvc-config/content-negotiation.adoc[] +**** xref:web/webmvc/mvc-config/message-converters.adoc[] +**** xref:web/webmvc/mvc-config/view-controller.adoc[] +**** xref:web/webmvc/mvc-config/view-resolvers.adoc[] +**** xref:web/webmvc/mvc-config/static-resources.adoc[] +**** xref:web/webmvc/mvc-config/default-servlet-handler.adoc[] +**** xref:web/webmvc/mvc-config/path-matching.adoc[] +**** xref:web/webmvc/mvc-config/advanced-java.adoc[] +**** xref:web/webmvc/mvc-config/advanced-xml.adoc[] +*** xref:web/webmvc/mvc-http2.adoc[] +** xref:web/web-data-binding-model-design.adoc[] +** xref:web/webmvc-functional.adoc[] +** xref:web/web-uris.adoc[] +** xref:web/webmvc-cors.adoc[] +** xref:web/webmvc-view.adoc[] +*** xref:web/webmvc-view/mvc-thymeleaf.adoc[] +*** xref:web/webmvc-view/mvc-freemarker.adoc[] +*** xref:web/webmvc-view/mvc-groovymarkup.adoc[] +*** xref:web/webmvc-view/mvc-script.adoc[] +*** xref:web/webmvc-view/mvc-jsp.adoc[] +*** xref:web/webmvc-view/mvc-feeds.adoc[] +*** xref:web/webmvc-view/mvc-document.adoc[] +*** xref:web/webmvc-view/mvc-jackson.adoc[] +*** xref:web/webmvc-view/mvc-xml-marshalling.adoc[] +*** xref:web/webmvc-view/mvc-xslt.adoc[] +** xref:web/webmvc-client.adoc[] +** xref:web/webmvc-test.adoc[] +** xref:web/websocket.adoc[] +*** xref:web/websocket/server.adoc[] +*** xref:web/websocket/fallback.adoc[] +*** xref:web/websocket/stomp.adoc[] +**** xref:web/websocket/stomp/overview.adoc[] +**** xref:web/websocket/stomp/benefits.adoc[] +**** xref:web/websocket/stomp/enable.adoc[] +**** xref:web/websocket/stomp/server-config.adoc[] +**** xref:web/websocket/stomp/message-flow.adoc[] +**** xref:web/websocket/stomp/handle-annotations.adoc[] +**** xref:web/websocket/stomp/handle-send.adoc[] +**** xref:web/websocket/stomp/handle-simple-broker.adoc[] +**** xref:web/websocket/stomp/handle-broker-relay.adoc[] +**** xref:web/websocket/stomp/handle-broker-relay-configure.adoc[] +**** xref:web/websocket/stomp/destination-separator.adoc[] +**** xref:web/websocket/stomp/authentication.adoc[] +**** xref:web/websocket/stomp/authentication-token-based.adoc[] +**** xref:web/websocket/stomp/authorization.adoc[] +**** xref:web/websocket/stomp/user-destination.adoc[] +**** xref:web/websocket/stomp/ordered-messages.adoc[] +**** xref:web/websocket/stomp/application-context-events.adoc[] +**** xref:web/websocket/stomp/interceptors.adoc[] +**** xref:web/websocket/stomp/client.adoc[] +**** xref:web/websocket/stomp/scope.adoc[] +**** xref:web/websocket/stomp/configuration-performance.adoc[] +**** xref:web/websocket/stomp/stats.adoc[] +**** xref:web/websocket/stomp/testing.adoc[] +** xref:web/websocket-intro.adoc[] +** xref:web/integration.adoc[] +* xref:web-reactive.adoc[] +** xref:web/webflux.adoc[] +*** xref:web/webflux/new-framework.adoc[] +*** xref:web/webflux/reactive-spring.adoc[] +*** xref:web/webflux/dispatcher-handler.adoc[] +*** xref:web/webflux/controller.adoc[] +**** xref:web/webflux/controller/ann.adoc[] +**** xref:web/webflux/controller/ann-requestmapping.adoc[] +**** xref:web/webflux/controller/ann-methods.adoc[] +***** xref:web/webflux/controller/ann-methods/arguments.adoc[] +***** xref:web/webflux/controller/ann-methods/return-types.adoc[] +***** xref:web/webflux/controller/ann-methods/typeconversion.adoc[] +***** xref:web/webflux/controller/ann-methods/matrix-variables.adoc[] +***** xref:web/webflux/controller/ann-methods/requestparam.adoc[] +***** xref:web/webflux/controller/ann-methods/requestheader.adoc[] +***** xref:web/webflux/controller/ann-methods/cookievalue.adoc[] +***** xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[] +***** xref:web/webflux/controller/ann-methods/sessionattributes.adoc[] +***** xref:web/webflux/controller/ann-methods/sessionattribute.adoc[] +***** xref:web/webflux/controller/ann-methods/requestattrib.adoc[] +***** xref:web/webflux/controller/ann-methods/multipart-forms.adoc[] +***** xref:web/webflux/controller/ann-methods/requestbody.adoc[] +***** xref:web/webflux/controller/ann-methods/httpentity.adoc[] +***** xref:web/webflux/controller/ann-methods/responsebody.adoc[] +***** xref:web/webflux/controller/ann-methods/responseentity.adoc[] +***** xref:web/webflux/controller/ann-methods/jackson.adoc[] +**** xref:web/webflux/controller/ann-modelattrib-methods.adoc[] +**** xref:web/webflux/controller/ann-initbinder.adoc[] +**** xref:web/webflux/controller/ann-exceptions.adoc[] +**** xref:web/webflux/controller/ann-advice.adoc[] +*** xref:web/webflux/uri-building.adoc[] +*** xref:web/webflux/ann-rest-exceptions.adoc[] +*** xref:web/webflux/security.adoc[] +*** xref:web/webflux/caching.adoc[] +*** xref:web/webflux/config.adoc[] +*** xref:web/webflux/http2.adoc[] +** xref:web/webflux-functional.adoc[] +** xref:web/webflux-cors.adoc[] +** xref:web/webflux-view.adoc[] +** xref:web/webflux-webclient.adoc[] +*** xref:web/webflux-webclient/client-builder.adoc[] +*** xref:web/webflux-webclient/client-retrieve.adoc[] +*** xref:web/webflux-webclient/client-exchange.adoc[] +*** xref:web/webflux-webclient/client-body.adoc[] +*** xref:web/webflux-webclient/client-filter.adoc[] +*** xref:web/webflux-webclient/client-attributes.adoc[] +*** xref:web/webflux-webclient/client-context.adoc[] +*** xref:web/webflux-webclient/client-synchronous.adoc[] +*** xref:web/webflux-webclient/client-testing.adoc[] +** xref:web/webflux-websocket.adoc[] +* xref:rsocket.adoc[] +* xref:integration.adoc[] +** xref:integration/rest-clients.adoc[] +** xref:integration/jms.adoc[] +*** xref:integration/jms/using.adoc[] +*** xref:integration/jms/sending.adoc[] +*** xref:integration/jms/receiving.adoc[] +*** xref:integration/jms/jca-message-endpoint-manager.adoc[] +*** xref:integration/jms/annotated.adoc[] +*** xref:integration/jms/namespace.adoc[] +** xref:integration/jmx.adoc[] +*** xref:integration/jmx/exporting.adoc[] +*** xref:integration/jmx/interface.adoc[] +*** xref:integration/jmx/naming.adoc[] +*** xref:integration/jmx/jsr160.adoc[] +*** xref:integration/jmx/proxy.adoc[] +*** xref:integration/jmx/notifications.adoc[] +*** xref:integration/jmx/resources.adoc[] +** xref:integration/email.adoc[] +** xref:integration/scheduling.adoc[] +** xref:integration/cache.adoc[] +*** xref:integration/cache/strategies.adoc[] +*** xref:integration/cache/annotations.adoc[] +*** xref:integration/cache/jsr-107.adoc[] +*** xref:integration/cache/declarative-xml.adoc[] +*** xref:integration/cache/store-configuration.adoc[] +*** xref:integration/cache/plug.adoc[] +*** xref:integration/cache/specific-config.adoc[] +** xref:integration/observability.adoc[] +** xref:integration/appendix.adoc[] +* xref:languages.adoc[] +** xref:languages/kotlin.adoc[] +*** xref:languages/kotlin/requirements.adoc[] +*** xref:languages/kotlin/extensions.adoc[] +*** xref:languages/kotlin/null-safety.adoc[] +*** xref:languages/kotlin/classes-interfaces.adoc[] +*** xref:languages/kotlin/annotations.adoc[] +*** xref:languages/kotlin/bean-definition-dsl.adoc[] +*** xref:languages/kotlin/web.adoc[] +*** xref:languages/kotlin/coroutines.adoc[] +*** xref:languages/kotlin/spring-projects-in.adoc[] +*** xref:languages/kotlin/getting-started.adoc[] +*** xref:languages/kotlin/resources.adoc[] +** xref:languages/groovy.adoc[] +** xref:languages/dynamic.adoc[] +* xref:appendix.adoc[] From 3b68f5ee2bffcd3c7ba9e7f128413deca65a1662 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:26:17 -0500 Subject: [PATCH 13/31] Remove includes --- framework-docs/modules/ROOT/pages/appendix.adoc | 2 -- framework-docs/modules/ROOT/pages/core.adoc | 13 ------------- framework-docs/modules/ROOT/pages/data-access.adoc | 2 -- framework-docs/modules/ROOT/pages/index.adoc | 1 - framework-docs/modules/ROOT/pages/integration.adoc | 10 ---------- framework-docs/modules/ROOT/pages/languages.adoc | 5 ----- framework-docs/modules/ROOT/pages/overview.adoc | 1 - framework-docs/modules/ROOT/pages/rsocket.adoc | 2 -- framework-docs/modules/ROOT/pages/testing.adoc | 11 ----------- .../modules/ROOT/pages/testing/appendix.adoc | 2 -- framework-docs/modules/ROOT/pages/web-reactive.adoc | 6 ------ framework-docs/modules/ROOT/pages/web.adoc | 7 ------- .../modules/ROOT/pages/web/webflux-websocket.adoc | 1 - .../modules/ROOT/pages/web/websocket.adoc | 1 - 14 files changed, 64 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/appendix.adoc b/framework-docs/modules/ROOT/pages/appendix.adoc index ab1f7a86be96..3a75550f6eb1 100644 --- a/framework-docs/modules/ROOT/pages/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/appendix.adoc @@ -1,7 +1,5 @@ [[appendix]] = Appendix -include::attributes.adoc[] -include::page-layout.adoc[] This part of the reference documentation covers topics that apply to multiple modules within the core Spring Framework. diff --git a/framework-docs/modules/ROOT/pages/core.adoc b/framework-docs/modules/ROOT/pages/core.adoc index 1517d7510874..6803a4b8895f 100644 --- a/framework-docs/modules/ROOT/pages/core.adoc +++ b/framework-docs/modules/ROOT/pages/core.adoc @@ -1,7 +1,5 @@ [[spring-core]] = Core Technologies -include::attributes.adoc[] -include::page-layout.adoc[] This part of the reference documentation covers all the technologies that are absolutely integral to the Spring Framework. @@ -20,24 +18,13 @@ is also provided. AOT processing can be used to optimize your application ahead-of-time. It is typically used for native image deployment using GraalVM. -include::core/beans.adoc[leveloffset=+1] -include::core/resources.adoc[leveloffset=+1] -include::core/validation.adoc[leveloffset=+1] -include::core/expressions.adoc[leveloffset=+1] -include::core/aop.adoc[leveloffset=+1] -include::core/aop-api.adoc[leveloffset=+1] -include::core/null-safety.adoc[leveloffset=+1] -include::core/databuffer-codec.adoc[leveloffset=+1] -include::core/spring-jcl.adoc[leveloffset=+1] -include::core/aot.adoc[leveloffset=+1] -include::core/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/data-access.adoc b/framework-docs/modules/ROOT/pages/data-access.adoc index 90adba00db30..0c13876f245c 100644 --- a/framework-docs/modules/ROOT/pages/data-access.adoc +++ b/framework-docs/modules/ROOT/pages/data-access.adoc @@ -1,7 +1,5 @@ [[spring-data-tier]] = Data Access -include::attributes.adoc[] -include::page-layout.adoc[] This part of the reference documentation is concerned with data access and the interaction between the data access layer and the business or service layer. diff --git a/framework-docs/modules/ROOT/pages/index.adoc b/framework-docs/modules/ROOT/pages/index.adoc index 80a46c4f1956..c62a2b2899f3 100644 --- a/framework-docs/modules/ROOT/pages/index.adoc +++ b/framework-docs/modules/ROOT/pages/index.adoc @@ -1,7 +1,6 @@ :noheader: [[spring-framework-documentation]] = Spring Framework Documentation -include::attributes.adoc[] [horizontal] <> :: History, Design Philosophy, Feedback, diff --git a/framework-docs/modules/ROOT/pages/integration.adoc b/framework-docs/modules/ROOT/pages/integration.adoc index 83f6b3c28f9f..e4de8269afd0 100644 --- a/framework-docs/modules/ROOT/pages/integration.adoc +++ b/framework-docs/modules/ROOT/pages/integration.adoc @@ -1,23 +1,13 @@ [[spring-integration]] = Integration -include::attributes.adoc[] -include::page-layout.adoc[] This part of the reference documentation covers Spring Framework's integration with a number of technologies. -include::integration/rest-clients.adoc[leveloffset=+1] -include::integration/jms.adoc[leveloffset=+1] -include::integration/jmx.adoc[leveloffset=+1] -include::integration/email.adoc[leveloffset=+1] -include::integration/scheduling.adoc[leveloffset=+1] -include::integration/cache.adoc[leveloffset=+1] -include::integration/observability.adoc[leveloffset=+1] -include::integration/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/languages.adoc b/framework-docs/modules/ROOT/pages/languages.adoc index 42c9615ae65e..b41773c13e00 100644 --- a/framework-docs/modules/ROOT/pages/languages.adoc +++ b/framework-docs/modules/ROOT/pages/languages.adoc @@ -1,12 +1,7 @@ [[languages]] = Language Support -include::attributes.adoc[] -include::page-layout.adoc[] -include::languages/kotlin.adoc[leveloffset=+1] -include::languages/groovy.adoc[leveloffset=+1] -include::languages/dynamic.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/overview.adoc b/framework-docs/modules/ROOT/pages/overview.adoc index 61b3b5bec02f..b0ed76a7d869 100644 --- a/framework-docs/modules/ROOT/pages/overview.adoc +++ b/framework-docs/modules/ROOT/pages/overview.adoc @@ -1,6 +1,5 @@ [[overview]] = Spring Framework Overview -include::attributes.adoc[] :docinfo1: Spring makes it easy to create Java enterprise applications. It provides everything you diff --git a/framework-docs/modules/ROOT/pages/rsocket.adoc b/framework-docs/modules/ROOT/pages/rsocket.adoc index 4da739d73c71..f3580d824d32 100644 --- a/framework-docs/modules/ROOT/pages/rsocket.adoc +++ b/framework-docs/modules/ROOT/pages/rsocket.adoc @@ -1,7 +1,5 @@ [[rsocket]] = RSocket -include::attributes.adoc[] -include::page-layout.adoc[] This section describes Spring Framework's support for the RSocket protocol. diff --git a/framework-docs/modules/ROOT/pages/testing.adoc b/framework-docs/modules/ROOT/pages/testing.adoc index 4f696b048d04..6339dbbe14bc 100644 --- a/framework-docs/modules/ROOT/pages/testing.adoc +++ b/framework-docs/modules/ROOT/pages/testing.adoc @@ -1,7 +1,5 @@ [[testing]] = Testing -include::attributes.adoc[] -include::page-layout.adoc[] This chapter covers Spring's support for integration testing and best practices for unit testing. The Spring team advocates test-driven development (TDD). The Spring team has @@ -11,20 +9,11 @@ constructors on classes makes them easier to wire together in a test without hav set up service locator registries and similar structures). -include::testing/introduction.adoc[leveloffset=+1] -include::testing/unit.adoc[leveloffset=+1] -include::testing/integration.adoc[leveloffset=+1] -include::testing/support-jdbc.adoc[leveloffset=+1] -include::testing/testcontext-framework.adoc[leveloffset=+1] -include::testing/webtestclient.adoc[leveloffset=+1] -include::testing/spring-mvc-test-framework.adoc[leveloffset=+1] -include::testing/spring-mvc-test-client.adoc[leveloffset=+1] -include::testing/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/testing/appendix.adoc b/framework-docs/modules/ROOT/pages/testing/appendix.adoc index 3d01da459c7f..580253377df9 100644 --- a/framework-docs/modules/ROOT/pages/testing/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/testing/appendix.adoc @@ -1,6 +1,4 @@ [[testing.appendix]] = Appendix -include::annotations.adoc[leveloffset=+1] -include::resources.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web-reactive.adoc b/framework-docs/modules/ROOT/pages/web-reactive.adoc index ea5d4c2b32bb..01d6cc8c552f 100644 --- a/framework-docs/modules/ROOT/pages/web-reactive.adoc +++ b/framework-docs/modules/ROOT/pages/web-reactive.adoc @@ -1,7 +1,5 @@ [[spring-web-reactive]] = Web on Reactive Stack -include::attributes.adoc[] -include::page-layout.adoc[] This part of the documentation covers support for reactive-stack web applications built on a https://www.reactive-streams.org/[Reactive Streams] API to run on non-blocking @@ -11,9 +9,7 @@ the reactive <>, support for <>. For Servlet-stack web applications, see <>. -include::web/webflux.adoc[leveloffset=+1] -include::web/webflux-webclient.adoc[leveloffset=+1] [[webflux-http-interface-client]] @@ -27,7 +23,6 @@ flexibility for to choose an API style such as synchronous or reactive. See <> for details. -include::web/webflux-websocket.adoc[leveloffset=+1] @@ -44,7 +39,6 @@ discussion of mock objects. response objects to provide support for testing WebFlux applications without an HTTP server. You can use the `WebTestClient` for end-to-end integration tests, too. -include::rsocket.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web.adoc b/framework-docs/modules/ROOT/pages/web.adoc index 9a6fe6f541ec..2772fc350883 100644 --- a/framework-docs/modules/ROOT/pages/web.adoc +++ b/framework-docs/modules/ROOT/pages/web.adoc @@ -1,19 +1,12 @@ [[spring-web]] = Web on Servlet Stack -include::attributes.adoc[] -include::page-layout.adoc[] This part of the documentation covers support for Servlet-stack web applications built on the Servlet API and deployed to Servlet containers. Individual chapters include <>, <>, <>, and <>. For reactive-stack web applications, see <>. -include::web/webmvc.adoc[leveloffset=+1] -include::web/webmvc-client.adoc[leveloffset=+1] -include::web/webmvc-test.adoc[leveloffset=+1] -include::web/websocket.adoc[leveloffset=+1] -include::web/integration.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc index d3644cf6543a..5e9b0e01081d 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc @@ -5,7 +5,6 @@ This part of the reference documentation covers support for reactive-stack WebSocket messaging. -include::websocket-intro.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/websocket.adoc b/framework-docs/modules/ROOT/pages/web/websocket.adoc index dec37b4eaeef..c429f5fe70ac 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket.adoc @@ -6,7 +6,6 @@ This part of the reference documentation covers support for Servlet stack, WebSo messaging that includes raw WebSocket interactions, WebSocket emulation through SockJS, and publish-subscribe messaging through STOMP as a sub-protocol over WebSocket. -include::websocket-intro.adoc[leveloffset=+1] From 8496778dacf8def88f9a182080011396eaefe0d2 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:26:17 -0500 Subject: [PATCH 14/31] Fix cross references --- .../modules/ROOT/pages/appendix.adoc | 18 ++--- .../pages/core/aop-api/concise-proxy.adoc | 2 +- .../modules/ROOT/pages/core/aop-api/pfb.adoc | 8 +- .../ROOT/pages/core/aop-api/pointcuts.adoc | 2 +- .../modules/ROOT/pages/core/aop.adoc | 6 +- .../pages/core/aop/aspectj-programmatic.adoc | 2 +- .../ROOT/pages/core/aop/ataspectj.adoc | 2 +- .../ROOT/pages/core/aop/ataspectj/advice.adoc | 28 +++---- .../core/aop/ataspectj/aspectj-support.adoc | 4 +- .../pages/core/aop/ataspectj/example.adoc | 4 +- .../pages/core/aop/ataspectj/pointcuts.adoc | 20 ++--- .../pages/core/aop/introduction-defn.adoc | 4 +- .../pages/core/aop/introduction-proxies.adoc | 4 +- .../core/aop/introduction-spring-defn.adoc | 4 +- .../modules/ROOT/pages/core/aop/schema.adoc | 30 ++++---- .../ROOT/pages/core/aop/using-aspectj.adoc | 24 +++--- .../modules/ROOT/pages/core/aot.adoc | 8 +- .../ROOT/pages/core/appendix/xml-custom.adoc | 16 ++-- .../ROOT/pages/core/appendix/xsd-schemas.adoc | 46 +++++------ .../pages/core/beans/annotation-config.adoc | 12 +-- .../autowired-qualifiers.adoc | 4 +- .../beans/annotation-config/autowired.adoc | 4 +- ...tconstruct-and-predestroy-annotations.adoc | 6 +- .../annotation-config/value-annotations.adoc | 2 +- .../modules/ROOT/pages/core/beans/basics.adoc | 18 ++--- .../ROOT/pages/core/beans/beanfactory.adoc | 2 +- .../pages/core/beans/classpath-scanning.adoc | 14 ++-- .../core/beans/context-introduction.adoc | 14 ++-- .../core/beans/context-load-time-weaver.adoc | 4 +- .../ROOT/pages/core/beans/definition.adoc | 44 +++++------ .../beans/dependencies/factory-autowire.adoc | 12 +-- .../dependencies/factory-collaborators.adoc | 14 ++-- .../beans/dependencies/factory-dependson.adoc | 2 +- .../beans/dependencies/factory-lazy-init.adoc | 2 +- .../factory-method-injection.adoc | 14 ++-- .../factory-properties-detailed.adoc | 20 ++--- .../ROOT/pages/core/beans/environment.adoc | 12 +-- .../pages/core/beans/factory-extension.adoc | 10 +-- .../ROOT/pages/core/beans/factory-nature.adoc | 64 ++++++++-------- .../ROOT/pages/core/beans/factory-scopes.adoc | 32 ++++---- .../ROOT/pages/core/beans/introduction.adoc | 2 +- .../modules/ROOT/pages/core/beans/java.adoc | 18 ++--- .../core/beans/java/bean-annotation.adoc | 28 +++---- .../java/composing-configuration-classes.adoc | 4 +- .../beans/java/configuration-annotation.adoc | 4 +- .../beans/java/instantiating-container.adoc | 2 +- .../ROOT/pages/core/databuffer-codec.adoc | 14 ++-- .../modules/ROOT/pages/core/expressions.adoc | 2 +- .../pages/core/expressions/evaluation.adoc | 6 +- .../pages/core/expressions/language-ref.adoc | 30 ++++---- .../expressions/language-ref/operators.adoc | 8 +- .../language-ref/properties-arrays.adoc | 4 +- .../modules/ROOT/pages/core/null-safety.adoc | 2 +- .../modules/ROOT/pages/core/resources.adoc | 46 +++++------ .../modules/ROOT/pages/core/validation.adoc | 4 +- .../pages/core/validation/beans-beans.adoc | 8 +- .../pages/core/validation/beanvalidation.adoc | 8 +- .../pages/core/validation/conversion.adoc | 2 +- .../ROOT/pages/core/validation/convert.adoc | 4 +- ...uring-formatting-globaldatetimeformat.adoc | 4 +- .../ROOT/pages/core/validation/format.adoc | 4 +- .../ROOT/pages/data-access/appendix.adoc | 10 +-- .../ROOT/pages/data-access/jdbc/advanced.adoc | 2 +- .../pages/data-access/jdbc/connections.adoc | 16 ++-- .../ROOT/pages/data-access/jdbc/core.adoc | 22 +++--- .../jdbc/embedded-database-support.adoc | 10 +-- .../ROOT/pages/data-access/jdbc/object.adoc | 4 +- .../ROOT/pages/data-access/jdbc/packages.adoc | 10 +-- .../ROOT/pages/data-access/jdbc/simple.adoc | 6 +- .../ROOT/pages/data-access/orm/general.adoc | 8 +- .../ROOT/pages/data-access/orm/hibernate.adoc | 8 +- .../pages/data-access/orm/introduction.adoc | 2 +- .../ROOT/pages/data-access/orm/jpa.adoc | 22 +++--- .../modules/ROOT/pages/data-access/oxm.adoc | 14 ++-- .../modules/ROOT/pages/data-access/r2dbc.adoc | 28 +++---- .../ROOT/pages/data-access/transaction.adoc | 22 +++--- .../data-access/transaction/declarative.adoc | 2 +- .../transaction/declarative/annotations.adoc | 24 +++--- .../applying-more-than-just-tx-advice.adoc | 4 +- .../transaction/declarative/aspectj.adoc | 10 +-- .../declarative/first-example.adoc | 4 +- .../transaction/declarative/rolling-back.adoc | 4 +- .../declarative/tx-decl-explained.adoc | 4 +- .../declarative/txadvice-settings.adoc | 2 +- .../data-access/transaction/programmatic.adoc | 4 +- .../solutions-to-common-problems.adoc | 2 +- .../data-access/transaction/strategies.adoc | 8 +- framework-docs/modules/ROOT/pages/index.adoc | 16 ++-- .../ROOT/pages/integration/appendix.adoc | 12 +-- .../modules/ROOT/pages/integration/cache.adoc | 4 +- .../pages/integration/cache/annotations.adoc | 28 +++---- .../integration/cache/declarative-xml.adoc | 4 +- .../ROOT/pages/integration/cache/jsr-107.adoc | 4 +- .../cache/store-configuration.adoc | 2 +- .../pages/integration/cache/strategies.adoc | 4 +- .../modules/ROOT/pages/integration/email.adoc | 2 +- .../ROOT/pages/integration/jms/annotated.adoc | 6 +- .../ROOT/pages/integration/jms/namespace.adoc | 6 +- .../ROOT/pages/integration/jms/receiving.adoc | 4 +- .../ROOT/pages/integration/jms/using.adoc | 12 +-- .../modules/ROOT/pages/integration/jmx.adoc | 2 +- .../ROOT/pages/integration/jmx/exporting.adoc | 12 +-- .../ROOT/pages/integration/jmx/interface.adoc | 8 +- .../ROOT/pages/integration/jmx/naming.adoc | 4 +- .../ROOT/pages/integration/observability.adoc | 10 +-- .../ROOT/pages/integration/rest-clients.adoc | 20 ++--- .../ROOT/pages/integration/scheduling.adoc | 14 ++-- .../modules/ROOT/pages/languages/dynamic.adoc | 40 +++++----- .../modules/ROOT/pages/languages/groovy.adoc | 4 +- .../languages/kotlin/getting-started.adoc | 4 +- .../pages/languages/kotlin/null-safety.adoc | 2 +- .../languages/kotlin/spring-projects-in.adoc | 2 +- .../modules/ROOT/pages/rsocket.adoc | 32 ++++---- .../ROOT/pages/testing/annotations.adoc | 10 +-- .../integration-junit-jupiter.adoc | 68 ++++++++--------- .../annotations/integration-junit4.adoc | 14 ++-- .../testing/annotations/integration-meta.adoc | 4 +- .../annotations/integration-spring.adoc | 36 ++++----- .../annotation-activeprofiles.adoc | 6 +- .../annotation-bootstrapwith.adoc | 2 +- .../annotation-contextconfiguration.adoc | 6 +- .../annotation-contexthierarchy.adoc | 2 +- .../annotation-dynamicpropertysource.adoc | 2 +- .../annotation-recordapplicationevents.adoc | 2 +- .../annotation-rollback.adoc | 2 +- .../integration-spring/annotation-sql.adoc | 2 +- .../annotation-testexecutionlisteners.adoc | 6 +- .../annotation-testpropertysource.adoc | 2 +- .../annotations/integration-standard.adoc | 2 +- .../ROOT/pages/testing/integration.adoc | 36 ++++----- .../ROOT/pages/testing/introduction.adoc | 4 +- .../modules/ROOT/pages/testing/resources.adoc | 4 +- .../testing/spring-mvc-test-framework.adoc | 2 +- .../async-requests.adoc | 4 +- .../server-htmlunit.adoc | 2 +- .../server-htmlunit/geb.adoc | 6 +- .../server-htmlunit/mah.adoc | 8 +- .../server-htmlunit/webdriver.adoc | 8 +- .../server-htmlunit/why.adoc | 6 +- .../server-performing-requests.adoc | 2 +- .../server-setup-options.adoc | 4 +- .../server-static-imports.adoc | 2 +- .../spring-mvc-test-framework/server.adoc | 4 +- .../ROOT/pages/testing/support-jdbc.adoc | 8 +- .../pages/testing/testcontext-framework.adoc | 8 +- .../testing/testcontext-framework/aot.adoc | 8 +- .../application-events.adoc | 6 +- .../testcontext-framework/ctx-management.adoc | 26 +++---- .../ctx-management/caching.adoc | 8 +- .../dynamic-property-sources.adoc | 4 +- .../ctx-management/env-profiles.adoc | 2 +- .../ctx-management/groovy.adoc | 4 +- .../ctx-management/hierarchies.adoc | 2 +- .../ctx-management/inheritance.adoc | 2 +- .../ctx-management/javaconfig.adoc | 2 +- .../ctx-management/property-sources.adoc | 4 +- .../ctx-management/web-mocks.adoc | 2 +- .../testcontext-framework/executing-sql.adoc | 18 ++--- .../testcontext-framework/fixture-di.adoc | 8 +- .../key-abstractions.adoc | 2 +- .../parallel-test-execution.adoc | 2 +- .../support-classes.adoc | 34 ++++----- .../testcontext-framework/tel-config.adoc | 14 ++-- .../test-execution-events.adoc | 6 +- .../testing/testcontext-framework/tx.adoc | 20 ++--- .../web-scoped-beans.adoc | 6 +- .../modules/ROOT/pages/testing/unit.adoc | 26 +++---- .../ROOT/pages/testing/webtestclient.adoc | 24 +++--- .../modules/ROOT/pages/web-reactive.adoc | 16 ++-- framework-docs/modules/ROOT/pages/web.adoc | 6 +- .../modules/ROOT/pages/web/integration.adoc | 4 +- .../modules/ROOT/pages/web/webflux-cors.adoc | 12 +-- .../ROOT/pages/web/webflux-functional.adoc | 38 +++++----- .../modules/ROOT/pages/web/webflux-view.adoc | 42 +++++----- .../ROOT/pages/web/webflux-webclient.adoc | 4 +- .../web/webflux-webclient/client-builder.adoc | 6 +- .../web/webflux-webclient/client-context.adoc | 2 +- .../ROOT/pages/web/webflux-websocket.adoc | 20 ++--- .../web/webflux/ann-rest-exceptions.adoc | 16 ++-- .../ROOT/pages/web/webflux/caching.adoc | 14 ++-- .../ROOT/pages/web/webflux/config.adoc | 44 +++++------ .../ROOT/pages/web/webflux/controller.adoc | 2 +- .../web/webflux/controller/ann-advice.adoc | 6 +- .../webflux/controller/ann-exceptions.adoc | 16 ++-- .../webflux/controller/ann-initbinder.adoc | 6 +- .../web/webflux/controller/ann-methods.adoc | 2 +- .../controller/ann-methods/arguments.adoc | 32 ++++---- .../controller/ann-methods/cookievalue.adoc | 4 +- .../controller/ann-methods/httpentity.adoc | 4 +- .../controller/ann-methods/jackson.adoc | 2 +- .../ann-methods/matrix-variables.adoc | 2 +- .../ann-methods/modelattrib-method-args.adoc | 14 ++-- .../ann-methods/multipart-forms.adoc | 8 +- .../controller/ann-methods/requestattrib.adoc | 2 +- .../controller/ann-methods/requestbody.adoc | 6 +- .../controller/ann-methods/requestheader.adoc | 4 +- .../controller/ann-methods/requestparam.adoc | 6 +- .../controller/ann-methods/responsebody.adoc | 12 +-- .../ann-methods/responseentity.adoc | 6 +- .../controller/ann-methods/return-types.adoc | 18 ++--- .../ann-methods/sessionattribute.adoc | 4 +- .../ann-methods/sessionattributes.adoc | 2 +- .../ann-methods/typeconversion.adoc | 6 +- .../controller/ann-modelattrib-methods.adoc | 6 +- .../controller/ann-requestmapping.adoc | 24 +++--- .../pages/web/webflux/controller/ann.adoc | 6 +- .../pages/web/webflux/dispatcher-handler.adoc | 52 ++++++------- .../modules/ROOT/pages/web/webflux/http2.adoc | 2 +- .../ROOT/pages/web/webflux/new-framework.adoc | 24 +++--- .../pages/web/webflux/reactive-spring.adoc | 76 +++++++++---------- .../ROOT/pages/web/webflux/security.adoc | 2 +- .../ROOT/pages/web/webflux/uri-building.adoc | 2 +- .../modules/ROOT/pages/web/webmvc-client.adoc | 8 +- .../modules/ROOT/pages/web/webmvc-cors.adoc | 14 ++-- .../ROOT/pages/web/webmvc-functional.adoc | 28 +++---- .../modules/ROOT/pages/web/webmvc-test.adoc | 12 +-- .../modules/ROOT/pages/web/webmvc-view.adoc | 4 +- .../pages/web/webmvc-view/mvc-freemarker.adoc | 8 +- .../pages/web/webmvc-view/mvc-jackson.adoc | 6 +- .../ROOT/pages/web/webmvc-view/mvc-jsp.adoc | 4 +- .../pages/web/webmvc-view/mvc-script.adoc | 6 +- .../pages/web/webmvc-view/mvc-thymeleaf.adoc | 2 +- .../web/webmvc-view/mvc-xml-marshalling.adoc | 2 +- .../ROOT/pages/web/webmvc-view/mvc-xslt.adoc | 2 +- .../modules/ROOT/pages/web/webmvc.adoc | 2 +- .../ROOT/pages/web/webmvc/filters.adoc | 26 +++---- .../ROOT/pages/web/webmvc/mvc-ann-async.adoc | 50 ++++++------ .../web/webmvc/mvc-ann-rest-exceptions.adoc | 16 ++-- .../ROOT/pages/web/webmvc/mvc-caching.adoc | 16 ++-- .../ROOT/pages/web/webmvc/mvc-config.adoc | 8 +- .../web/webmvc/mvc-config/advanced-java.adoc | 2 +- .../mvc-config/content-negotiation.adoc | 4 +- .../web/webmvc/mvc-config/conversion.adoc | 4 +- .../web/webmvc/mvc-config/customize.adoc | 2 +- .../pages/web/webmvc/mvc-config/enable.adoc | 4 +- .../webmvc/mvc-config/message-converters.adoc | 2 +- .../web/webmvc/mvc-config/path-matching.adoc | 2 +- .../webmvc/mvc-config/static-resources.adoc | 4 +- .../web/webmvc/mvc-config/validation.adoc | 6 +- .../web/webmvc/mvc-config/view-resolvers.adoc | 2 +- .../ROOT/pages/web/webmvc/mvc-controller.adoc | 2 +- .../web/webmvc/mvc-controller/ann-advice.adoc | 6 +- .../mvc-controller/ann-exceptionhandler.adoc | 26 +++---- .../webmvc/mvc-controller/ann-initbinder.adoc | 6 +- .../webmvc/mvc-controller/ann-methods.adoc | 2 +- .../mvc-controller/ann-methods/arguments.adoc | 34 ++++----- .../ann-methods/cookievalue.adoc | 4 +- .../ann-methods/httpentity.adoc | 4 +- .../mvc-controller/ann-methods/jackson.adoc | 2 +- .../ann-methods/matrix-variables.adoc | 4 +- .../ann-methods/modelattrib-method-args.adoc | 16 ++-- .../ann-methods/multipart-forms.adoc | 8 +- .../ann-methods/redirecting-passing-data.adoc | 2 +- .../ann-methods/requestattrib.adoc | 2 +- .../ann-methods/requestbody.adoc | 6 +- .../ann-methods/requestheader.adoc | 4 +- .../ann-methods/requestparam.adoc | 4 +- .../ann-methods/responsebody.adoc | 10 +-- .../ann-methods/responseentity.adoc | 6 +- .../ann-methods/return-types.adoc | 28 +++---- .../ann-methods/sessionattribute.adoc | 4 +- .../ann-methods/sessionattributes.adoc | 2 +- .../ann-methods/typeconversion.adoc | 6 +- .../ann-modelattrib-methods.adoc | 6 +- .../mvc-controller/ann-requestmapping.adoc | 36 ++++----- .../pages/web/webmvc/mvc-controller/ann.adoc | 6 +- .../ROOT/pages/web/webmvc/mvc-http2.adoc | 4 +- .../ROOT/pages/web/webmvc/mvc-security.adoc | 2 +- .../ROOT/pages/web/webmvc/mvc-servlet.adoc | 8 +- .../pages/web/webmvc/mvc-servlet/config.adoc | 6 +- .../webmvc/mvc-servlet/context-hierarchy.adoc | 2 +- .../webmvc/mvc-servlet/exceptionhandlers.adoc | 8 +- .../handlermapping-interceptor.adoc | 4 +- .../mvc-servlet/handlermapping-path.adoc | 4 +- .../webmvc/mvc-servlet/localeresolver.adoc | 12 +-- .../pages/web/webmvc/mvc-servlet/logging.adoc | 4 +- .../web/webmvc/mvc-servlet/multipart.adoc | 2 +- .../web/webmvc/mvc-servlet/sequence.adoc | 10 +-- .../mvc-servlet/special-bean-types.adoc | 28 +++---- .../web/webmvc/mvc-servlet/themeresolver.adoc | 2 +- .../web/webmvc/mvc-servlet/viewresolver.adoc | 18 ++--- .../pages/web/webmvc/mvc-uri-building.adoc | 6 +- .../modules/ROOT/pages/web/websocket.adoc | 2 +- .../ROOT/pages/web/websocket/fallback.adoc | 4 +- .../ROOT/pages/web/websocket/server.adoc | 16 ++-- .../pages/web/websocket/stomp/benefits.adoc | 2 +- .../pages/web/websocket/stomp/client.adoc | 4 +- .../stomp/configuration-performance.adoc | 2 +- .../pages/web/websocket/stomp/enable.adoc | 6 +- .../websocket/stomp/handle-annotations.adoc | 22 +++--- .../stomp/handle-broker-relay-configure.adoc | 2 +- .../websocket/stomp/handle-broker-relay.adoc | 2 +- .../websocket/stomp/handle-simple-broker.adoc | 2 +- .../web/websocket/stomp/interceptors.adoc | 2 +- .../web/websocket/stomp/server-config.adoc | 2 +- .../web/websocket/stomp/user-destination.adoc | 2 +- 296 files changed, 1505 insertions(+), 1505 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/appendix.adoc b/framework-docs/modules/ROOT/pages/appendix.adoc index 3a75550f6eb1..c25f35e2de7f 100644 --- a/framework-docs/modules/ROOT/pages/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/appendix.adoc @@ -30,7 +30,7 @@ for details. | `spring.expression.compiler.mode` | The mode to use when compiling expressions for the -<>. +xref:core/expressions/evaluation.adoc#expressions-compiler-configuration[Spring Expression Language]. | `spring.getenv.ignore` | Instructs Spring to ignore operating system environment variables if a Spring @@ -41,12 +41,12 @@ for details. | `spring.index.ignore` | Instructs Spring to ignore the components index located in -`META-INF/spring.components`. See <>. +`META-INF/spring.components`. See xref:core/beans/classpath-scanning.adoc#beans-scanning-index[Generating an Index of Candidate Components] +. | `spring.jdbc.getParameterType.ignore` | Instructs Spring to ignore `java.sql.ParameterMetaData.getParameterType` completely. -See the note in <>. +See the note in xref:data-access/jdbc/advanced.adoc#jdbc-batch-list[Batch Operations with a List of Objects]. | `spring.jndi.ignore` | Instructs Spring to ignore a default JNDI environment, as an optimization for scenarios @@ -62,17 +62,17 @@ for details. | `spring.test.constructor.autowire.mode` | The default _test constructor autowire mode_ to use if `@TestConstructor` is not present -on a test class. See <>. +on a test class. See xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[Changing the default test constructor autowire mode] +. | `spring.test.context.cache.maxSize` | The maximum size of the context cache in the _Spring TestContext Framework_. See -<>. +xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching]. | `spring.test.enclosing.configuration` | The default _enclosing configuration inheritance mode_ to use if `@NestedTestConfiguration` is not present on a test class. See -<>. +xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration[Changing the default enclosing configuration inheritance mode] +. |=== diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc index 7fa0edea71b2..a0218c763080 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc @@ -58,7 +58,7 @@ we override the transaction propagation settings: Note that in the parent bean example, we explicitly marked the parent bean definition as being abstract by setting the `abstract` attribute to `true`, as described -<>, so that it may not actually ever be +xref:core/beans/child-bean-definitions.adoc[previously], so that it may not actually ever be instantiated. Application contexts (but not simple bean factories), by default, pre-instantiate all singletons. Therefore, it is important (at least for singleton beans) that, if you have a (parent) bean definition that you intend to use only as a template, diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc index 4de522e0c95c..4ede450416fd 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc @@ -40,7 +40,7 @@ In common with most `FactoryBean` implementations provided with Spring, the `ProxyFactoryBean` class is itself a JavaBean. Its properties are used to: * Specify the target you want to proxy. -* Specify whether to use CGLIB (described later and see also <>). +* Specify whether to use CGLIB (described later and see also xref:core/aop-api/pfb.adoc#aop-pfb-proxy-types[JDK- and CGLIB-based proxies]). Some key properties are inherited from `org.springframework.aop.framework.ProxyConfig` (the superclass for all AOP proxy factories in Spring). These key properties include @@ -48,7 +48,7 @@ the following: * `proxyTargetClass`: `true` if the target class is to be proxied, rather than the target class's interfaces. If this property value is set to `true`, then CGLIB proxies - are created (but see also <>). + are created (but see also xref:core/aop-api/pfb.adoc#aop-pfb-proxy-types[JDK- and CGLIB-based proxies]). * `optimize`: Controls whether or not aggressive optimizations are applied to proxies created through CGLIB. You should not blithely use this setting unless you fully understand how the relevant AOP proxy handles optimization. This is currently used @@ -66,7 +66,7 @@ the following: Other properties specific to `ProxyFactoryBean` include the following: * `proxyInterfaces`: An array of `String` interface names. If this is not supplied, a CGLIB - proxy for the target class is used (but see also <>). + proxy for the target class is used (but see also xref:core/aop-api/pfb.adoc#aop-pfb-proxy-types[JDK- and CGLIB-based proxies]). * `interceptorNames`: A `String` array of `Advisor`, interceptor, or other advice names to apply. Ordering is significant, on a first come-first served basis. That is to say that the first interceptor in the list is the first to be able to intercept the @@ -78,7 +78,7 @@ factories. You cannot mention bean references here, since doing so results in th + You can append an interceptor name with an asterisk (`*`). Doing so results in the application of all advisor beans with names that start with the part before the asterisk -to be applied. You can find an example of using this feature in <>. +to be applied. You can find an example of using this feature in xref:core/aop-api/pfb.adoc#aop-global-advisors[Using "`Global`" Advisors]. * singleton: Whether or not the factory should return a single object, no matter how often the `getObject()` method is called. Several `FactoryBean` implementations offer diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc index 334097228e2a..a99cfd000deb 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc @@ -92,7 +92,7 @@ Since 2.0, the most important type of pointcut used by Spring is `org.springframework.aop.aspectj.AspectJExpressionPointcut`. This is a pointcut that uses an AspectJ-supplied library to parse an AspectJ pointcut expression string. -See the <> for a discussion of supported AspectJ pointcut primitives. +See the xref:core/aop.adoc[previous chapter] for a discussion of supported AspectJ pointcut primitives. diff --git a/framework-docs/modules/ROOT/pages/core/aop.adoc b/framework-docs/modules/ROOT/pages/core/aop.adoc index 1421a1bacdf9..3d86b381f32b 100644 --- a/framework-docs/modules/ROOT/pages/core/aop.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop.adoc @@ -15,18 +15,18 @@ to), AOP complements Spring IoC to provide a very capable middleware solution. .Spring AOP with AspectJ pointcuts **** Spring provides simple and powerful ways of writing custom aspects by using either a -<> or the <>. +xref:core/aop/schema.adoc[schema-based approach] or the xref:core/aop/ataspectj.adoc[@AspectJ annotation style]. Both of these styles offer fully typed advice and use of the AspectJ pointcut language while still using Spring AOP for weaving. This chapter discusses the schema- and @AspectJ-based AOP support. -The lower-level AOP support is discussed in <>. +The lower-level AOP support is discussed in xref:core/aop-api.adoc[the following chapter]. **** AOP is used in the Spring Framework to: * Provide declarative enterprise services. The most important such service is - <>. + xref:data-access/transaction/declarative.adoc[declarative transaction management]. * Let users implement custom aspects, complementing their use of OOP with AOP. NOTE: If you are interested only in generic declarative services or other pre-packaged diff --git a/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc b/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc index 8e76aadb60eb..66fbd2209b25 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc @@ -4,7 +4,7 @@ In addition to declaring aspects in your configuration by using either `` or ``, it is also possible to programmatically create proxies that advise target objects. For the full details of Spring's AOP API, see the -<>. Here, we want to focus on the ability to automatically +xref:core/aop-api.adoc[next chapter]. Here, we want to focus on the ability to automatically create proxies by using @AspectJ aspects. You can use the `org.springframework.aop.aspectj.annotation.AspectJProxyFactory` class diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc index bcda90151581..7adfe44de78f 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc @@ -9,7 +9,7 @@ for pointcut parsing and matching. The AOP runtime is still pure Spring AOP, tho there is no dependency on the AspectJ compiler or weaver. NOTE: Using the AspectJ compiler and weaver enables use of the full AspectJ language and -is discussed in <>. +is discussed in xref:core/aop/using-aspectj.adoc[Using AspectJ with Spring Applications]. diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc index 0b1f36c11acc..856e66041256 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc @@ -3,7 +3,7 @@ Advice is associated with a pointcut expression and runs before, after, or around method executions matched by the pointcut. The pointcut expression may be either an _inline -pointcut_ or a reference to a <>. +pointcut_ or a reference to a xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[_named pointcut_]. [[aop-advice-before]] @@ -44,7 +44,7 @@ The following example uses an inline pointcut expression. } ---- -If we use a <>, we can rewrite the preceding example +If we use a xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[named pointcut], we can rewrite the preceding example as follows: [source,java,indent=0,subs="verbatim",role="primary"] @@ -352,7 +352,7 @@ execution-only semantics. You only need to be aware of this difference if you co `@AspectJ` aspects written for Spring and use `proceed` with arguments with the AspectJ compiler and weaver. There is a way to write such aspects that is 100% compatible across both Spring AOP and AspectJ, and this is discussed in the -<>. +xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-proceeding-with-the-call[following section on advice parameters]. ==== The value returned by the around advice is the return value seen by the caller of the @@ -536,7 +536,7 @@ The following shows the advice that matches the execution of `@Auditable` method // ... } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin @@ -547,7 +547,7 @@ The following shows the advice that matches the execution of `@Auditable` method // ... } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [[aop-ataspectj-advice-params-generics]] === Advice Parameters and Generics @@ -633,7 +633,7 @@ of determining parameter names, an exception will be thrown. `AspectJAnnotationParameterNameDiscoverer` :: Uses parameter names that have been explicitly specified by the user via the `argNames` attribute in the corresponding advice or - pointcut annotation. See <> for details. + pointcut annotation. See xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-params-names-explicit[Explicit Argument Names] for details. `KotlinReflectionParameterNameDiscoverer` :: Uses Kotlin reflection APIs to determine parameter names. This discoverer is only used if such APIs are present on the classpath. `StandardReflectionParameterNameDiscoverer` :: Uses the standard `java.lang.reflect.Parameter` @@ -679,7 +679,7 @@ The following example shows how to use the `argNames` attribute: // ... use code and bean } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. [source,kotlin,indent=0,subs="verbatim",role="secondary"] @@ -693,7 +693,7 @@ The following example shows how to use the `argNames` attribute: // ... use code and bean } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. If the first parameter is of type `JoinPoint`, `ProceedingJoinPoint`, or @@ -712,7 +712,7 @@ point object, the `argNames` attribute does not need to include it: // ... use code, bean, and jp } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. [source,kotlin,indent=0,subs="verbatim",role="secondary"] @@ -726,7 +726,7 @@ point object, the `argNames` attribute does not need to include it: // ... use code, bean, and jp } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. The special treatment given to the first parameter of type `JoinPoint`, @@ -743,7 +743,7 @@ the `argNames` attribute: // ... use jp } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin @@ -753,7 +753,7 @@ the `argNames` attribute: // ... use jp } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [[aop-ataspectj-advice-proceeding-with-the-call]] @@ -776,7 +776,7 @@ The following example shows how to do so: return pjp.proceed(new Object[] {newPattern}); } ---- -<1> References the `inDataAccessLayer` named pointcut defined in <>. +<1> References the `inDataAccessLayer` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin @@ -790,7 +790,7 @@ The following example shows how to do so: return pjp.proceed(arrayOf(newPattern)) } ---- -<1> References the `inDataAccessLayer` named pointcut defined in <>. +<1> References the `inDataAccessLayer` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. In many cases, you do this binding anyway (as in the preceding example). diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc index e0725013ea03..c75a21e7e4ee 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc @@ -47,8 +47,8 @@ element, as the following example shows: ---- This assumes that you use schema support as described in -<>. -See <> for how to +xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration]. +See xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-aop[the AOP schema] for how to import the tags in the `aop` namespace. diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc index 46507ec9ff11..d16aba8949d1 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc @@ -56,7 +56,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl } } ---- -<1> References the `businessService` named pointcut defined in <>. +<1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin @@ -97,7 +97,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl } } ---- -<1> References the `businessService` named pointcut defined in <>. +<1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. Note that the aspect implements the `Ordered` interface so that we can set the precedence of the aspect higher than the transaction advice (we want a fresh transaction each time we diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc index 4ddddf4fb893..722405ef7618 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc @@ -99,7 +99,7 @@ If a pointcut is strictly meant to be public-only, even in a CGLIB proxy scenari potential non-public interactions through proxies, it needs to be defined accordingly. If your interception needs include method calls or even constructors within the target -class, consider the use of Spring-driven <> instead +class, consider the use of Spring-driven xref:core/aop/using-aspectj.adoc#aop-aj-ltw[native AspectJ weaving] instead of Spring's proxy-based AOP framework. This constitutes a different mode of AOP usage with different characteristics, so be sure to make yourself familiar with weaving before making a decision. @@ -350,8 +350,8 @@ could write the following which references the ---- -The `` and `` elements are discussed in <>. The -transaction elements are discussed in <>. +The `` and `` elements are discussed in xref:core/aop/schema.adoc[Schema-based AOP Support]. The +transaction elements are discussed in xref:data-access/transaction.adoc[Transaction Management]. [[aop-pointcuts-examples]] @@ -444,7 +444,7 @@ sub-packages: this(com.xyz.service.AccountService) ---- + -NOTE: `this` is more commonly used in a binding form. See the section on <> +NOTE: `this` is more commonly used in a binding form. See the section on xref:core/aop/ataspectj/advice.adoc[Declaring Advice] for how to make the proxy object available in the advice body. * Any join point (method execution only in Spring AOP) where the target object @@ -455,7 +455,7 @@ implements the `AccountService` interface: target(com.xyz.service.AccountService) ---- + -NOTE: `target` is more commonly used in a binding form. See the <> section +NOTE: `target` is more commonly used in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the target object available in the advice body. * Any join point (method execution only in Spring AOP) that takes a single parameter @@ -466,7 +466,7 @@ and where the argument passed at runtime is `Serializable`: args(java.io.Serializable) ---- + -NOTE: `args` is more commonly used in a binding form. See the <> section +NOTE: `args` is more commonly used in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the method arguments available in the advice body. + Note that the pointcut given in this example is different from `execution(* @@ -482,7 +482,7 @@ parameter of type `Serializable`. @target(org.springframework.transaction.annotation.Transactional) ---- + -NOTE: You can also use `@target` in a binding form. See the <> section for +NOTE: You can also use `@target` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the annotation object available in the advice body. * Any join point (method execution only in Spring AOP) where the declared type of the @@ -493,7 +493,7 @@ target object has an `@Transactional` annotation: @within(org.springframework.transaction.annotation.Transactional) ---- + -NOTE: You can also use `@within` in a binding form. See the <> section for +NOTE: You can also use `@within` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the annotation object available in the advice body. * Any join point (method execution only in Spring AOP) where the executing method has an @@ -504,7 +504,7 @@ how to make the annotation object available in the advice body. @annotation(org.springframework.transaction.annotation.Transactional) ---- + -NOTE: You can also use `@annotation` in a binding form. See the <> section +NOTE: You can also use `@annotation` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the annotation object available in the advice body. * Any join point (method execution only in Spring AOP) which takes a single parameter, @@ -515,7 +515,7 @@ and where the runtime type of the argument passed has the `@Classified` annotati @args(com.xyz.security.Classified) ---- + -NOTE: You can also use `@args` in a binding form. See the <> section +NOTE: You can also use `@args` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section how to make the annotation object(s) available in the advice body. * Any join point (method execution only in Spring AOP) on a Spring bean named diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc index 55ec9db45e31..82b705f17c29 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc @@ -8,8 +8,8 @@ However, it would be even more confusing if Spring used its own terminology. * Aspect: A modularization of a concern that cuts across multiple classes. Transaction management is a good example of a crosscutting concern in enterprise Java applications. In Spring AOP, aspects are implemented by using regular classes - (the <>) or regular classes annotated with the - `@Aspect` annotation (the <>). + (the xref:core/aop/schema.adoc[schema-based approach]) or regular classes annotated with the + `@Aspect` annotation (the xref:core/aop/ataspectj.adoc[@AspectJ style]). * Join point: A point during the execution of a program, such as the execution of a method or the handling of an exception. In Spring AOP, a join point always represents a method execution. diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc index 872673dbf4de..de27700eaa3b 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc @@ -8,12 +8,12 @@ Spring AOP can also use CGLIB proxies. This is necessary to proxy classes rather interfaces. By default, CGLIB is used if a business object does not implement an interface. As it is good practice to program to interfaces rather than classes, business classes normally implement one or more business interfaces. It is possible to -<>, in those (hopefully rare) cases where you +xref:core/aop/proxying.adoc[force the use of CGLIB], in those (hopefully rare) cases where you need to advise a method that is not declared on an interface or where you need to pass a proxied object to a method as a concrete type. It is important to grasp the fact that Spring AOP is proxy-based. See -<> for a thorough examination of exactly what this +xref:core/aop/proxying.adoc#aop-understanding-aop-proxies[Understanding AOP Proxies] for a thorough examination of exactly what this implementation detail actually means. diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc index 48110b52cde9..84ef5d6e5829 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc @@ -30,7 +30,7 @@ frameworks such as AspectJ are valuable and that they are complementary, rather competition. Spring seamlessly integrates Spring AOP and IoC with AspectJ, to enable all uses of AOP within a consistent Spring-based application architecture. This integration does not affect the Spring AOP API or the AOP Alliance -API. Spring AOP remains backward-compatible. See <> +API. Spring AOP remains backward-compatible. See xref:core/aop-api.adoc[the following chapter] for a discussion of the Spring AOP APIs. [NOTE] @@ -52,7 +52,7 @@ configuration-style approach. The fact that this chapter chooses to introduce th @AspectJ-style approach first should not be taken as an indication that the Spring team favors the @AspectJ annotation-style approach over the Spring XML configuration-style. -See <> for a more complete discussion of the advantages and disadvantages of +See xref:core/aop/choosing.adoc[Choosing which AOP Declaration Style to Use] for a more complete discussion of the advantages and disadvantages of each style. ==== diff --git a/framework-docs/modules/ROOT/pages/core/aop/schema.adoc b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc index a0fe4a24746f..875bcc2d80ea 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/schema.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc @@ -5,12 +5,12 @@ If you prefer an XML-based format, Spring also offers support for defining aspec using the `aop` namespace tags. The exact same pointcut expressions and advice kinds as when using the @AspectJ style are supported. Hence, in this section we focus on that syntax and refer the reader to the discussion in the previous section -(<>) for an understanding of writing pointcut expressions and the binding +(xref:core/aop/ataspectj.adoc[@AspectJ support]) for an understanding of writing pointcut expressions and the binding of advice parameters. To use the aop namespace tags described in this section, you need to import the -`spring-aop` schema, as described in <>. See <> +`spring-aop` schema, as described in xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration] +. See xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-aop[the AOP schema] for how to import the tags in the `aop` namespace. Within your Spring configurations, all aspect and advisor elements must be placed within @@ -19,7 +19,7 @@ application context configuration). An `` element can contain pointc advisor, and aspect elements (note that these must be declared in that order). WARNING: The `` style of configuration makes heavy use of Spring's -<> mechanism. This can cause issues (such as advice +xref:core/aop-api/autoproxy.adoc[auto-proxying] mechanism. This can cause issues (such as advice not being woven) if you already use explicit auto-proxying through the use of `BeanNameAutoProxyCreator` or something similar. The recommended usage pattern is to use either only the `` style or only the `AutoProxyCreator` style and @@ -75,7 +75,7 @@ be defined as follows: ---- Note that the pointcut expression itself uses the same AspectJ pointcut expression -language as described in <>. If you use the schema based declaration +language as described in xref:core/aop/ataspectj.adoc[@AspectJ support]. If you use the schema based declaration style, you can also refer to _named pointcuts_ defined in `@Aspect` types within the pointcut expression. Thus, another way of defining the above pointcut would be as follows: @@ -88,7 +88,7 @@ pointcut expression. Thus, another way of defining the above pointcut would be a ---- -<1> References the `businessService` named pointcut defined in <>. +<1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. Declaring a pointcut _inside_ an aspect is very similar to declaring a top-level pointcut, as the following example shows: @@ -203,10 +203,10 @@ Before advice runs before a matched method execution. It is declared inside an ---- In the example above, `dataAccessOperation` is the `id` of a _named pointcut_ defined at -the top (``) level (see <>). +the top (``) level (see xref:core/aop/schema.adoc#aop-schema-pointcuts[Declaring a Pointcut]). NOTE: As we noted in the discussion of the @AspectJ style, using _named pointcuts_ can -significantly improve the readability of your code. See <> for +significantly improve the readability of your code. See xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions] for details. To define the pointcut inline instead, replace the `pointcut-ref` attribute with a @@ -379,7 +379,7 @@ Invoking `proceed()` without arguments will result in the caller's original argu being supplied to the underlying method when it is invoked. For advanced use cases, there is an overloaded variant of the `proceed()` method which accepts an array of arguments (`Object[]`). The values in the array will be used as the arguments to the underlying -method when it is invoked. See <> for notes on calling +method when it is invoked. See xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-around-advice[Around Advice] for notes on calling `proceed` with an `Object[]`. The following example shows how to declare around advice in XML: @@ -426,11 +426,11 @@ The implementation of the `doBasicProfiling` advice can be exactly the same as i The schema-based declaration style supports fully typed advice in the same way as described for the @AspectJ support -- by matching pointcut parameters by name against -advice method parameters. See <> for details. If you wish +advice method parameters. See xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-params[Advice Parameters] for details. If you wish to explicitly specify argument names for the advice methods (not relying on the detection strategies previously described), you can do so by using the `arg-names` attribute of the advice element, which is treated in the same manner as the `argNames` -attribute in an advice annotation (as described in <>). +attribute in an advice annotation (as described in xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-params-names[Determining Argument Names]). The following example shows how to specify an argument name in XML: [source,xml,indent=0,subs="verbatim"] @@ -440,7 +440,7 @@ The following example shows how to specify an argument name in XML: method="audit" arg-names="auditable" /> ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. The `arg-names` attribute accepts a comma-delimited list of parameter names. @@ -608,7 +608,7 @@ ms % Task name === Advice Ordering When multiple pieces of advice need to run at the same join point (executing method) -the ordering rules are as described in <>. The precedence +the ordering rules are as described in xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice Ordering]. The precedence between aspects is determined via the `order` attribute in the `` element or by either adding the `@Order` annotation to the bean that backs the aspect or by having the bean implement the `Ordered` interface. @@ -718,7 +718,7 @@ The concept of "advisors" comes from the AOP support defined in Spring and does not have a direct equivalent in AspectJ. An advisor is like a small self-contained aspect that has a single piece of advice. The advice itself is represented by a bean and must implement one of the advice interfaces described in -<>. Advisors can take advantage of AspectJ pointcut expressions. +xref:core/aop-api/advice.adoc#aop-api-advice-types[Advice Types in Spring]. Advisors can take advantage of AspectJ pointcut expressions. Spring supports the advisor concept with the `` element. You most commonly see it used in conjunction with transactional advice, which also has its own @@ -756,7 +756,7 @@ use the `order` attribute to define the `Ordered` value of the advisor. == An AOP Schema Example This section shows how the concurrent locking failure retry example from -<> looks when rewritten with the schema support. +xref:core/aop/ataspectj/example.adoc[An AOP Example] looks when rewritten with the schema support. The execution of business services can sometimes fail due to concurrency issues (for example, a deadlock loser). If the operation is retried, it is likely to succeed diff --git a/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc index d0c65500d049..ea8cf920a26f 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc @@ -8,10 +8,10 @@ alone. Spring ships with a small AspectJ aspect library, which is available stand-alone in your distribution as `spring-aspects.jar`. You need to add this to your classpath in order -to use the aspects in it. <> and <> discuss the -content of this library and how you can use it. <> discusses how to +to use the aspects in it. xref:core/aop/using-aspectj.adoc#aop-atconfigurable[Using AspectJ to Dependency Inject Domain Objects with Spring] and xref:core/aop/using-aspectj.adoc#aop-ajlib-other[Other Spring aspects for AspectJ] discuss the +content of this library and how you can use it. xref:core/aop/using-aspectj.adoc#aop-aj-configure[Configuring AspectJ Aspects by Using Spring IoC] discusses how to dependency inject AspectJ aspects that are woven using the AspectJ compiler. Finally, -<> provides an introduction to load-time weaving for Spring applications +xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework] provides an introduction to load-time weaving for Spring applications that use AspectJ. @@ -108,7 +108,7 @@ annotation. You can specify either `@Configurable(autowire=Autowire.BY_TYPE)` or `@Configurable(autowire=Autowire.BY_NAME)` for autowiring by type or by name, respectively. As an alternative, it is preferable to specify explicit, annotation-driven dependency injection for your `@Configurable` beans through `@Autowired` or `@Inject` -at the field or method level (see <> for further details). +at the field or method level (see xref:core/beans/annotation-config.adoc[Annotation-based Container Configuration] for further details). Finally, you can enable Spring dependency checking for the object references in the newly created and configured object by using the `dependencyCheck` attribute (for example, @@ -158,7 +158,7 @@ Programming Guide]. For this to work, the annotated types must be woven with the AspectJ weaver. You can either use a build-time Ant or Maven task to do this (see, for example, the https://www.eclipse.org/aspectj/doc/released/devguide/antTasks.html[AspectJ Development -Environment Guide]) or load-time weaving (see <>). The +Environment Guide]) or load-time weaving (see xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework]). The `AnnotationBeanConfigurerAspect` itself needs to be configured by Spring (in order to obtain a reference to the bean factory that is to be used to configure new objects). If you use Java-based configuration, you can add `@EnableSpringConfigured` to any @@ -182,7 +182,7 @@ use Java-based configuration, you can add `@EnableSpringConfigured` to any ---- If you prefer XML based configuration, the Spring -<> +xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-context[`context` namespace] defines a convenient `context:spring-configured` element, which you can use as follows: [source,xml,indent=0,subs="verbatim"] @@ -387,7 +387,7 @@ per-`ClassLoader` basis, which is more fine-grained and which can make more sense in a 'single-JVM-multiple-application' environment (such as is found in a typical application server environment). -Further, <>, this support enables +Further, xref:core/aop/using-aspectj.adoc#aop-aj-ltw-environments[in certain environments], this support enables load-time weaving without making any modifications to the application server's launch script that is needed to add `-javaagent:path/to/aspectjweaver.jar` or (as we describe later in this section) `-javaagent:path/to/spring-instrument.jar`. Developers configure @@ -410,9 +410,9 @@ quickly get some performance metrics. We can then apply a finer-grained profilin tool to that specific area immediately afterwards. NOTE: The example presented here uses XML configuration. You can also configure and -use @AspectJ with <>. Specifically, you can use the +use @AspectJ with xref:core/beans/java.adoc[Java configuration]. Specifically, you can use the `@EnableLoadTimeWeaving` annotation as an alternative to `` -(see <> for details). +(see xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[below] for details). The following example shows the profiling aspect, which is not fancy. It is a time-based profiler that uses the @AspectJ-style of aspect declaration: @@ -692,8 +692,8 @@ for AspectJ LTW: * `spring-aop.jar` * `aspectjweaver.jar` -If you use the <>, you also need: +If you use the xref:core/aop/using-aspectj.adoc#aop-aj-ltw-environments-generic[Spring-provided agent to enable instrumentation] +, you also need: * `spring-instrument.jar` @@ -900,7 +900,7 @@ containers. Tomcat, JBoss/WildFly, IBM WebSphere Application Server and Oracle WebLogic Server all provide a general app `ClassLoader` that is capable of local instrumentation. Spring's native LTW may leverage those ClassLoader implementations to provide AspectJ weaving. -You can simply enable load-time weaving, as <>. +You can simply enable load-time weaving, as xref:core/aop/using-aspectj.adoc[described earlier]. Specifically, you do not need to modify the JVM launch script to add `-javaagent:path/to/spring-instrument.jar`. diff --git a/framework-docs/modules/ROOT/pages/core/aot.adoc b/framework-docs/modules/ROOT/pages/core/aot.adoc index d4f0fca362e3..9a1553db5b80 100644 --- a/framework-docs/modules/ROOT/pages/core/aot.adoc +++ b/framework-docs/modules/ROOT/pages/core/aot.adoc @@ -3,7 +3,7 @@ This chapter covers Spring's Ahead of Time (AOT) optimizations. -For AOT support specific to integration tests, see <>. +For AOT support specific to integration tests, see xref:testing/testcontext-framework/aot.adoc[Ahead of Time Support for Tests]. [[core.aot.introduction]] == Introduction to Ahead of Time Optimizations @@ -57,12 +57,12 @@ Let's look at a basic example: include::code:AotProcessingSample[tag=myapplication] Starting this application with the regular runtime involves a number of steps including classpath scanning, configuration class parsing, bean instantiation, and lifecycle callback handling. -Refresh for AOT processing only applies a subset of what happens with a <>. +Refresh for AOT processing only applies a subset of what happens with a xref:core/beans/introduction.adoc[regular `refresh`]. AOT processing can be triggered as follows: include::code:AotProcessingSample[tag=aotcontext] -In this mode, <> are invoked as usual. +In this mode, xref:core/beans/factory-extension.adoc#beans-factory-extension-factory-postprocessors[`BeanFactoryPostProcessor` implementations] are invoked as usual. This includes configuration class parsing, import selectors, classpath scanning, etc. Such steps make sure that the `BeanRegistry` contains the relevant bean definitions for the application. If bean definitions are guarded by conditions (such as `@Profile`), these are discarded at this stage. @@ -108,7 +108,7 @@ It does so using a dedicated `BeanRegistrationAotProcessor`. This interface is used as follows: * Implemented by a `BeanPostProcessor` bean, to replace its runtime behavior. -For instance <> implements this interface to generate code that injects members annotated with `@Autowired`. +For instance xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp-examples-aabpp[`AutowiredAnnotationBeanPostProcessor`] implements this interface to generate code that injects members annotated with `@Autowired`. * Implemented by a type registered in `META-INF/spring/aot.factories` with a key equal to the fully qualified name of the interface. Typically used when the bean definition needs to be tuned for specific features of the core framework. diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc index 8ae321e2b491..aa7f4fda1997 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc @@ -10,16 +10,16 @@ integrate such parsers into the Spring IoC container. To facilitate authoring configuration files that use a schema-aware XML editor, Spring's extensible XML configuration mechanism is based on XML Schema. If you are not familiar with Spring's current XML configuration extensions that come with the standard -Spring distribution, you should first read the previous section on <>. +Spring distribution, you should first read the previous section on xref:core/appendix/xsd-schemas.adoc[XML Schemas]. To create new XML configuration extensions: -. <> an XML schema to describe your custom element(s). -. <> a custom `NamespaceHandler` implementation. -. <> one or more `BeanDefinitionParser` implementations +. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-schema[Author] an XML schema to describe your custom element(s). +. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-namespacehandler[Code] a custom `NamespaceHandler` implementation. +. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-parser[Code] one or more `BeanDefinitionParser` implementations (this is where the real work is done). -. <> your new artifacts with Spring. +. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-registration[Register] your new artifacts with Spring. For a unified example, we create an XML extension (a custom XML element) that lets us configure objects of the type @@ -129,7 +129,7 @@ The `NamespaceHandler` interface features three methods: * `BeanDefinitionHolder decorate(Node, BeanDefinitionHolder, ParserContext)`: Called when Spring encounters an attribute or nested element of a different namespace. The decoration of one or more bean definitions is used (for example) with the - <>. + xref:core/beans/factory-scopes.adoc[scopes that Spring supports]. We start by highlighting a simple example, without using decoration, after which we show decoration in a somewhat more advanced example. @@ -541,7 +541,7 @@ setter property for the `components` property. The following listing shows such This works nicely, but it exposes a lot of Spring plumbing to the end user. What we are going to do is write a custom extension that hides away all of this Spring plumbing. -If we stick to <>, we start off +If we stick to xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-introduction[the steps described previously], we start off by creating the XSD schema to define the structure of our custom tag, as the following listing shows: @@ -568,7 +568,7 @@ listing shows: ---- -Again following <>, +Again following xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-introduction[the process described earlier], we then create a custom `NamespaceHandler`: [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc index c5ab44c73adc..a948355129a1 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc @@ -312,7 +312,7 @@ Consider the following example: The preceding configuration uses a Spring `FactoryBean` implementation (the `PropertiesFactoryBean`) to instantiate a `java.util.Properties` instance with values -loaded from the supplied <> location). +loaded from the supplied xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[`Resource`] location). The following example uses a `util:properties` element to make a more concise representation: @@ -494,8 +494,8 @@ If no `set-class` attribute is supplied, the container chooses a `Set` implement The `aop` tags deal with configuring all things AOP in Spring, including Spring's own proxy-based AOP framework and Spring's integration with the AspectJ AOP framework. -These tags are comprehensively covered in the chapter entitled <>. +These tags are comprehensively covered in the chapter entitled xref:core/aop.adoc[Aspect Oriented Programming with Spring] +. In the interest of completeness, to use the tags in the `aop` schema, you need to have the following preamble at the top of your Spring XML configuration file (the text in the @@ -548,9 +548,9 @@ available to you: === Using `` This element activates the replacement of `${...}` placeholders, which are resolved against a -specified properties file (as a <>). This element -is a convenience mechanism that sets up a <> for you. If you need more control over the specific +specified properties file (as a xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Spring resource location]). This element +is a convenience mechanism that sets up a xref:core/beans/factory-extension.adoc#beans-factory-placeholderconfigurer[`PropertySourcesPlaceholderConfigurer`] + for you. If you need more control over the specific `PropertySourcesPlaceholderConfigurer` setup, you can explicitly define it as a bean yourself. @@ -559,50 +559,50 @@ is a convenience mechanism that sets up a <> model -* <>, `@Value`, and `@Lookup` +* Spring's xref:core/beans/basics.adoc#beans-factory-metadata[`@Configuration`] model +* xref:core/beans/annotation-config.adoc[`@Autowired`/`@Inject`], `@Value`, and `@Lookup` * JSR-250's `@Resource`, `@PostConstruct`, and `@PreDestroy` (if available) * JAX-WS's `@WebServiceRef` and EJB 3's `@EJB` (if available) * JPA's `@PersistenceContext` and `@PersistenceUnit` (if available) -* Spring's <> +* Spring's xref:core/beans/context-introduction.adoc#context-functionality-events-annotation[`@EventListener`] Alternatively, you can choose to explicitly activate the individual `BeanPostProcessors` for those annotations. NOTE: This element does not activate processing of Spring's -<> annotation; +xref:data-access/transaction/declarative/annotations.adoc[`@Transactional`] annotation; you can use the <`>> element for that purpose. Similarly, Spring's -<> need to be explicitly -<> as well. +xref:integration/cache/annotations.adoc[caching annotations] need to be explicitly +xref:integration/cache/annotations.adoc#cache-annotation-enable[enabled] as well. [[core.appendix.xsd-schemas-context-component-scan]] === Using `` -This element is detailed in the section on <>. +This element is detailed in the section on xref:core/beans/annotation-config.adoc[annotation-based container configuration] +. [[core.appendix.xsd-schemas-context-ltw]] === Using `` -This element is detailed in the section on <>. +This element is detailed in the section on xref:core/aop/using-aspectj.adoc#aop-aj-ltw[load-time weaving with AspectJ in the Spring Framework] +. [[core.appendix.xsd-schemas-context-sc]] === Using `` -This element is detailed in the section on <>. +This element is detailed in the section on xref:core/aop/using-aspectj.adoc#aop-atconfigurable[using AspectJ to dependency inject domain objects with Spring] +. [[core.appendix.xsd-schemas-context-mbe]] === Using `` -This element is detailed in the section on <>. +This element is detailed in the section on xref:integration/jmx/naming.adoc#jmx-context-mbeanexport[configuring annotation-based MBean export] +. @@ -612,13 +612,13 @@ configuring annotation-based MBean export>>. Last but not least, we have the elements in the `beans` schema. These elements have been in Spring since the very dawn of the framework. Examples of the various elements in the `beans` schema are not shown here because they are quite comprehensively covered -in <> -(and, indeed, in that entire <>). +in xref:core/beans/dependencies/factory-properties-detailed.adoc[dependencies and configuration in detail] +(and, indeed, in that entire xref:web/webmvc-view/mvc-xslt.adoc#mvc-view-xslt-beandefs[chapter]). Note that you can add zero or more key-value pairs to `` XML definitions. What, if anything, is done with this extra metadata is totally up to your own custom logic (and so is typically only of use if you write your own custom elements as described -in the appendix entitled <>). +in the appendix entitled xref:core/appendix/xml-custom.adoc[XML Schema Authoring]). The following example shows the `` element in the context of a surrounding `` (note that, without any logic to interpret it, the metadata is effectively useless diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc index 5c6d43e19d10..c369aaa71514 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc @@ -14,7 +14,7 @@ while others argue that annotated classes are no longer POJOs and, furthermore, configuration becomes decentralized and harder to control. No matter the choice, Spring can accommodate both styles and even mix them together. -It is worth pointing out that through its <> option, Spring lets +It is worth pointing out that through its xref:core/beans/java.adoc[JavaConfig] option, Spring lets annotations be used in a non-invasive way, without touching the target components' source code and that, in terms of tooling, all configuration styles are supported by https://spring.io/tools[Spring Tools] for Eclipse, Visual Studio Code, and Theia. @@ -24,15 +24,15 @@ An alternative to XML setup is provided by annotation-based configuration, which on bytecode metadata for wiring up components instead of XML declarations. Instead of using XML to describe a bean wiring, the developer moves the configuration into the component class itself by using annotations on the relevant class, method, or field -declaration. As mentioned in <>, using a +declaration. As mentioned in xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp-examples-aabpp[Example: The `AutowiredAnnotationBeanPostProcessor`], using a `BeanPostProcessor` in conjunction with annotations is a common means of extending the -Spring IoC container. For example, the <> -annotation provides the same capabilities as described in <> but +Spring IoC container. For example, the xref:core/beans/annotation-config/autowired.adoc[`@Autowired`] +annotation provides the same capabilities as described in xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators] but with more fine-grained control and wider applicability. In addition, Spring provides support for JSR-250 annotations, such as `@PostConstruct` and `@PreDestroy`, as well as support for JSR-330 (Dependency Injection for Java) annotations contained in the `jakarta.inject` package such as `@Inject` and `@Named`. Details about those annotations -can be found in the <>. +can be found in the xref:core/beans/standard-annotations.adoc[relevant section]. [NOTE] ==== @@ -74,7 +74,7 @@ The `` element implicitly registers the following po application context in which it is defined. This means that, if you put `` in a `WebApplicationContext` for a `DispatcherServlet`, it only checks for `@Autowired` beans in your controllers, and not your services. See -<> for more information. +xref:web/webmvc/mvc-servlet.adoc[The DispatcherServlet] for more information. ==== diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc index 5d2c314078d1..a63b5e8bbae1 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc @@ -296,8 +296,8 @@ demonstrates both approaches: ---- -- -In <>, you can see an annotation-based alternative to -providing the qualifier metadata in XML. Specifically, see <>. +In xref:core/beans/classpath-scanning.adoc[Classpath Scanning and Managed Components], you can see an annotation-based alternative to +providing the qualifier metadata in XML. Specifically, see xref:core/beans/classpath-scanning.adoc#beans-scanning-qualifiers[Providing Qualifier Metadata with Annotations]. In some cases, using an annotation without a value may suffice. This can be useful when the annotation serves a more generic purpose and can be applied across diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc index d63163b1957b..2e5f36016b6c 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc @@ -4,7 +4,7 @@ [NOTE] ==== JSR 330's `@Inject` annotation can be used in place of Spring's `@Autowired` annotation in the -examples included in this section. See <> for more details. +examples included in this section. See xref:core/beans/standard-annotations.adoc[here] for more details. ==== You can apply the `@Autowired` annotation to constructors, as the following example shows: @@ -38,7 +38,7 @@ necessary if the target bean defines only one constructor to begin with. However several constructors are available and there is no primary/default constructor, at least one of the constructors must be annotated with `@Autowired` in order to instruct the container which one to use. See the discussion on -<> for details. +xref:core/beans/annotation-config/autowired.adoc#beans-autowired-annotation-constructor-resolution[constructor resolution] for details. ==== You can also apply the `@Autowired` annotation to _traditional_ setter methods, diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc index 919410020245..391158c84ab7 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc @@ -5,8 +5,8 @@ The `CommonAnnotationBeanPostProcessor` not only recognizes the `@Resource` anno but also the JSR-250 lifecycle annotations: `jakarta.annotation.PostConstruct` and `jakarta.annotation.PreDestroy`. Introduced in Spring 2.5, the support for these annotations offers an alternative to the lifecycle callback mechanism described in -<> and -<>. Provided that the +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[initialization callbacks] and +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[destruction callbacks]. Provided that the `CommonAnnotationBeanPostProcessor` is registered within the Spring `ApplicationContext`, a method carrying one of these annotations is invoked at the same point in the lifecycle as the corresponding Spring lifecycle interface method or explicitly declared callback @@ -47,7 +47,7 @@ cleared upon destruction: ---- For details about the effects of combining various lifecycle mechanisms, see -<>. +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-combined-effects[Combining Lifecycle Mechanisms]. [NOTE] ==== diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc index 7a5dd0a83a6e..006d8da85e3a 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc @@ -149,7 +149,7 @@ provide conversion support for your own custom type, you can provide your own } ---- -When `@Value` contains a <> the value will be dynamically +When `@Value` contains a xref:core/expressions.adoc[`SpEL` expression] the value will be dynamically computed at runtime as the following example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] diff --git a/framework-docs/modules/ROOT/pages/core/beans/basics.adoc b/framework-docs/modules/ROOT/pages/core/beans/basics.adoc index d0c464344851..c38218c32cf7 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/basics.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/basics.adoc @@ -22,7 +22,7 @@ additional metadata formats. In most application scenarios, explicit user code is not required to instantiate one or more instances of a Spring IoC container. For example, in a web application scenario, a simple eight (or so) lines of boilerplate web descriptor XML in the `web.xml` file -of the application typically suffices (see <>). If you use the +of the application typically suffices (see xref:core/beans/context-introduction.adoc#context-create[Convenient ApplicationContext Instantiation for Web Applications]). If you use the https://spring.io/tools[Spring Tools for Eclipse] (an Eclipse-powered development environment), you can easily create this boilerplate configuration with a few mouse clicks or keystrokes. @@ -52,13 +52,13 @@ Spring IoC container. NOTE: XML-based metadata is not the only allowed form of configuration metadata. The Spring IoC container itself is totally decoupled from the format in which this configuration metadata is actually written. These days, many developers choose -<> for their Spring applications. +xref:core/beans/java.adoc[Java-based configuration] for their Spring applications. For information about using other forms of metadata with the Spring container, see: -* <>: define beans using +* xref:core/beans/annotation-config.adoc[Annotation-based configuration]: define beans using annotation-based configuration metadata. -* <>: define beans external to your application +* xref:core/beans/java.adoc[Java-based configuration]: define beans external to your application classes by using Java rather than XML files. To use these features, see the {api-spring-framework}/context/annotation/Configuration.html[`@Configuration`], {api-spring-framework}/context/annotation/Bean.html[`@Bean`], @@ -107,7 +107,7 @@ class name. The value of the `id` attribute can be used to refer to collaborating objects. The XML for referring to collaborating objects is not shown in this example. See -<> for more information. +xref:core/beans/dependencies.adoc[Dependencies] for more information. @@ -133,9 +133,9 @@ as the local file system, the Java `CLASSPATH`, and so on. [NOTE] ==== After you learn about Spring's IoC container, you may want to know more about Spring's -`Resource` abstraction (as described in <>), which provides a convenient +`Resource` abstraction (as described in xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Resources]), which provides a convenient mechanism for reading an InputStream from locations defined in a URI syntax. In particular, -`Resource` paths are used to construct applications contexts, as described in <>. +`Resource` paths are used to construct applications contexts, as described in xref:core/resources.adoc#resources-app-ctx[Application Contexts and Resource Paths]. ==== The following example shows the service layer objects `(services.xml)` configuration file: @@ -191,7 +191,7 @@ on the JPA Object-Relational Mapping standard). The `property name` element refe name of the JavaBean property, and the `ref` element refers to the name of another bean definition. This linkage between `id` and `ref` elements expresses the dependency between collaborating objects. For details of configuring an object's dependencies, see -<>. +xref:core/beans/dependencies.adoc[Dependencies]. [[beans-factory-xml-import]] @@ -202,7 +202,7 @@ XML configuration file represents a logical layer or module in your architecture You can use the application context constructor to load bean definitions from all these XML fragments. This constructor takes multiple `Resource` locations, as was shown in the -<>. Alternatively, use one or more +xref:core/beans/basics.adoc#beans-factory-instantiation[previous section]. Alternatively, use one or more occurrences of the `` element to load bean definitions from another file or files. The following example shows how to do so: diff --git a/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc b/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc index b8ca8fc3f274..e88c5d196c7a 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc @@ -43,7 +43,7 @@ by convention (that is, by bean name or by bean type -- in particular, post-proc while a plain `DefaultListableBeanFactory` is agnostic about any special beans. For many extended container features, such as annotation processing and AOP proxying, -the <> is essential. +the xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp[`BeanPostProcessor` extension point] is essential. If you use only a plain `DefaultListableBeanFactory`, such post-processors do not get detected and activated by default. This situation could be confusing, because nothing is actually wrong with your bean configuration. Rather, in such a scenario, diff --git a/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc b/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc index 64b3bcf146ab..e595b82d6080 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc @@ -3,7 +3,7 @@ Most examples in this chapter use XML to specify the configuration metadata that produces each `BeanDefinition` within the Spring container. The previous section -(<>) demonstrates how to provide a lot of the configuration +(xref:core/beans/annotation-config.adoc[Annotation-based Container Configuration]) demonstrates how to provide a lot of the configuration metadata through source-level annotations. Even in those examples, however, the "base" bean definitions are explicitly defined in the XML file, while the annotations drive only the dependency injection. This section describes an option for implicitly detecting the @@ -29,7 +29,7 @@ use these features. The `@Repository` annotation is a marker for any class that fulfills the role or stereotype of a repository (also known as Data Access Object or DAO). Among the uses of this marker is the automatic translation of exceptions, as described in -<>. +xref:data-access/orm/general.adoc#orm-exception-translation[Exception Translation]. Spring provides further stereotype annotations: `@Component`, `@Service`, and `@Controller`. `@Component` is a generic stereotype for any Spring-managed component. @@ -52,7 +52,7 @@ supported as a marker for automatic exception translation in your persistence la Many of the annotations provided by Spring can be used as meta-annotations in your own code. A meta-annotation is an annotation that can be applied to another annotation. -For example, the `@Service` annotation mentioned <> +For example, the `@Service` annotation mentioned xref:core/beans/classpath-scanning.adoc#beans-stereotype-annotations[earlier] is meta-annotated with `@Component`, as the following example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -723,7 +723,7 @@ definitions, there is no notion of bean definition inheritance, and inheritance hierarchies at the class level are irrelevant for metadata purposes. For details on web-specific scopes such as "`request`" or "`session`" in a Spring context, -see <>. As with the pre-built annotations for those scopes, +see xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other[Request, Session, Application, and WebSocket Scopes]. As with the pre-built annotations for those scopes, you may also compose your own scoping annotations by using Spring's meta-annotation approach: for example, a custom annotation meta-annotated with `@Scope("prototype")`, possibly also declaring a custom scoped-proxy mode. @@ -762,7 +762,7 @@ an annotation and a bean definition shows: ---- When using certain non-singleton scopes, it may be necessary to generate proxies for the -scoped objects. The reasoning is described in <>. +scoped objects. The reasoning is described in xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[Scoped Beans as Dependencies]. For this purpose, a scoped-proxy attribute is available on the component-scan element. The three possible values are: `no`, `interfaces`, and `targetClass`. For example, the following configuration results in standard JDK dynamic proxies: @@ -798,7 +798,7 @@ the following configuration results in standard JDK dynamic proxies: [[beans-scanning-qualifiers]] == Providing Qualifier Metadata with Annotations -The `@Qualifier` annotation is discussed in <>. +The `@Qualifier` annotation is discussed in xref:core/beans/annotation-config/autowired-qualifiers.adoc[Fine-tuning Annotation-based Autowiring with Qualifiers]. The examples in that section demonstrate the use of the `@Qualifier` annotation and custom qualifier annotations to provide fine-grained control when you resolve autowire candidates. Because those examples were based on XML bean definitions, the qualifier @@ -930,7 +930,7 @@ on the classpath. If an index is partially available for some libraries (or use but could not be built for the whole application, you can fall back to a regular classpath arrangement (as though no index were present at all) by setting `spring.index.ignore` to `true`, either as a JVM system property or via the -<> mechanism. +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism. diff --git a/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc b/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc index d568e9b3ac40..4caec82ef440 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc @@ -1,7 +1,7 @@ [[context-introduction]] = Additional Capabilities of the `ApplicationContext` -As discussed in the <>, the `org.springframework.beans.factory` +As discussed in the xref:web/webmvc-view/mvc-xslt.adoc#mvc-view-xslt-beandefs[chapter introduction], the `org.springframework.beans.factory` package provides basic functionality for managing and manipulating beans, including in a programmatic way. The `org.springframework.context` package adds the {api-spring-framework}/context/ApplicationContext.html[`ApplicationContext`] @@ -266,7 +266,7 @@ class and the `ApplicationListener` interface. If a bean that implements the Essentially, this is the standard Observer design pattern. TIP: As of Spring 4.2, the event infrastructure has been significantly improved and offers -an <> as well as the +an xref:core/beans/context-introduction.adoc#context-functionality-events-annotation[annotation-based model] as well as the ability to publish any arbitrary event (that is, an object that does not necessarily extend from `ApplicationEvent`). When such an object is published, we wrap it in an event for you. @@ -555,7 +555,7 @@ following example shows how to do so: ---- It is also possible to add additional runtime filtering by using the `condition` attribute -of the annotation that defines a <>, which should match +of the annotation that defines a xref:core/expressions.adoc[`SpEL` expression], which should match to actually invoke the method for a particular event. The following example shows how our notifier can be rewritten to be invoked only if the @@ -631,7 +631,7 @@ method signature to return the event that should be published, as the following ---- NOTE: This feature is not supported for -<>. +xref:core/beans/context-introduction.adoc#context-functionality-events-async[asynchronous listeners]. The `handleBlockedListEvent()` method publishes a new `ListUpdateEvent` for every `BlockedListEvent` that it handles. If you need to publish several events, you can return @@ -642,7 +642,7 @@ a `Collection` or an array of events instead. === Asynchronous Listeners If you want a particular listener to process events asynchronously, you can reuse the -<>. +xref:integration/scheduling.adoc#scheduling-annotation-support-async[regular `@Async` support]. The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -771,7 +771,7 @@ an event. == Convenient Access to Low-level Resources For optimal usage and understanding of application contexts, you should familiarize -yourself with Spring's `Resource` abstraction, as described in <>. +yourself with Spring's `Resource` abstraction, as described in xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Resources]. An application context is a `ResourceLoader`, which can be used to load `Resource` objects. A `Resource` is essentially a more feature rich version of the JDK `java.net.URL` class. @@ -847,7 +847,7 @@ Here is an example of instrumentation in the `AnnotationConfigApplicationContext The application context is already instrumented with multiple steps. Once recorded, these startup steps can be collected, displayed and analyzed with specific tools. For a complete list of existing startup steps, you can check out the -<>. +xref:core/appendix/application-startup-steps.adoc[dedicated appendix section]. The default `ApplicationStartup` implementation is a no-op variant, for minimal overhead. This means no metrics will be collected during application startup by default. diff --git a/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc b/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc index 249ef15f3806..c7280792b3ff 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc @@ -35,11 +35,11 @@ Alternatively, for XML configuration, you can use the `context:load-time-weaver` Once configured for the `ApplicationContext`, any bean within that `ApplicationContext` may implement `LoadTimeWeaverAware`, thereby receiving a reference to the load-time weaver instance. This is particularly useful in combination with -<> where load-time weaving may be +xref:data-access/orm/jpa.adoc[Spring's JPA support] where load-time weaving may be necessary for JPA class transformation. Consult the {api-spring-framework}/orm/jpa/LocalContainerEntityManagerFactoryBean.html[`LocalContainerEntityManagerFactoryBean`] -javadoc for more detail. For more on AspectJ load-time weaving, see <>. +javadoc for more detail. For more on AspectJ load-time weaving, see xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework]. diff --git a/framework-docs/modules/ROOT/pages/core/beans/definition.adoc b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc index 7caf554ce272..48efa61acae9 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/definition.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc @@ -27,31 +27,31 @@ The following table describes these properties: | Property| Explained in... | Class -| <> +| xref:core/beans/definition.adoc#beans-factory-class[Instantiating Beans] | Name -| <> +| xref:core/beans/definition.adoc#beans-beanname[Naming Beans] | Scope -| <> +| xref:core/beans/factory-scopes.adoc[Bean Scopes] | Constructor arguments -| <> +| xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection] | Properties -| <> +| xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection] | Autowiring mode -| <> +| xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators] | Lazy initialization mode -| <> +| xref:core/beans/dependencies/factory-lazy-init.adoc[Lazy-initialized Beans] | Initialization method -| <> +| xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[Initialization Callbacks] | Destruction method -| <> +| xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[Destruction Callbacks] |=== In addition to bean definitions that contain information on how to create a specific @@ -95,8 +95,8 @@ You are not required to supply a `name` or an `id` for a bean. If you do not sup `name` or `id` explicitly, the container generates a unique name for that bean. However, if you want to refer to that bean by name, through the use of the `ref` element or a Service Locator style lookup, you must provide a name. -Motivations for not supplying a name are related to using <> and <>. +Motivations for not supplying a name are related to using xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-inner-beans[inner beans] + and xref:core/beans/dependencies/factory-autowire.adoc[autowiring collaborators]. .Bean Naming Conventions **** @@ -163,7 +163,7 @@ creating a namespace), yet they refer to the same bean. .Java-configuration **** If you use Java Configuration, the `@Bean` annotation can be used to provide aliases. -See <> for details. +See xref:core/beans/java/bean-annotation.adoc[Using the `@Bean` Annotation] for details. **** @@ -179,7 +179,7 @@ If you use XML-based configuration metadata, you specify the type (or class) of that is to be instantiated in the `class` attribute of the `` element. This `class` attribute (which, internally, is a `Class` property on a `BeanDefinition` instance) is usually mandatory. (For exceptions, see -<> and <>.) +xref:core/beans/definition.adoc#beans-factory-class-instance-factory-method[Instantiation by Using an Instance Factory Method] and xref:core/beans/child-bean-definitions.adoc[Bean Definition Inheritance].) You can use the `Class` property in one of two ways: * Typically, to specify the bean class to be constructed in the case where the container @@ -232,7 +232,7 @@ With XML-based configuration metadata you can specify your bean class as follows For details about the mechanism for supplying arguments to the constructor (if required) and setting object instance properties after the object is constructed, see -<>. +xref:core/beans/dependencies/factory-collaborators.adoc[Injecting Dependencies]. [[beans-factory-class-static-factory-method]] @@ -286,14 +286,14 @@ The following example shows a class that would work with the preceding bean defi For details about the mechanism for supplying (optional) arguments to the factory method and setting object instance properties after the object is returned from the factory, -see <>. +see xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail]. [[beans-factory-class-instance-factory-method]] === Instantiation by Using an Instance Factory Method -Similar to instantiation through a <>, instantiation with an instance factory method invokes a non-static +Similar to instantiation through a xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[static factory method] +, instantiation with an instance factory method invokes a non-static method of an existing bean from the container to create a new bean. To use this mechanism, leave the `class` attribute empty and, in the `factory-bean` attribute, specify the name of a bean in the current (or parent or ancestor) container that contains @@ -398,15 +398,15 @@ The following example shows the corresponding class: ---- This approach shows that the factory bean itself can be managed and configured through -dependency injection (DI). See <>. +dependency injection (DI). See xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail] +. NOTE: In Spring documentation, "factory bean" refers to a bean that is configured in the Spring container and that creates objects through an -<> or -<> factory method. By contrast, +xref:core/beans/definition.adoc#beans-factory-class-instance-factory-method[instance] or +xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[static] factory method. By contrast, `FactoryBean` (notice the capitalization) refers to a Spring-specific -<> implementation class. +xref:core/beans/factory-extension.adoc#beans-factory-extension-factorybean[`FactoryBean`] implementation class. [[beans-factory-type-determination]] diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc index 3ca999ae95d7..829fe815a81c 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc @@ -8,7 +8,7 @@ advantages: * Autowiring can significantly reduce the need to specify properties or constructor arguments. (Other mechanisms such as a bean template - <> are also valuable + xref:core/beans/child-bean-definitions.adoc[discussed elsewhere in this chapter] are also valuable in this regard.) * Autowiring can update a configuration as your objects evolve. For example, if you need to add a dependency to a class, that dependency can be satisfied automatically without @@ -16,7 +16,7 @@ advantages: during development, without negating the option of switching to explicit wiring when the code base becomes more stable. -When using XML-based configuration metadata (see <>), you +When using XML-based configuration metadata (see xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection]), you can specify the autowire mode for a bean definition with the `autowire` attribute of the `` element. The autowiring functionality has four modes. You specify autowiring per bean and can thus choose which ones to autowire. The following table describes the @@ -89,11 +89,11 @@ In the latter scenario, you have several options: * Abandon autowiring in favor of explicit wiring. * Avoid autowiring for a bean definition by setting its `autowire-candidate` attributes - to `false`, as described in the <>. + to `false`, as described in the xref:core/beans/dependencies/factory-autowire.adoc#beans-factory-autowire-candidate[next section]. * Designate a single bean definition as the primary candidate by setting the `primary` attribute of its `` element to `true`. * Implement the more fine-grained control available with annotation-based configuration, - as described in <>. + as described in xref:core/beans/annotation-config.adoc[Annotation-based Container Configuration]. @@ -103,8 +103,8 @@ In the latter scenario, you have several options: On a per-bean basis, you can exclude a bean from autowiring. In Spring's XML format, set the `autowire-candidate` attribute of the `` element to `false`. The container makes that specific bean definition unavailable to the autowiring infrastructure -(including annotation style configurations such as <>). +(including annotation style configurations such as xref:core/beans/annotation-config/autowired.adoc[`@Autowired`] +). NOTE: The `autowire-candidate` attribute is designed to only affect type-based autowiring. It does not affect explicit references by name, which get resolved even if the diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc index 7d686d4e1364..becfead14bce 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc @@ -16,8 +16,8 @@ not know the location or class of the dependencies. As a result, your classes be to test, particularly when the dependencies are on interfaces or abstract base classes, which allow for stub or mock implementations to be used in unit tests. -DI exists in two major variants: <> and <>. +DI exists in two major variants: xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[Constructor-based dependency injection] + and xref:core/beans/dependencies/factory-collaborators.adoc#beans-setter-injection[Setter-based dependency injection]. [[beans-constructor-injection]] @@ -279,7 +279,7 @@ load an entire Spring IoC container instance. **** Since you can mix constructor-based and setter-based DI, it is a good rule of thumb to use constructors for mandatory dependencies and setter methods or configuration methods -for optional dependencies. Note that use of the <> +for optional dependencies. Note that use of the xref:core/beans/annotation-config/autowired.adoc[@Autowired] annotation on a setter method can be used to make the property be a required dependency; however, constructor injection with programmatic validation of arguments is preferable. @@ -294,7 +294,7 @@ Setter injection should primarily only be used for optional dependencies that ca assigned reasonable default values within the class. Otherwise, not-null checks must be performed everywhere the code uses the dependency. One benefit of setter injection is that setter methods make objects of that class amenable to reconfiguration or re-injection -later. Management through <> is therefore a compelling +later. Management through xref:integration/jmx.adoc[JMX MBeans] is therefore a compelling use case for setter injection. Use the DI style that makes the most sense for a particular class. Sometimes, when dealing @@ -326,7 +326,7 @@ The container performs bean dependency resolution as follows: The Spring container validates the configuration of each bean as the container is created. However, the bean properties themselves are not set until the bean is actually created. Beans that are singleton-scoped and set to be pre-instantiated (the default) are created -when the container is created. Scopes are defined in <>. Otherwise, +when the container is created. Scopes are defined in xref:core/beans/factory-scopes.adoc[Bean Scopes]. Otherwise, the bean is created only when it is requested. Creation of a bean potentially causes a graph of beans to be created, as the bean's dependencies and its dependencies' dependencies (and so on) are created and assigned. Note that resolution mismatches among @@ -373,8 +373,8 @@ to being injected into the dependent bean. This means that, if bean A has a depe bean B, the Spring IoC container completely configures bean B prior to invoking the setter method on bean A. In other words, the bean is instantiated (if it is not a pre-instantiated singleton), its dependencies are set, and the relevant lifecycle -methods (such as a <> -or the <>) +methods (such as a xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[configured init method] +or the xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[InitializingBean callback method]) are invoked. diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc index 988075e19d04..17e5e98246bb 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc @@ -31,7 +31,7 @@ delimiters): ---- NOTE: The `depends-on` attribute can specify both an initialization-time dependency and, -in the case of <> beans only, a corresponding +in the case of xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton] beans only, a corresponding destruction-time dependency. Dependent beans that define a `depends-on` relationship with a given bean are destroyed first, prior to the given bean itself being destroyed. Thus, `depends-on` can also control shutdown order. diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc index cbb8eeb36111..59fd3a319b9e 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc @@ -2,7 +2,7 @@ = Lazy-initialized Beans By default, `ApplicationContext` implementations eagerly create and configure all -<> beans as part of the initialization +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton] beans as part of the initialization process. Generally, this pre-instantiation is desirable, because errors in the configuration or surrounding environment are discovered immediately, as opposed to hours or even days later. When this behavior is not desirable, you can prevent diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc index 5f97b946fdef..18742fe6e1b8 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc @@ -2,7 +2,7 @@ = Method Injection In most application scenarios, most beans in the container are -<>. When a singleton bean needs to +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singletons]. When a singleton bean needs to collaborate with another singleton bean or a non-singleton bean needs to collaborate with another non-singleton bean, you typically handle the dependency by defining one bean as a property of the other. A problem arises when the bean lifecycles are @@ -11,9 +11,9 @@ perhaps on each method invocation on A. The container creates the singleton bean once, and thus only gets one opportunity to set the properties. The container cannot provide bean A with a new instance of bean B every time one is needed. -A solution is to forego some inversion of control. You can <> by implementing the `ApplicationContextAware` interface, -and by <> ask for (a +A solution is to forego some inversion of control. You can xref:core/beans/factory-nature.adoc#beans-factory-aware[make bean A aware of the container] + by implementing the `ApplicationContextAware` interface, +and by xref:core/beans/basics.adoc#beans-factory-client[making a `getBean("B")` call to the container] ask for (a typically new) bean B instance every time bean A needs it. The following example shows this approach: @@ -104,7 +104,7 @@ https://spring.io/blog/2004/08/06/method-injection/[this blog entry]. Lookup method injection is the ability of the container to override methods on container-managed beans and return the lookup result for another named bean in the container. The lookup typically involves a prototype bean, as in the scenario described -in <>. The Spring Framework +in xref:core/beans/dependencies/factory-method-injection.adoc[the preceding section]. The Spring Framework implements this method injection by using bytecode generation from the CGLIB library to dynamically generate a subclass that overrides the method. @@ -198,7 +198,7 @@ the original class. Consider the following example: The bean identified as `commandManager` calls its own `createCommand()` method whenever it needs a new instance of the `myCommand` bean. You must be careful to deploy the `myCommand` bean as a prototype if that is actually what is needed. If it is -a <>, the same instance of the `myCommand` +a xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton], the same instance of the `myCommand` bean is returned each time. Alternatively, within the annotation-based component model, you can declare a lookup @@ -277,7 +277,7 @@ apply to explicitly registered or explicitly imported bean classes. [TIP] ==== Another way of accessing differently scoped target beans is an `ObjectFactory`/ -`Provider` injection point. See <>. +`Provider` injection point. See xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[Scoped Beans as Dependencies]. You may also find the `ServiceLocatorFactoryBean` (in the `org.springframework.beans.factory.config` package) to be useful. diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc index 0453dc43ca9b..25b41d07a76c 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc @@ -1,7 +1,7 @@ [[beans-factory-properties-detailed]] = Dependencies and Configuration in Detail -As mentioned in the <>, you can define bean +As mentioned in the xref:core/beans/dependencies/factory-collaborators.adoc[previous section], you can define bean properties and constructor arguments as references to other managed beans (collaborators) or as values defined inline. Spring's XML-based configuration metadata supports sub-element types within its `` and `` elements for this @@ -13,7 +13,7 @@ purpose. The `value` attribute of the `` element specifies a property or constructor argument as a human-readable string representation. Spring's -<> is used to convert these +xref:core/validation/convert.adoc#core-convert-ConversionService-API[conversion service] is used to convert these values from a `String` to the actual type of the property or argument. The following example shows various values being set: @@ -28,7 +28,7 @@ The following example shows various values being set: ---- -The following example uses the <> for even more succinct +The following example uses the xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-p-namespace[p-namespace] for even more succinct XML configuration: [source,xml,indent=0,subs="verbatim,quotes"] @@ -112,7 +112,7 @@ container validate at deployment time that the referenced, named bean actually exists. In the second variation, no validation is performed on the value that is passed to the `targetName` property of the `client` bean. Typos are only discovered (with most likely fatal results) when the `client` bean is actually instantiated. If the `client` -bean is a <> bean, this typo and the resulting exception +bean is a xref:core/beans/factory-scopes.adoc[prototype] bean, this typo and the resulting exception may only be discovered long after the container is deployed. NOTE: The `local` attribute on the `idref` element is no longer supported in the 4.0 beans @@ -120,7 +120,7 @@ XSD, since it does not provide value over a regular `bean` reference any more. C your existing `idref local` references to `idref bean` when upgrading to the 4.0 schema. A common place (at least in versions earlier than Spring 2.0) where the `` element -brings value is in the configuration of <> in a +brings value is in the configuration of xref:core/aop-api/pfb.adoc#aop-pfb-1[AOP interceptors] in a `ProxyFactoryBean` bean definition. Using `` elements when you specify the interceptor names prevents you from misspelling an interceptor ID. @@ -277,7 +277,7 @@ collection elements overriding values specified in the parent collection. This section on merging discusses the parent-child bean mechanism. Readers unfamiliar with parent and child bean definitions may wish to read the -<> before continuing. +xref:core/beans/child-bean-definitions.adoc[relevant section] before continuing. The following example demonstrates collection merging: @@ -451,7 +451,7 @@ The preceding configuration is equivalent to the following Java code: The p-namespace lets you use the `bean` element's attributes (instead of nested `` elements) to describe your property values collaborating beans, or both. -Spring supports extensible configuration formats <>, +Spring supports extensible configuration formats xref:core/appendix/xsd-schemas.adoc[with namespaces], which are based on an XML Schema definition. The `beans` configuration format discussed in this chapter is defined in an XML Schema document. However, the p-namespace is not defined in an XSD file and exists only in the core of Spring. @@ -526,12 +526,12 @@ three approaches at the same time. [[beans-c-namespace]] == XML Shortcut with the c-namespace -Similar to the <>, the c-namespace, introduced in Spring +Similar to the xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-p-namespace[XML Shortcut with the p-namespace], the c-namespace, introduced in Spring 3.1, allows inlined attributes for configuring the constructor arguments rather then nested `constructor-arg` elements. The following example uses the `c:` namespace to do the same thing as the from -<>: +xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[Constructor-based Dependency Injection]: [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -580,7 +580,7 @@ A corresponding index notation is also available for `` element not commonly used since the plain order of declaration is usually sufficient there. In practice, the constructor resolution -<> is quite efficient in matching +xref:core/beans/dependencies/factory-collaborators.adoc#beans-factory-ctor-arguments-resolution[mechanism] is quite efficient in matching arguments, so unless you really need to, we recommend using the name notation throughout your configuration. diff --git a/framework-docs/modules/ROOT/pages/core/beans/environment.adoc b/framework-docs/modules/ROOT/pages/core/beans/environment.adoc index 9c51906bdac9..137e0c32b4e8 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/environment.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/environment.adoc @@ -3,8 +3,8 @@ The {api-spring-framework}/core/env/Environment.html[`Environment`] interface is an abstraction integrated in the container that models two key -aspects of the application environment: <> -and <>. +aspects of the application environment: xref:core/beans/environment.adoc#beans-definition-profiles[profiles] +and xref:core/beans/environment.adoc#beans-property-source-abstraction[properties]. A profile is a named, logical group of bean definitions to be registered with the container only if the given profile is active. Beans may be assigned to a profile @@ -200,7 +200,7 @@ NOTE: You cannot mix the `&` and `|` operators without using parentheses. For ex `production & us-east | eu-central` is not a valid expression. It must be expressed as `production & (us-east | eu-central)`. -You can use `@Profile` as a <> for the purpose +You can use `@Profile` as a xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotation] for the purpose of creating a custom composed annotation. The following example defines a custom `@Production` annotation that you can use as a drop-in replacement for `@Profile("production")`: @@ -437,10 +437,10 @@ it programmatically against the `Environment` API which is available through an In addition, you can also declaratively activate profiles through the `spring.profiles.active` property, which may be specified through system environment variables, JVM system properties, servlet context parameters in `web.xml`, or even as an -entry in JNDI (see <>). In integration tests, active +entry in JNDI (see xref:core/beans/environment.adoc#beans-property-source-abstraction[`PropertySource` Abstraction]). In integration tests, active profiles can be declared by using the `@ActiveProfiles` annotation in the `spring-test` -module (see <>). +module (see xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[context configuration with environment profiles] +). Note that profiles are not an "`either-or`" proposition. You can activate multiple profiles at once. Programmatically, you can provide multiple profile names to the diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc index 51a30ee61062..df156b2372f8 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc @@ -24,8 +24,8 @@ interface. If you write your own `BeanPostProcessor`, you should consider implem the `Ordered` interface, too. For further details, see the javadoc of the {api-spring-framework}/beans/factory/config/BeanPostProcessor.html[`BeanPostProcessor`] and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces. See also the note -on <>. +on xref:core/beans/factory-extension.adoc#beans-factory-programmatically-registering-beanpostprocessors[programmatic registration of `BeanPostProcessor` instances] +. [NOTE] ==== @@ -41,7 +41,7 @@ another container, even if both containers are part of the same hierarchy. To change the actual bean definition (that is, the blueprint that defines the bean), you instead need to use a `BeanFactoryPostProcessor`, as described in -<>. +xref:core/beans/factory-extension.adoc#beans-factory-extension-factory-postprocessors[Customizing Configuration Metadata with a `BeanFactoryPostProcessor`]. ==== The `org.springframework.beans.factory.config.BeanPostProcessor` interface consists of @@ -192,7 +192,7 @@ Notice how the `InstantiationTracingBeanPostProcessor` is merely defined. It doe even have a name, and, because it is a bean, it can be dependency-injected as you would any other bean. (The preceding configuration also defines a bean that is backed by a Groovy script. The Spring dynamic language support is detailed in the chapter entitled -<>.) +xref:languages/dynamic.adoc[Dynamic Language Support].) The following Java application runs the preceding code and configuration: @@ -268,7 +268,7 @@ and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces for more deta ==== If you want to change the actual bean instances (that is, the objects that are created from the configuration metadata), then you instead need to use a `BeanPostProcessor` -(described earlier in <>). While it is technically possible +(described earlier in xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp[Customizing Beans by Using a `BeanPostProcessor`]). While it is technically possible to work with bean instances within a `BeanFactoryPostProcessor` (for example, by using `BeanFactory.getBean()`), doing so causes premature bean instantiation, violating the standard container lifecycle. This may cause negative side effects, such as bypassing diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc index 13cf361ed28b..b13f08e79529 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc @@ -4,9 +4,9 @@ The Spring Framework provides a number of interfaces you can use to customize the nature of a bean. This section groups them as follows: -* <> -* <> -* <> +* xref:core/beans/factory-nature.adoc#beans-factory-lifecycle[Lifecycle Callbacks] +* xref:core/beans/factory-nature.adoc#beans-factory-aware[`ApplicationContextAware` and `BeanNameAware`] +* xref:core/beans/factory-nature.adoc#aware-list[Other `Aware` Interfaces] @@ -23,7 +23,7 @@ perform certain actions upon initialization and destruction of your beans. The JSR-250 `@PostConstruct` and `@PreDestroy` annotations are generally considered best practice for receiving lifecycle callbacks in a modern Spring application. Using these annotations means that your beans are not coupled to Spring-specific interfaces. -For details, see <>. +For details, see xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[Using `@PostConstruct` and `@PreDestroy`]. If you do not want to use the JSR-250 annotations but you still want to remove coupling, consider `init-method` and `destroy-method` bean definition metadata. @@ -33,7 +33,7 @@ Internally, the Spring Framework uses `BeanPostProcessor` implementations to pro callback interfaces it can find and call the appropriate methods. If you need custom features or other lifecycle behavior Spring does not by default offer, you can implement a `BeanPostProcessor` yourself. For more information, see -<>. +xref:core/beans/factory-extension.adoc[Container Extension Points]. In addition to the initialization and destruction callbacks, Spring-managed objects may also implement the `Lifecycle` interface so that those objects can participate in the @@ -56,11 +56,11 @@ bean. The `InitializingBean` interface specifies a single method: We recommend that you do not use the `InitializingBean` interface, because it unnecessarily couples the code to Spring. Alternatively, we suggest using -the <> annotation or +the xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[`@PostConstruct`] annotation or specifying a POJO initialization method. In the case of XML-based configuration metadata, you can use the `init-method` attribute to specify the name of the method that has a void no-argument signature. With Java configuration, you can use the `initMethod` attribute of -`@Bean`. See <>. Consider the following example: +`@Bean`. See xref:core/beans/java/bean-annotation.adoc#beans-java-lifecycle-callbacks[Receiving Lifecycle Callbacks]. Consider the following example: [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -135,11 +135,11 @@ bean get a callback when the container that contains it is destroyed. The We recommend that you do not use the `DisposableBean` callback interface, because it unnecessarily couples the code to Spring. Alternatively, we suggest using -the <> annotation or +the xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[`@PreDestroy`] annotation or specifying a generic method that is supported by bean definitions. With XML-based configuration metadata, you can use the `destroy-method` attribute on the ``. With Java configuration, you can use the `destroyMethod` attribute of `@Bean`. See -<>. Consider the following definition: +xref:core/beans/java/bean-annotation.adoc#beans-java-lifecycle-callbacks[Receiving Lifecycle Callbacks]. Consider the following definition: [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -204,7 +204,7 @@ TIP: You can assign the `destroy-method` attribute of a `` element a speci `java.lang.AutoCloseable` or `java.io.Closeable` would therefore match.) You can also set this special `(inferred)` value on the `default-destroy-method` attribute of a `` element to apply this behavior to an entire set of beans (see -<>). Note that this is the +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-default-init-destroy-methods[Default Initialization and Destroy Methods]). Note that this is the default behavior with Java configuration. [[beans-factory-lifecycle-default-init-destroy-methods]] @@ -221,8 +221,8 @@ callback method names on every bean. This means that you, as an application developer, can write your application classes and use an initialization callback called `init()`, without having to configure an `init-method="init"` attribute with each bean definition. The Spring IoC container calls that method when the bean is created (and in -accordance with the standard lifecycle callback contract <>). This feature also enforces a consistent naming convention for +accordance with the standard lifecycle callback contract xref:core/beans/factory-nature.adoc#beans-factory-lifecycle[described previously] +). This feature also enforces a consistent naming convention for initialization and destroy method callbacks. Suppose that your initialization callback methods are named `init()` and your destroy @@ -308,18 +308,18 @@ interacts directly with the raw target bean. As of Spring 2.5, you have three options for controlling bean lifecycle behavior: -* The <> and -<> callback interfaces +* The xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[`InitializingBean`] and +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[`DisposableBean`] callback interfaces * Custom `init()` and `destroy()` methods -* The <>. You can combine these mechanisms to control a given bean. +* The xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[`@PostConstruct` and `@PreDestroy` annotations] +. You can combine these mechanisms to control a given bean. NOTE: If multiple lifecycle mechanisms are configured for a bean and each mechanism is configured with a different method name, then each configured method is run in the order listed after this note. However, if the same method name is configured -- for example, `init()` for an initialization method -- for more than one of these lifecycle mechanisms, that method is run once, as explained in the -<>. +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-default-init-destroy-methods[preceding section]. Multiple lifecycle mechanisms configured for the same bean, with different initialization methods, are called as follows: @@ -542,18 +542,18 @@ it couples the code to Spring and does not follow the Inversion of Control style where collaborators are provided to beans as properties. Other methods of the `ApplicationContext` provide access to file resources, publishing application events, and accessing a `MessageSource`. These additional features are described in -<>. +xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`]. Autowiring is another alternative to obtain a reference to the `ApplicationContext`. The _traditional_ `constructor` and `byType` autowiring modes -(as described in <>) can provide a dependency of type +(as described in xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators]) can provide a dependency of type `ApplicationContext` for a constructor argument or a setter method parameter, respectively. For more flexibility, including the ability to autowire fields and multiple parameter methods, use the annotation-based autowiring features. If you do, the `ApplicationContext` is autowired into a field, constructor argument, or method parameter that expects the `ApplicationContext` type if the field, constructor, or method in question carries the `@Autowired` annotation. For more information, see -<>. +xref:core/beans/annotation-config/autowired.adoc[Using `@Autowired`]. When an `ApplicationContext` creates a class that implements the `org.springframework.beans.factory.BeanNameAware` interface, the class is provided with @@ -577,7 +577,7 @@ init-method. [[aware-list]] == Other `Aware` Interfaces -Besides `ApplicationContextAware` and `BeanNameAware` (discussed <>), +Besides `ApplicationContextAware` and `BeanNameAware` (discussed xref:core/beans/factory-nature.adoc#beans-factory-aware[earlier]), Spring offers a wide range of `Aware` callback interfaces that let beans indicate to the container that they require a certain infrastructure dependency. As a general rule, the name indicates the dependency type. The following table summarizes the most important `Aware` interfaces: @@ -589,50 +589,50 @@ dependency type. The following table summarizes the most important `Aware` inter | `ApplicationContextAware` | Declaring `ApplicationContext`. -| <> +| xref:core/beans/factory-nature.adoc#beans-factory-aware[`ApplicationContextAware` and `BeanNameAware`] | `ApplicationEventPublisherAware` | Event publisher of the enclosing `ApplicationContext`. -| <> +| xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`] | `BeanClassLoaderAware` | Class loader used to load the bean classes. -| <> +| xref:core/beans/definition.adoc#beans-factory-class[Instantiating Beans] | `BeanFactoryAware` | Declaring `BeanFactory`. -| <> +| xref:core/beans/beanfactory.adoc[The `BeanFactory` API] | `BeanNameAware` | Name of the declaring bean. -| <> +| xref:core/beans/factory-nature.adoc#beans-factory-aware[`ApplicationContextAware` and `BeanNameAware`] | `LoadTimeWeaverAware` | Defined weaver for processing class definition at load time. -| <> +| xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework] | `MessageSourceAware` | Configured strategy for resolving messages (with support for parameterization and internationalization). -| <> +| xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`] | `NotificationPublisherAware` | Spring JMX notification publisher. -| <> +| xref:integration/jmx/notifications.adoc[Notifications] | `ResourceLoaderAware` | Configured loader for low-level access to resources. -| <> +| xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Resources] | `ServletConfigAware` | Current `ServletConfig` the container runs in. Valid only in a web-aware Spring `ApplicationContext`. -| <> +| xref:web/webmvc.adoc#mvc[Spring MVC] | `ServletContextAware` | Current `ServletContext` the container runs in. Valid only in a web-aware Spring `ApplicationContext`. -| <> +| xref:web/webmvc.adoc#mvc[Spring MVC] |=== Note again that using these interfaces ties your code to the Spring API and does not diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc index 7925a2504c70..06eb5eba3f5f 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc @@ -14,7 +14,7 @@ through configuration instead of having to bake in the scope of an object at the class level. Beans can be defined to be deployed in one of a number of scopes. The Spring Framework supports six scopes, four of which are available only if you use a web-aware `ApplicationContext`. You can also create -<> +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-custom[a custom scope.] The following table describes the supported scopes: @@ -24,27 +24,27 @@ The following table describes the supported scopes: |=== | Scope| Description -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton] | (Default) Scopes a single bean definition to a single object instance for each Spring IoC container. -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-prototype[prototype] | Scopes a single bean definition to any number of object instances. -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-request[request] | Scopes a single bean definition to the lifecycle of a single HTTP request. That is, each HTTP request has its own instance of a bean created off the back of a single bean definition. Only valid in the context of a web-aware Spring `ApplicationContext`. -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-session[session] | Scopes a single bean definition to the lifecycle of an HTTP `Session`. Only valid in the context of a web-aware Spring `ApplicationContext`. -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-application[application] | Scopes a single bean definition to the lifecycle of a `ServletContext`. Only valid in the context of a web-aware Spring `ApplicationContext`. -| <> +| xref:web/websocket/stomp/scope.adoc[websocket] | Scopes a single bean definition to the lifecycle of a `WebSocket`. Only valid in the context of a web-aware Spring `ApplicationContext`. |=== @@ -53,7 +53,7 @@ NOTE: A thread scope is available but is not registered by default. For more inf see the documentation for {api-spring-framework}/context/support/SimpleThreadScope.html[`SimpleThreadScope`]. For instructions on how to register this or any other custom scope, see -<>. +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-custom-using[Using a Custom Scope]. @@ -125,13 +125,13 @@ objects regardless of scope, in the case of prototypes, configured destruction lifecycle callbacks are not called. The client code must clean up prototype-scoped objects and release expensive resources that the prototype beans hold. To get the Spring container to release resources held by prototype-scoped beans, try using a -custom <>, which holds a reference to +custom xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp[bean post-processor], which holds a reference to beans that need to be cleaned up. In some respects, the Spring container's role in regard to a prototype-scoped bean is a replacement for the Java `new` operator. All lifecycle management past that point must be handled by the client. (For details on the lifecycle of a bean in the Spring -container, see <>.) +container, see xref:core/beans/factory-nature.adoc#beans-factory-lifecycle[Lifecycle Callbacks].) @@ -149,7 +149,7 @@ prototype-scoped bean repeatedly at runtime. You cannot dependency-inject a prototype-scoped bean into your singleton bean, because that injection occurs only once, when the Spring container instantiates the singleton bean and resolves and injects its dependencies. If you need a new instance of a prototype bean at -runtime more than once, see <>. +runtime more than once, see xref:core/beans/dependencies/factory-method-injection.adoc[Method Injection]. @@ -362,7 +362,7 @@ following example shows how to do so: WebSocket scope is associated with the lifecycle of a WebSocket session and applies to STOMP over WebSocket applications, see -<> for more details. +xref:web/websocket/stomp/scope.adoc[WebSocket scope] for more details. @@ -399,7 +399,7 @@ several additional access variants, including `getIfAvailable` and `getIfUnique` The JSR-330 variant of this is called `Provider` and is used with a `Provider` declaration and a corresponding `get()` call for every retrieval attempt. -See <> for more details on JSR-330 overall. +See xref:core/beans/standard-annotations.adoc[here] for more details on JSR-330 overall. ==== The configuration in the following example is only one line, but it is important to @@ -433,8 +433,8 @@ understand the "`why`" as well as the "`how`" behind it: To create such a proxy, you insert a child `` element into a scoped -bean definition (see <> and -<>). +bean definition (see xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection-proxies[Choosing the Type of Proxy to Create] and +xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration]). Why do definitions of beans scoped at the `request`, `session` and custom-scope levels require the `` element? Consider the following singleton bean definition and contrast it with @@ -521,7 +521,7 @@ interfaces. The following example shows a proxy based on an interface: ---- For more detailed information about choosing class-based or interface-based proxying, -see <>. +see xref:core/aop/proxying.adoc[Proxying Mechanisms]. diff --git a/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc b/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc index 8ceef04028d5..84fce22f428d 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc @@ -30,7 +30,7 @@ and the `ApplicationContext` adds more enterprise-specific functionality. The `ApplicationContext` is a complete superset of the `BeanFactory` and is used exclusively in this chapter in descriptions of Spring's IoC container. For more information on using the `BeanFactory` instead of the `ApplicationContext,` see the section covering the -<>. +xref:core/beans/beanfactory.adoc[`BeanFactory` API]. In Spring, the objects that form the backbone of your application and that are managed by the Spring IoC container are called beans. A bean is an object that is diff --git a/framework-docs/modules/ROOT/pages/core/beans/java.adoc b/framework-docs/modules/ROOT/pages/core/beans/java.adoc index 7cd289d7c44e..146880ab0523 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java.adoc @@ -4,15 +4,15 @@ This section covers how to use annotations in your Java code to configure the Spring container. It includes the following topics: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:core/beans/java/basic-concepts.adoc[Basic Concepts: `@Bean` and `@Configuration`] +* xref:core/beans/java/instantiating-container.adoc[Instantiating the Spring Container by Using `AnnotationConfigApplicationContext`] +* xref:core/beans/java/bean-annotation.adoc[Using the `@Bean` Annotation] +* xref:core/beans/java/configuration-annotation.adoc[Using the `@Configuration` annotation] +* xref:core/beans/java/composing-configuration-classes.adoc[Composing Java-based Configurations] +* xref:core/beans/environment.adoc#beans-definition-profiles[Bean Definition Profiles] +* xref:core/beans/environment.adoc#beans-property-source-abstraction[`PropertySource` Abstraction] +* xref:core/beans/environment.adoc#beans-using-propertysource[Using `@PropertySource`] +* xref:core/beans/environment.adoc#beans-placeholder-resolution-in-statements[Placeholder Resolution in Statements] diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc index 7872e94cfa72..e39ad32d4712 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc @@ -4,9 +4,9 @@ `@Bean` is a method-level annotation and a direct analog of the XML `` element. The annotation supports some of the attributes offered by ``, such as: -* <> -* <> -* <> +* xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[init-method] +* xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[destroy-method] +* xref:core/beans/dependencies/factory-autowire.adoc[autowiring] * `name`. You can use the `@Bean` annotation in a `@Configuration`-annotated or in a @@ -160,7 +160,7 @@ parameter, as the following example shows: The resolution mechanism is pretty much identical to constructor-based dependency -injection. See <> for more details. +injection. See xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[the relevant section] for more details. [[beans-java-lifecycle-callbacks]] @@ -168,17 +168,17 @@ injection. See <> for more de Any classes defined with the `@Bean` annotation support the regular lifecycle callbacks and can use the `@PostConstruct` and `@PreDestroy` annotations from JSR-250. See -<> for further +xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[JSR-250 annotations] for further details. -The regular Spring <> callbacks are fully supported as +The regular Spring xref:core/beans/factory-nature.adoc[lifecycle] callbacks are fully supported as well. If a bean implements `InitializingBean`, `DisposableBean`, or `Lifecycle`, their respective methods are called by the container. -The standard set of `*Aware` interfaces (such as <>, -<>, -<>, -<>, and so on) are also fully supported. +The standard set of `*Aware` interfaces (such as xref:core/beans/beanfactory.adoc[BeanFactoryAware], +xref:core/beans/factory-nature.adoc#beans-factory-aware[BeanNameAware], +xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSourceAware], +xref:core/beans/factory-nature.adoc#beans-factory-aware[ApplicationContextAware], and so on) are also fully supported. The `@Bean` annotation supports specifying arbitrary initialization and destruction callback methods, much like Spring XML's `init-method` and `destroy-method` attributes @@ -331,7 +331,7 @@ Spring includes the `@Scope` annotation so that you can specify the scope of a b You can specify that your beans defined with the `@Bean` annotation should have a specific scope. You can use any of the standard scopes specified in the -<> section. +xref:core/beans/factory-scopes.adoc[Bean Scopes] section. The default scope is `singleton`, but you can override this with the `@Scope` annotation, as the following example shows: @@ -367,7 +367,7 @@ as the following example shows: === `@Scope` and `scoped-proxy` Spring offers a convenient way of working with scoped dependencies through -<>. The easiest way to create +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[scoped proxies]. The easiest way to create such a proxy when using the XML configuration is the `` element. Configuring your beans in Java with a `@Scope` annotation offers equivalent support with the `proxyMode` attribute. The default is `ScopedProxyMode.DEFAULT`, which @@ -376,7 +376,7 @@ has been configured at the component-scan instruction level. You can specify `ScopedProxyMode.TARGET_CLASS`, `ScopedProxyMode.INTERFACES` or `ScopedProxyMode.NO`. If you port the scoped proxy example from the XML reference documentation (see -<>) to our `@Bean` using Java, +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[scoped proxies]) to our `@Bean` using Java, it resembles the following: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -448,7 +448,7 @@ as the following example shows: [[beans-java-bean-aliasing]] == Bean Aliasing -As discussed in <>, it is sometimes desirable to give a single bean +As discussed in xref:core/beans/definition.adoc#beans-beanname[Naming Beans], it is sometimes desirable to give a single bean multiple names, otherwise known as bean aliasing. The `name` attribute of the `@Bean` annotation accepts a String array for this purpose. The following example shows how to set a number of aliases for a bean: diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc index 9b02fa8f3367..13b342fcab39 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc @@ -101,7 +101,7 @@ issue, because no compiler is involved, and you can declare When using `@Configuration` classes, the Java compiler places constraints on the configuration model, in that references to other beans must be valid Java syntax. -Fortunately, solving this problem is simple. As <>, +Fortunately, solving this problem is simple. As xref:core/beans/java/bean-annotation.adoc#beans-java-dependencies[we already discussed], a `@Bean` method can have an arbitrary number of parameters that describe the bean dependencies. Consider the following more real-world scenario with several `@Configuration` classes, each depending on beans declared in the others: @@ -474,7 +474,7 @@ created before the current bean, beyond what the latter's direct dependencies im It is often useful to conditionally enable or disable a complete `@Configuration` class or even individual `@Bean` methods, based on some arbitrary system state. One common example of this is to use the `@Profile` annotation to activate beans only when a specific -profile has been enabled in the Spring `Environment` (see <> +profile has been enabled in the Spring `Environment` (see xref:core/beans/environment.adoc#beans-definition-profiles[Bean Definition Profiles] for details). The `@Profile` annotation is actually implemented by using a much more flexible annotation diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc index 74907e874b25..ccf861e92150 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc @@ -4,7 +4,7 @@ `@Configuration` is a class-level annotation indicating that an object is a source of bean definitions. `@Configuration` classes declare beans through `@Bean`-annotated methods. Calls to `@Bean` methods on `@Configuration` classes can also be used to define -inter-bean dependencies. See <> for a general introduction. +inter-bean dependencies. See xref:core/beans/java/basic-concepts.adoc[Basic Concepts: `@Bean` and `@Configuration`] for a general introduction. [[beans-java-injecting-dependencies]] @@ -56,7 +56,7 @@ by using plain `@Component` classes. [[beans-java-method-injection]] == Lookup Method Injection -As noted earlier, <> is an +As noted earlier, xref:core/beans/dependencies/factory-method-injection.adoc[lookup method injection] is an advanced feature that you should use rarely. It is useful in cases where a singleton-scoped bean has a dependency on a prototype-scoped bean. Using Java for this type of configuration provides a natural means for implementing this pattern. The diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc index 9b3c6605aa71..1a082498c4cf 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc @@ -177,7 +177,7 @@ following example shows: } ---- -NOTE: Remember that `@Configuration` classes are <> +NOTE: Remember that `@Configuration` classes are xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotated] with `@Component`, so they are candidates for component-scanning. In the preceding example, assuming that `AppConfig` is declared within the `com.acme` package (or any package underneath), it is picked up during the call to `scan()`. Upon `refresh()`, all its `@Bean` diff --git a/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc b/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc index 1f9f6e995a07..6991a5f30f68 100644 --- a/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc +++ b/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc @@ -8,10 +8,10 @@ XNIO, Jetty uses pooled byte buffers with a callback to be released, and so on. The `spring-core` module provides a set of abstractions to work with various byte buffer APIs as follows: -* <> abstracts the creation of a data buffer. -* <> represents a byte buffer, which may be -<>. -* <> offers utility methods for data buffers. +* xref:core/databuffer-codec.adoc#databuffers-factory[`DataBufferFactory`] abstracts the creation of a data buffer. +* xref:core/databuffer-codec.adoc#databuffers-buffer[`DataBuffer`] represents a byte buffer, which may be +xref:core/databuffer-codec.adoc#databuffers-buffer-pooled[pooled]. +* xref:core/databuffer-codec.adoc#databuffers-utils[`DataBufferUtils`] offers utility methods for data buffers. * <> decode or encode data buffer streams into higher level objects. @@ -45,7 +45,7 @@ Below is a partial list of benefits: * Read and write with independent positions, i.e. not requiring a call to `flip()` to alternate between read and write. * Capacity expanded on demand as with `java.lang.StringBuilder`. -* Pooled buffers and reference counting via <>. +* Pooled buffers and reference counting via xref:core/databuffer-codec.adoc#databuffers-buffer-pooled[`PooledDataBuffer`]. * View a buffer as `java.nio.ByteBuffer`, `InputStream`, or `OutputStream`. * Determine the index, or the last index, for a given byte. @@ -104,7 +104,7 @@ The `org.springframework.core.codec` package provides the following strategy int The `spring-core` module provides `byte[]`, `ByteBuffer`, `DataBuffer`, `Resource`, and `String` encoder and decoder implementations. The `spring-web` module adds Jackson JSON, Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders. See -<> in the WebFlux section. +xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] in the WebFlux section. @@ -113,7 +113,7 @@ Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders. See == Using `DataBuffer` When working with data buffers, special care must be taken to ensure buffers are released -since they may be <>. We'll use codecs to illustrate +since they may be xref:core/databuffer-codec.adoc#databuffers-buffer-pooled[pooled]. We'll use codecs to illustrate how that works but the concepts apply more generally. Let's see what codecs must do internally to manage data buffers. diff --git a/framework-docs/modules/ROOT/pages/core/expressions.adoc b/framework-docs/modules/ROOT/pages/core/expressions.adoc index 69cc559abf01..a87addc06f54 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions.adoc @@ -23,7 +23,7 @@ infrastructure classes, such as the parser. Most Spring users need not deal with this infrastructure and can, instead, author only expression strings for evaluation. An example of this typical use is the integration of SpEL into creating XML or annotation-based bean definitions, as shown in -<>. +xref:core/expressions/beandef.adoc[Expression support for defining bean definitions]. This chapter covers the features of the expression language, its API, and its language syntax. In several places, `Inventor` and `Society` classes are used as the target diff --git a/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc b/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc index d427d16586e9..096714936b9f 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc @@ -3,7 +3,7 @@ This section introduces the simple use of SpEL interfaces and its expression language. The complete language reference can be found in -<>. +xref:core/expressions/language-ref.adoc[Language Reference]. The following code introduces the SpEL API to evaluate the literal string expression, `Hello World`. @@ -376,7 +376,7 @@ interpreter and only 3ms using the compiled version of the expression. The compiler is not turned on by default, but you can turn it on in either of two different ways. You can turn it on by using the parser configuration process -(<>) or by using a Spring property +(xref:core/expressions/evaluation.adoc#expressions-parser-configuration[discussed earlier]) or by using a Spring property when SpEL usage is embedded inside another component. This section discusses both of these options. @@ -443,7 +443,7 @@ The second way to configure the compiler is for use when SpEL is embedded inside other component and it may not be possible to configure it through a configuration object. In these cases, it is possible to set the `spring.expression.compiler.mode` property via a JVM system property (or via the -<> mechanism) to one of the +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism) to one of the `SpelCompilerMode` enum values (`off`, `immediate`, or `mixed`). diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc index 2f17606729e9..c6c7e138d039 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc @@ -4,21 +4,21 @@ This section describes how the Spring Expression Language works. It covers the following topics: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:core/expressions/language-ref/literal.adoc[Literal Expressions] +* xref:core/expressions/language-ref/properties-arrays.adoc[Properties, Arrays, Lists, Maps, and Indexers] +* xref:core/expressions/language-ref/inline-lists.adoc[Inline Lists] +* xref:core/expressions/language-ref/inline-maps.adoc[Inline Maps] +* xref:core/expressions/language-ref/array-construction.adoc[Array Construction] +* xref:core/expressions/language-ref/methods.adoc[Methods] +* xref:core/expressions/language-ref/operators.adoc[Operators] +* xref:core/expressions/language-ref/types.adoc[Types] +* xref:core/expressions/language-ref/constructors.adoc[Constructors] +* xref:core/expressions/language-ref/variables.adoc[Variables] +* xref:core/expressions/language-ref/functions.adoc[Functions] +* xref:core/expressions/language-ref/bean-references.adoc[Bean References] +* xref:core/expressions/language-ref/operator-ternary.adoc[Ternary Operator (If-Then-Else)] +* xref:core/expressions/language-ref/operator-elvis.adoc[The Elvis Operator] +* xref:core/expressions/language-ref/operator-safe-navigation.adoc[Safe Navigation Operator] diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc index 2f0e56c1a2c0..240073f7daab 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc @@ -3,10 +3,10 @@ The Spring Expression Language supports the following kinds of operators: -* <> -* <> -* <> -* <> +* xref:core/expressions/language-ref/operators.adoc#expressions-operators-relational[Relational Operators] +* xref:core/expressions/language-ref/operators.adoc#expressions-operators-logical[Logical Operators] +* xref:core/expressions/language-ref/operators.adoc#expressions-operators-mathematical[Mathematical Operators] +* xref:core/expressions/language-ref/operators.adoc#expressions-assignment[The Assignment Operator] [[expressions-operators-relational]] diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc index 5935065e403b..bc717138aefe 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc @@ -3,8 +3,8 @@ Navigating with property references is easy. To do so, use a period to indicate a nested property value. The instances of the `Inventor` class, `pupin` and `tesla`, were -populated with data listed in the <> section. To navigate "down" the object graph and get Tesla's year of birth and +populated with data listed in the xref:core/expressions/example-classes.adoc[Classes used in the examples] + section. To navigate "down" the object graph and get Tesla's year of birth and Pupin's city of birth, we use the following expressions: [source,java,indent=0,subs="verbatim,quotes",role="primary"] diff --git a/framework-docs/modules/ROOT/pages/core/null-safety.adoc b/framework-docs/modules/ROOT/pages/core/null-safety.adoc index 2e649691ab4e..f64cef9b34a4 100644 --- a/framework-docs/modules/ROOT/pages/core/null-safety.adoc +++ b/framework-docs/modules/ROOT/pages/core/null-safety.adoc @@ -39,7 +39,7 @@ warnings related to null-safety in order to avoid `NullPointerException` at runt They are also used to make Spring API null-safe in Kotlin projects, since Kotlin natively supports https://kotlinlang.org/docs/reference/null-safety.html[null-safety]. More details -are available in the <>. +are available in the xref:languages/kotlin/null-safety.adoc[Kotlin support documentation]. diff --git a/framework-docs/modules/ROOT/pages/core/resources.adoc b/framework-docs/modules/ROOT/pages/core/resources.adoc index 4aaa4575c875..d645fcca280d 100644 --- a/framework-docs/modules/ROOT/pages/core/resources.adoc +++ b/framework-docs/modules/ROOT/pages/core/resources.adoc @@ -4,14 +4,14 @@ This chapter covers how Spring handles resources and how you can work with resources in Spring. It includes the following topics: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:core/resources.adoc#resources-introduction[Introduction] +* xref:core/resources.adoc#resources-resource[The `Resource` Interface] +* xref:core/resources.adoc#resources-implementations[Built-in `Resource` Implementations] +* xref:core/resources.adoc#resources-resourceloader[The `ResourceLoader` Interface] +* xref:core/resources.adoc#resources-resourcepatternresolver[The `ResourcePatternResolver` Interface] +* xref:core/resources.adoc#resources-resourceloaderaware[The `ResourceLoaderAware` Interface] +* xref:core/resources.adoc#resources-as-dependencies[Resources as Dependencies] +* xref:core/resources.adoc#resources-app-ctx[Application Contexts and Resource Paths] @@ -133,13 +133,13 @@ work. Spring includes several built-in `Resource` implementations: -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:core/resources.adoc#resources-implementations-urlresource[`UrlResource`] +* xref:core/resources.adoc#resources-implementations-classpathresource[`ClassPathResource`] +* xref:core/resources.adoc#resources-implementations-filesystemresource[`FileSystemResource`] +* xref:core/resources.adoc#resources-implementations-pathresource[`PathResource`] +* xref:core/resources.adoc#resources-implementations-servletcontextresource[`ServletContextResource`] +* xref:core/resources.adoc#resources-implementations-inputstreamresource[`InputStreamResource`] +* xref:core/resources.adoc#resources-implementations-bytearrayresource[`ByteArrayResource`] For a complete list of `Resource` implementations available in Spring, consult the "All Known Implementing Classes" section of the @@ -349,7 +349,7 @@ objects: | file: | `\file:///data/config.xml` -| Loaded as a `URL` from the filesystem. See also <>. +| Loaded as a `URL` from the filesystem. See also xref:core/resources.adoc#resources-filesystemresource-caveats[`FileSystemResource` Caveats]. | https: | `\https://myserver/logo.png` @@ -385,11 +385,11 @@ for all matching resources from the class path. Note that the resource location expected to be a path without placeholders in this case -- for example, `classpath*:/config/beans.xml`. JAR files or different directories in the class path can contain multiple files with the same path and the same name. See -<> and its subsections for further details +xref:core/resources.adoc#resources-app-ctx-wildcards-in-resource-paths[Wildcards in Application Context Constructor Resource Paths] and its subsections for further details on wildcard support with the `classpath*:` resource prefix. A passed-in `ResourceLoader` (for example, one supplied via -<> semantics) can be checked whether +xref:core/resources.adoc#resources-resourceloaderaware[`ResourceLoaderAware`] semantics) can be checked whether it implements this extended interface too. `PathMatchingResourcePatternResolver` is a standalone implementation that is usable @@ -444,18 +444,18 @@ interface (which can be considered a utility interface) and not to the whole Spr In application components, you may also rely upon autowiring of the `ResourceLoader` as an alternative to implementing the `ResourceLoaderAware` interface. The _traditional_ -`constructor` and `byType` autowiring modes (as described in <>) +`constructor` and `byType` autowiring modes (as described in xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators]) are capable of providing a `ResourceLoader` for either a constructor argument or a setter method parameter, respectively. For more flexibility (including the ability to autowire fields and multiple parameter methods), consider using the annotation-based autowiring features. In that case, the `ResourceLoader` is autowired into a field, constructor argument, or method parameter that expects the `ResourceLoader` type as long as the field, constructor, or method in question carries the `@Autowired` annotation. -For more information, see <>. +For more information, see xref:core/beans/annotation-config/autowired.adoc[Using `@Autowired`]. NOTE: To load one or more `Resource` objects for a resource path that contains wildcards or makes use of the special `classpath*:` resource prefix, consider having an instance of -<> autowired into your +xref:core/resources.adoc#resources-resourcepatternresolver[`ResourcePatternResolver`] autowired into your application components instead of `ResourceLoader`. @@ -531,8 +531,8 @@ latter being used to access a file in the filesystem): If the `MyBean` class is refactored for use with annotation-driven configuration, the path to `myTemplate.txt` can be stored under a key named `template.path` -- for example, in a properties file made available to the Spring `Environment` (see -<>). The template path can then be referenced via the `@Value` -annotation using a property placeholder (see <>). Spring will +xref:core/beans/environment.adoc[Environment Abstraction]). The template path can then be referenced via the `@Value` +annotation using a property placeholder (see xref:core/beans/annotation-config/value-annotations.adoc[Using `@Value`]). Spring will retrieve the value of the template path as a string, and a special `PropertyEditor` will convert the string to a `Resource` object to be injected into the `MyBean` constructor. The following example demonstrates how to achieve this. diff --git a/framework-docs/modules/ROOT/pages/core/validation.adoc b/framework-docs/modules/ROOT/pages/core/validation.adoc index 84bad43d2d14..cc55989412c0 100644 --- a/framework-docs/modules/ROOT/pages/core/validation.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation.adoc @@ -30,9 +30,9 @@ implementations. They are also discussed in this chapter. Spring supports Java Bean Validation through setup infrastructure and an adaptor to Spring's own `Validator` contract. Applications can enable Bean Validation once globally, -as described in <>, and use it exclusively for all validation +as described in xref:core/validation/beanvalidation.adoc[Java Bean Validation], and use it exclusively for all validation needs. In the web layer, applications can further register controller-local Spring -`Validator` instances per `DataBinder`, as described in <>, which can +`Validator` instances per `DataBinder`, as described in xref:core/validation/beanvalidation.adoc#validation-binder[Configuring a `DataBinder`], which can be useful for plugging in custom validation logic. diff --git a/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc b/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc index 439125a3cb03..c22f3c6ff63f 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc @@ -57,7 +57,7 @@ details. The below table shows some examples of these conventions: (This next section is not vitally important to you if you do not plan to work with the `BeanWrapper` directly. If you use only the `DataBinder` and the `BeanFactory` and their default implementations, you should skip ahead to the -<>.) +xref:core/validation/beans-beans.adoc#beans-beans-conversion[section on `PropertyEditors`].) The following two example classes use the `BeanWrapper` to get and set properties: @@ -378,7 +378,7 @@ where it can be automatically detected and applied. Note that all bean factories and application contexts automatically use a number of built-in property editors, through their use of a `BeanWrapper` to handle property conversions. The standard property editors that the `BeanWrapper` -registers are listed in the <>. +registers are listed in the xref:core/validation/beans-beans.adoc#beans-beans-conversion[previous section]. Additionally, ``ApplicationContext``s also override or add additional editors to handle resource lookups in a manner appropriate to the specific application context type. @@ -495,7 +495,7 @@ You can write a corresponding registrar and reuse it in each case. `PropertyEditorRegistry`, an interface that is implemented by the Spring `BeanWrapper` (and `DataBinder`). `PropertyEditorRegistrar` instances are particularly convenient when used in conjunction with `CustomEditorConfigurer` (described -<>), which exposes a property +xref:core/validation/beans-beans.adoc#beans-beans-conversion-customeditor-registration[here]), which exposes a property called `setPropertyEditorRegistrars(..)`. `PropertyEditorRegistrar` instances added to a `CustomEditorConfigurer` in this fashion can easily be shared with `DataBinder` and Spring MVC controllers. Furthermore, it avoids the need for synchronization on custom @@ -562,7 +562,7 @@ of our `CustomPropertyEditorRegistrar` into it: ---- Finally (and in a bit of a departure from the focus of this chapter) for those of you -using <>, using a `PropertyEditorRegistrar` in +using xref:web/webmvc.adoc#mvc[Spring's MVC web framework], using a `PropertyEditorRegistrar` in conjunction with data-binding web controllers can be very convenient. The following example uses a `PropertyEditorRegistrar` in the implementation of an `@InitBinder` method: diff --git a/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc b/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc index 9a7978e5bdb6..46b410824ff6 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc @@ -265,10 +265,10 @@ for setup details with the Hibernate Validator and Bean Validation 1.1 providers [TIP] ==== -Method validation relies on <> around the +Method validation relies on xref:core/aop/introduction-proxies.adoc[AOP Proxies] around the target classes, either JDK dynamic proxies for methods on interfaces or CGLIB proxies. There are certain limitations with the use of proxies, some of which are described in -<>. In addition remember +xref:core/aop/proxying.adoc#aop-understanding-aop-proxies[Understanding AOP Proxies]. In addition remember to always use methods and accessors on proxied classes; direct field access will not work. ==== @@ -333,11 +333,11 @@ You can also configure a `DataBinder` with multiple `Validator` instances throug `dataBinder.addValidators` and `dataBinder.replaceValidators`. This is useful when combining globally configured bean validation with a Spring `Validator` configured locally on a DataBinder instance. See -<>. +xref:web/webmvc/mvc-config/validation.adoc[Spring MVC Validation Configuration]. [[validation-mvc]] == Spring MVC 3 Validation -See <> in the Spring MVC chapter. +See xref:web/webmvc/mvc-config/validation.adoc[Validation] in the Spring MVC chapter. diff --git a/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc b/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc index 07bc88f06436..49deddde0c33 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc @@ -2,7 +2,7 @@ = Resolving Codes to Error Messages We covered databinding and validation. This section covers outputting messages that correspond -to validation errors. In the example shown in the <>, +to validation errors. In the example shown in the xref:core/validation/validator.adoc[preceding section], we rejected the `name` and `age` fields. If we want to output the error messages by using a `MessageSource`, we can do so using the error code we provide when rejecting the field ('name' and 'age' in this case). When you call (either directly, or indirectly, by using, diff --git a/framework-docs/modules/ROOT/pages/core/validation/convert.adoc b/framework-docs/modules/ROOT/pages/core/validation/convert.adoc index fd5fc3af68bf..3d33722dcea9 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/convert.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/convert.adoc @@ -246,10 +246,10 @@ any of the `Converter`, `ConverterFactory`, or `GenericConverter` interfaces. ---- It is also common to use a `ConversionService` within a Spring MVC application. See -<> in the Spring MVC chapter. +xref:web/webmvc/mvc-config/conversion.adoc[Conversion and Formatting] in the Spring MVC chapter. In certain situations, you may wish to apply formatting during conversion. See -<> for details on using `FormattingConversionServiceFactoryBean`. +xref:core/validation/format.adoc#format-FormatterRegistry-SPI[The `FormatterRegistry` SPI] for details on using `FormattingConversionServiceFactoryBean`. diff --git a/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc b/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc index 90eb0f374f39..053d98d73c17 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc @@ -108,8 +108,8 @@ If you prefer XML-based configuration, you can use a Note there are extra considerations when configuring date and time formats in web applications. Please see -<> or -<>. +xref:web/webmvc/mvc-config/conversion.adoc[WebMVC Conversion and Formatting] or +xref:web/webflux/config.adoc#webflux-config-conversion[WebFlux Conversion and Formatting]. diff --git a/framework-docs/modules/ROOT/pages/core/validation/format.adoc b/framework-docs/modules/ROOT/pages/core/validation/format.adoc index b636cb094399..c344b2c73133 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/format.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/format.adoc @@ -1,7 +1,7 @@ [[format]] = Spring Field Formatting -As discussed in the previous section, <> is a +As discussed in the previous section, xref:core/validation/convert.adoc[`core.convert`] is a general-purpose type conversion system. It provides a unified `ConversionService` API as well as a strongly typed `Converter` SPI for implementing conversion logic from one type to another. A Spring container uses this system to bind bean property values. In @@ -356,7 +356,7 @@ converter and formatter registration. [[format-configuring-formatting-mvc]] == Configuring Formatting in Spring MVC -See <> in the Spring MVC chapter. +See xref:web/webmvc/mvc-config/conversion.adoc[Conversion and Formatting] in the Spring MVC chapter. diff --git a/framework-docs/modules/ROOT/pages/data-access/appendix.adoc b/framework-docs/modules/ROOT/pages/data-access/appendix.adoc index 449c86095d88..3bd4f80fdeea 100644 --- a/framework-docs/modules/ROOT/pages/data-access/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/appendix.adoc @@ -9,8 +9,8 @@ This part of the appendix lists XML schemas for data access, including the following: -* <> -* <> +* xref:data-access/appendix.adoc#xsd-schemas-tx[The `tx` Schema] +* xref:data-access/appendix.adoc#xsd-schemas-jdbc[The `jdbc` Schema] @@ -19,7 +19,7 @@ This part of the appendix lists XML schemas for data access, including the follo The `tx` tags deal with configuring all of those beans in Spring's comprehensive support for transactions. These tags are covered in the chapter entitled -<>. +xref:data-access/transaction.adoc[Transaction Management]. TIP: We strongly encourage you to look at the `'spring-tx.xsd'` file that ships with the Spring distribution. This file contains the XML Schema for Spring's transaction @@ -68,8 +68,8 @@ to you. The `jdbc` elements let you quickly configure an embedded database or initialize an existing data source. These elements are documented in -<> and -<>, respectively. +xref:data-access/jdbc/embedded-database-support.adoc[Embedded Database Support] and +xref:data-access/jdbc/initializing-datasource.adoc[Initializing a DataSource], respectively. To use the elements in the `jdbc` schema, you need to have the following preamble at the top of your Spring XML configuration file. The text in the following snippet references diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc index 9c40642d575a..203952f64a86 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc @@ -198,7 +198,7 @@ While this usually works well, there is a potential for issues (for example, wit case, which can be expensive with your JDBC driver. You should use a recent driver version and consider setting the `spring.jdbc.getParameterType.ignore` property to `true` (as a JVM system property or via the -<> mechanism) if you encounter +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism) if you encounter a performance issue (as reported on Oracle 12c, JBoss, and PostgreSQL). Alternatively, you might consider specifying the corresponding JDBC types explicitly, diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc index 80fe71b59359..fb787e7fa655 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc @@ -3,14 +3,14 @@ This section covers: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:data-access/jdbc/connections.adoc#jdbc-datasource[Using `DataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-DataSourceUtils[Using `DataSourceUtils`] +* xref:data-access/jdbc/connections.adoc#jdbc-SmartDataSource[Implementing `SmartDataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-AbstractDataSource[Extending `AbstractDataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-SingleConnectionDataSource[Using `SingleConnectionDataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-DriverManagerDataSource[Using `DriverManagerDataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-TransactionAwareDataSourceProxy[Using `TransactionAwareDataSourceProxy`] +* xref:data-access/jdbc/connections.adoc#jdbc-DataSourceTransactionManager[Using `DataSourceTransactionManager`] [[jdbc-datasource]] diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc index a2488bfa2106..73c5bda829ce 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc @@ -4,13 +4,13 @@ This section covers how to use the JDBC core classes to control basic JDBC processing, including error handling. It includes the following topics: -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate[Using `JdbcTemplate`] +* xref:data-access/jdbc/core.adoc#jdbc-NamedParameterJdbcTemplate[Using `NamedParameterJdbcTemplate`] +* xref:data-access/jdbc/core.adoc#jdbc-SQLExceptionTranslator[Using `SQLExceptionTranslator`] +* xref:data-access/jdbc/core.adoc#jdbc-statements-executing[Running Statements] +* xref:data-access/jdbc/core.adoc#jdbc-statements-querying[Running Queries] +* xref:data-access/jdbc/core.adoc#jdbc-updates[Updating the Database] +* xref:data-access/jdbc/core.adoc#jdbc-auto-generated-keys[Retrieving Auto-generated Keys] [[jdbc-JdbcTemplate]] @@ -26,7 +26,7 @@ SQL and extract results. The `JdbcTemplate` class: * Updates statements and stored procedure calls * Performs iteration over `ResultSet` instances and extraction of returned parameter values. * Catches JDBC exceptions and translates them to the generic, more informative, exception -hierarchy defined in the `org.springframework.dao` package. (See <>.) +hierarchy defined in the `org.springframework.dao` package. (See xref:data-access/dao.adoc#dao-exceptions[Consistent Exception Hierarchy].) When you use the `JdbcTemplate` for your code, you need only to implement callback interfaces, giving them a clearly defined contract. Given a `Connection` provided by the @@ -270,7 +270,7 @@ The following example invokes a stored procedure: ---- -More sophisticated stored procedure support is <>. +More sophisticated stored procedure support is xref:data-access/jdbc/object.adoc#jdbc-StoredProcedure[covered later]. [[jdbc-JdbcTemplate-idioms]] === `JdbcTemplate` Best Practices @@ -282,7 +282,7 @@ The `JdbcTemplate` is stateful, in that it maintains a reference to a `DataSourc this state is not conversational state. A common practice when using the `JdbcTemplate` class (and the associated -<> class) is to +xref:data-access/jdbc/core.adoc#jdbc-NamedParameterJdbcTemplate[`NamedParameterJdbcTemplate`] class) is to configure a `DataSource` in your Spring configuration file and then dependency-inject that shared `DataSource` bean into your DAO classes. The `JdbcTemplate` is created in the setter for the `DataSource`. This leads to DAOs that resemble the following: @@ -607,7 +607,7 @@ functionality that is present only in the `JdbcTemplate` class, you can use the `getJdbcOperations()` method to access the wrapped `JdbcTemplate` through the `JdbcOperations` interface. -See also <> for guidelines on using the +See also xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate-idioms[`JdbcTemplate` Best Practices] for guidelines on using the `NamedParameterJdbcTemplate` class in the context of an application. diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc index 53b4a855aed8..740d49db44d0 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc @@ -129,9 +129,9 @@ configuration, as the following example shows: This section covers how to select one of the three embedded databases that Spring supports. It includes the following topics: -* <> -* <> -* <> +* xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-using-HSQL[Using HSQL] +* xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-using-H2[Using H2] +* xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-using-Derby[Using Derby] [[jdbc-embedded-database-using-HSQL]] === Using HSQL @@ -163,9 +163,9 @@ Embedded databases provide a lightweight way to test data access code. The next data access integration test template that uses an embedded database. Using such a template can be useful for one-offs when the embedded database does not need to be reused across test classes. However, if you wish to create an embedded database that is shared within a test suite, -consider using the <> and +consider using the xref:testing/testcontext-framework.adoc[Spring TestContext Framework] and configuring the embedded database as a bean in the Spring `ApplicationContext` as described -in <> and <>. The following listing +in xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-xml[Creating an Embedded Database by Using Spring XML] and xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-java[Creating an Embedded Database Programmatically]. The following listing shows the test template: [source,java,indent=0,subs="verbatim,quotes",role="primary"] diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc index f3489b5082cc..4e0610bfd12d 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc @@ -10,7 +10,7 @@ procedures and run update, delete, and insert statements. [NOTE] ==== Many Spring developers believe that the various RDBMS operation classes described below -(with the exception of the <> class) can often +(with the exception of the xref:data-access/jdbc/object.adoc#jdbc-StoredProcedure[`StoredProcedure`] class) can often be replaced with straight `JdbcTemplate` calls. Often, it is simpler to write a DAO method that calls a method on a `JdbcTemplate` directly (as opposed to encapsulating a query as a full-blown class). @@ -236,7 +236,7 @@ The SQL type is specified using the `java.sql.Types` constants. The first line (with the `SqlParameter`) declares an IN parameter. You can use IN parameters both for stored procedure calls and for queries using the `SqlQuery` and its -subclasses (covered in <>). +subclasses (covered in xref:data-access/jdbc/object.adoc#jdbc-SqlQuery[Understanding `SqlQuery`]). The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in the stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc index 5d4a56cbb531..e6719fec871f 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc @@ -8,19 +8,19 @@ various callback interfaces, plus a variety of related classes. A subpackage nam `org.springframework.jdbc.core.simple` contains the `SimpleJdbcInsert` and `SimpleJdbcCall` classes. Another subpackage named `org.springframework.jdbc.core.namedparam` contains the `NamedParameterJdbcTemplate` -class and the related support classes. See <>, <>, and -<>. +class and the related support classes. See xref:data-access/jdbc/core.adoc[Using the JDBC Core Classes to Control Basic JDBC Processing and Error Handling], xref:data-access/jdbc/advanced.adoc[JDBC Batch Operations], and +xref:data-access/jdbc/simple.adoc[Simplifying JDBC Operations with the `SimpleJdbc` Classes]. * `datasource`: The `org.springframework.jdbc.datasource` package contains a utility class for easy `DataSource` access and various simple `DataSource` implementations that you can use for testing and running unmodified JDBC code outside of a Jakarta EE container. A subpackage named `org.springfamework.jdbc.datasource.embedded` provides support for creating embedded databases by using Java database engines, such as HSQL, H2, and Derby. See -<> and <>. +xref:data-access/jdbc/connections.adoc[Controlling Database Connections] and xref:data-access/jdbc/embedded-database-support.adoc[Embedded Database Support]. * `object`: The `org.springframework.jdbc.object` package contains classes that represent RDBMS queries, updates, and stored procedures as thread-safe, reusable objects. See -<>. This approach is modeled by JDO, although objects returned by queries +xref:data-access/jdbc/object.adoc[Modeling JDBC Operations as Java Objects]. This approach is modeled by JDO, although objects returned by queries are naturally disconnected from the database. This higher-level of JDBC abstraction depends on the lower-level abstraction in the `org.springframework.jdbc.core` package. @@ -30,7 +30,7 @@ translated to exceptions defined in the `org.springframework.dao` package. This that code using the Spring JDBC abstraction layer does not need to implement JDBC or RDBMS-specific error handling. All translated exceptions are unchecked, which gives you the option of catching the exceptions from which you can recover while letting other -exceptions be propagated to the caller. See <>. +exceptions be propagated to the caller. See xref:data-access/jdbc/core.adoc#jdbc-SQLExceptionTranslator[Using `SQLExceptionTranslator`]. diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc index ef434dce1c4c..8b711afb5561 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc @@ -437,7 +437,7 @@ returned `out` parameters. Earlier in this chapter, we described how parameters are deduced from metadata, but you can declare them explicitly if you wish. You can do so by creating and configuring `SimpleJdbcCall` with the `declareParameters` method, which takes a variable number of `SqlParameter` objects -as input. See the <> for details on how to define an `SqlParameter`. +as input. See the xref:data-access/jdbc/simple.adoc#jdbc-params[next section] for details on how to define an `SqlParameter`. NOTE: Explicit declarations are necessary if the database you use is not a Spring-supported database. Currently, Spring supports metadata lookup of stored procedure calls for the @@ -510,7 +510,7 @@ details explicitly rather than relying on metadata. == How to Define `SqlParameters` To define a parameter for the `SimpleJdbc` classes and also for the RDBMS operations -classes (covered in <>) you can use `SqlParameter` or one of its subclasses. +classes (covered in xref:data-access/jdbc/object.adoc[Modeling JDBC Operations as Java Objects]) you can use `SqlParameter` or one of its subclasses. To do so, you typically specify the parameter name and SQL type in the constructor. The SQL type is specified by using the `java.sql.Types` constants. Earlier in this chapter, we saw declarations similar to the following: @@ -530,7 +530,7 @@ similar to the following: The first line with the `SqlParameter` declares an IN parameter. You can use IN parameters for both stored procedure calls and for queries by using the `SqlQuery` and its -subclasses (covered in <>). +subclasses (covered in xref:data-access/jdbc/object.adoc#jdbc-SqlQuery[Understanding `SqlQuery`]). The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in a stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc index 846760f93d81..bb47bbd68f68 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc @@ -2,7 +2,7 @@ = General ORM Integration Considerations This section highlights considerations that apply to all ORM technologies. -The <> section provides more details and also show these features and +The xref:data-access/orm/hibernate.adoc[Hibernate] section provides more details and also show these features and configurations in a concrete context. The major goal of Spring's ORM integration is clear application layering (with any data @@ -31,18 +31,18 @@ interceptors for the ORM technologies. The infrastructure provides proper resource handling and appropriate conversion of specific API exceptions to an unchecked infrastructure exception hierarchy. Spring introduces a DAO exception hierarchy, applicable to any data access strategy. For direct -JDBC, the `JdbcTemplate` class mentioned in a <> +JDBC, the `JdbcTemplate` class mentioned in a xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate[previous section] provides connection handling and proper conversion of `SQLException` to the `DataAccessException` hierarchy, including translation of database-specific SQL error codes to meaningful exception classes. For ORM technologies, see the -<> for how to get the same exception +xref:data-access/orm/general.adoc#orm-exception-translation[next section] for how to get the same exception translation benefits. When it comes to transaction management, the `JdbcTemplate` class hooks in to the Spring transaction support and supports both JTA and JDBC transactions, through respective Spring transaction managers. For the supported ORM technologies, Spring offers Hibernate and JPA support through the Hibernate and JPA transaction managers as well as JTA support. -For details on transaction support, see the <> chapter. +For details on transaction support, see the xref:data-access/transaction.adoc[Transaction Management] chapter. [[orm-exception-translation]] diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc index fb32064e91f0..c449194c0aa7 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc @@ -21,7 +21,7 @@ To avoid tying application objects to hard-coded resource lookups, you can defin resources (such as a JDBC `DataSource` or a Hibernate `SessionFactory`) as beans in the Spring container. Application objects that need to access resources receive references to such predefined instances through bean references, as illustrated in the DAO -definition in the <>. +definition in the xref:data-access/orm/hibernate.adoc#orm-hibernate-straight[next section]. The following excerpt from an XML application context definition shows how to set up a JDBC `DataSource` and a Hibernate `SessionFactory` on top of it: @@ -83,7 +83,7 @@ property. On the programmatic `LocalSessionFactoryBuilder`, there is an overload As of Spring Framework 5.1, such a native Hibernate setup can also expose a JPA `EntityManagerFactory` for standard JPA interaction next to native Hibernate access. -See <> for details. +See xref:data-access/orm/jpa.adoc#orm-jpa-hibernate[Native Hibernate Setup for JPA] for details. ==== @@ -185,7 +185,7 @@ container by using either Java annotations or XML. This declarative transaction lets you keep business services free of repetitive transaction demarcation code and focus on adding business logic, which is the real value of your application. -NOTE: Before you continue, we are strongly encourage you to read <> +NOTE: Before you continue, we are strongly encourage you to read xref:data-access/transaction/declarative.adoc[Declarative Transaction Management] if you have not already done so. You can annotate the service layer with `@Transactional` annotations and instruct the @@ -447,7 +447,7 @@ to which it synchronizes (along with Spring). You have two options for doing thi * Pass your Spring `JtaTransactionManager` bean to your Hibernate setup. The easiest way is a bean reference into the `jtaTransactionManager` property for your - `LocalSessionFactoryBean` bean (see <>). + `LocalSessionFactoryBean` bean (see xref:data-access/transaction/strategies.adoc#transaction-strategies-hibernate[Hibernate Transaction Setup]). Spring then makes the corresponding JTA strategies available to Hibernate. * You may also configure Hibernate's JTA-related properties explicitly, in particular "hibernate.transaction.coordinator_class", "hibernate.connection.handling_mode" diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc index 58b4b8aadeb1..bfb3e3c532ac 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc @@ -48,7 +48,7 @@ The benefits of using the Spring Framework to create your ORM DAOs include: aspect-oriented programming (AOP) style method interceptor either through the `@Transactional` annotation or by explicitly configuring the transaction AOP advice in an XML configuration file. In both cases, transaction semantics and exception handling - (rollback and so on) are handled for you. As discussed in <>, + (rollback and so on) are handled for you. As discussed in xref:data-access/orm/general.adoc#orm-resource-mngmnt[Resource and Transaction Management], you can also swap various transaction managers, without affecting your ORM-related code. For example, you can swap between local transactions and JTA, with the same full services (such as declarative transactions) available in both scenarios. Additionally, diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc index 76fc82209824..3f0265169796 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc @@ -14,9 +14,9 @@ the underlying implementation in order to provide additional features. The Spring JPA support offers three ways of setting up the JPA `EntityManagerFactory` that is used by the application to obtain an entity manager. -* <> -* <> -* <> +* xref:data-access/orm/jpa.adoc#orm-jpa-setup-lemfb[Using `LocalEntityManagerFactoryBean`] +* xref:data-access/orm/jpa.adoc#orm-jpa-setup-jndi[Obtaining an EntityManagerFactory from JNDI] +* xref:data-access/orm/jpa.adoc#orm-jpa-setup-lcemfb[Using `LocalContainerEntityManagerFactoryBean`] [[orm-jpa-setup-lemfb]] === Using `LocalEntityManagerFactoryBean` @@ -92,7 +92,7 @@ NOTE: If you want to specifically configure a Hibernate setup, an immediate alte is to set up a native Hibernate `LocalSessionFactoryBean` instead of a plain JPA `LocalContainerEntityManagerFactoryBean`, letting it interact with JPA access code as well as native Hibernate access code. -See <> for details. +See xref:data-access/orm/jpa.adoc#orm-jpa-hibernate[Native Hibernate setup for JPA interaction] for details. The `LocalContainerEntityManagerFactoryBean` gives full control over `EntityManagerFactory` configuration and is appropriate for environments where @@ -172,11 +172,11 @@ Spring provides a number of `LoadTimeWeaver` implementations for various environ letting `ClassTransformer` instances be applied only for each class loader and not for each VM. -See the <> in the AOP chapter for +See the xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration] in the AOP chapter for more insight regarding the `LoadTimeWeaver` implementations and their setup, either generic or customized to various platforms (such as Tomcat, JBoss and WebSphere). -As described in <>, you can configure +As described in xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration], you can configure a context-wide `LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation or the `context:load-time-weaver` XML element. Such a global weaver is automatically picked up by all JPA `LocalContainerEntityManagerFactoryBean` instances. The following example @@ -452,7 +452,7 @@ a non-invasiveness perspective and can feel more natural to JPA developers. [[orm-jpa-tx]] == Spring-driven JPA transactions -NOTE: We strongly encourage you to read <>, if you have not +NOTE: We strongly encourage you to read xref:data-access/transaction/declarative.adoc[Declarative Transaction Management], if you have not already done so, to get more detailed coverage of Spring's declarative transaction support. The recommended strategy for JPA is local transactions through JPA's native transaction @@ -464,12 +464,12 @@ Spring JPA also lets a configured `JpaTransactionManager` expose a JPA transacti to JDBC access code that accesses the same `DataSource`, provided that the registered `JpaDialect` supports retrieval of the underlying JDBC `Connection`. Spring provides dialects for the EclipseLink and Hibernate JPA implementations. -See the <> for details on the `JpaDialect` mechanism. +See the xref:data-access/orm/jpa.adoc#orm-jpa-dialect[next section] for details on the `JpaDialect` mechanism. NOTE: As an immediate alternative, Spring's native `HibernateTransactionManager` is capable of interacting with JPA access code, adapting to several Hibernate specifics and providing JDBC interaction. This makes particular sense in combination with `LocalSessionFactoryBean` -setup. See <> for details. +setup. See xref:data-access/orm/jpa.adoc#orm-jpa-hibernate[Native Hibernate Setup for JPA Interaction] for details. [[orm-jpa-dialect]] @@ -529,7 +529,7 @@ Hibernate 5.0 but not any more in Hibernate 5.1+. For a JTA setup, make sure to your persistence unit transaction type as "JTA". Alternatively, set Hibernate 5.2's `hibernate.connection.handling_mode` property to `DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT` to restore Hibernate's own default. -See <> for related notes. +See xref:data-access/orm/hibernate.adoc#orm-hibernate-invalid-jdbc-access-error[Spurious Application Server Warnings with Hibernate] for related notes. * Alternatively, consider obtaining the `EntityManagerFactory` from your application server itself (that is, through a JNDI lookup instead of a locally declared @@ -565,7 +565,7 @@ seamlessly integrating with `@Bean` style configuration (no `FactoryBean` involv ==== `LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background bootstrapping, just as the JPA `LocalContainerEntityManagerFactoryBean` does. -See <> for an introduction. +See xref:data-access/orm/jpa.adoc#orm-jpa-setup-background[Background Bootstrapping] for an introduction. On `LocalSessionFactoryBean`, this is available through the `bootstrapExecutor` property. On the programmatic `LocalSessionFactoryBuilder`, an overloaded diff --git a/framework-docs/modules/ROOT/pages/data-access/oxm.adoc b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc index 1ead502a7ffd..81aec53f134f 100644 --- a/framework-docs/modules/ROOT/pages/data-access/oxm.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc @@ -18,9 +18,9 @@ stream, or a SAX handler. Some of the benefits of using Spring for your O/X mapping needs are: -* <> -* <> -* <> +* xref:data-access/oxm.adoc#oxm-ease-of-configuration[Ease of configuration] +* xref:data-access/oxm.adoc#oxm-consistent-interfaces[Consistent Interfaces] +* xref:data-access/oxm.adoc#oxm-consistent-exception-hierarchy[Consistent Exception Hierarchy] [[oxm-ease-of-configuration]] @@ -57,7 +57,7 @@ These runtime exceptions wrap the original exception so that no information is l [[oxm-marshaller-unmarshaller]] == `Marshaller` and `Unmarshaller` -As stated in the <>, a marshaller serializes an object +As stated in the xref:data-access/oxm.adoc#oxm-introduction[introduction], a marshaller serializes an object to XML, and an unmarshaller deserializes XML stream to an object. This section describes the two Spring interfaces used for this purpose. @@ -332,8 +332,8 @@ preamble of the XML configuration file. The following example shows how to do so The schema makes the following elements available: -* <> -* <> +* xref:data-access/oxm.adoc#oxm-jaxb2-xsd[`jaxb2-marshaller`] +* xref:data-access/oxm.adoc#oxm-jibx-xsd[`jibx-marshaller`] Each tag is explained in its respective marshaller's section. As an example, though, the configuration of a JAXB2 marshaller might resemble the following: @@ -353,7 +353,7 @@ The JAXB binding compiler translates a W3C XML Schema into one or more Java clas generate a schema from annotated Java classes. Spring supports the JAXB 2.0 API as XML marshalling strategies, following the -`Marshaller` and `Unmarshaller` interfaces described in <>. +`Marshaller` and `Unmarshaller` interfaces described in xref:data-access/oxm.adoc#oxm-marshaller-unmarshaller[`Marshaller` and `Unmarshaller`]. The corresponding integration classes reside in the `org.springframework.oxm.jaxb` package. diff --git a/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc b/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc index 178387529f02..1345dd5fb0ef 100644 --- a/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc @@ -11,11 +11,11 @@ specification effort to standardize access to SQL databases using reactive patte The Spring Framework's R2DBC abstraction framework consists of two different packages: * `core`: The `org.springframework.r2dbc.core` package contains the `DatabaseClient` -class plus a variety of related classes. See <>. +class plus a variety of related classes. See xref:data-access/r2dbc.adoc#r2dbc-core[Using the R2DBC Core Classes to Control Basic R2DBC Processing and Error Handling]. * `connection`: The `org.springframework.r2dbc.connection` package contains a utility class for easy `ConnectionFactory` access and various simple `ConnectionFactory` implementations -that you can use for testing and running unmodified R2DBC. See <>. +that you can use for testing and running unmodified R2DBC. See xref:data-access/r2dbc.adoc#r2dbc-connections[Controlling Database Connections]. [[r2dbc-core]] @@ -24,12 +24,12 @@ that you can use for testing and running unmodified R2DBC. See <> -* <> -* <> -* <> -* <> -* <> +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient[Using `DatabaseClient`] +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-examples-statement[Executing Statements] +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-examples-query[Querying (`SELECT`)] +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-examples-update[Updating (`INSERT`, `UPDATE`, and `DELETE`) with `DatabaseClient`] +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-filter[Statement Filters] +* xref:data-access/r2dbc.adoc#r2dbc-auto-generated-keys[Retrieving Auto-generated Keys] [[r2dbc-DatabaseClient]] === Using `DatabaseClient` @@ -44,7 +44,7 @@ SQL and extract results. The `DatabaseClient` class: * Update statements and stored procedure calls * Performs iteration over `Result` instances * Catches R2DBC exceptions and translates them to the generic, more informative, exception -hierarchy defined in the `org.springframework.dao` package. (See <>.) +hierarchy defined in the `org.springframework.dao` package. (See xref:data-access/dao.adoc#dao-exceptions[Consistent Exception Hierarchy].) The client has a functional, fluent API using reactive types for declarative composition. @@ -543,11 +543,11 @@ requests the generated key for the desired column. This section covers: -* <> -* <> -* <> -* <> -* <> +* xref:data-access/r2dbc.adoc#r2dbc-ConnectionFactory[Using `ConnectionFactory`] +* xref:data-access/r2dbc.adoc#r2dbc-ConnectionFactoryUtils[Using `ConnectionFactoryUtils`] +* xref:data-access/r2dbc.adoc#r2dbc-SingleConnectionFactory[Using `SingleConnectionFactory`] +* xref:data-access/r2dbc.adoc#r2dbc-TransactionAwareConnectionFactoryProxy[Using `TransactionAwareConnectionFactoryProxy`] +* xref:data-access/r2dbc.adoc#r2dbc-R2dbcTransactionManager[Using `R2dbcTransactionManager`] [[r2dbc-ConnectionFactory]] diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction.adoc index 758ef2eddb97..10254968d87f 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction.adoc @@ -7,34 +7,34 @@ management that delivers the following benefits: * A consistent programming model across different transaction APIs, such as Java Transaction API (JTA), JDBC, Hibernate, and the Java Persistence API (JPA). -* Support for <>. -* A simpler API for <> transaction management +* Support for xref:data-access/transaction/declarative.adoc[declarative transaction management]. +* A simpler API for xref:data-access/transaction/programmatic.adoc[programmatic] transaction management than complex transaction APIs, such as JTA. * Excellent integration with Spring's data access abstractions. The following sections describe the Spring Framework's transaction features and technologies: -* <> describes why you would use the Spring Framework's transaction abstraction +* xref:data-access/transaction/motivation.adoc[Advantages of the Spring Framework's transaction support model] + describes why you would use the Spring Framework's transaction abstraction instead of EJB Container-Managed Transactions (CMT) or choosing to drive local transactions through a proprietary API, such as Hibernate. -* <> +* xref:data-access/transaction/strategies.adoc[Understanding the Spring Framework transaction abstraction] outlines the core classes and describes how to configure and obtain `DataSource` instances from a variety of sources. -* <> describes +* xref:data-access/transaction/tx-resource-synchronization.adoc[Synchronizing resources with transactions] describes how the application code ensures that resources are created, reused, and cleaned up properly. -* <> describes support for +* xref:data-access/transaction/declarative.adoc[Declarative transaction management] describes support for declarative transaction management. -* <> covers support for +* xref:data-access/transaction/programmatic.adoc[Programmatic transaction management] covers support for programmatic (that is, explicitly coded) transaction management. -* <> describes how you could use application +* xref:data-access/transaction/event.adoc[Transaction bound event] describes how you could use application events within a transaction. The chapter also includes discussions of best practices, -<>, -and <>. +xref:data-access/transaction/application-server-integration.adoc[application server integration], +and xref:data-access/transaction/solutions-to-common-problems.adoc[solutions to common problems]. diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc index 949f8285df60..a87442d89167 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc @@ -22,7 +22,7 @@ necessary. The differences between the two types of transaction management are: * You can apply the Spring Framework declarative transaction management to any class, not merely special classes such as EJBs. * The Spring Framework offers declarative - <>, a feature with no EJB + xref:data-access/transaction/declarative/rolling-back.adoc[rollback rules], a feature with no EJB equivalent. Both programmatic and declarative support for rollback rules is provided. * The Spring Framework lets you customize transactional behavior by using AOP. For example, you can insert custom behavior in the case of transaction rollback. You diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc index 536df97c369a..83c9609e7000 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc @@ -70,7 +70,7 @@ Consider the following class definition: Used at the class level as above, the annotation indicates a default for all methods of the declaring class (as well as its subclasses). Alternatively, each method can be -annotated individually. See <> for +annotated individually. See xref:data-access/transaction/declarative/annotations.adoc#transaction-declarative-annotations-method-visibility[null] for further details on which methods Spring considers transactional. Note that a class-level annotation does not apply to ancestor classes up the class hierarchy; in such a scenario, inherited methods need to be locally redeclared in order to participate in a @@ -182,7 +182,7 @@ programming arrangements as the following listing shows: ---- Note that there are special considerations for the returned `Publisher` with regards to -Reactive Streams cancellation signals. See the <> section under +Reactive Streams cancellation signals. See the xref:data-access/transaction/programmatic.adoc#tx-prog-operator-cancel[Cancel Signals] section under "Using the TransactionalOperator" for more details. @@ -221,7 +221,7 @@ Note, however, that transactional methods in interface-based proxies must always ---- The _Spring TestContext Framework_ supports non-private `@Transactional` test methods by -default. See <> in the testing +default. See xref:testing/testcontext-framework/tx.adoc[Transaction Management] in the testing chapter for examples. ==== @@ -276,7 +276,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method. affected classes with Spring's AspectJ transaction aspect, modifying the target class byte code to apply to any kind of method call. AspectJ weaving requires `spring-aspects.jar` in the classpath as well as having load-time weaving (or compile-time - weaving) enabled. (See <> + weaving) enabled. (See xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration] for details on how to set up load-time weaving.) | `proxy-target-class` @@ -286,7 +286,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method. for classes annotated with the `@Transactional` annotation. If the `proxy-target-class` attribute is set to `true`, class-based proxies are created. If `proxy-target-class` is `false` or if the attribute is omitted, then standard JDK - interface-based proxies are created. (See <> + interface-based proxies are created. (See xref:core/aop/proxying.adoc[Proxying Mechanisms] for a detailed examination of the different proxy types.) | `order` @@ -294,7 +294,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method. | `Ordered.LOWEST_PRECEDENCE` | Defines the order of the transaction advice that is applied to beans annotated with `@Transactional`. (For more information about the rules related to ordering of AOP - advice, see <>.) + advice, see xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice Ordering].) No specified ordering means that the AOP subsystem determines the order of the advice. |=== @@ -307,14 +307,14 @@ NOTE: The `proxy-target-class` attribute controls what type of transactional pro created for classes annotated with the `@Transactional` annotation. If `proxy-target-class` is set to `true`, class-based proxies are created. If `proxy-target-class` is `false` or if the attribute is omitted, standard JDK -interface-based proxies are created. (See <> +interface-based proxies are created. (See xref:core/aop/proxying.adoc[Proxying Mechanisms] for a discussion of the different proxy types.) NOTE: `@EnableTransactionManagement` and `` look for `@Transactional` only on beans in the same application context in which they are defined. This means that, if you put annotation-driven configuration in a `WebApplicationContext` for a `DispatcherServlet`, it checks for `@Transactional` beans only in your controllers -and not in your services. See <> for more information. +and not in your services. See xref:web/webmvc/mvc-servlet.adoc[MVC] for more information. The most derived location takes precedence when evaluating the transactional settings for a method. In the case of the following example, the `DefaultFooService` class is @@ -382,7 +382,7 @@ properties of the `@Transactional` annotation: |=== | Property| Type| Description -| <> +| xref:data-access/transaction/declarative/annotations.adoc#tx-multiple-tx-mgrs-with-attransactional[value] | `String` | Optional qualifier that specifies the transaction manager to be used. @@ -394,7 +394,7 @@ properties of the `@Transactional` annotation: | Array of `String` labels to add an expressive description to the transaction. | Labels may be evaluated by transaction managers to associate implementation-specific behavior with the actual transaction. -| <> +| xref:data-access/transaction/declarative/tx-propagation.adoc[propagation] | `enum`: `Propagation` | Optional propagation setting. @@ -431,7 +431,7 @@ properties of the `@Transactional` annotation: | Optional array of exception name patterns that must not cause rollback. |=== -TIP: See <> for further details +TIP: See xref:data-access/transaction/declarative/rolling-back.adoc#transaction-declarative-rollback-rules[Rollback rules] for further details on rollback rule semantics, patterns, and warnings regarding possible unintentional matches for pattern-based rollback rules. @@ -523,7 +523,7 @@ is still used if no specifically qualified `TransactionManager` bean is found. == Custom Composed Annotations If you find you repeatedly use the same attributes with `@Transactional` on many different -methods, <> lets you +methods, xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[Spring's meta-annotation support] lets you define custom composed annotations for your specific use cases. For example, consider the following annotation definitions: diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc index a9fd8d8b2f8b..38d49bc4b095 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc @@ -13,7 +13,7 @@ When you invoke the `updateFoo(Foo)` method, you want to see the following actio * The profiling aspect reports the exact duration of the whole transactional method invocation. NOTE: This chapter is not concerned with explaining AOP in any great detail (except as it -applies to transactions). See <> for detailed coverage of the AOP +applies to transactions). See xref:core/aop.adoc[AOP] for detailed coverage of the AOP configuration and AOP in general. The following code shows the simple profiling aspect discussed earlier: @@ -95,7 +95,7 @@ The following code shows the simple profiling aspect discussed earlier: The ordering of advice is controlled through the `Ordered` interface. For full details on advice ordering, see -<>. +xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice ordering]. The following configuration creates a `fooService` bean that has profiling and transactional aspects applied to it in the desired order: diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc index cddd2e292479..477d4b0e9e6b 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc @@ -10,12 +10,12 @@ and then link (weave) your application with the manager. You can use the Spring Framework's IoC container to take care of dependency-injecting the aspect. The simplest way to configure the transaction management aspect is to use the `` element and specify the `mode` -attribute to `aspectj` as described in <>. Because +attribute to `aspectj` as described in xref:data-access/transaction/declarative/annotations.adoc[Using `@Transactional`]. Because we focus here on applications that run outside of a Spring container, we show you how to do it programmatically. -NOTE: Prior to continuing, you may want to read <> and -<> respectively. +NOTE: Prior to continuing, you may want to read xref:data-access/transaction/declarative/annotations.adoc[Using `@Transactional`] and +xref:core/aop.adoc[AOP] respectively. The following example shows how to create a transaction manager and configure the `AnnotationTransactionAspect` to use it: @@ -53,8 +53,8 @@ regardless of visibility. To weave your applications with the `AnnotationTransactionAspect`, you must either build your application with AspectJ (see the https://www.eclipse.org/aspectj/doc/released/devguide/index.html[AspectJ Development -Guide]) or use load-time weaving. See <> for a discussion of load-time weaving with AspectJ. +Guide]) or use load-time weaving. See xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time weaving with AspectJ in the Spring Framework] + for a discussion of load-time weaving with AspectJ. diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc index 167e109daf10..5bbe41208f1c 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc @@ -187,7 +187,7 @@ advisor. The result indicates that, at the execution of a `fooServiceOperation`, the advice defined by `txAdvice` is run. The expression defined within the `` element is an AspectJ pointcut -expression. See <> for more details on pointcut +expression. See xref:core/aop.adoc[the AOP section] for more details on pointcut expressions in Spring. A common requirement is to make an entire service layer transactional. The best way to @@ -203,7 +203,7 @@ service layer. The following example shows how to do so: ---- NOTE: In the preceding example, it is assumed that all your service interfaces are defined -in the `x.y.service` package. See <> for more details. +in the `x.y.service` package. See xref:core/aop.adoc[the AOP section] for more details. Now that we have analyzed the configuration, you may be asking yourself, "What does all this configuration actually do?" diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc index 4391a8ef4a95..1145aabb86d8 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc @@ -6,7 +6,7 @@ classes, typically service layer classes, declaratively in your application. Thi describes how you can control the rollback of transactions in a simple, declarative fashion in XML configuration. For details on controlling rollback semantics declaratively with the `@Transactional` annotation, see -<>. +xref:data-access/transaction/declarative/annotations.adoc#transaction-declarative-attransactional-settings[`@Transactional` Settings]. The recommended way to indicate to the Spring Framework's transaction infrastructure that a transaction's work is to be rolled back is to throw an `Exception` from code that @@ -51,7 +51,7 @@ thrown, and the rules are based on exception types or exception patterns. Rollback rules may be configured in XML via the `rollback-for` and `no-rollback-for` attributes, which allow rules to be defined as patterns. When using -<>, rollback rules may +xref:data-access/transaction/declarative/annotations.adoc#transaction-declarative-attransactional-settings[`@Transactional`], rollback rules may be configured via the `rollbackFor`/`noRollbackFor` and `rollbackForClassName`/`noRollbackForClassName` attributes, which allow rules to be defined based on exception types or patterns, respectively. diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc index e3372fc1edc5..f59bb26b0005 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc @@ -9,13 +9,13 @@ infrastructure in the context of transaction-related issues. The most important concepts to grasp with regard to the Spring Framework's declarative transaction support are that this support is enabled -<> and that the transactional +xref:core/aop/proxying.adoc#aop-understanding-aop-proxies[via AOP proxies] and that the transactional advice is driven by metadata (currently XML- or annotation-based). The combination of AOP with transactional metadata yields an AOP proxy that uses a `TransactionInterceptor` in conjunction with an appropriate `TransactionManager` implementation to drive transactions around method invocations. -NOTE: Spring AOP is covered in <>. +NOTE: Spring AOP is covered in xref:core/aop.adoc[the AOP section]. Spring Framework's `TransactionInterceptor` provides transaction management for imperative and reactive programming models. The interceptor detects the desired flavor of diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc index cac80d805b42..566f44d1f65a 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc @@ -4,7 +4,7 @@ This section summarizes the various transactional settings that you can specify by using the `` tag. The default `` settings are: -* The <> is `REQUIRED.` +* The xref:data-access/transaction/declarative/tx-propagation.adoc[propagation setting] is `REQUIRED.` * The isolation level is `DEFAULT.` * The transaction is read-write. * The transaction timeout defaults to the default timeout of the underlying transaction diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc index 60a51310fabb..4b211aff981f 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc @@ -139,7 +139,7 @@ Code within the callback can roll the transaction back by calling the You can specify transaction settings (such as the propagation mode, the isolation level, the timeout, and so forth) on the `TransactionTemplate` either programmatically or in configuration. By default, `TransactionTemplate` instances have the -<>. The +xref:data-access/transaction/declarative/txadvice-settings.adoc[default transactional settings]. The following example shows the programmatic customization of the transactional settings for a specific `TransactionTemplate:` @@ -302,7 +302,7 @@ the full output must be consumed to allow the transaction to complete. You can specify transaction settings (such as the propagation mode, the isolation level, the timeout, and so forth) for the `TransactionalOperator`. By default, `TransactionalOperator` instances have -<>. The +xref:data-access/transaction/declarative/txadvice-settings.adoc[default transactional settings]. The following example shows customization of the transactional settings for a specific `TransactionalOperator:` diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc index 562a5162441e..2c5ecd6e66ec 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc @@ -12,7 +12,7 @@ transactional technologies and requirements. Used properly, the Spring Framework provides a straightforward and portable abstraction. If you use global transactions, you must use the `org.springframework.transaction.jta.JtaTransactionManager` class (or an -<> of +xref:data-access/transaction/application-server-integration.adoc[application server-specific subclass] of it) for all your transactional operations. Otherwise, the transaction infrastructure tries to perform local transactions on such resources as container `DataSource` instances. Such local transactions do not make sense, and a good application server diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc index 7b3c8f9368d9..52a2ddb264fe 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc @@ -22,7 +22,7 @@ transaction management. The following listing shows the definition of the ---- This is primarily a service provider interface (SPI), although you can use it -<> from your application code. Because +xref:data-access/transaction/programmatic.adoc#transaction-programmatic-ptm[programmatically] from your application code. Because `PlatformTransactionManager` is an interface, it can be easily mocked or stubbed as necessary. It is not tied to a lookup strategy, such as JNDI. `PlatformTransactionManager` implementations are defined like any other object (or bean) @@ -63,7 +63,7 @@ listing shows the transaction strategy defined by ---- The reactive transaction manager is primarily a service provider interface (SPI), -although you can use it <> from your +although you can use it xref:data-access/transaction/programmatic.adoc#transaction-programmatic-rtm[programmatically] from your application code. Because `ReactiveTransactionManager` is an interface, it can be easily mocked or stubbed as necessary. @@ -75,7 +75,7 @@ The `TransactionDefinition` interface specifies: example, code can continue running in the existing transaction (the common case), or the existing transaction can be suspended and a new transaction created. Spring offers all of the transaction propagation options familiar from EJB CMT. To read - about the semantics of transaction propagation in Spring, see <>. + about the semantics of transaction propagation in Spring, see xref:data-access/transaction/declarative/tx-propagation.adoc[Transaction Propagation]. * Isolation: The degree to which this transaction is isolated from the work of other transactions. For example, can this transaction see uncommitted writes from other transactions? @@ -179,7 +179,7 @@ infrastructure. NOTE: The preceding definition of the `dataSource` bean uses the `` tag from the `jee` namespace. For more information see -<>. +xref:integration/appendix.adoc#integration.appendix.xsd-schemas-jee[The JEE Schema]. NOTE: If you use JTA, your transaction manager definition should look the same, regardless of what data access technology you use, be it JDBC, Hibernate JPA, or any other supported diff --git a/framework-docs/modules/ROOT/pages/index.adoc b/framework-docs/modules/ROOT/pages/index.adoc index c62a2b2899f3..b6897ab17616 100644 --- a/framework-docs/modules/ROOT/pages/index.adoc +++ b/framework-docs/modules/ROOT/pages/index.adoc @@ -3,22 +3,22 @@ = Spring Framework Documentation [horizontal] -<> :: History, Design Philosophy, Feedback, +xref:web/websocket/stomp/overview.adoc[Overview] :: History, Design Philosophy, Feedback, Getting Started. -<> :: IoC Container, Events, Resources, i18n, +xref:core.adoc[Core] :: IoC Container, Events, Resources, i18n, Validation, Data Binding, Type Conversion, SpEL, AOP, AOT. <> :: Mock Objects, TestContext Framework, Spring MVC Test, WebTestClient. -<> :: Transactions, DAO Support, +xref:data-access.adoc[Data Access] :: Transactions, DAO Support, JDBC, R2DBC, O/R Mapping, XML Marshalling. -<> :: Spring MVC, WebSocket, SockJS, +xref:web.adoc[Web Servlet] :: Spring MVC, WebSocket, SockJS, STOMP Messaging. -<> :: Spring WebFlux, WebClient, +xref:testing/unit.adoc#mock-objects-web-reactive[Web Reactive] :: Spring WebFlux, WebClient, WebSocket, RSocket. -<> :: REST Clients, JMS, JCA, JMX, +xref:integration.adoc[Integration] :: REST Clients, JMS, JCA, JMX, Email, Tasks, Scheduling, Caching, Observability. -<> :: Kotlin, Groovy, Dynamic Languages. -<> :: Spring properties. +xref:languages.adoc[Languages] :: Kotlin, Groovy, Dynamic Languages. +xref:testing/appendix.adoc[Appendix] :: Spring properties. https://github.com/spring-projects/spring-framework/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information. diff --git a/framework-docs/modules/ROOT/pages/integration/appendix.adoc b/framework-docs/modules/ROOT/pages/integration/appendix.adoc index e714522b6165..b07294bdbaf1 100644 --- a/framework-docs/modules/ROOT/pages/integration/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/integration/appendix.adoc @@ -272,9 +272,9 @@ with `jee`: === The `jms` Schema The `jms` elements deal with configuring JMS-related beans, such as Spring's -<>. These elements are detailed in the -section of the <> entitled <>. See that chapter for full details on this support +xref:integration/jms/using.adoc#jms-mdp[Message Listener Containers]. These elements are detailed in the +section of the xref:integration/jms.adoc[JMS chapter] entitled xref:integration/jms/namespace.adoc[JMS Namespace Support] +. See that chapter for full details on this support and the `jms` elements themselves. In the interest of completeness, to use the elements in the `jms` schema, you need to have @@ -305,7 +305,7 @@ are available to you: === Using `` This element is detailed in -<>. +xref:integration/jmx/naming.adoc#jmx-context-mbeanexport[Configuring Annotation-based MBean Export]. @@ -314,8 +314,8 @@ This element is detailed in You can use the `cache` elements to enable support for Spring's `@CacheEvict`, `@CachePut`, and `@Caching` annotations. It it also supports declarative XML-based caching. See -<> and -<> for details. +xref:integration/cache/annotations.adoc#cache-annotation-enable[Enabling Caching Annotations] and +xref:integration/cache/declarative-xml.adoc[Declarative XML-based Caching] for details. To use the elements in the `cache` schema, you need to have the following preamble at the top of your Spring XML configuration file. The text in the following snippet references diff --git a/framework-docs/modules/ROOT/pages/integration/cache.adoc b/framework-docs/modules/ROOT/pages/integration/cache.adoc index 9042bfdc8b2c..689a031b22c4 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache.adoc @@ -2,12 +2,12 @@ = Cache Abstraction Since version 3.1, the Spring Framework provides support for transparently adding caching to -an existing Spring application. Similar to the <> +an existing Spring application. Similar to the xref:data-access/transaction.adoc[transaction] support, the caching abstraction allows consistent use of various caching solutions with minimal impact on the code. In Spring Framework 4.1, the cache abstraction was significantly extended with support -for <> and more customization options. +for xref:integration/cache/jsr-107.adoc[JSR-107 annotations] and more customization options. diff --git a/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc index a602e14f0384..f4114765cbfd 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc @@ -94,16 +94,16 @@ they are no use for the cache. Furthermore, what if only one of the two is impor while the other is not? For such cases, the `@Cacheable` annotation lets you specify how the key is generated -through its `key` attribute. You can use <> to pick the +through its `key` attribute. You can use xref:core/expressions.adoc[SpEL] to pick the arguments of interest (or their nested properties), perform operations, or even invoke arbitrary methods without having to write any code or implement any interface. This is the recommended approach over the -<>, since methods tend to be +xref:integration/cache/annotations.adoc#cache-annotations-cacheable-default-key[default generator], since methods tend to be quite different in signatures as the code base grows. While the default strategy might work for some methods, it rarely works for all methods. The following examples use various SpEL declarations (if you are not familiar with SpEL, -do yourself a favor and read <>): +do yourself a favor and read xref:core/expressions.adoc[Spring Expression Language]): [source,java,indent=0,subs="verbatim,quotes"] ---- @@ -162,7 +162,7 @@ For applications that work with several cache managers, you can set the You can also replace the `CacheResolver` entirely in a fashion similar to that of -replacing <>. The resolution is +replacing xref:integration/cache/annotations.adoc#cache-annotations-cacheable-key[key generation]. The resolution is requested for every cache operation, letting the implementation actually resolve the caches to use based on runtime arguments. The following example shows how to specify a `CacheResolver`: @@ -256,12 +256,12 @@ as follows: ---- Note that `#result` still refers to `Book` and not `Optional`. Since it might be -`null`, we use SpEL's <>. +`null`, we use SpEL's xref:core/expressions/language-ref/operator-safe-navigation.adoc[safe navigation operator]. [[cache-spel-context]] === Available Caching SpEL Evaluation Context -Each `SpEL` expression evaluates against a dedicated <>. +Each `SpEL` expression evaluates against a dedicated xref:core/expressions/language-ref.adoc[`context`]. In addition to the built-in parameters, the framework provides dedicated caching-related metadata, such as the argument names. The following table describes the items made available to the context so that you can use them for key and conditional computations: @@ -472,7 +472,7 @@ Alternatively, for XML configuration you can use the `cache:annotation-driven` e Both the `cache:annotation-driven` element and the `@EnableCaching` annotation let you specify various options that influence the way the caching behavior is added to the application through AOP. The configuration is intentionally similar with that of -<>. +xref:data-access/transaction/declarative/annotations.adoc#tx-annotation-driven-settings[`@Transactional`]. NOTE: The default advice mode for processing caching annotations is `proxy`, which allows for interception of calls through the proxy only. Local calls within the same class @@ -524,7 +524,7 @@ required to implement `CachingConfigurer`, see the affected classes with Spring's AspectJ caching aspect, modifying the target class byte code to apply to any kind of method call. AspectJ weaving requires `spring-aspects.jar` in the classpath as well as load-time weaving (or compile-time weaving) enabled. (See - <> for details on how to set up + xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration] for details on how to set up load-time weaving.) | `proxy-target-class` @@ -534,7 +534,7 @@ required to implement `CachingConfigurer`, see the classes annotated with the `@Cacheable` or `@CacheEvict` annotations. If the `proxy-target-class` attribute is set to `true`, class-based proxies are created. If `proxy-target-class` is `false` or if the attribute is omitted, standard JDK - interface-based proxies are created. (See <> + interface-based proxies are created. (See xref:core/aop/proxying.adoc[Proxying Mechanisms] for a detailed examination of the different proxy types.) | `order` @@ -542,7 +542,7 @@ required to implement `CachingConfigurer`, see the | Ordered.LOWEST_PRECEDENCE | Defines the order of the cache advice that is applied to beans annotated with `@Cacheable` or `@CacheEvict`. (For more information about the rules related to - ordering AOP advice, see <>.) + ordering AOP advice, see xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice Ordering].) No specified ordering means that the AOP subsystem determines the order of the advice. |=== @@ -550,7 +550,7 @@ NOTE: `` looks for `@Cacheable/@CachePut/@CacheEvict/@ only on beans in the same application context in which it is defined. This means that, if you put `` in a `WebApplicationContext` for a `DispatcherServlet`, it checks for beans only in your controllers, not your services. -See <> for more information. +See xref:web/webmvc/mvc-servlet.adoc[the MVC section] for more information. .Method visibility and cache annotations **** @@ -595,9 +595,9 @@ triggers cache population or eviction. This is quite handy as a template mechani as it eliminates the need to duplicate cache annotation declarations, which is especially useful if the key or condition are specified or if the foreign imports (`org.springframework`) are not allowed in your code base. Similarly to the rest -of the <> annotations, you can +of the xref:core/beans/classpath-scanning.adoc#beans-stereotype-annotations[stereotype] annotations, you can use `@Cacheable`, `@CachePut`, `@CacheEvict`, and `@CacheConfig` as -<> (that is, annotations that +xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotations] (that is, annotations that can annotate other annotations). In the following example, we replace a common `@Cacheable` declaration with our own custom annotation: @@ -630,7 +630,7 @@ preceding code: Even though `@SlowService` is not a Spring annotation, the container automatically picks up its declaration at runtime and understands its meaning. Note that, as mentioned -<>, annotation-driven behavior needs to be enabled. +xref:integration/cache/annotations.adoc#cache-annotation-enable[earlier], annotation-driven behavior needs to be enabled. diff --git a/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc b/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc index b62a6a5e5d5a..7b28afd74675 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc @@ -5,7 +5,7 @@ If annotations are not an option (perhaps due to having no access to the sources or no external code), you can use XML for declarative caching. So, instead of annotating the methods for caching, you can specify the target method and the caching directives externally (similar to the declarative transaction management -<>). The example +xref:data-access/transaction/declarative/first-example.adoc[advice]). The example from the previous section can be translated into the following example: [source,xml,indent=0] @@ -37,7 +37,7 @@ data. Both definitions work against the `books` cache. The `aop:config` definition applies the cache advice to the appropriate points in the program by using the AspectJ pointcut expression (more information is available in -<>). In the preceding example, +xref:core/aop.adoc[Aspect Oriented Programming with Spring]). In the preceding example, all methods from the `BookService` are considered and the cache advice is applied to them. The declarative XML caching supports all of the annotation-based model, so moving between diff --git a/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc b/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc index 20f2735545ba..1bf06494097b 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc @@ -74,8 +74,8 @@ bean lifecycle callbacks, such as dependency injection. Keys are generated by a `javax.cache.annotation.CacheKeyGenerator` that serves the same purpose as Spring's `KeyGenerator`. By default, all method arguments are taken into account, unless at least one parameter is annotated with `@CacheKey`. This is -similar to Spring's <>. For instance, the following are identical operations, one using +similar to Spring's xref:integration/cache/annotations.adoc#cache-annotations-cacheable-key[custom key generation declaration] +. For instance, the following are identical operations, one using Spring's abstraction and the other using JCache: [source,java,indent=0,subs="verbatim,quotes"] diff --git a/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc b/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc index 1bda81c330d8..c8009ce25154 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc @@ -40,7 +40,7 @@ or eviction contracts. == Ehcache-based Cache Ehcache 3.x is fully JSR-107 compliant and no dedicated support is required for it. See -<> for details. +xref:integration/cache/store-configuration.adoc#cache-store-configuration-jsr107[JSR-107 Cache] for details. [[cache-store-configuration-caffeine]] diff --git a/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc b/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc index 826a4e9c8a6f..4235f0617454 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc @@ -45,10 +45,10 @@ that is, the abstraction frees you from having to write the caching logic but do provide the actual data store. This abstraction is materialized by the `org.springframework.cache.Cache` and `org.springframework.cache.CacheManager` interfaces. -Spring provides <> of that abstraction: +Spring provides xref:integration/cache/store-configuration.adoc[a few implementations] of that abstraction: JDK `java.util.concurrent.ConcurrentMap` based caches, Gemfire cache, https://github.com/ben-manes/caffeine/wiki[Caffeine], and JSR-107 compliant caches (such -as Ehcache 3.x). See <> for more information on plugging in other cache +as Ehcache 3.x). See xref:integration/cache/plug.adoc[Plugging-in Different Back-end Caches] for more information on plugging in other cache stores and providers. IMPORTANT: The caching abstraction has no special handling for multi-threaded and diff --git a/framework-docs/modules/ROOT/pages/integration/email.adoc b/framework-docs/modules/ROOT/pages/integration/email.adoc index fd82a39febfa..610fda7c8797 100644 --- a/framework-docs/modules/ROOT/pages/integration/email.adoc +++ b/framework-docs/modules/ROOT/pages/integration/email.adoc @@ -181,7 +181,7 @@ callback interface. In the following example, the `mailSender` property is of ty ---- NOTE: The mail code is a crosscutting concern and could well be a candidate for -refactoring into a <>, which could then +refactoring into a xref:core/aop.adoc[custom Spring AOP aspect], which could then be run at appropriate joinpoints on the `OrderManager` target. The Spring Framework's mail support ships with the standard JavaMail implementation. diff --git a/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc b/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc index e42387063a25..edda9de3d387 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc @@ -18,7 +18,7 @@ bean as a JMS listener endpoint. The following example shows how to use it: The idea of the preceding example is that, whenever a message is available on the `jakarta.jms.Destination` `myDestination`, the `processOrder` method is invoked accordingly (in this case, with the content of the JMS message, similar to -what the <> +what the xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[`MessageListenerAdapter`] provides). The annotated endpoint infrastructure creates a message listener container @@ -67,7 +67,7 @@ container factory. See the javadoc of classes that implement {api-spring-framework}/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`] for details and examples. -If you prefer <>, you can use the `` +If you prefer xref:integration/jms/namespace.adoc[XML configuration], you can use the `` element, as the following example shows: [source,xml,indent=0,subs="verbatim,quotes"] @@ -197,7 +197,7 @@ annotate the payload with `@Valid` and configure the necessary validator, as the [[jms-annotated-response]] == Response Management -The existing support in <> +The existing support in xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[`MessageListenerAdapter`] already lets your method have a non-`void` return type. When that is the case, the result of the invocation is encapsulated in a `jakarta.jms.Message`, sent either in the destination specified in the `JMSReplyTo` header of the original message or in the default destination configured on diff --git a/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc b/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc index b6e2f580e0da..be6cb7b45cbd 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc @@ -24,8 +24,8 @@ namespace elements, you need to reference the JMS schema, as the following examp The namespace consists of three top-level elements: ``, `` -and ``. `` enables the use of <>. `` and `` +and ``. `` enables the use of xref:integration/jms/annotated.adoc[annotation-driven listener endpoints] +. `` and `` define shared listener container configuration and can contain `` child elements. The following example shows a basic configuration for two listeners: @@ -42,7 +42,7 @@ The following example shows a basic configuration for two listeners: The preceding example is equivalent to creating two distinct listener container bean definitions and two distinct `MessageListenerAdapter` bean definitions, as shown -in <>. In addition to the attributes shown +in xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[Using `MessageListenerAdapter`]. In addition to the attributes shown in the preceding example, the `listener` element can contain several optional ones. The following table describes all of the available attributes: diff --git a/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc b/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc index 72658c5464b6..ff47edf51210 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc @@ -21,11 +21,11 @@ the receiver should wait before giving up waiting for a message. NOTE: Spring also supports annotated-listener endpoints through the use of the `@JmsListener` annotation and provides an open infrastructure to register endpoints programmatically. This is, by far, the most convenient way to setup an asynchronous receiver. -See <> for more details. +See xref:integration/jms/annotated.adoc#jms-annotated-support[Enable Listener Endpoint Annotations] for more details. In a fashion similar to a Message-Driven Bean (MDB) in the EJB world, the Message-Driven POJO (MDP) acts as a receiver for JMS messages. The one restriction (but see -<>) on an MDP is that it must implement +xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[Using `MessageListenerAdapter`]) on an MDP is that it must implement the `jakarta.jms.MessageListener` interface. Note that, if your POJO receives messages on multiple threads, it is important to ensure that your implementation is thread-safe. diff --git a/framework-docs/modules/ROOT/pages/integration/jms/using.adoc b/framework-docs/modules/ROOT/pages/integration/jms/using.adoc index 53883f7fa387..db342992e03e 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/using.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/using.adoc @@ -167,9 +167,9 @@ operations that do not refer to a specific destination. One of the most common uses of JMS messages in the EJB world is to drive message-driven beans (MDBs). Spring offers a solution to create message-driven POJOs (MDPs) in a way -that does not tie a user to an EJB container. (See <> for detailed +that does not tie a user to an EJB container. (See xref:integration/jms/receiving.adoc#jms-receiving-async[Asynchronous reception: Message-Driven POJOs] for detailed coverage of Spring's MDP support.) Since Spring Framework 4.1, endpoint methods can be -annotated with `@JmsListener` -- see <> for more details. +annotated with `@JmsListener` -- see xref:integration/jms/annotated.adoc[Annotation-driven Listener Endpoints] for more details. A message listener container is used to receive messages from a JMS message queue and drive the `MessageListener` that is injected into it. The listener container is @@ -184,8 +184,8 @@ boilerplate JMS infrastructure concerns to the framework. There are two standard JMS message listener containers packaged with Spring, each with its specialized feature set. -* <> -* <> +* xref:integration/jms/using.adoc#jms-mdp-simple[`SimpleMessageListenerContainer`] +* xref:integration/jms/using.adoc#jms-mdp-default[`DefaultMessageListenerContainer`] [[jms-mdp-simple]] === Using `SimpleMessageListenerContainer` @@ -236,7 +236,7 @@ a simple `BackOff` implementation retries every five seconds. You can specify a custom `BackOff` implementation for more fine-grained recovery options. See {api-spring-framework}/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example. -NOTE: Like its sibling (<>), +NOTE: Like its sibling (xref:integration/jms/using.adoc#jms-mdp-simple[`SimpleMessageListenerContainer`]), `DefaultMessageListenerContainer` supports native JMS transactions and allows for customizing the acknowledgment mode. If feasible for your scenario, This is strongly recommended over externally managed transactions -- that is, if you can live with @@ -263,7 +263,7 @@ reliability needs (for example, for reliable queue handling and durable topic su Spring provides a `JmsTransactionManager` that manages transactions for a single JMS `ConnectionFactory`. This lets JMS applications leverage the managed-transaction features of Spring, as described in -<>. +xref:data-access/transaction.adoc[Transaction Management section of the Data Access chapter]. The `JmsTransactionManager` performs local resource transactions, binding a JMS Connection/Session pair from the specified `ConnectionFactory` to the thread. `JmsTemplate` automatically detects such transactional resources and operates diff --git a/framework-docs/modules/ROOT/pages/integration/jmx.adoc b/framework-docs/modules/ROOT/pages/integration/jmx.adoc index 10a8c063d8a1..40e2bcd0096b 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx.adoc @@ -7,7 +7,7 @@ easily and transparently integrate your Spring application into a JMX infrastruc .JMX? **** This chapter is not an introduction to JMX. It does not try to explain why you might want -to use JMX. If you are new to JMX, see <> at the end of this chapter. +to use JMX. If you are new to JMX, see xref:integration/jmx/resources.adoc[Further Resources] at the end of this chapter. **** Specifically, Spring's JMX support provides four core features: diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc index fb452d849f99..fdc637ad2e04 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc @@ -67,15 +67,15 @@ The pertinent bean definition from the preceding configuration snippet is the `e bean. The `beans` property tells the `MBeanExporter` exactly which of your beans must be exported to the JMX `MBeanServer`. In the default configuration, the key of each entry in the `beans` `Map` is used as the `ObjectName` for the bean referenced by the -corresponding entry value. You can change this behavior, as described in <>. +corresponding entry value. You can change this behavior, as described in xref:integration/jmx/naming.adoc[Controlling `ObjectName` Instances for Your Beans]. With this configuration, the `testBean` bean is exposed as an MBean under the `ObjectName` `bean:name=testBean1`. By default, all `public` properties of the bean are exposed as attributes and all `public` methods (except those inherited from the `Object` class) are exposed as operations. -NOTE: `MBeanExporter` is a `Lifecycle` bean (see <>). By default, MBeans are exported as late as possible during +NOTE: `MBeanExporter` is a `Lifecycle` bean (see xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-processor[Startup and Shutdown Callbacks] +). By default, MBeans are exported as late as possible during the application lifecycle. You can configure the `phase` at which the export happens or disable automatic registration by setting the `autoStartup` flag. @@ -83,7 +83,7 @@ the export happens or disable automatic registration by setting the `autoStartup [[jmx-exporting-mbeanserver]] == Creating an MBeanServer -The configuration shown in the <> assumes that the +The configuration shown in the xref:integration/jmx/exporting.adoc[preceding section] assumes that the application is running in an environment that has one (and only one) `MBeanServer` already running. In this case, Spring tries to locate the running `MBeanServer` and register your beans with that server (if any). This behavior is useful when your @@ -159,7 +159,7 @@ be used, as the following example shows: For platforms or cases where the existing `MBeanServer` has a dynamic (or unknown) `agentId` that is retrieved through lookup methods, you should use -<>, +xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[factory-method], as the following example shows: [source,xml,indent=0,subs="verbatim,quotes"] @@ -208,7 +208,7 @@ property to `true`, as the following example shows: In the preceding example, the bean called `spring:mbean=true` is already a valid JMX MBean and is automatically registered by Spring. By default, a bean that is autodetected for JMX registration has its bean name used as the `ObjectName`. You can override this behavior, -as detailed in <>. +as detailed in xref:integration/jmx/naming.adoc[Controlling `ObjectName` Instances for Your Beans]. [[jmx-exporting-registration-behavior]] diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc index 98598aefefd4..f9458765aac1 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc @@ -1,7 +1,7 @@ [[jmx-interface]] = Controlling the Management Interface of Your Beans -In the example in the <>, +In the example in the xref:integration/jmx/exporting.adoc#jmx-exporting-registration-behavior[preceding section], you had little control over the management interface of your bean. All of the `public` properties and methods of each exported bean were exposed as JMX attributes and operations, respectively. To exercise finer-grained control over exactly which @@ -47,7 +47,7 @@ NOTE: A `ManagedResource`-annotated bean must be public, as must the methods exp an operation or an attribute. The following example shows the annotated version of the `JmxTestBean` class that we -used in <>: +used in xref:integration/jmx/exporting.adoc#jmx-exporting-mbeanserver[Creating an MBeanServer]: [source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ---- @@ -113,7 +113,7 @@ In the preceding example, you can see that the `JmxTestBean` class is marked wit `ManagedResource` annotation and that this `ManagedResource` annotation is configured with a set of properties. These properties can be used to configure various aspects of the MBean that is generated by the `MBeanExporter` and are explained in greater -detail later in <>. +detail later in xref:integration/jmx/interface.adoc#jmx-interface-metadata-types[Source-level Metadata Types]. Both the `age` and `name` properties are annotated with the `ManagedAttribute` annotation, but, in the case of the `age` property, only the getter is marked. @@ -293,7 +293,7 @@ However, the `JmxTestBean` is still registered, since it is marked with the `Man attribute and the `MetadataMBeanInfoAssembler` detects this and votes to include it. The only problem with this approach is that the name of the `JmxTestBean` now has business meaning. You can address this issue by changing the default behavior for `ObjectName` -creation as defined in <>. +creation as defined in xref:integration/jmx/naming.adoc[Controlling `ObjectName` Instances for Your Beans]. [[jmx-interface-java]] diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc index 0a0d423d3530..39b958281900 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc @@ -116,7 +116,7 @@ example, the generated `ObjectName` for the following bean would be [[jmx-context-mbeanexport]] == Configuring Annotation-based MBean Export -If you prefer to use <> to define +If you prefer to use xref:integration/jmx/interface.adoc#jmx-interface-metadata[the annotation-based approach] to define your management interfaces, a convenience subclass of `MBeanExporter` is available: `AnnotationMBeanExporter`. When defining an instance of this subclass, you no longer need the `namingStrategy`, `assembler`, and `attributeSource` configuration, @@ -146,7 +146,7 @@ If necessary, you can provide a reference to a particular MBean `server`, and th `defaultDomain` attribute (a property of `AnnotationMBeanExporter`) accepts an alternate value for the generated MBean `ObjectName` domains. This is used in place of the fully qualified package name as described in the previous section on -<>, as the following example shows: +xref:integration/jmx/naming.adoc#jmx-naming-metadata[MetadataNamingStrategy], as the following example shows: [source,java,indent=0,subs="verbatim,quotes"] ---- diff --git a/framework-docs/modules/ROOT/pages/integration/observability.adoc b/framework-docs/modules/ROOT/pages/integration/observability.adoc index 735d6aeb3b7b..b7453decaa88 100644 --- a/framework-docs/modules/ROOT/pages/integration/observability.adoc +++ b/framework-docs/modules/ROOT/pages/integration/observability.adoc @@ -14,17 +14,17 @@ You can learn more about {docs-spring-boot}/html/actuator.html#actuator.metrics[ == List of produced Observations Spring Framework instruments various features for observability. -As outlined <>, observations can generate timer Metrics and/or Traces depending on the configuration. +As outlined xref:integration/observability.adoc[at the beginning of this section], observations can generate timer Metrics and/or Traces depending on the configuration. .Observations produced by Spring Framework [%autowidth] |=== |Observation name |Description -|<> +|xref:integration/observability.adoc#integration.observability.http-client[`"http.client.requests"`] |Time spent for HTTP client exchanges -|<> +|xref:integration/observability.adoc#integration.observability.http-server[`"http.server.requests"`] |Processing time for HTTP server exchanges at the Framework level |=== @@ -92,7 +92,7 @@ Applications need to configure the `org.springframework.web.filter.ServerHttpObs It is using the `org.springframework.http.server.observation.DefaultServerRequestObservationConvention` by default, backed by the `ServerRequestObservationContext`. This will only record an observation as an error if the `Exception` has not been handled by the web Framework and has bubbled up to the Servlet filter. -Typically, all exceptions handled by Spring MVC's `@ExceptionHandler` and <> will not be recorded with the observation. +Typically, all exceptions handled by Spring MVC's `@ExceptionHandler` and xref:web/webmvc/mvc-ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: include::code:UserController[] @@ -125,7 +125,7 @@ Applications need to configure the `org.springframework.web.filter.reactive.Serv It is using the `org.springframework.http.server.reactive.observation.DefaultServerRequestObservationConvention` by default, backed by the `ServerRequestObservationContext`. This will only record an observation as an error if the `Exception` has not been handled by the web Framework and has bubbled up to the `WebFilter`. -Typically, all exceptions handled by Spring WebFlux's `@ExceptionHandler` and <> will not be recorded with the observation. +Typically, all exceptions handled by Spring WebFlux's `@ExceptionHandler` and xref:web/webflux/ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: include::code:UserController[] diff --git a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc index 8a47198d4b10..b34aa4c85d09 100644 --- a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc +++ b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc @@ -3,9 +3,9 @@ The Spring Framework provides the following choices for making calls to REST endpoints: -* <> - non-blocking, reactive client w fluent API. -* <> - synchronous client with template method API. -* <> - annotated interface with generated, dynamic proxy implementation. +* xref:integration/rest-clients.adoc#rest-webclient[`WebClient`] - non-blocking, reactive client w fluent API. +* xref:integration/rest-clients.adoc#rest-resttemplate[`RestTemplate`] - synchronous client with template method API. +* xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface] - annotated interface with generated, dynamic proxy implementation. [[rest-webclient]] @@ -24,7 +24,7 @@ synchronous, asynchronous, and streaming scenarios. * Synchronous and asynchronous interactions. * Streaming up to or streaming down from a server. -See <> for more details. +See xref:web/webflux-webclient.adoc[WebClient] for more details. @@ -38,7 +38,7 @@ overloaded methods: NOTE: `RestTemplate` is in maintenance mode, with only requests for minor changes and bugs to be accepted. Please, consider using the -<> instead. +xref:web/webflux-webclient.adoc[WebClient] instead. [[rest-overview-of-resttemplate-methods-tbl]] .RestTemplate methods @@ -118,7 +118,7 @@ accessing the status of a response that represents an error (such as 401). If th issue, switch to another HTTP client library. NOTE: `RestTemplate` can be instrumented for observability, in order to produce metrics and traces. -See the <> section. +See the xref:integration/observability.adoc#integration.observability.http-client.resttemplate[RestTemplate Observability support] section. [[rest-resttemplate-uri]] ==== URIs @@ -157,7 +157,7 @@ You can use the `uriTemplateHandler` property of `RestTemplate` to customize how are encoded. Alternatively, you can prepare a `java.net.URI` and pass it into one of the `RestTemplate` methods that accepts a `URI`. -For more details on working with and encoding URIs, see <>. +For more details on working with and encoding URIs, see xref:web/webmvc/mvc-uri-building.adoc[URI Links]. [[rest-template-headers]] ==== Headers @@ -212,13 +212,13 @@ then helps to populate the `Accept` header. If necessary, you can use the `excha methods to provide the `Accept` header explicitly. By default, `RestTemplate` registers all built-in -<>, depending on classpath checks that help +xref:integration/rest-clients.adoc#rest-message-conversion[message converters], depending on classpath checks that help to determine what optional conversion libraries are present. You can also set the message converters to use explicitly. [[rest-message-conversion]] ==== Message Conversion -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs[See equivalent in the Reactive stack]# The `spring-web` module contains the `HttpMessageConverter` contract for reading and writing the body of HTTP requests and responses through `InputStream` and `OutputStream`. @@ -228,7 +228,7 @@ on the server side (for example, in Spring MVC REST controllers). Concrete implementations for the main media (MIME) types are provided in the framework and are, by default, registered with the `RestTemplate` on the client side and with `RequestMappingHandlerAdapter` on the server side (see -<>). +xref:web/webmvc/mvc-config/message-converters.adoc[Configuring Message Converters]). The implementations of `HttpMessageConverter` are described in the following sections. For all converters, a default media type is used, but you can override it by setting the diff --git a/framework-docs/modules/ROOT/pages/integration/scheduling.adoc b/framework-docs/modules/ROOT/pages/integration/scheduling.adoc index 6f60f4aef041..eae7ff2e7045 100644 --- a/framework-docs/modules/ROOT/pages/integration/scheduling.adoc +++ b/framework-docs/modules/ROOT/pages/integration/scheduling.adoc @@ -209,7 +209,7 @@ default). The following listing shows the available methods for `Trigger` implem Spring provides two implementations of the `Trigger` interface. The most interesting one is the `CronTrigger`. It enables the scheduling of tasks based on -<>. +xref:integration/scheduling.adoc#scheduling-cron-expression[cron expressions]. For example, the following task is scheduled to run 15 minutes past each hour but only during the 9-to-5 "business hours" on weekdays: @@ -361,7 +361,7 @@ amount of time to wait before the first execution of the method, as the followin ---- If simple periodic scheduling is not expressive enough, you can provide a -<>. +xref:integration/scheduling.adoc#scheduling-cron-expression[cron expression]. The following example runs only on weekdays: [source,java,indent=0] @@ -485,7 +485,7 @@ in combination with a custom pointcut. === Executor Qualification with `@Async` By default, when specifying `@Async` on a method, the executor that is used is the -one <>, +one xref:integration/scheduling.adoc#scheduling-enable-annotation-support[configured when enabling async support], i.e. the "`annotation-driven`" element if you are using XML or your `AsyncConfigurer` implementation, if any. However, you can use the `value` attribute of the `@Async` annotation when you need to indicate that an executor other than the default should be @@ -565,7 +565,7 @@ The following creates a `ThreadPoolTaskExecutor` instance: ---- -As with the scheduler shown in the <>, +As with the scheduler shown in the xref:integration/scheduling.adoc#scheduling-task-namespace-scheduler[previous section], the value provided for the `id` attribute is used as the prefix for thread names within the pool. As far as the pool size is concerned, the `executor` element supports more configuration options than the `scheduler` element. For one thing, the thread pool for @@ -676,7 +676,7 @@ milliseconds to wait after each task execution has completed. Another option is any previous execution takes. Additionally, for both `fixed-delay` and `fixed-rate` tasks, you can specify an 'initial-delay' parameter, indicating the number of milliseconds to wait before the first execution of the method. For more control, you can instead provide a `cron` attribute -to provide a <>. +to provide a xref:integration/scheduling.adoc#scheduling-cron-expression[cron expression]. The following example shows these other options: [source,xml,indent=0] @@ -697,8 +697,8 @@ The following example shows these other options: == Cron Expressions All Spring cron expressions have to conform to the same format, whether you are using them in -<>, -<>, +xref:integration/scheduling.adoc#scheduling-annotation-support-scheduled[`@Scheduled` annotations], +xref:integration/scheduling.adoc#scheduling-task-namespace-scheduled-tasks[`task:scheduled-tasks` elements], or someplace else. A well-formed cron expression, such as `* * * * * *`, consists of six space-separated time and date fields, each with its own range of valid values: diff --git a/framework-docs/modules/ROOT/pages/languages/dynamic.adoc b/framework-docs/modules/ROOT/pages/languages/dynamic.adoc index 60d20034adb6..fed4d8574e70 100644 --- a/framework-docs/modules/ROOT/pages/languages/dynamic.adoc +++ b/framework-docs/modules/ROOT/pages/languages/dynamic.adoc @@ -13,7 +13,7 @@ for integration with any JSR-223 capable language provider (as of Spring 4.2), e.g. JRuby. You can find fully working examples of where this dynamic language support can be -immediately useful in <>. +immediately useful in xref:languages/dynamic.adoc#dynamic-language-scenarios[Scenarios]. @@ -88,8 +88,8 @@ container. Using the dynamic-language-backed beans with a plain `BeanFactory` implementation is supported, but you have to manage the plumbing of the Spring internals to do so. -For more information on schema-based configuration, see <>. +For more information on schema-based configuration, see xref:languages/dynamic.adoc#xsd-schemas-lang[XML Schema-based Configuration] +. ==== Finally, the following example shows the bean definitions that effect the injection of the @@ -138,7 +138,7 @@ supported dynamic languages. Note that this chapter does not attempt to explain the syntax and idioms of the supported dynamic languages. For example, if you want to use Groovy to write certain of the classes in your application, we assume that you already know Groovy. If you need further details -about the dynamic languages themselves, see <> at the end of +about the dynamic languages themselves, see xref:languages/dynamic.adoc#dynamic-language-resources[Further Resources] at the end of this chapter. @@ -168,7 +168,7 @@ of your dynamic language source files. [[dynamic-language-beans-concepts-xml-language-element]] ==== The element -The final step in the list in the <> +The final step in the list in the xref:languages/dynamic.adoc#dynamic-language-beans-concepts[preceding section] involves defining dynamic-language-backed bean definitions, one for each bean that you want to configure (this is no different from normal JavaBean configuration). However, instead of specifying the fully qualified class name of the class that is to be @@ -212,7 +212,7 @@ NOTE: This feature is off by default. Now we can take a look at an example to see how easy it is to start using refreshable beans. To turn on the refreshable beans feature, you have to specify exactly one additional attribute on the `` element of your bean definition. So, -if we stick with <> from earlier in +if we stick with xref:languages/dynamic.adoc#dynamic-language-a-first-example[the example] from earlier in this chapter, the following example shows what we would change in the Spring XML configuration to effect refreshable beans: @@ -310,7 +310,7 @@ results in a fatal exception being propagated to the calling code. The refreshable bean behavior described earlier does not apply to dynamic language source files defined with the `` element notation (see -<>). Additionally, it applies only to beans where +xref:languages/dynamic.adoc#dynamic-language-beans-inline[Inline Dynamic Language Source Files]). Additionally, it applies only to beans where changes to the underlying source file can actually be detected (for example, by code that checks the last modified date of a dynamic language source file that exists on the file system). @@ -347,7 +347,7 @@ If we put to one side the issues surrounding whether it is good practice to defi dynamic language source inside a Spring configuration file, the `` element can be useful in some scenarios. For instance, we might want to quickly add a Spring `Validator` implementation to a Spring MVC `Controller`. This is but a moment's -work using inline source. (See <> for such an +work using inline source. (See xref:languages/dynamic.adoc#dynamic-language-scenarios-validators[Scripted Validators] for such an example.) @@ -416,7 +416,7 @@ features that people like so much in languages like Python, Ruby and Smalltalk, them available to Java developers using a Java-like syntax.`" If you have read this chapter straight from the top, you have already -<> of a Groovy-dynamic-language-backed +xref:languages/dynamic.adoc#dynamic-language-a-first-example[seen an example] of a Groovy-dynamic-language-backed bean. Now consider another example (again using an example from the Spring test suite): [source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] @@ -475,7 +475,7 @@ Finally, the following small application exercises the preceding configuration: The resulting output from running the above program is (unsurprisingly) `10`. (For more interesting examples, see the dynamic language showcase project for a more -complex example or see the examples <> later in this chapter). +complex example or see the examples xref:languages/dynamic.adoc#dynamic-language-scenarios[Scenarios] later in this chapter). You must not define more than one class per Groovy source file. While this is perfectly legal in Groovy, it is (arguably) a bad practice. In the interests of a consistent @@ -633,7 +633,7 @@ The following example shows the Spring XML that defines an "`instance`" of the a ---- -See <> for some scenarios where you might want to use +See xref:languages/dynamic.adoc#dynamic-language-scenarios[Scenarios] for some scenarios where you might want to use BeanShell-based beans. @@ -670,7 +670,7 @@ automatically reflected in the beans that are backed by dynamic language source NOTE: To effect this automatic "`pickup`" of any changes to dynamic-language-backed beans, you have to enable the "`refreshable beans`" functionality. See -<> for a full treatment of this feature. +xref:languages/dynamic.adoc#dynamic-language-refreshable-beans[Refreshable Beans] for a full treatment of this feature. The following example shows an `org.springframework.web.servlet.mvc.Controller` implemented by using the Groovy dynamic language: @@ -725,11 +725,11 @@ running application and would not require the restart of an application. NOTE: To effect the automatic "`pickup`" of any changes to dynamic-language-backed beans, you have to enable the 'refreshable beans' feature. See -<> for a full and detailed treatment of this feature. +xref:languages/dynamic.adoc#dynamic-language-refreshable-beans[Refreshable Beans] for a full and detailed treatment of this feature. The following example shows a Spring `org.springframework.validation.Validator` -implemented by using the Groovy dynamic language (see <> for a discussion of the +implemented by using the Groovy dynamic language (see xref:core/validation/validator.adoc[Validation using Spring’s Validator interface] + for a discussion of the `Validator` interface): [source,groovy,indent=0,subs="verbatim,quotes"] @@ -770,7 +770,7 @@ You can use the Spring AOP framework to advise scripted beans. The Spring AOP framework actually is unaware that a bean that is being advised might be a scripted bean, so all of the AOP use cases and functionality that you use (or aim to use) work with scripted beans. When you advise scripted beans, you cannot use class-based -proxies. You must use <>. +proxies. You must use xref:core/aop/proxying.adoc[interface-based proxies]. You are not limited to advising scripted beans. You can also write aspects themselves in a supported dynamic language and use such beans to advise other Spring beans. @@ -784,11 +784,11 @@ This really would be an advanced use of the dynamic language support though. In case it is not immediately obvious, scripted beans can be scoped in the same way as any other bean. The `scope` attribute on the various `` elements lets you control the scope of the underlying scripted bean, as it does with a regular -bean. (The default scope is <>, +bean. (The default scope is xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton], as it is with "`regular`" beans.) The following example uses the `scope` attribute to define a Groovy bean scoped as -a <>: +a xref:core/beans/factory-scopes.adoc#beans-factory-scopes-prototype[prototype]: [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -810,7 +810,7 @@ a <>: ---- -See <> in <> +See xref:core/beans/factory-scopes.adoc[Bean Scopes] in xref:web/webmvc-view/mvc-xslt.adoc#mvc-view-xslt-beandefs[The IoC Container] for a full discussion of the scoping support in the Spring Framework. @@ -822,7 +822,7 @@ The `lang` elements in Spring XML configuration deal with exposing objects that written in a dynamic language (such as Groovy or BeanShell) as beans in the Spring container. These elements (and the dynamic language support) are comprehensively covered in -<>. See that section +xref:languages/dynamic.adoc[Dynamic Language Support]. See that section for full details on this support and the `lang` elements. To use the elements in the `lang` schema, you need to have the following preamble at the diff --git a/framework-docs/modules/ROOT/pages/languages/groovy.adoc b/framework-docs/modules/ROOT/pages/languages/groovy.adoc index 1fd0d3c9242f..d0833c2e801c 100644 --- a/framework-docs/modules/ROOT/pages/languages/groovy.adoc +++ b/framework-docs/modules/ROOT/pages/languages/groovy.adoc @@ -7,7 +7,7 @@ existing Java application. The Spring Framework provides a dedicated `ApplicationContext` that supports a Groovy-based Bean Definition DSL. For more details, see -<>. +xref:core/beans/basics.adoc#groovy-bean-definition-dsl[The Groovy Bean Definition DSL]. Further support for Groovy, including beans written in Groovy, refreshable script beans, -and more is available in <>. +and more is available in xref:languages/dynamic.adoc[Dynamic Language Support]. diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc index 78b32230f4a2..c53a37351ded 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc @@ -17,8 +17,8 @@ Boot 2 project on https://start.spring.io/#!language=kotlin&type=gradle-project[ [[choosing-the-web-flavor]] == Choosing the Web Flavor -Spring Framework now comes with two different web stacks: <> and -<>. +Spring Framework now comes with two different web stacks: xref:web/webmvc.adoc#mvc[Spring MVC] and +xref:testing/unit.adoc#mock-objects-web-reactive[Spring WebFlux]. Spring WebFlux is recommended if you want to create applications that will deal with latency, long-lived connections, streaming scenarios or if you want to use the web functional diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc index 3c8cc756c7d1..dc1a3f0257b8 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc @@ -9,7 +9,7 @@ declarations and expressing "`value or no value`" semantics without paying the c https://www.baeldung.com/kotlin-null-safety[comprehensive guide to Kotlin null-safety].) Although Java does not let you express null-safety in its type-system, the Spring Framework -provides <> +provides xref:languages/kotlin/null-safety.adoc[null-safety of the whole Spring Framework API] via tooling-friendly annotations declared in the `org.springframework.lang` package. By default, types from Java APIs used in Kotlin are recognized as https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc index 4bcb633c479f..721eda14c8a0 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc @@ -250,7 +250,7 @@ https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-featu [[constructor-injection]] === Constructor injection -As described in the <>, +As described in the xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-di[dedicated section], JUnit 5 allows constructor injection of beans which is pretty useful with Kotlin in order to use `val` instead of `lateinit var`. You can use {api-spring-framework}/test/context/TestConstructor.html[`@TestConstructor(autowireMode = AutowireMode.ALL)`] diff --git a/framework-docs/modules/ROOT/pages/rsocket.adoc b/framework-docs/modules/ROOT/pages/rsocket.adoc index f3580d824d32..0672161ec6ce 100644 --- a/framework-docs/modules/ROOT/pages/rsocket.adoc +++ b/framework-docs/modules/ROOT/pages/rsocket.adoc @@ -137,9 +137,9 @@ demonstrate its API and protocol features. The `spring-messaging` module contains the following: -* <> -- fluent API to make requests through an `io.rsocket.RSocket` +* xref:rsocket.adoc#rsocket-requester[RSocketRequester] -- fluent API to make requests through an `io.rsocket.RSocket` with data and metadata encoding/decoding. -* <> -- `@MessageMapping` annotated handler methods for +* xref:rsocket.adoc#rsocket-annot-responders[Annotated Responders] -- `@MessageMapping` annotated handler methods for responding. The `spring-web` module contains `Encoder` and `Decoder` implementations such as Jackson @@ -219,7 +219,7 @@ metadata, the default mime type is metadata value and mime type pairs per request. Typically both don't need to be changed. Data and metadata in the `SETUP` frame is optional. On the server side, -<> methods can be used to handle the start of a +xref:rsocket.adoc#rsocket-annot-connectmapping[@ConnectMapping] methods can be used to handle the start of a connection and the content of the `SETUP` frame. Metadata may be used for connection level security. @@ -344,7 +344,7 @@ annotation such as `@RSocketClientResponder` vs the default `@Controller`. This is necessary in scenarios with client and server, or multiple clients in the same application. -See also <>, for more on the programming model. +See also xref:rsocket.adoc#rsocket-annot-responders[Annotated Responders], for more on the programming model. [[rsocket-requester-client-advanced]] @@ -382,7 +382,7 @@ at that level as follows: To make requests from a server to connected clients is a matter of obtaining the requester for the connected client from the server. -In <>, `@ConnectMapping` and `@MessageMapping` methods support an +In xref:rsocket.adoc#rsocket-annot-responders[Annotated Responders], `@ConnectMapping` and `@MessageMapping` methods support an `RSocketRequester` argument. Use it to access the requester for the connection. Keep in mind that `@ConnectMapping` methods are essentially handlers of the `SETUP` frame which must be handled before requests can begin. Therefore, requests at the very start must be @@ -425,8 +425,8 @@ decoupled from handling. For example: [[rsocket-requester-requests]] === Requests -Once you have a <> or -<> requester, you can make requests as follows: +Once you have a xref:rsocket.adoc#rsocket-requester-client[client] or +xref:rsocket.adoc#rsocket-requester-server[server] requester, you can make requests as follows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -604,7 +604,7 @@ Then start an RSocket server through the Java RSocket API and plug the `RSocketMessageHandler` supports {gh-rsocket-extensions}/CompositeMetadata.md[composite] and {gh-rsocket-extensions}/Routing.md[routing] metadata by default. You can set its -<> if you need to switch to a +xref:rsocket.adoc#rsocket-metadata-extractor[MetadataExtractor] if you need to switch to a different mime type or register additional metadata mime types. You'll need to set the `Encoder` and `Decoder` instances required for metadata and data @@ -669,15 +669,15 @@ you need to share configuration between a client and a server in the same proces Annotated responders on the client side need to be configured in the `RSocketRequester.Builder`. For details, see -<>. +xref:rsocket.adoc#rsocket-requester-client-responder[Client Responders]. [[rsocket-annot-messagemapping]] === @MessageMapping -Once <> or -<> responder configuration is in place, +Once xref:rsocket.adoc#rsocket-annot-responders-server[server] or +xref:rsocket.adoc#rsocket-annot-responders-client[client] responder configuration is in place, `@MessageMapping` methods can be used as follows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -729,10 +729,10 @@ use the following method arguments: pass:q[`@MessageMapping("find.radar.{id}")`]. | `@Header` -| Metadata value registered for extraction as described in <>. +| Metadata value registered for extraction as described in xref:rsocket.adoc#rsocket-metadata-extractor[MetadataExtractor]. | `@Headers Map` -| All metadata values registered for extraction as described in <>. +| All metadata values registered for extraction as described in xref:rsocket.adoc#rsocket-metadata-extractor[MetadataExtractor]. |=== @@ -800,7 +800,7 @@ any subsequent metadata push notifications through the `METADATA_PUSH` frame, i. `metadataPush(Payload)` in `io.rsocket.RSocket`. `@ConnectMapping` methods support the same arguments as -<> but based on metadata and data from the `SETUP` and +xref:rsocket.adoc#rsocket-annot-messagemapping[@MessageMapping] but based on metadata and data from the `SETUP` and `METADATA_PUSH` frames. `@ConnectMapping` can have a pattern to narrow handling to specific connections that have a route in the metadata, or if no patterns are declared then all connections match. @@ -809,7 +809,7 @@ then all connections match. `Mono` as the return value. If handling returns an error for a new connection then the connection is rejected. Handling must not be held up to make requests to the `RSocketRequester` for the connection. See -<> for details. +xref:rsocket.adoc#rsocket-requester-server[Server Requester] for details. @@ -911,7 +911,7 @@ simply use a callback to customize registrations as follows: The Spring Framework lets you define an RSocket service as a Java interface with annotated methods for RSocket exchanges. You can then generate a proxy that implements this interface and performs the exchanges. This helps to simplify RSocket remote access by wrapping the -use of the underlying <>. +use of the underlying xref:rsocket.adoc#rsocket-requester[RSocketRequester]. One, declare an interface with `@RSocketExchange` methods: diff --git a/framework-docs/modules/ROOT/pages/testing/annotations.adoc b/framework-docs/modules/ROOT/pages/testing/annotations.adoc index a13a911735e3..6e0ce2f52cd2 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations.adoc @@ -4,11 +4,11 @@ This section covers annotations that you can use when you test Spring applications. It includes the following topics: -* <> -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-standard.adoc[Standard Annotation Support] +* xref:testing/annotations/integration-spring.adoc[Spring Testing Annotations] +* xref:testing/annotations/integration-junit4.adoc[Spring JUnit 4 Testing Annotations] +* xref:testing/annotations/integration-junit-jupiter.adoc[Spring JUnit Jupiter Testing Annotations] +* xref:testing/annotations/integration-meta.adoc[Meta-Annotation Support for Testing] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc index bc53256f22a3..aaa87fca2acc 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc @@ -2,15 +2,15 @@ = Spring JUnit Jupiter Testing Annotations The following annotations are supported when used in conjunction with the -<> and JUnit Jupiter +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-extension[`SpringExtension`] and JUnit Jupiter (that is, the programming model in JUnit 5): -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-springjunitconfig[`@SpringJUnitConfig`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-springjunitwebconfig[`@SpringJUnitWebConfig`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration[`@NestedTestConfiguration`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-enabledif[`@EnabledIf`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-disabledif[`@DisabledIf`] [[integration-testing-annotations-junit-jupiter-springjunitconfig]] == `@SpringJUnitConfig` @@ -70,7 +70,7 @@ location of a configuration file: <1> Specify the location of a configuration file. -See <> as well as the javadoc for +See xref:testing/testcontext-framework/ctx-management.adoc[Context Management] as well as the javadoc for {api-spring-framework}/test/context/junit/jupiter/SpringJUnitConfig.html[`@SpringJUnitConfig`] and `@ContextConfiguration` for further details. @@ -135,7 +135,7 @@ location of a configuration file: <1> Specify the location of a configuration file. -See <> as well as the javadoc for +See xref:testing/testcontext-framework/ctx-management.adoc[Context Management] as well as the javadoc for {api-spring-framework}/test/context/junit/jupiter/web/SpringJUnitWebConfig.html[`@SpringJUnitWebConfig`], {api-spring-framework}/test/context/ContextConfiguration.html[`@ContextConfiguration`], and {api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`] @@ -159,7 +159,7 @@ constructor takes precedence over both `@TestConstructor` and the default mode. The default _test constructor autowire mode_ can be changed by setting the `spring.test.constructor.autowire.mode` JVM system property to `all`. Alternatively, the default mode may be set via the -<> mechanism. +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism. As of Spring Framework 5.3, the default mode may also be configured as a https://junit.org/junit5/docs/current/user-guide/#running-tests-config-params[JUnit Platform configuration parameter]. @@ -192,36 +192,36 @@ change the default mode. The default _enclosing configuration inheritance mode_ is `INHERIT`, but it can be changed by setting the `spring.test.enclosing.configuration` JVM system property to `OVERRIDE`. Alternatively, the default mode may be set via the -<> mechanism. +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism. ===== -The <> honors `@NestedTestConfiguration` semantics for the +The xref:testing/testcontext-framework.adoc[Spring TestContext Framework] honors `@NestedTestConfiguration` semantics for the following annotations. -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-spring/annotation-bootstrapwith.adoc[`@BootstrapWith`] +* xref:testing/annotations/integration-spring/annotation-contextconfiguration.adoc[`@ContextConfiguration`] +* xref:testing/annotations/integration-spring/annotation-webappconfiguration.adoc[`@WebAppConfiguration`] +* xref:testing/annotations/integration-spring/annotation-contexthierarchy.adoc[`@ContextHierarchy`] +* xref:testing/annotations/integration-spring/annotation-activeprofiles.adoc[`@ActiveProfiles`] +* xref:testing/annotations/integration-spring/annotation-testpropertysource.adoc[`@TestPropertySource`] +* xref:testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc[`@DynamicPropertySource`] +* xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[`@DirtiesContext`] +* xref:testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc[`@TestExecutionListeners`] +* xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[`@RecordApplicationEvents`] +* xref:testing/testcontext-framework/tx.adoc[`@Transactional`] +* xref:testing/annotations/integration-spring/annotation-commit.adoc[`@Commit`] +* xref:testing/annotations/integration-spring/annotation-rollback.adoc[`@Rollback`] +* xref:testing/annotations/integration-spring/annotation-sql.adoc[`@Sql`] +* xref:testing/annotations/integration-spring/annotation-sqlconfig.adoc[`@SqlConfig`] +* xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[`@SqlMergeMode`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`] NOTE: The use of `@NestedTestConfiguration` typically only makes sense in conjunction with `@Nested` test classes in JUnit Jupiter; however, there may be other testing frameworks with support for Spring and nested test classes that make use of this annotation. -See <> for an example and further +See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] for an example and further details. [[integration-testing-annotations-junit-jupiter-enabledif]] @@ -235,9 +235,9 @@ within that class are automatically enabled by default as well. Expressions can be any of the following: -* <> (SpEL) expression. For example: +* xref:core/expressions.adoc[Spring Expression Language] (SpEL) expression. For example: `@EnabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")` -* Placeholder for a property available in the Spring <>. +* Placeholder for a property available in the Spring xref:core/beans/environment.adoc[`Environment`]. For example: `@EnabledIf("${smoke.tests.enabled}")` * Text literal. For example: `@EnabledIf("true")` @@ -295,9 +295,9 @@ test methods within that class are automatically disabled as well. Expressions can be any of the following: -* <> (SpEL) expression. For example: +* xref:core/expressions.adoc[Spring Expression Language] (SpEL) expression. For example: `@DisabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")` -* Placeholder for a property available in the Spring <>. +* Placeholder for a property available in the Spring xref:core/beans/environment.adoc[`Environment`]. For example: `@DisabledIf("${smoke.tests.disabled}")` * Text literal. For example: `@DisabledIf("true")` diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc index 077c53dbf06b..924a17f81c73 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc @@ -2,13 +2,13 @@ = Spring JUnit 4 Testing Annotations The following annotations are supported only when used in conjunction with the -<>, <>, or <>: +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-runner[SpringRunner], xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules[Spring's JUnit 4 rules] +, or xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-junit4[Spring's JUnit 4 support classes]: -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-junit4.adoc#integration-testing-annotations-junit4-ifprofilevalue[`@IfProfileValue`] +* xref:testing/annotations/integration-junit4.adoc#integration-testing-annotations-junit4-profilevaluesourceconfiguration[`@ProfileValueSourceConfiguration`] +* xref:testing/annotations/integration-junit4.adoc#integration-testing-annotations-junit4-timed[`@Timed`] +* xref:testing/annotations/integration-junit4.adoc#integration-testing-annotations-junit4-repeat[`@Repeat`] [[integration-testing-annotations-junit4-ifprofilevalue]] == `@IfProfileValue` @@ -154,7 +154,7 @@ times that the test method is to be run is specified in the annotation. The scope of execution to be repeated includes execution of the test method itself as well as any setting up or tearing down of the test fixture. When used with the -<>, the scope additionally includes +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules[`SpringMethodRule`], the scope additionally includes preparation of the test instance by `TestExecutionListener` implementations. The following example shows how to use the `@Repeat` annotation: diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc index 8cb176ac1bb7..66ee7b11232b 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc @@ -2,11 +2,11 @@ = Meta-Annotation Support for Testing You can use most test-related annotations as -<> to create custom composed +xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotations] to create custom composed annotations and reduce configuration duplication across a test suite. You can use each of the following as a meta-annotation in conjunction with the -<>. +xref:testing/testcontext-framework.adoc[TestContext framework]. * `@BootstrapWith` * `@ContextConfiguration` diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc index 8bfde481a8cc..3db79d44bc4d 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc @@ -8,22 +8,22 @@ values, attribute aliases, and other details. Spring's testing annotations include the following: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-spring/annotation-bootstrapwith.adoc[`@BootstrapWith`] +* xref:testing/annotations/integration-spring/annotation-contextconfiguration.adoc[`@ContextConfiguration`] +* xref:testing/annotations/integration-spring/annotation-webappconfiguration.adoc[`@WebAppConfiguration`] +* xref:testing/annotations/integration-spring/annotation-contexthierarchy.adoc[`@ContextHierarchy`] +* xref:testing/annotations/integration-spring/annotation-activeprofiles.adoc[`@ActiveProfiles`] +* xref:testing/annotations/integration-spring/annotation-testpropertysource.adoc[`@TestPropertySource`] +* xref:testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc[`@DynamicPropertySource`] +* xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[`@DirtiesContext`] +* xref:testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc[`@TestExecutionListeners`] +* xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[`@RecordApplicationEvents`] +* xref:testing/annotations/integration-spring/annotation-commit.adoc[`@Commit`] +* xref:testing/annotations/integration-spring/annotation-rollback.adoc[`@Rollback`] +* xref:testing/annotations/integration-spring/annotation-beforetransaction.adoc[`@BeforeTransaction`] +* xref:testing/annotations/integration-spring/annotation-aftertransaction.adoc[`@AfterTransaction`] +* xref:testing/annotations/integration-spring/annotation-sql.adoc[`@Sql`] +* xref:testing/annotations/integration-spring/annotation-sqlconfig.adoc[`@SqlConfig`] +* xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[`@SqlMergeMode`] +* xref:testing/annotations/integration-spring/annotation-sqlgroup.adoc[`@SqlGroup`] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc index 42a1284f6d34..7ff17ec5425a 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc @@ -59,11 +59,11 @@ be active: NOTE: `@ActiveProfiles` provides support for inheriting active bean definition profiles declared by superclasses and enclosing classes by default. You can also resolve active bean definition profiles programmatically by implementing a custom -<> +xref:testing/testcontext-framework/ctx-management/env-profiles.adoc#testcontext-ctx-management-env-profiles-ActiveProfilesResolver[`ActiveProfilesResolver`] and registering it by using the `resolver` attribute of `@ActiveProfiles`. -See <>, -<>, and the +See xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[Context Configuration with Environment Profiles], +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration], and the {api-spring-framework}/test/context/ActiveProfiles.html[`@ActiveProfiles`] javadoc for examples and further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc index 6646495d547c..be83db1212f3 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc @@ -4,5 +4,5 @@ `@BootstrapWith` is a class-level annotation that you can use to configure how the Spring TestContext Framework is bootstrapped. Specifically, you can use `@BootstrapWith` to specify a custom `TestContextBootstrapper`. See the section on -<> for further details. +xref:testing/testcontext-framework/bootstrapping.adoc[bootstrapping the TestContext framework] for further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc index e39524afd925..8d783ac240ce 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc @@ -10,7 +10,7 @@ Resource locations are typically XML configuration files or Groovy scripts locat classpath, while component classes are typically `@Configuration` classes. However, resource locations can also refer to files and scripts in the file system, and component classes can be `@Component` classes, `@Service` classes, and so on. See -<> for further details. +xref:testing/testcontext-framework/ctx-management/javaconfig.adoc#testcontext-ctx-management-javaconfig-component-classes[null] for further details. The following example shows a `@ContextConfiguration` annotation that refers to an XML file: @@ -116,7 +116,7 @@ NOTE: `@ContextConfiguration` provides support for inheriting resource locations configuration classes as well as context initializers that are declared by superclasses or enclosing classes. -See <>, -<>, and the `@ContextConfiguration` +See xref:testing/testcontext-framework/ctx-management.adoc[Context Management], +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration], and the `@ContextConfiguration` javadocs for further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc index e0f0c48b54a5..89bf31905899 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc @@ -57,7 +57,7 @@ within a test class hierarchy): If you need to merge or override the configuration for a given level of the context hierarchy within a test class hierarchy, you must explicitly name that level by supplying the same value to the `name` attribute in `@ContextConfiguration` at each corresponding -level in the class hierarchy. See <> and the +level in the class hierarchy. See xref:testing/testcontext-framework/ctx-management/hierarchies.adoc[Context Hierarchies] and the {api-spring-framework}/test/context/ContextHierarchy.html[`@ContextHierarchy`] javadoc for further examples. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc index 70bb526e0de0..21bafb5324d6 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc @@ -55,5 +55,5 @@ The following example demonstrates how to register a dynamic property: <2> Accept a `DynamicPropertyRegistry` as an argument. <3> Register a dynamic `server.port` property to be retrieved lazily from the server. -See <> for further details. +See xref:testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc[Context Configuration with Dynamic Property Sources] for further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc index dcb9a2df441f..51a1c2100021 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc @@ -7,7 +7,7 @@ _Spring TestContext Framework_ to record all application events that are publish The recorded events can be accessed via the `ApplicationEvents` API within tests. -See <> and the +See xref:testing/testcontext-framework/application-events.adoc[Application Events] and the {api-spring-framework}/test/context/event/RecordApplicationEvents.html[`@RecordApplicationEvents` javadoc] for an example and further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc index 2d4c7ace099a..d5eb93ed280a 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc @@ -4,7 +4,7 @@ `@Rollback` indicates whether the transaction for a transactional test method should be rolled back after the test method has completed. If `true`, the transaction is rolled back. Otherwise, the transaction is committed (see also -<>). Rollback for integration tests in the Spring +xref:testing/annotations/integration-spring/annotation-commit.adoc[`@Commit`]). Rollback for integration tests in the Spring TestContext Framework defaults to `true` even if `@Rollback` is not explicitly declared. When declared as a class-level annotation, `@Rollback` defines the default rollback diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc index 32dd573437df..975e043e868c 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc @@ -27,6 +27,6 @@ it: ---- <1> Run two scripts for this test. -See <> for further details. +See xref:testing/testcontext-framework/executing-sql.adoc#testcontext-executing-sql-declaratively[Executing SQL scripts declaratively with @Sql] for further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc index 38548fc41505..e79aa245eca2 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc @@ -4,7 +4,7 @@ `@TestExecutionListeners` is used to register listeners for a particular test class, its subclasses, and its nested classes. If you wish to register a listener globally, you should register it via the automatic discovery mechanism described in -<>. +xref:testing/testcontext-framework/tel-config.adoc[`TestExecutionListener` Configuration]. The following example shows how to register two `TestExecutionListener` implementations: @@ -33,9 +33,9 @@ The following example shows how to register two `TestExecutionListener` implemen By default, `@TestExecutionListeners` provides support for inheriting listeners from superclasses or enclosing classes. See -<> and the +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] and the {api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners` javadoc] for an example and further details. If you discover that you need to switch back to using the default `TestExecutionListener` implementations, see the note -in <>. +in xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-registering-tels[Registering `TestExecutionListener` Implementations]. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc index c793c4b057e5..40ba2240a392 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc @@ -55,5 +55,5 @@ The following example demonstrates how to declare inlined properties: ---- <1> Declare `timezone` and `port` properties. -See <> for examples and further details. +See xref:testing/testcontext-framework/ctx-management/property-sources.adoc[Context Configuration with Test Property Sources] for examples and further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc index c18d763e571f..4406377286df 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc @@ -15,7 +15,7 @@ and can be used anywhere in the Spring Framework. * `@PersistenceContext` (jakarta.persistence) if JPA is present * `@PersistenceUnit` (jakarta.persistence) if JPA is present * `@Transactional` (org.springframework.transaction.annotation) - _with <>_ + _with xref:testing/testcontext-framework/tx.adoc#testcontext-tx-attribute-support[limited attribute support]_ .JSR-250 Lifecycle Annotations [NOTE] diff --git a/framework-docs/modules/ROOT/pages/testing/integration.adoc b/framework-docs/modules/ROOT/pages/testing/integration.adoc index 5c5bc4e90b30..a7a4b39729ea 100644 --- a/framework-docs/modules/ROOT/pages/testing/integration.adoc +++ b/framework-docs/modules/ROOT/pages/testing/integration.adoc @@ -12,7 +12,7 @@ Doing so lets you test things such as: The Spring Framework provides first-class support for integration testing in the `spring-test` module. The name of the actual JAR file might include the release version and might also be in the long `org.springframework.test` form, depending on where you get -it from (see the <> +it from (see the xref:core/beans/dependencies.adoc[section on Dependency Management] for an explanation). This library includes the `org.springframework.test` package, which contains valuable classes for integration testing with a Spring container. This testing does not rely on an application server or other deployment environment. Such tests are @@ -20,19 +20,19 @@ slower to run than unit tests but much faster than the equivalent Selenium tests remote tests that rely on deployment to an application server. Unit and integration testing support is provided in the form of the annotation-driven -<>. The TestContext framework is +xref:testing/testcontext-framework.adoc[Spring TestContext Framework]. The TestContext framework is agnostic of the actual testing framework in use, which allows instrumentation of tests in various environments, including JUnit, TestNG, and others. The following section provides an overview of the high-level goals of Spring's integration support, and the rest of this chapter then focuses on dedicated topics: -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/support-jdbc.adoc[JDBC Testing Support] +* xref:testing/testcontext-framework.adoc[Spring TestContext Framework] +* xref:testing/webtestclient.adoc[WebTestClient] +* xref:testing/spring-mvc-test-framework.adoc[MockMvc] +* xref:testing/spring-mvc-test-client.adoc[Testing Client Applications] +* xref:testing/annotations.adoc[Annotations] @@ -41,10 +41,10 @@ integration support, and the rest of this chapter then focuses on dedicated topi Spring's integration testing support has the following primary goals: -* To manage <> between tests. -* To provide <>. -* To provide <> appropriate to integration testing. -* To supply <> that assist +* To manage xref:testing/integration.adoc#testing-ctx-management[Spring IoC container caching] between tests. +* To provide xref:testing/integration.adoc#testing-fixture-di[Dependency Injection of test fixture instances]. +* To provide xref:testing/integration.adoc#testing-tx[transaction management] appropriate to integration testing. +* To supply xref:testing/integration.adoc#testing-support-classes[Spring-specific base classes] that assist developers in writing integration tests. The next few sections describe each goal and provide links to implementation and @@ -78,7 +78,7 @@ reloading (for example, by modifying a bean definition or the state of an applic object) the TestContext framework can be configured to reload the configuration and rebuild the application context before executing the next test. -See <> and <> with the +See xref:testing/testcontext-framework/ctx-management.adoc[Context Management] and xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching] with the TestContext framework. @@ -105,7 +105,7 @@ integration tests that test the following areas: perform as anticipated? See dependency injection of test fixtures with the -<>. +xref:testing/testcontext-framework/fixture-di.adoc[TestContext framework]. [[testing-tx]] @@ -128,9 +128,9 @@ using a `PlatformTransactionManager` bean defined in the test's application cont If you want a transaction to commit (unusual, but occasionally useful when you want a particular test to populate or modify the database), you can tell the TestContext framework to cause the transaction to commit instead of roll back by using the -<> annotation. +xref:testing/annotations.adoc[`@Commit`] annotation. -See transaction management with the <>. +See transaction management with the xref:testing/testcontext-framework/tx.adoc[TestContext framework]. [[testing-support-classes]] @@ -147,9 +147,9 @@ which let you access: queries to confirm database state both before and after execution of database-related application code, and Spring ensures that such queries run in the scope of the same transaction as the application code. When used in conjunction with an ORM tool, be sure - to avoid <>. + to avoid xref:testing/testcontext-framework/tx.adoc#testcontext-tx-false-positives[false positives]. In addition, you may want to create your own custom, application-wide superclass with instance variables and methods specific to your project. -See support classes for the <>. +See support classes for the xref:testing/testcontext-framework/support-classes.adoc[TestContext framework]. diff --git a/framework-docs/modules/ROOT/pages/testing/introduction.adoc b/framework-docs/modules/ROOT/pages/testing/introduction.adoc index 1bc210f4b171..71bf53da3676 100644 --- a/framework-docs/modules/ROOT/pages/testing/introduction.adoc +++ b/framework-docs/modules/ROOT/pages/testing/introduction.adoc @@ -2,7 +2,7 @@ = Introduction to Spring Testing Testing is an integral part of enterprise software development. This chapter focuses on -the value added by the IoC principle to <> and on the benefits -of the Spring Framework's support for <>. (A +the value added by the IoC principle to xref:testing/unit.adoc[unit testing] and on the benefits +of the Spring Framework's support for xref:testing/integration.adoc[integration testing]. (A thorough treatment of testing in the enterprise is beyond the scope of this reference manual.) diff --git a/framework-docs/modules/ROOT/pages/testing/resources.adoc b/framework-docs/modules/ROOT/pages/testing/resources.adoc index e274dd94f9f4..c7b3c247dc10 100644 --- a/framework-docs/modules/ROOT/pages/testing/resources.adoc +++ b/framework-docs/modules/ROOT/pages/testing/resources.adoc @@ -4,10 +4,10 @@ See the following resources for more information about testing: * https://www.junit.org/[JUnit]: "A programmer-friendly testing framework for Java and the JVM". Used by the Spring Framework in its test suite and supported in the - <>. + xref:testing/testcontext-framework.adoc[Spring TestContext Framework]. * https://testng.org/[TestNG]: A testing framework inspired by JUnit with added support for test groups, data-driven testing, distributed testing, and other features. Supported - in the <> + in the xref:testing/testcontext-framework.adoc[Spring TestContext Framework] * https://assertj.github.io/doc/[AssertJ]: "Fluent assertions for Java", including support for Java 8 lambdas, streams, and numerous other features. * https://en.wikipedia.org/wiki/Mock_Object[Mock Objects]: Article in Wikipedia. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc index 20e842203e41..19ed89221550 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc @@ -6,7 +6,7 @@ MVC applications. It performs full Spring MVC request handling but via mock requ response objects instead of a running server. MockMvc can be used on its own to perform requests and verify responses. It can also be -used through the <> where MockMvc is plugged in as the server to handle +used through the xref:testing/webtestclient.adoc[WebTestClient] where MockMvc is plugged in as the server to handle requests with. The advantage of `WebTestClient` is the option to work with higher level objects instead of raw data as well as the ability to switch to full, end-to-end HTTP tests against a live server and use the same test API. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc index b6b4f06ff1b1..f8e8cda9090c 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc @@ -2,11 +2,11 @@ = Async Requests This section shows how to use MockMvc on its own to test asynchronous request handling. -If using MockMvc through the <>, there is nothing special to do to make +If using MockMvc through the xref:testing/webtestclient.adoc[WebTestClient], there is nothing special to do to make asynchronous requests work as the `WebTestClient` automatically does what is described in this section. -Servlet asynchronous requests, <>, +Servlet asynchronous requests, xref:web/webmvc/mvc-ann-async.adoc[supported in Spring MVC], work by exiting the Servlet container thread and allowing the application to compute the response asynchronously, after which an async dispatch is made to complete processing on a Servlet container thread. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc index 579c3e5e97fa..fda2259ef345 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc @@ -1,7 +1,7 @@ [[spring-mvc-test-server-htmlunit]] = HtmlUnit Integration -Spring provides integration between <> and +Spring provides integration between xref:testing/spring-mvc-test-framework/server.adoc[MockMvc] and https://htmlunit.sourceforge.io/[HtmlUnit]. This simplifies performing end-to-end testing when using HTML-based views. This integration lets you: diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc index 39d603320172..8be8dd529290 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc @@ -8,7 +8,7 @@ use https://www.gebish.org/[Geb] to make our tests even Groovy-er. == Why Geb and MockMvc? Geb is backed by WebDriver, so it offers many of the -<> that we get from +xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc#spring-mvc-test-server-htmlunit-webdriver-why[same benefits] that we get from WebDriver. However, Geb makes things even easier by taking care of some of the boilerplate code for us. @@ -28,7 +28,7 @@ def setup() { ---- NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced -usage, see <>. +usage, see xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc#spring-mvc-test-server-htmlunit-webdriver-advanced-builder[Advanced `MockMvcHtmlUnitDriverBuilder`]. This ensures that any URL referencing `localhost` as the server is directed to our `MockMvc` instance without the need for a real HTTP connection. Any other URL is @@ -62,7 +62,7 @@ forwarded to the current page object. This removes a lot of the boilerplate code needed when using WebDriver directly. As with direct WebDriver usage, this improves on the design of our -<> by using the Page Object +xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-usage[HtmlUnit test] by using the Page Object Pattern. As mentioned previously, we can use the Page Object Pattern with HtmlUnit and WebDriver, but it is even easier with Geb. Consider our new Groovy-based `CreateMessagePage` implementation: diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc index c34323787234..3809ffd3b555 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc @@ -41,7 +41,7 @@ We can easily create an HtmlUnit `WebClient` that integrates with MockMvc by usi ---- NOTE: This is a simple example of using `MockMvcWebClientBuilder`. For advanced usage, -see <>. +see xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-advanced-builder[Advanced `MockMvcWebClientBuilder`]. This ensures that any URL that references `localhost` as the server is directed to our `MockMvc` instance without the need for a real HTTP connection. Any other URL is @@ -68,7 +68,7 @@ message with the following: ---- NOTE: The default context path is `""`. Alternatively, we can specify the context path, -as described in <>. +as described in xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-advanced-builder[Advanced `MockMvcWebClientBuilder`]. Once we have a reference to the `HtmlPage`, we can then fill out the form and submit it to create a message, as the following example shows: @@ -123,7 +123,7 @@ assertions use the https://assertj.github.io/doc/[AssertJ] library: ---- The preceding code improves on our -<> in a number of ways. +xref:testing/spring-mvc-test-framework/server-htmlunit/why.adoc#spring-mvc-test-server-htmlunit-mock-mvc-test[MockMvc test] in a number of ways. First, we no longer have to explicitly verify our form and then create a request that looks like the form. Instead, we request the form, fill it out, and submit it, thereby significantly reducing the overhead. @@ -238,5 +238,5 @@ This is more verbose, but, by building the `WebClient` with a `MockMvc` instance the full power of MockMvc at our fingertips. TIP: For additional information on creating a `MockMvc` instance, see -<>. +xref:testing/spring-mvc-test-framework/server-setup-options.adoc[Setup Choices]. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc index 57a91b65951e..fbc2d34485fa 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc @@ -180,7 +180,7 @@ We can easily create a Selenium WebDriver that integrates with MockMvc by using ---- NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced -usage, see <>. +usage, see xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc#spring-mvc-test-server-htmlunit-webdriver-advanced-builder[Advanced `MockMvcHtmlUnitDriverBuilder`]. The preceding example ensures that any URL that references `localhost` as the server is directed to our `MockMvc` instance without the need for a real HTTP connection. Any other @@ -226,9 +226,9 @@ We can then fill out the form and submit it to create a message, as follows: ---- -- -This improves on the design of our <> +This improves on the design of our xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-usage[HtmlUnit test] by leveraging the Page Object Pattern. As we mentioned in -<>, we can use the Page Object Pattern +xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc#spring-mvc-test-server-htmlunit-webdriver-why[Why WebDriver and MockMvc?], we can use the Page Object Pattern with HtmlUnit, but it is much easier with WebDriver. Consider the following `CreateMessagePage` implementation: @@ -499,5 +499,5 @@ This is more verbose, but, by building the `WebDriver` with a `MockMvc` instance the full power of MockMvc at our fingertips. TIP: For additional information on creating a `MockMvc` instance, see -<>. +xref:testing/spring-mvc-test-framework/server-setup-options.adoc[Setup Choices]. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc index 55b478e20d8c..174f9108fa1d 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc @@ -177,11 +177,11 @@ with HtmlUnit.`" You have a number of options when you want to integrate MockMvc with HtmlUnit: -* <>: Use this option if you +* xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc[MockMvc and HtmlUnit]: Use this option if you want to use the raw HtmlUnit libraries. -* <>: Use this option to +* xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc[MockMvc and WebDriver]: Use this option to ease development and reuse code between integration and end-to-end testing. -* <>: Use this option if you want to +* xref:testing/spring-mvc-test-framework/server-htmlunit/geb.adoc[MockMvc and Geb]: Use this option if you want to use Groovy for testing, ease development, and reuse code between integration and end-to-end testing. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc index adc596e5497a..4bb64992e32d 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc @@ -3,7 +3,7 @@ This section shows how to use MockMvc on its own to perform requests and verify responses. If using MockMvc through the `WebTestClient` please see the corresponding section on -<> instead. +xref:testing/webtestclient.adoc#webtestclient-tests[Writing Tests] instead. To perform requests that use any HTTP method, as the following example shows: diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc index 26e34e16411d..d6a6cf9f4844 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc @@ -42,7 +42,7 @@ To set up MockMvc for testing a specific controller, use the following: ---- Or you can also use this setup when testing through the -<> which delegates to the same builder +xref:testing/webtestclient.adoc#webtestclient-controller-config[WebTestClient] which delegates to the same builder as shown above. To set up MockMvc through Spring configuration, use the following: @@ -84,7 +84,7 @@ To set up MockMvc through Spring configuration, use the following: ---- Or you can also use this setup when testing through the -<> which delegates to the same builder +xref:testing/webtestclient.adoc#webtestclient-context-config[WebTestClient] which delegates to the same builder as shown above. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc index 834ee8d26b4f..a082636a620f 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc @@ -11,7 +11,7 @@ When using MockMvc directly to perform requests, you'll need static imports for: An easy way to remember that is search for `MockMvc*`. If using Eclipse be sure to also add the above as "`favorite static members`" in the Eclipse preferences. -When using MockMvc through the <> you do not need static imports. +When using MockMvc through the xref:testing/webtestclient.adoc[WebTestClient] you do not need static imports. The `WebTestClient` provides a fluent API without static imports. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc index 929faaf13b41..f319cabb9acc 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc @@ -10,14 +10,14 @@ do they involve any of the supporting `@InitBinder`, `@ModelAttribute`, or The Spring MVC Test framework, also known as `MockMvc`, aims to provide more complete testing for Spring MVC controllers without a running server. It does that by invoking the `DispatcherServlet` and passing -<> from the +xref:testing/unit.adoc#mock-objects-servlet["`mock`" implementations of the Servlet API] from the `spring-test` module which replicates the full Spring MVC request handling without a running server. MockMvc is a server side test framework that lets you verify most of the functionality of a Spring MVC application using lightweight and targeted tests. You can use it on its own to perform requests and to verify responses, or you can also use it through -the <> API with MockMvc plugged in as the server to handle requests +the xref:testing/webtestclient.adoc[WebTestClient] API with MockMvc plugged in as the server to handle requests with. diff --git a/framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc b/framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc index 8ae2a2be22b7..cc09b76658d9 100644 --- a/framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc +++ b/framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc @@ -19,8 +19,8 @@ methods. [TIP] ==== -<> -and <> +xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-junit4[`AbstractTransactionalJUnit4SpringContextTests`] +and xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-testng[`AbstractTransactionalTestNGSpringContextTests`] provide convenience methods that delegate to the aforementioned methods in `JdbcTestUtils`. ==== @@ -30,6 +30,6 @@ provide convenience methods that delegate to the aforementioned methods in The `spring-jdbc` module provides support for configuring and launching an embedded database, which you can use in integration tests that interact with a database. -For details, see <> and <>. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc index fe336ea7d5a0..0acb1ddcb736 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc @@ -17,9 +17,9 @@ required to extend a particular class hierarchy, such as the `abstract` support The following section provides an overview of the internals of the TestContext framework. If you are interested only in using the framework and are not interested in extending it with your own custom listeners or custom loaders, feel free to go directly to the -configuration (<>, -<>, <>), <>, and -<> sections. +configuration (xref:testing/testcontext-framework/ctx-management.adoc[context management], +xref:testing/testcontext-framework/fixture-di.adoc[dependency injection], xref:testing/testcontext-framework/tx.adoc[transaction management] +), xref:testing/testcontext-framework/support-classes.adoc[support classes], and +xref:testing/annotations.adoc[annotation support] sections. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc index d7a9e735c989..88487c500217 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc @@ -4,7 +4,7 @@ This chapter covers Spring's Ahead of Time (AOT) support for integration tests using the Spring TestContext Framework. -The testing support extends Spring's <> with the +The testing support extends Spring's xref:core/aot.adoc[core AOT support] with the following features. * Build-time detection of all integration tests in the current project that use the @@ -14,10 +14,10 @@ following features. testing annotations -- as long as the tests are run using a JUnit Platform `TestEngine` that is registered for the current project. * Build-time AOT processing: each unique test `ApplicationContext` in the current project - will be <>. + will be xref:core/aot.adoc#core.aot.refresh[refreshed for AOT processing]. * Runtime AOT support: when executing in AOT runtime mode, a Spring integration test will use an AOT-optimized `ApplicationContext` that participates transparently with the - <>. + xref:testing/testcontext-framework/ctx-management/caching.adoc[context cache]. [WARNING] ==== @@ -35,7 +35,7 @@ the following options. via {api-spring-framework}/context/annotation/ImportRuntimeHints.html[`@ImportRuntimeHints`]. * Annotate a test class with {api-spring-framework}/aot/hint/annotation/Reflective.html[`@Reflective`] or {api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`]. -* See <> for details on Spring's core runtime hints +* See xref:core/aot.adoc#core.aot.hints[Runtime Hints] for details on Spring's core runtime hints and annotation support. [TIP] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc index 516e5de64d2d..b9779c015226 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc @@ -2,7 +2,7 @@ = Application Events Since Spring Framework 5.3.3, the TestContext framework provides support for recording -<> published in the +xref:core/beans/context-introduction.adoc#context-functionality-events[application events] published in the `ApplicationContext` so that assertions can be performed against those events within tests. All events published during the execution of a single test are made available via the `ApplicationEvents` API which allows you to process the events as a @@ -11,7 +11,7 @@ the `ApplicationEvents` API which allows you to process the events as a To use `ApplicationEvents` in your tests, do the following. * Ensure that your test class is annotated or meta-annotated with - <>. + xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[`@RecordApplicationEvents`]. * Ensure that the `ApplicationEventsTestExecutionListener` is registered. Note, however, that `ApplicationEventsTestExecutionListener` is registered by default and only needs to be manually registered if you have custom configuration via @@ -19,7 +19,7 @@ To use `ApplicationEvents` in your tests, do the following. * Annotate a field of type `ApplicationEvents` with `@Autowired` and use that instance of `ApplicationEvents` in your test and lifecycle methods (such as `@BeforeEach` and `@AfterEach` methods in JUnit Jupiter). -** When using the <>, you may declare a method +** When using the xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-extension[SpringExtension for JUnit Jupiter], you may declare a method parameter of type `ApplicationEvents` in a test or lifecycle method as an alternative to an `@Autowired` field in the test class. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc index 605aef0a4baf..3807f827d0d1 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc @@ -80,7 +80,7 @@ the web application context into your test, as follows: Dependency injection by using `@Autowired` is provided by the `DependencyInjectionTestExecutionListener`, which is configured by default -(see <>). +(see xref:testing/testcontext-framework/fixture-di.adoc[Dependency Injection of Test Fixtures]). ===== Test classes that use the TestContext framework do not need to extend any particular @@ -98,16 +98,16 @@ component classes (typically `@Configuration` classes), or context initializers. Alternatively, you can implement and configure your own custom `SmartContextLoader` for advanced use cases. -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/testcontext-framework/ctx-management/xml.adoc[Context Configuration with XML resources] +* xref:testing/testcontext-framework/ctx-management/groovy.adoc[Context Configuration with Groovy Scripts] +* xref:testing/testcontext-framework/ctx-management/javaconfig.adoc[Context Configuration with Component Classes] +* xref:testing/testcontext-framework/ctx-management/mixed-config.adoc[Mixing XML, Groovy Scripts, and Component Classes] +* xref:testing/testcontext-framework/ctx-management/initializers.adoc[Context Configuration with Context Initializers] +* xref:testing/testcontext-framework/ctx-management/inheritance.adoc[Context Configuration Inheritance] +* xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[Context Configuration with Environment Profiles] +* xref:testing/testcontext-framework/ctx-management/property-sources.adoc[Context Configuration with Test Property Sources] +* xref:testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc[Context Configuration with Dynamic Property Sources] +* xref:testing/testcontext-framework/ctx-management/web.adoc[Loading a `WebApplicationContext`] +* xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching] +* xref:testing/testcontext-framework/ctx-management/hierarchies.adoc[Context Hierarchies] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc index fd6f51764aab..0a4f02f91206 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc @@ -60,7 +60,7 @@ maximum size is reached, a least recently used (LRU) eviction policy is used to close stale contexts. You can configure the maximum size from the command line or a build script by setting a JVM system property named `spring.test.context.cache.maxSize`. As an alternative, you can set the same property via the -<> mechanism. +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism. Since having a large number of application contexts loaded within a given test suite can cause the suite to take an unnecessarily long time to run, it is often beneficial to @@ -71,8 +71,8 @@ the underlying context cache, you can set the log level for the In the unlikely case that a test corrupts the application context and requires reloading (for example, by modifying a bean definition or the state of an application object), you can annotate your test class or test method with `@DirtiesContext` (see the discussion of -`@DirtiesContext` in <>). This instructs Spring to remove the context from the cache and rebuild +`@DirtiesContext` in xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[Spring Testing Annotations] +). This instructs Spring to remove the context from the cache and rebuild the application context before running the next test that requires the same application context. Note that support for the `@DirtiesContext` annotation is provided by the `DirtiesContextBeforeModesTestExecutionListener` and the @@ -96,7 +96,7 @@ class is being prepared -- for example, to perform dependency injection into `@A fields of the test instance. This means that any console logging triggered during the initialization of the `ApplicationContext` typically cannot be associated with an individual test method. However, if the context is closed immediately before the -execution of a test method according to <> +execution of a test method according to xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[`@DirtiesContext`] semantics, a new instance of the context will be loaded just prior to execution of the test method. In the latter scenario, an IDE or build tool may potentially associate console logging with the individual test method. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc index d1935942e25a..30de9635eb9e 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc @@ -16,7 +16,7 @@ Spring integration tests. However, this feature may also be used with any form o external resource whose lifecycle is maintained outside the test's `ApplicationContext`. ==== -In contrast to the <> +In contrast to the xref:testing/testcontext-framework/ctx-management/property-sources.adoc[`@TestPropertySource`] annotation that is applied at the class level, `@DynamicPropertySource` must be applied to a `static` method that accepts a single `DynamicPropertyRegistry` argument which is used to add _name-value_ pairs to the `Environment`. Values are dynamic and provided via @@ -33,7 +33,7 @@ abstraction or injected directly into Spring-managed components – for example, ==== If you use `@DynamicPropertySource` in a base class and discover that tests in subclasses fail because the dynamic properties change between subclasses, you may need to annotate -your base class with <> to +your base class with xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[`@DirtiesContext`] to ensure that each subclass gets its own `ApplicationContext` with the correct dynamic properties. ==== diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc index 2a96d0bd4207..1f41ef8a09c2 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc @@ -331,7 +331,7 @@ following example, the declaration of `@ActiveProfiles` (as well as other annota has been moved to an abstract superclass, `AbstractIntegrationTest`: NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing -classes. See <> for details. +classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] for details. [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc index fcd850e9d7ed..e34e5b3becc9 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc @@ -2,11 +2,11 @@ = Context Configuration with Groovy Scripts To load an `ApplicationContext` for your tests by using Groovy scripts that use the -<>, you can annotate +xref:core/beans/basics.adoc#groovy-bean-definition-dsl[Groovy Bean Definition DSL], you can annotate your test class with `@ContextConfiguration` and configure the `locations` or `value` attribute with an array that contains the resource locations of Groovy scripts. Resource lookup semantics for Groovy scripts are the same as those described for -<>. +xref:testing/testcontext-framework/ctx-management/xml.adoc[XML configuration files]. .Enabling Groovy script support TIP: Support for using Groovy scripts to load an `ApplicationContext` in the Spring diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc index 6cfd1b3a4eaf..1411e7c1b187 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc @@ -212,7 +212,7 @@ shows this configuration scenario: NOTE: If you use `@DirtiesContext` in a test whose context is configured as part of a context hierarchy, you can use the `hierarchyMode` flag to control how the context cache is cleared. For further details, see the discussion of `@DirtiesContext` in -<> and the +xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[Spring Testing Annotations] and the {api-spring-framework}/test/annotation/DirtiesContext.html[`@DirtiesContext`] javadoc. -- diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc index 8229e9c89a87..6c7b7650f266 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc @@ -18,7 +18,7 @@ initializers, respectively, for the test class shadow and effectively replace th configuration defined by superclasses. NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing -classes. See <> for details. +classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] for details. In the next example, which uses XML resource locations, the `ApplicationContext` for `ExtendedTest` is loaded from `base-config.xml` and `extended-config.xml`, in that order. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc index fbc1b11114c5..bd7af6c1487c 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc @@ -2,7 +2,7 @@ = Context Configuration with Component Classes To load an `ApplicationContext` for your tests by using component classes (see -<>), you can annotate your test +xref:core/beans/java.adoc[Java-based container configuration]), you can annotate your test class with `@ContextConfiguration` and configure the `classes` attribute with an array that contains references to component classes. The following example shows how to do so: diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc index 7d59858e248c..263e21446d41 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc @@ -137,7 +137,7 @@ declaratively by using `@PropertySource` or programmatically. Thus, test propert be used to selectively override properties loaded from system and application property sources. Furthermore, inlined properties have higher precedence than properties loaded from resource locations. Note, however, that properties registered via -<> have +xref:testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc[`@DynamicPropertySource`] have higher precedence than those loaded via `@TestPropertySource`. In the next example, the `timezone` and `port` properties and any properties defined in @@ -191,7 +191,7 @@ set to `false`, the locations or inlined properties, respectively, for the test shadow and effectively replace the configuration defined by superclasses. NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing -classes. See <> for details. +classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] for details. In the next example, the `ApplicationContext` for `BaseTest` is loaded by using only the `base.properties` file as a test property source. In contrast, the `ApplicationContext` diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc index bd5a31d226ae..990888625389 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc @@ -3,7 +3,7 @@ To provide comprehensive web testing support, the TestContext framework has a `ServletTestExecutionListener` that is enabled by default. When testing against a -`WebApplicationContext`, this <> +`WebApplicationContext`, this xref:testing/testcontext-framework/key-abstractions.adoc[`TestExecutionListener`] sets up default thread-local state by using Spring Web's `RequestContextHolder` before each test method and creates a `MockHttpServletRequest`, a `MockHttpServletResponse`, and a `ServletWebRequest` based on the base resource path configured with diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc index c09002d9a652..bfb51004538e 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc @@ -5,9 +5,9 @@ When writing integration tests against a relational database, it is often benefi run SQL scripts to modify the database schema or insert test data into tables. The `spring-jdbc` module provides support for _initializing_ an embedded or existing database by executing SQL scripts when the Spring `ApplicationContext` is loaded. See -<> and -<> for details. +xref:data-access/jdbc/embedded-database-support.adoc[Embedded database support] and +xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-dao-testing[Testing data access logic with an embedded database] + for details. Although it is very useful to initialize a database for testing _once_ when the `ApplicationContext` is loaded, sometimes it is essential to be able to modify the @@ -77,8 +77,8 @@ specifies SQL scripts for a test schema and test data, sets the statement separa Note that `ResourceDatabasePopulator` internally delegates to `ScriptUtils` for parsing and running SQL scripts. Similarly, the `executeSqlScript(..)` methods in -<> -and <> +xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-junit4[`AbstractTransactionalJUnit4SpringContextTests`] +and xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-testng[`AbstractTransactionalTestNGSpringContextTests`] internally use a `ResourceDatabasePopulator` to run SQL scripts. See the Javadoc for the various `executeSqlScript(..)` methods for further details. @@ -95,7 +95,7 @@ run against a given database before or after an integration test method. Support NOTE: Method-level `@Sql` declarations override class-level declarations by default. As of Spring Framework 5.2, however, this behavior may be configured per test class or per test method via `@SqlMergeMode`. See -<> for further details. +xref:testing/testcontext-framework/executing-sql.adoc#testcontext-executing-sql-declaratively-script-merging[Merging and Overriding Configuration with `@SqlMergeMode`] for further details. [[testcontext-executing-sql-declaratively-script-resources]] === Path Resource Semantics @@ -382,7 +382,7 @@ that uses JUnit Jupiter and transactional tests with `@Sql`: Note that there is no need to clean up the database after the `usersTest()` method is run, since any changes made to the database (either within the test method or within the `/test-data.sql` script) are automatically rolled back by the -`TransactionalTestExecutionListener` (see <> for +`TransactionalTestExecutionListener` (see xref:testing/testcontext-framework/tx.adoc[transaction management] for details). [[testcontext-executing-sql-declaratively-script-merging]] @@ -394,7 +394,7 @@ database schema or some common test data once per test class and then provide ad use case specific test data per test method. To enable `@Sql` merging, annotate either your test class or test method with `@SqlMergeMode(MERGE)`. To disable merging for a specific test method (or specific test subclass), you can switch back to the default mode -via `@SqlMergeMode(OVERRIDE)`. Consult the <> for examples and further details. +via `@SqlMergeMode(OVERRIDE)`. Consult the xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[`@SqlMergeMode` annotation documentation section] + for examples and further details. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc index e42242d68b79..2951d0430d28 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc @@ -7,7 +7,7 @@ application context that you configured with `@ContextConfiguration` or related annotations. You may use setter injection, field injection, or both, depending on which annotations you choose and whether you place them on setter methods or fields. If you are using JUnit Jupiter you may also optionally use constructor injection -(see <>). For consistency with Spring's annotation-based +(see xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-di[Dependency Injection with `SpringExtension`]). For consistency with Spring's annotation-based injection support, you may also use Spring's `@Autowired` annotation or the `@Inject` annotation from JSR-330 for field and setter injection. @@ -20,8 +20,8 @@ actually quite natural in test code. The rationale for the difference is that yo never instantiate your test class directly. Consequently, there is no need to be able to invoke a `public` constructor or setter method on your test class. -Because `@Autowired` is used to perform <>, if you have multiple bean definitions of the same type, you cannot rely on this +Because `@Autowired` is used to perform xref:core/beans/dependencies/factory-autowire.adoc[autowiring by type] +, if you have multiple bean definitions of the same type, you cannot rely on this approach for those particular beans. In that case, you can use `@Autowired` in conjunction with `@Qualifier`. You can also choose to use `@Inject` in conjunction with `@Named`. Alternatively, if your test class has access to its `ApplicationContext`, you @@ -35,7 +35,7 @@ dependency injection altogether by explicitly configuring your class with from the list of listeners. Consider the scenario of testing a `HibernateTitleRepository` class, as outlined in the -<> section. The next two code listings demonstrate the +xref:testing/integration.adoc#integration-testing-goals[Goals] section. The next two code listings demonstrate the use of `@Autowired` on fields and setter methods. The application context configuration is presented after all sample code listings. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc index 7a360139104f..04e5e9ce4aa8 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc @@ -40,7 +40,7 @@ responsible for managing a single `TestContext` and signaling events to each reg == `TestExecutionListener` `TestExecutionListener` defines the API for reacting to test-execution events published by -the `TestContextManager` with which the listener is registered. See <>. +the `TestContextManager` with which the listener is registered. See xref:testing/testcontext-framework/tel-config.adoc[`TestExecutionListener` Configuration]. [[context-loaders]] == Context Loaders diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc index dfa8b13add10..1a3c642f6261 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc @@ -34,7 +34,7 @@ This may be due to the use of `@DirtiesContext` or due to automatic eviction fro `ContextCache`. If `@DirtiesContext` is the culprit, you either need to find a way to avoid using `@DirtiesContext` or exclude such tests from parallel execution. If the maximum size of the `ContextCache` has been exceeded, you can increase the maximum size -of the cache. See the discussion on <> +of the cache. See the discussion on xref:testing/testcontext-framework/ctx-management/caching.adoc[context caching] for details. ==== diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc index 543ee423e1f1..ae9aa71b1bca 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc @@ -15,7 +15,7 @@ loading application contexts, dependency injection of test instances, transactio method execution, and so on. If you want to use the Spring TestContext Framework with an alternative runner (such as JUnit 4's `Parameterized` runner) or third-party runners (such as the `MockitoJUnitRunner`), you can, optionally, use -<> instead. +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules[Spring's support for JUnit rules] instead. The following code listing shows the minimal requirements for configuring a test class to run with the custom Spring `Runner`: @@ -140,8 +140,8 @@ extend `AbstractTransactionalJUnit4SpringContextTests`, you can access a `protec database. You can use such queries to confirm database state both before and after running database-related application code, and Spring ensures that such queries run in the scope of the same transaction as the application code. When used in conjunction with -an ORM tool, be sure to avoid <>. -As mentioned in <>, +an ORM tool, be sure to avoid xref:testing/testcontext-framework/tx.adoc#testcontext-tx-false-positives[false positives]. +As mentioned in xref:testing/support-jdbc.adoc[JDBC Testing Support], `AbstractTransactionalJUnit4SpringContextTests` also provides convenience methods that delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`. Furthermore, `AbstractTransactionalJUnit4SpringContextTests` provides an @@ -149,8 +149,8 @@ Furthermore, `AbstractTransactionalJUnit4SpringContextTests` provides an TIP: These classes are a convenience for extension. If you do not want your test classes to be tied to a Spring-specific class hierarchy, you can configure your own custom test -classes by using `@RunWith(SpringRunner.class)` or <>. +classes by using `@RunWith(SpringRunner.class)` or xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules[Spring's JUnit rules] +. [[testcontext-junit-jupiter-extension]] == SpringExtension for JUnit Jupiter @@ -167,14 +167,14 @@ following features above and beyond the feature set that Spring supports for JUn TestNG: * Dependency injection for test constructors, test methods, and test lifecycle callback - methods. See <> for further details. + methods. See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-di[Dependency Injection with `SpringExtension`] for further details. * Powerful support for link:https://junit.org/junit5/docs/current/user-guide/#extensions-conditions[conditional test execution] based on SpEL expressions, environment variables, system properties, and so on. See the documentation for `@EnabledIf` and `@DisabledIf` in - <> for further details and examples. + xref:testing/annotations/integration-junit-jupiter.adoc[Spring JUnit Jupiter Testing Annotations] for further details and examples. * Custom composed annotations that combine annotations from Spring and JUnit Jupiter. See the `@TransactionalDevTestConfig` and `@TransactionalIntegrationTest` examples in - <> for further details. + xref:testing/annotations/integration-meta.adoc[Meta-Annotation Support for Testing] for further details. The following code listing shows how to configure a test class to use the `SpringExtension` in conjunction with `@ContextConfiguration`: @@ -282,7 +282,7 @@ Similarly, the following example uses `@SpringJUnitWebConfig` to create a ---- See the documentation for `@SpringJUnitConfig` and `@SpringJUnitWebConfig` in -<> for further details. +xref:testing/annotations/integration-junit-jupiter.adoc[Spring JUnit Jupiter Testing Annotations] for further details. [[testcontext-junit-jupiter-di]] === Dependency Injection with `SpringExtension` @@ -314,7 +314,7 @@ autowirable if one of the following conditions is met (in order of precedence). attribute set to `ALL`. * The default _test constructor autowire mode_ has been changed to `ALL`. -See <> for details on the use of +See xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`] for details on the use of `@TestConstructor` and how to change the global _test constructor autowire mode_. WARNING: If the constructor for a test class is considered to be _autowirable_, Spring @@ -375,7 +375,7 @@ In the following example, Spring injects the `OrderService` bean from the Note that this feature lets test dependencies be `final` and therefore immutable. If the `spring.test.constructor.autowire.mode` property is to `all` (see -<>), we can omit the declaration of +xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`]), we can omit the declaration of `@Autowired` on the constructor in the previous example, resulting in the following. [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -502,16 +502,16 @@ recursively. In order to allow development teams to change the default to `OVERRIDE` – for example, for compatibility with Spring Framework 5.0 through 5.2 – the default mode can be changed globally via a JVM system property or a `spring.properties` file in the root of the -classpath. See the <> note for details. +classpath. See the xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration["Changing the default enclosing configuration inheritance mode"] + note for details. Although the following "Hello World" example is very simplistic, it shows how to declare common configuration on a top-level class that is inherited by its `@Nested` test classes. In this particular example, only the `TestConfig` configuration class is inherited. Each nested test class provides its own set of active profiles, resulting in a distinct `ApplicationContext` for each nested test class (see -<> for details). Consult the list of -<> to see +xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching] for details). Consult the list of +xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration[supported annotations] to see which annotations can be inherited in `@Nested` test classes. [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -594,8 +594,8 @@ extend `AbstractTransactionalTestNGSpringContextTests`, you can access a `protec database. You can use such queries to confirm database state both before and after running database-related application code, and Spring ensures that such queries run in the scope of the same transaction as the application code. When used in conjunction with -an ORM tool, be sure to avoid <>. -As mentioned in <>, +an ORM tool, be sure to avoid xref:testing/testcontext-framework/tx.adoc#testcontext-tx-false-positives[false positives]. +As mentioned in xref:testing/support-jdbc.adoc[JDBC Testing Support], `AbstractTransactionalTestNGSpringContextTests` also provides convenience methods that delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`. Furthermore, `AbstractTransactionalTestNGSpringContextTests` provides an diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc index cb6856f261b1..6b255cb59b21 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc @@ -9,7 +9,7 @@ by default, exactly in the following order: * `DirtiesContextBeforeModesTestExecutionListener`: Handles the `@DirtiesContext` annotation for "`before`" modes. * `ApplicationEventsTestExecutionListener`: Provides support for - <>. + xref:testing/testcontext-framework/application-events.adoc[`ApplicationEvents`]. * `DependencyInjectionTestExecutionListener`: Provides dependency injection for the test instance. * `DirtiesContextTestExecutionListener`: Handles the `@DirtiesContext` annotation for @@ -19,14 +19,14 @@ by default, exactly in the following order: * `SqlScriptsTestExecutionListener`: Runs SQL scripts configured by using the `@Sql` annotation. * `EventPublishingTestExecutionListener`: Publishes test execution events to the test's - `ApplicationContext` (see <>). + `ApplicationContext` (see xref:testing/testcontext-framework/test-execution-events.adoc[Test Execution Events]). [[testcontext-tel-config-registering-tels]] == Registering `TestExecutionListener` Implementations You can register `TestExecutionListener` implementations explicitly for a test class, its subclasses, and its nested classes by using the `@TestExecutionListeners` annotation. See -<> and the javadoc for +xref:testing/annotations.adoc[annotation support] and the javadoc for {api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners`] for details and examples. @@ -84,7 +84,7 @@ file. == Ordering `TestExecutionListener` Implementations When the TestContext framework discovers default `TestExecutionListener` implementations -through the <> +through the xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-automatic-discovery[aforementioned] `SpringFactoriesLoader` mechanism, the instantiated listeners are sorted by using Spring's `AnnotationAwareOrderComparator`, which honors Spring's `Ordered` interface and `@Order` annotation for ordering. `AbstractTestExecutionListener` and all default @@ -145,15 +145,15 @@ change from release to release -- for example, `SqlScriptsTestExecutionListener` introduced in Spring Framework 4.1, and `DirtiesContextBeforeModesTestExecutionListener` was introduced in Spring Framework 4.2. Furthermore, third-party frameworks like Spring Boot and Spring Security register their own default `TestExecutionListener` -implementations by using the aforementioned <>. +implementations by using the aforementioned xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-automatic-discovery[automatic discovery mechanism] +. To avoid having to be aware of and re-declare all default listeners, you can set the `mergeMode` attribute of `@TestExecutionListeners` to `MergeMode.MERGE_WITH_DEFAULTS`. `MERGE_WITH_DEFAULTS` indicates that locally declared listeners should be merged with the default listeners. The merging algorithm ensures that duplicates are removed from the list and that the resulting set of merged listeners is sorted according to the semantics -of `AnnotationAwareOrderComparator`, as described in <>. +of `AnnotationAwareOrderComparator`, as described in xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-ordering[Ordering `TestExecutionListener` Implementations]. If a listener implements `Ordered` or is annotated with `@Order`, it can influence the position in which it is merged with the defaults. Otherwise, locally declared listeners are appended to the list of default listeners when merged. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc index 73dda5f70c26..b83c12736731 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc @@ -52,7 +52,7 @@ In order to listen to test execution events, a Spring bean may choose to impleme `org.springframework.context.ApplicationListener` interface. Alternatively, listener methods can be annotated with `@EventListener` and configured to listen to one of the particular event types listed above (see -<>). +xref:core/beans/context-introduction.adoc#context-functionality-events-annotation[Annotation-based Event Listeners]). Due to the popularity of this approach, Spring provides the following dedicated `@EventListener` annotations to simplify registration of test execution event listeners. These annotations reside in the `org.springframework.test.context.event.annotation` @@ -81,8 +81,8 @@ asynchronous exception handling, consult the class-level javadoc for `@EventList == Asynchronous Listeners If you want a particular test execution event listener to process events asynchronously, -you can use Spring's <>. For further details, consult the class-level javadoc for +you can use Spring's xref:integration/scheduling.adoc#scheduling-annotation-support-async[regular `@Async` support] +. For further details, consult the class-level javadoc for `@EventListener`. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc index 72e74703420f..babf258e0ffc 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc @@ -21,7 +21,7 @@ application code that is invoked by tests). Spring-managed and application-manag transactions typically participate in test-managed transactions. However, you should use caution if Spring-managed or application-managed transactions are configured with any propagation type other than `REQUIRED` or `SUPPORTS` (see the discussion on -<> for details). +xref:data-access/transaction/declarative/tx-propagation.adoc[transaction propagation] for details). .Preemptive timeouts and test-managed transactions [WARNING] @@ -94,9 +94,9 @@ your test class and then use that with a `TransactionTemplate` for programmatic transaction management. ==== -Note that <> and -<> +Note that xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-junit4[`AbstractTransactionalJUnit4SpringContextTests`] + and +xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-testng[`AbstractTransactionalTestNGSpringContextTests`] are preconfigured for transactional support at the class level. The following example demonstrates a common scenario for writing an integration test for @@ -188,7 +188,7 @@ a Hibernate-based `UserRepository`: } ---- -As explained in <>, there is no need to +As explained in xref:testing/testcontext-framework/tx.adoc#testcontext-tx-rollback-and-commit-behavior[Transaction Rollback and Commit Behavior], there is no need to clean up the database after the `createUser()` method runs, since any changes made to the database are automatically rolled back by the `TransactionalTestExecutionListener`. @@ -198,7 +198,7 @@ database are automatically rolled back by the `TransactionalTestExecutionListene By default, test transactions will be automatically rolled back after completion of the test; however, transactional commit and rollback behavior can be configured declaratively via the `@Commit` and `@Rollback` annotations. See the corresponding entries in the -<> section for further details. +xref:testing/annotations.adoc[annotation support] section for further details. [[testcontext-tx-programmatic-tx-mgt]] == Programmatic Transaction Management @@ -312,9 +312,9 @@ algorithm used to look up a transaction manager in the test's `ApplicationContex The following JUnit Jupiter based example displays a fictitious integration testing scenario that highlights all transaction-related annotations. The example is not intended to demonstrate best practices but rather to demonstrate how these annotations can be -used. See the <> section for further -information and configuration examples. <> contains an additional example that uses `@Sql` for +used. See the xref:testing/annotations.adoc[annotation support] section for further +information and configuration examples. xref:testing/testcontext-framework/executing-sql.adoc#testcontext-executing-sql-declaratively-tx[Transaction management for `@Sql`] + contains an additional example that uses `@Sql` for declarative SQL script execution with default transaction rollback semantics. The following example shows the relevant annotations: @@ -521,7 +521,7 @@ The following example shows matching methods for JPA: .Testing ORM entity lifecycle callbacks [NOTE] ===== -Similar to the note about avoiding <> +Similar to the note about avoiding xref:testing/testcontext-framework/tx.adoc#testcontext-tx-false-positives[false positives] when testing ORM code, if your application makes use of entity lifecycle callbacks (also known as entity listeners), make sure to flush the underlying unit of work within test methods that run that code. Failing to _flush_ or _clear_ the underlying unit of work can diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc index fd70310f118c..5c87d206a113 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc @@ -1,8 +1,8 @@ [[testcontext-web-scoped-beans]] = Testing Request- and Session-scoped Beans -Spring has supported <> since the early years, and you can test your request-scoped and session-scoped +Spring has supported xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other[Request- and session-scoped beans] + since the early years, and you can test your request-scoped and session-scoped beans by following these steps: * Ensure that a `WebApplicationContext` is loaded for your test by annotating your test @@ -15,7 +15,7 @@ beans by following these steps: The next code snippet shows the XML configuration for a login use case. Note that the `userService` bean has a dependency on a request-scoped `loginAction` bean. Also, the -`LoginAction` is instantiated by using <> that +`LoginAction` is instantiated by using xref:core/expressions.adoc[SpEL expressions] that retrieve the username and password from the current HTTP request. In our test, we want to configure these request parameters through the mock managed by the TestContext framework. The following listing shows the configuration for this use case: diff --git a/framework-docs/modules/ROOT/pages/testing/unit.adoc b/framework-docs/modules/ROOT/pages/testing/unit.adoc index 6a3cbe027548..f137331a5138 100644 --- a/framework-docs/modules/ROOT/pages/testing/unit.adoc +++ b/framework-docs/modules/ROOT/pages/testing/unit.adoc @@ -4,7 +4,7 @@ Dependency injection should make your code less dependent on the container than it would be with traditional J2EE / Java EE development. The POJOs that make up your application should be testable in JUnit or TestNG tests, with objects instantiated by using the `new` -operator, without Spring or any other container. You can use <> +operator, without Spring or any other container. You can use xref:testing/unit.adoc#mock-objects[mock objects] (in conjunction with other valuable testing techniques) to test your code in isolation. If you follow the architecture recommendations for Spring, the resulting clean layering and componentization of your codebase facilitate easier unit testing. For example, @@ -25,10 +25,10 @@ are described in this chapter. Spring includes a number of packages dedicated to mocking: -* <> -* <> -* <> -* <> +* xref:testing/unit.adoc#mock-objects-env[Environment] +* xref:testing/unit.adoc#mock-objects-jndi[JNDI] +* xref:testing/unit.adoc#mock-objects-servlet[Servlet API] +* xref:testing/unit.adoc#mock-objects-web-reactive[Spring Web Reactive] [[mock-objects-env]] @@ -36,8 +36,8 @@ Spring includes a number of packages dedicated to mocking: The `org.springframework.mock.env` package contains mock implementations of the `Environment` and `PropertySource` abstractions (see -<> -and <>). +xref:core/beans/environment.adoc#beans-definition-profiles[Bean Definition Profiles] +and xref:core/beans/environment.adoc#beans-property-source-abstraction[`PropertySource` Abstraction]). `MockEnvironment` and `MockPropertySource` are useful for developing out-of-container tests for code that depends on environment-specific properties. @@ -69,7 +69,7 @@ TIP: Since Spring Framework 6.0, the mock objects in `org.springframework.mock.w based on the Servlet 6.0 API. The Spring MVC Test framework builds on the mock Servlet API objects to provide an -integration testing framework for Spring MVC. See <>. +integration testing framework for Spring MVC. See xref:testing/spring-mvc-test-framework.adoc[MockMvc]. [[mock-objects-web-reactive]] @@ -90,7 +90,7 @@ write completion handle (that is, `Mono`), it by default uses a `Flux` wit `cache().then()`, which buffers the data and makes it available for assertions in tests. Applications can set a custom write function (for example, to test an infinite stream). -The <> builds on the mock request and response to provide support for +The xref:testing/webtestclient.adoc[WebTestClient] builds on the mock request and response to provide support for testing WebFlux applications without an HTTP server. The client can also be used for end-to-end tests with a running server. @@ -102,8 +102,8 @@ end-to-end tests with a running server. Spring includes a number of classes that can help with unit testing. They fall into two categories: -* <> -* <> +* xref:testing/unit.adoc#unit-testing-utilities[General Testing Utilities] +* xref:testing/unit.adoc#unit-testing-spring-mvc[Spring MVC Testing Utilities] [[unit-testing-utilities]] @@ -162,7 +162,7 @@ that deal with Spring MVC `ModelAndView` objects. .Unit testing Spring MVC Controllers TIP: To unit test your Spring MVC `Controller` classes as POJOs, use `ModelAndViewAssert` combined with `MockHttpServletRequest`, `MockHttpSession`, and so on from Spring's -<>. For thorough integration testing of your +xref:testing/unit.adoc#mock-objects-servlet[Servlet API mocks]. For thorough integration testing of your Spring MVC and REST `Controller` classes in conjunction with your `WebApplicationContext` configuration for Spring MVC, use the -<> instead. +xref:testing/spring-mvc-test-framework.adoc[Spring MVC Test Framework] instead. diff --git a/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc b/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc index 4335760e1048..f5f1cab0a7bb 100644 --- a/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc +++ b/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc @@ -2,12 +2,12 @@ = WebTestClient `WebTestClient` is an HTTP client designed for testing server applications. It wraps -Spring's <> and uses it to perform requests +Spring's xref:web/webflux-webclient.adoc[WebClient] and uses it to perform requests but exposes a testing facade for verifying responses. `WebTestClient` can be used to perform end-to-end HTTP tests. It can also be used to test Spring MVC and Spring WebFlux applications without a running server via mock server request and response objects. -TIP: Kotlin users: See <> +TIP: Kotlin users: See xref:languages/kotlin/spring-projects-in.adoc#kotlin-webtestclient-issue[this section] related to use of the `WebTestClient`. @@ -28,8 +28,8 @@ This setup allows you to test specific controller(s) via mock request and respon without a running server. For WebFlux applications, use the following which loads infrastructure equivalent to the -<>, registers the given -controller(s), and creates a <> +xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Java config], registers the given +controller(s), and creates a xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[WebHandler chain] to handle requests: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -46,9 +46,9 @@ to handle requests: For Spring MVC, use the following which delegates to the {api-spring-framework}/test/web/servlet/setup/StandaloneMockMvcBuilder.html[StandaloneMockMvcBuilder] -to load infrastructure equivalent to the <>, +to load infrastructure equivalent to the xref:web/webmvc/mvc-config.adoc[WebMvc Java config], registers the given controller(s), and creates an instance of -<> to handle requests: +xref:testing/spring-mvc-test-framework.adoc[MockMvc] to handle requests: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -73,7 +73,7 @@ and response objects, without a running server. For WebFlux, use the following where the Spring `ApplicationContext` is passed to {api-spring-framework}/web/server/adapter/WebHttpHandlerBuilder.html#applicationContext-org.springframework.context.ApplicationContext-[WebHttpHandlerBuilder] -to create the <> to handle +to create the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[WebHandler chain] to handle requests: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -114,7 +114,7 @@ requests: For Spring MVC, use the following where the Spring `ApplicationContext` is passed to {api-spring-framework}/test/web/servlet/setup/MockMvcBuilders.html#webAppContextSetup-org.springframework.web.context.WebApplicationContext-[MockMvcBuilders.webAppContextSetup] -to create a <> instance to handle +to create a xref:testing/spring-mvc-test-framework.adoc[MockMvc] instance to handle requests: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -194,7 +194,7 @@ create a server setup to handle requests: ---- For Spring MVC there are currently no options to test -<>. +xref:web/webmvc-functional.adoc[WebMvc functional endpoints]. @@ -248,9 +248,9 @@ follows: [[webtestclient-tests]] == Writing Tests -`WebTestClient` provides an API identical to <> +`WebTestClient` provides an API identical to xref:web/webflux-webclient.adoc[WebClient] up to the point of performing a request by using `exchange()`. See the -<> documentation for examples on how to +xref:web/webflux-webclient/client-body.adoc[WebClient] documentation for examples on how to prepare a request with any content including form data, multipart data, and more. After the call to `exchange()`, `WebTestClient` diverges from the `WebClient` and @@ -298,7 +298,7 @@ You can then choose to decode the response body through one of the following: * `expectBody(Class)`: Decode to single object. * `expectBodyList(Class)`: Decode and collect objects to `List`. -* `expectBody()`: Decode to `byte[]` for <> or an empty body. +* `expectBody()`: Decode to `byte[]` for xref:testing/webtestclient.adoc#webtestclient-json[JSON Content] or an empty body. And perform assertions on the resulting higher level Object(s): diff --git a/framework-docs/modules/ROOT/pages/web-reactive.adoc b/framework-docs/modules/ROOT/pages/web-reactive.adoc index 01d6cc8c552f..4fc5fbe565c1 100644 --- a/framework-docs/modules/ROOT/pages/web-reactive.adoc +++ b/framework-docs/modules/ROOT/pages/web-reactive.adoc @@ -4,10 +4,10 @@ This part of the documentation covers support for reactive-stack web applications built on a https://www.reactive-streams.org/[Reactive Streams] API to run on non-blocking servers, such as Netty, Undertow, and Servlet containers. Individual chapters cover -the <> framework, -the reactive <>, support for <>, -and <>. For Servlet-stack web applications, -see <>. +the xref:web/webflux.adoc#webflux[Spring WebFlux] framework, +the reactive xref:web/webflux-webclient.adoc[`WebClient`], support for xref:web-reactive.adoc#webflux-test[testing], +and xref:web-reactive.adoc#webflux-reactive-libraries[reactive libraries]. For Servlet-stack web applications, +see xref:web.adoc[Web on Servlet Stack]. @@ -20,7 +20,7 @@ exchange methods. You can then generate a proxy that implements this interface a performs the exchanges. This helps to simplify HTTP remote access and provides additional flexibility for to choose an API style such as synchronous or reactive. -See <> for details. +See xref:integration/rest-clients.adoc#rest-http-interface[REST Endpoints] for details. @@ -28,14 +28,14 @@ See <> for details. [[webflux-test]] == Testing -[.small]#<># +[.small]#xref:web/webmvc-test.adoc[Same in Spring MVC]# The `spring-test` module provides mock implementations of `ServerHttpRequest`, `ServerHttpResponse`, and `ServerWebExchange`. -See <> for a +See xref:testing/unit.adoc#mock-objects-web-reactive[Spring Web Reactive] for a discussion of mock objects. -<> builds on these mock request and +xref:testing/webtestclient.adoc[`WebTestClient`] builds on these mock request and response objects to provide support for testing WebFlux applications without an HTTP server. You can use the `WebTestClient` for end-to-end integration tests, too. diff --git a/framework-docs/modules/ROOT/pages/web.adoc b/framework-docs/modules/ROOT/pages/web.adoc index 2772fc350883..2cfb7be73e59 100644 --- a/framework-docs/modules/ROOT/pages/web.adoc +++ b/framework-docs/modules/ROOT/pages/web.adoc @@ -2,9 +2,9 @@ = Web on Servlet Stack This part of the documentation covers support for Servlet-stack web applications built on the -Servlet API and deployed to Servlet containers. Individual chapters include <>, -<>, <>, and <>. -For reactive-stack web applications, see <>. +Servlet API and deployed to Servlet containers. Individual chapters include xref:web/webmvc.adoc#mvc[Spring MVC], +xref:web/webmvc-view.adoc[View Technologies], xref:web/webmvc-cors.adoc[CORS Support], and xref:web/websocket.adoc[WebSocket Support]. +For reactive-stack web applications, see xref:testing/unit.adoc#mock-objects-web-reactive[Web on Reactive Stack]. diff --git a/framework-docs/modules/ROOT/pages/web/integration.adoc b/framework-docs/modules/ROOT/pages/web/integration.adoc index 5fdd1595dd6e..6d362d916ae7 100644 --- a/framework-docs/modules/ROOT/pages/web/integration.adoc +++ b/framework-docs/modules/ROOT/pages/web/integration.adoc @@ -9,7 +9,7 @@ particular architecture, technology, or methodology (although it certainly recom some over others). This freedom to pick and choose the architecture, technology, or methodology that is most relevant to a developer and their development team is arguably most evident in the web area, where Spring provides its own web frameworks -(<> and <>) while, at the same time, +(xref:web/webmvc.adoc#mvc[Spring MVC] and xref:web/webflux.adoc#webflux[Spring WebFlux]) while, at the same time, supporting integration with a number of popular third-party web frameworks. @@ -178,7 +178,7 @@ https://struts.apache.org/plugins/spring/[Spring Plugin] for built-in Spring int https://tapestry.apache.org/[Tapestry] is a "Component oriented framework for creating dynamic, robust, highly scalable web applications in Java." -While Spring has its own <>, there are a number of unique +While Spring has its own xref:web/webmvc.adoc#mvc[powerful web layer], there are a number of unique advantages to building an enterprise Java application by using a combination of Tapestry for the web user interface and the Spring container for the lower layers. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc b/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc index b8805e226a7d..8ee097700de1 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc @@ -1,6 +1,6 @@ [[webflux-cors]] = CORS -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc[See equivalent in the Servlet stack]# Spring WebFlux lets you handle CORS (Cross-Origin Resource Sharing). This section describes how to do so. @@ -10,7 +10,7 @@ describes how to do so. [[webflux-cors-intro]] == Introduction -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-intro[See equivalent in the Servlet stack]# For security reasons, browsers prohibit AJAX calls to resources outside the current origin. For example, you could have your bank account in one tab and evil.com in another. Scripts @@ -27,7 +27,7 @@ powerful workarounds based on IFRAME or JSONP. [[webflux-cors-processing]] == Processing -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-processing[See equivalent in the Servlet stack]# The CORS specification distinguishes between preflight, simple, and actual requests. To learn how CORS works, you can read @@ -77,7 +77,7 @@ To learn more from the source or to make advanced customizations, see: [[webflux-cors-controller]] == `@CrossOrigin` -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-controller[See equivalent in the Servlet stack]# The {api-spring-framework}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`] annotation enables cross-origin requests on annotated controller methods, as the @@ -237,7 +237,7 @@ as the following example shows: [[webflux-cors-global]] == Global Configuration -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-global[See equivalent in the Servlet stack]# In addition to fine-grained, controller method-level configuration, you probably want to define some global CORS configuration, too. You can set URL-based `CorsConfiguration` @@ -308,7 +308,7 @@ as the following example shows: [[webflux-cors-webfilter]] == CORS `WebFilter` -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-filter[See equivalent in the Servlet stack]# You can apply CORS support through the built-in {api-spring-framework}/web/cors/reactive/CorsWebFilter.html[`CorsWebFilter`], which is a diff --git a/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc b/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc index 882c68200d7f..daba67c29027 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc @@ -1,18 +1,18 @@ [[webflux-fn]] = Functional Endpoints -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc[See equivalent in the Servlet stack]# Spring WebFlux includes WebFlux.fn, a lightweight functional programming model in which functions are used to route and handle requests and contracts are designed for immutability. It is an alternative to the annotation-based programming model but otherwise runs on -the same <> foundation. +the same xref:web/webflux/reactive-spring.adoc[Reactive Core] foundation. [[webflux-fn-overview]] == Overview -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-overview[See equivalent in the Servlet stack]# In WebFlux.fn, an HTTP request is handled with a `HandlerFunction`: a function that takes `ServerRequest` and returns a delayed `ServerResponse` (i.e. `Mono`). @@ -101,19 +101,19 @@ as the following example shows: <1> Create router using Coroutines router DSL; a Reactive alternative is also available via `router { }`. One way to run a `RouterFunction` is to turn it into an `HttpHandler` and install it -through one of the built-in <>: +through one of the built-in xref:web/webflux/reactive-spring.adoc#webflux-httphandler[server adapters]: * `RouterFunctions.toHttpHandler(RouterFunction)` * `RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)` -Most applications can run through the WebFlux Java configuration, see <>. +Most applications can run through the WebFlux Java configuration, see xref:web/webflux-functional.adoc#webflux-fn-running[Running a Server]. [[webflux-fn-handler-functions]] == HandlerFunction -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-handler-functions[See equivalent in the Servlet stack]# `ServerRequest` and `ServerResponse` are immutable interfaces that offer JDK 8-friendly access to the HTTP request and response. @@ -121,7 +121,7 @@ Both request and response provide https://www.reactive-streams.org[Reactive Stre against the body streams. The request body is represented with a Reactor `Flux` or `Mono`. The response body is represented with any Reactive Streams `Publisher`, including `Flux` and `Mono`. -For more on that, see <>. +For more on that, see xref:web-reactive.adoc#webflux-reactive-libraries[Reactive Libraries]. @@ -418,9 +418,9 @@ found. If it is not found, we return a 404 Not Found response. [[webflux-fn-handler-validation]] === Validation -A functional endpoint can use Spring's <> to +A functional endpoint can use Spring's xref:web/webmvc/mvc-config/validation.adoc[validation facilities] to apply validation to the request body. For example, given a custom Spring -<> implementation for a `Person`: +xref:web/webmvc/mvc-config/validation.adoc[Validator] implementation for a `Person`: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -480,13 +480,13 @@ apply validation to the request body. For example, given a custom Spring Handlers can also use the standard bean validation API (JSR-303) by creating and injecting a global `Validator` instance based on `LocalValidatorFactoryBean`. -See <>. +See xref:core/validation/beanvalidation.adoc[Spring Validation]. [[webflux-fn-router-functions]] == `RouterFunction` -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-router-functions[See equivalent in the Servlet stack]# Router functions are used to route the requests to the corresponding `HandlerFunction`. Typically, you do not write router functions yourself, but rather use a method on the @@ -688,7 +688,7 @@ We can further improve by using the `nest` method together with `accept`: [[webflux-fn-running]] == Running a Server -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-running[See equivalent in the Servlet stack]# How do you run a router function in an HTTP server? A simple option is to convert a router function to an `HttpHandler` by using one of the following: @@ -697,16 +697,16 @@ function to an `HttpHandler` by using one of the following: * `RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)` You can then use the returned `HttpHandler` with a number of server adapters by following -<> for server-specific instructions. +xref:web/webflux/reactive-spring.adoc#webflux-httphandler[HttpHandler] for server-specific instructions. A more typical option, also used by Spring Boot, is to run with a -<>-based setup through the -<>, which uses Spring configuration to declare the +xref:web/webflux/dispatcher-handler.adoc[`DispatcherHandler`]-based setup through the +xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config], which uses Spring configuration to declare the components required to process requests. The WebFlux Java configuration declares the following infrastructure components to support functional endpoints: * `RouterFunctionMapping`: Detects one or more `RouterFunction` beans in the Spring -configuration, <>, combines them through +configuration, xref:core/beans/annotation-config/autowired.adoc#beans-factory-ordered[orders them], combines them through `RouterFunction.andOther`, and routes requests to the resulting composed `RouterFunction`. * `HandlerFunctionAdapter`: Simple adapter that lets `DispatcherHandler` invoke a `HandlerFunction` that was mapped to a request. @@ -719,7 +719,7 @@ any are declared. It is also how functional endpoints are enabled by the Spring starter. The following example shows a WebFlux Java configuration (see -<> for how to run it): +xref:web/webflux/dispatcher-handler.adoc[DispatcherHandler] for how to run it): [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -794,7 +794,7 @@ The following example shows a WebFlux Java configuration (see [[webflux-fn-handler-filter-function]] == Filtering Handler Functions -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-handler-filter-function[See equivalent in the Servlet stack]# You can filter handler functions by using the `before`, `after`, or `filter` methods on the routing function builder. @@ -903,4 +903,4 @@ Besides using the `filter` method on the router function builder, it is possible filter to an existing router function via `RouterFunction.filter(HandlerFilterFunction)`. NOTE: CORS support for functional endpoints is provided through a dedicated -<>. +xref:web/webflux-cors.adoc#webflux-cors-webfilter[`CorsWebFilter`]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-view.adoc b/framework-docs/modules/ROOT/pages/web/webflux-view.adoc index 9348d3ca561b..6122ef22bd11 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-view.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-view.adoc @@ -1,18 +1,18 @@ [[webflux-view]] = View Technologies -[.small]#<># +[.small]#xref:web/webmvc-view.adoc[See equivalent in the Servlet stack]# The use of view technologies in Spring WebFlux is pluggable. Whether you decide to use Thymeleaf, FreeMarker, or some other view technology is primarily a matter of a configuration change. This chapter covers the view technologies integrated with Spring -WebFlux. We assume you are already familiar with <>. +WebFlux. We assume you are already familiar with xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution[View Resolution]. [[webflux-view-thymeleaf]] == Thymeleaf -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-thymeleaf.adoc[See equivalent in the Servlet stack]# Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML templates that can be previewed in a browser by double-clicking, which is very @@ -33,7 +33,7 @@ https://web.archive.org/web/20210623051330/http%3A//forum.thymeleaf.org/Thymelea [[webflux-view-freemarker]] == FreeMarker -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc[See equivalent in the Servlet stack]# https://freemarker.apache.org/[Apache FreeMarker] is a template engine for generating any kind of text output from HTML to email and others. The Spring Framework has built-in @@ -43,7 +43,7 @@ integration for using Spring WebFlux with FreeMarker templates. [[webflux-view-freemarker-contextconfig]] === View Configuration -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-freemarker-contextconfig[See equivalent in the Servlet stack]# The following example shows how to configure FreeMarker as a view technology: @@ -98,7 +98,7 @@ returns the view name, `welcome`, the resolver looks for the [[webflux-views-freemarker]] === FreeMarker Configuration -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-freemarker[See equivalent in the Servlet stack]# You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker `Configuration` object (which is managed by Spring) by setting the appropriate bean @@ -151,7 +151,7 @@ the `Configuration` object. [[webflux-view-freemarker-forms]] === Form Handling -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-freemarker-forms[See equivalent in the Servlet stack]# Spring provides a tag library for use in JSPs that contains, among others, a `` element. This element primarily lets forms display values from @@ -162,7 +162,7 @@ with additional convenience macros for generating form input elements themselves [[webflux-view-bind-macros]] ==== The Bind Macros -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-bind-macros[See equivalent in the Servlet stack]# A standard set of macros are maintained within the `spring-webflux.jar` file for FreeMarker, so they are always available to a suitably configured application. @@ -174,8 +174,8 @@ you need to directly call from within your templates. If you wish to view the ma directly, the file is called `spring.ftl` and is in the `org.springframework.web.reactive.result.view.freemarker` package. -For additional details on binding support, see <> for Spring MVC. +For additional details on binding support, see xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-simple-binding[Simple Binding] + for Spring MVC. [[webflux-views-form-macros]] @@ -184,16 +184,16 @@ Binding>> for Spring MVC. For details on Spring's form macro support for FreeMarker templates, consult the following sections of the Spring MVC documentation. -* <> -* <> -* <> -* <> +* xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros[Input Macros] +* xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros-input[Input Fields] +* xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros-select[Selection Fields] +* xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros-html-escaping[HTML Escaping] [[webflux-view-script]] == Script Views -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-script.adoc[See equivalent in the Servlet stack]# The Spring Framework has a built-in integration for using Spring WebFlux with any templating library that can run on top of the @@ -219,7 +219,7 @@ TIP: The basic rule for integrating any other script engine is that it must impl [[webflux-view-script-dependencies]] === Requirements -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-script.adoc#mvc-view-script-dependencies[See equivalent in the Servlet stack]# You need to have the script engine on your classpath, the details of which vary by script engine: @@ -239,7 +239,7 @@ through https://www.webjars.org/[WebJars]. [[webflux-view-script-integrate]] === Script Templates -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-script.adoc#mvc-view-script-integrate[See equivalent in the Servlet stack]# You can declare a `ScriptTemplateConfigurer` bean to specify the script engine to use, the script files to load, what function to call to render templates, and so on. @@ -389,17 +389,17 @@ for more configuration examples. [[webflux-view-httpmessagewriter]] == JSON and XML -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-jackson.adoc[See equivalent in the Servlet stack]# -For <> purposes, it is useful to be able to alternate +For xref:web/webflux/dispatcher-handler.adoc#webflux-multiple-representations[Content Negotiation] purposes, it is useful to be able to alternate between rendering a model with an HTML template or as other formats (such as JSON or XML), depending on the content type requested by the client. To support doing so, Spring WebFlux provides the `HttpMessageWriterView`, which you can use to plug in any of the available -<> from `spring-web`, such as `Jackson2JsonEncoder`, `Jackson2SmileEncoder`, +xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] from `spring-web`, such as `Jackson2JsonEncoder`, `Jackson2SmileEncoder`, or `Jaxb2XmlEncoder`. Unlike other view technologies, `HttpMessageWriterView` does not require a `ViewResolver` -but is instead <> as a default view. You can +but is instead xref:web/webflux/config.adoc#webflux-config-view-resolvers[configured] as a default view. You can configure one or more such default views, wrapping different `HttpMessageWriter` instances or `Encoder` instances. The one that matches the requested content type is used at runtime. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc index 4f367cf44fd4..4b4a7c845b5e 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc @@ -2,10 +2,10 @@ = WebClient Spring WebFlux includes a client to perform HTTP requests with. `WebClient` has a -functional, fluent API based on Reactor, see <>, +functional, fluent API based on Reactor, see xref:web-reactive.adoc#webflux-reactive-libraries[Reactive Libraries], which enables declarative composition of asynchronous logic without the need to deal with threads or concurrency. It is fully non-blocking, it supports streaming, and relies on -the same <> that are also used to encode and +the same xref:web/webflux/reactive-spring.adoc#webflux-codecs[codecs] that are also used to encode and decode request and response content on the server side. `WebClient` needs an HTTP client library to perform requests with. There is built-in diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc index 75c429669747..608d2cc117c7 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc @@ -16,8 +16,8 @@ You can also use `WebClient.builder()` with further options: * `filter`: Client filter for every request. * `exchangeStrategies`: HTTP message reader/writer customizations. * `clientConnector`: HTTP client library settings. -* `observationRegistry`: the registry to use for enabling <>. -* `observationConvention`: <> for recorded observations. +* `observationRegistry`: the registry to use for enabling xref:integration/observability.adoc#integration.observability.http-client.webclient[Observability support]. +* `observationConvention`: xref:integration/observability.adoc#integration.observability.config[an optional, custom convention to extract metadata] for recorded observations. For example: @@ -69,7 +69,7 @@ modified copy as follows: [[webflux-client-builder-maxinmemorysize]] == MaxInMemorySize -Codecs have <> for buffering data in +Codecs have xref:web/webflux/reactive-spring.adoc#webflux-codecs-limits[limits] for buffering data in memory to avoid application memory issues. By default those are set to 256KB. If that's not enough you'll get the following error: diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc index 406f80c4de15..0cb4e619b3c1 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc @@ -1,7 +1,7 @@ [[webflux-client-context]] = Context -<> provide a convenient way to pass information to the filter +xref:web/webflux-webclient/client-attributes.adoc[Attributes] provide a convenient way to pass information to the filter chain but they only influence the current request. If you want to pass information that propagates to additional requests that are nested, e.g. via `flatMap`, or executed after, e.g. via `concatMap`, then you'll need to use the Reactor `Context`. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc index 5e9b0e01081d..e68b54067a66 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc @@ -1,6 +1,6 @@ [[webflux-websocket]] = WebSockets -[.small]#<># +[.small]#xref:web/websocket.adoc[See equivalent in the Servlet stack]# This part of the reference documentation covers support for reactive-stack WebSocket messaging. @@ -11,7 +11,7 @@ messaging. [[webflux-websocket-server]] == WebSocket API -[.small]#<># +[.small]#xref:web/websocket/stomp/server-config.adoc[See equivalent in the Servlet stack]# The Spring Framework provides a WebSocket API that you can use to write client- and server-side applications that handle WebSocket messages. @@ -20,7 +20,7 @@ server-side applications that handle WebSocket messages. [[webflux-websocket-server-handler]] === Server -[.small]#<># +[.small]#xref:web/websocket/server.adoc#websocket-server-handler[See equivalent in the Servlet stack]# To create a WebSocket server, you can first create a `WebSocketHandler`. The following example shows how to do so: @@ -87,7 +87,7 @@ Then you can map it to a URL: } ---- -If using the <> there is nothing +If using the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] there is nothing further to do, or otherwise if not using the WebFlux config you'll need to declare a `WebSocketHandlerAdapter` as shown below: @@ -206,7 +206,7 @@ following example shows such an implementation: TIP: For nested, asynchronous operations, you may need to call `message.retain()` on underlying servers that use pooled data buffers (for example, Netty). Otherwise, the data buffer may be released before you have had a chance to read the data. For more background, see -<>. +xref:core/databuffer-codec.adoc[Data Buffers and Codecs]. The following implementation combines the inbound and outbound streams: @@ -325,7 +325,7 @@ as the following example shows: `DataBuffer` is the representation for a byte buffer in WebFlux. The Spring Core part of the reference has more on that in the section on -<>. The key point to understand is that on some +xref:core/databuffer-codec.adoc[Data Buffers and Codecs]. The key point to understand is that on some servers like Netty, byte buffers are pooled and reference counted, and must be released when consumed to avoid memory leaks. @@ -338,7 +338,7 @@ subsequently use `DataBufferUtils.release(dataBuffer)` when the buffers are cons [[webflux-websocket-server-handshake]] === Handshake -[.small]#<># +[.small]#xref:web/websocket/server.adoc#websocket-server-handshake[See equivalent in the Servlet stack]# `WebSocketHandlerAdapter` delegates to a `WebSocketService`. By default, that is an instance of `HandshakeWebSocketService`, which performs basic checks on the WebSocket request and @@ -353,12 +353,12 @@ into the attributes of the `WebSocketSession`. [[webflux-websocket-server-config]] === Server Configuration -[.small]#<># +[.small]#xref:web/websocket/server.adoc#websocket-server-runtime-configuration[See equivalent in the Servlet stack]# The `RequestUpgradeStrategy` for each server exposes configuration specific to the underlying WebSocket server engine. When using the WebFlux Java config you can customize such properties as shown in the corresponding section of the -<>, or otherwise if +xref:web/webflux/config.adoc#webflux-config-websocket-service[WebFlux Config], or otherwise if not using the WebFlux config, use the below: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -407,7 +407,7 @@ only Tomcat and Jetty expose such options. [[webflux-websocket-server-cors]] === CORS -[.small]#<># +[.small]#xref:web/websocket/server.adoc#websocket-server-allowed-origins[See equivalent in the Servlet stack]# The easiest way to configure CORS and restrict access to a WebSocket endpoint is to have your `WebSocketHandler` implement `CorsConfigurationSource` and return a diff --git a/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc index e46f27228f5e..b9e731e9b585 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc @@ -1,7 +1,7 @@ [[webflux-ann-rest-exceptions]] = Error Responses -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc[See equivalent in the Servlet stack]# A common requirement for REST services is to include details in the body of error responses. The Spring Framework supports the "Problem Details for HTTP APIs" @@ -18,14 +18,14 @@ exceptions implement this. - `ErrorResponseException` -- basic `ErrorResponse` implementation that others can use as a convenient base class. - `ResponseEntityExceptionHandler` -- convenient base class for an -<> that handles all Spring WebFlux exceptions, +xref:web/webflux/controller/ann-advice.adoc[@ControllerAdvice] that handles all Spring WebFlux exceptions, and any `ErrorResponseException`, and renders an error response with a body. [[webflux-ann-rest-exceptions-render]] == Render -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc#mvc-ann-rest-exceptions-render[See equivalent in the Servlet stack]# You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from any `@RequestMapping` method to render an RFC 7807 response. This is processed as follows: @@ -39,7 +39,7 @@ and also falls back on it if no compatible media type is found. To enable RFC 7807 responses for Spring WebFlux exceptions and for any `ErrorResponseException`, extend `ResponseEntityExceptionHandler` and declare it as an -<> in Spring configuration. The handler +xref:web/webflux/controller/ann-advice.adoc[@ControllerAdvice] in Spring configuration. The handler has an `@ExceptionHandler` method that handles any `ErrorResponse` exception, which includes all built-in web exceptions. You can add more exception handling methods, and use a protected method to map any exception to a `ProblemDetail`. @@ -48,7 +48,7 @@ use a protected method to map any exception to a `ProblemDetail`. [[webflux-ann-rest-exceptions-non-standard]] == Non-Standard Fields -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc#mvc-ann-rest-exceptions-non-standard[See equivalent in the Servlet stack]# You can extend an RFC 7807 response with non-standard fields in one of two ways. @@ -68,13 +68,13 @@ from an existing `ProblemDetail`. This could be done centrally, e.g. from an [[webflux-ann-rest-exceptions-i18n]] == Internationalization -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc#mvc-ann-rest-exceptions-i18n[See equivalent in the Servlet stack]# It is a common requirement to internationalize error response details, and good practice to customize the problem details for Spring WebFlux exceptions. This is supported as follows: - Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field -through a <>. +through a xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSource]. The actual message code value is parameterized with placeholders, e.g. `"HTTP method {0} not supported"` to be expanded from the arguments. - Each `ErrorResponse` also exposes a message code to resolve the "title" field. @@ -139,7 +139,7 @@ qualified exception class name. [[webflux-ann-rest-exceptions-client]] == Client Handling -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc#mvc-ann-rest-exceptions-client[See equivalent in the Servlet stack]# A client application can catch `WebClientResponseException`, when using the `WebClient`, or `RestClientResponseException` when using the `RestTemplate`, and use their diff --git a/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc index 0178ebf2b162..7586c31997ba 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc @@ -1,7 +1,7 @@ [[webflux-caching]] = HTTP Caching -[.small]#<># +[.small]#xref:web/webmvc/mvc-caching.adoc[See equivalent in the Servlet stack]# HTTP caching can significantly improve the performance of a web application. HTTP caching revolves around the `Cache-Control` response header and subsequent conditional request @@ -17,14 +17,14 @@ This section describes the HTTP caching related options available in Spring WebF [[webflux-caching-cachecontrol]] == `CacheControl` -[.small]#<># +[.small]#xref:web/webmvc/mvc-caching.adoc#mvc-caching-cachecontrol[See equivalent in the Servlet stack]# {api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for configuring settings related to the `Cache-Control` header and is accepted as an argument in a number of places: -* <> -* <> +* xref:web/webflux/caching.adoc#webflux-caching-etag-lastmodified[Controllers] +* xref:web/webflux/caching.adoc#webflux-caching-static-resources[Static Resources] While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all possible directives for the `Cache-Control` response header, the `CacheControl` type takes a @@ -65,7 +65,7 @@ use case-oriented approach that focuses on the common scenarios, as the followin [[webflux-caching-etag-lastmodified]] == Controllers -[.small]#<># +[.small]#xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[See equivalent in the Servlet stack]# Controllers can add explicit support for HTTP caching. We recommend doing so, since the `lastModified` or `ETag` value for a resource needs to be calculated before it can be compared @@ -166,10 +166,10 @@ to 412 (PRECONDITION_FAILED) to prevent concurrent modification. [[webflux-caching-static-resources]] == Static Resources -[.small]#<># +[.small]#xref:web/webmvc/mvc-caching.adoc#mvc-caching-static-resources[See equivalent in the Servlet stack]# You should serve static resources with a `Cache-Control` and conditional response headers -for optimal performance. See the section on configuring <>. +for optimal performance. See the section on configuring xref:web/webflux/config.adoc#webflux-config-static-resources[Static Resources]. include:../:webflux-view.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc index 62b53bb86357..4ee87320682f 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc @@ -1,24 +1,24 @@ [[webflux-config]] = WebFlux Config -[.small]#<># +[.small]#xref:web/webmvc/mvc-config.adoc[See equivalent in the Servlet stack]# The WebFlux Java configuration declares the components that are required to process requests with annotated controllers or functional endpoints, and it offers an API to customize the configuration. That means you do not need to understand the underlying beans created by the Java configuration. However, if you want to understand them, you can see them in `WebFluxConfigurationSupport` or read more about what they are -in <>. +in xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[Special Bean Types]. For more advanced customizations, not available in the configuration API, you can gain full control over the configuration through the -<>. +xref:web/webflux/config.adoc#webflux-config-advanced-java[Advanced Configuration Mode]. [[webflux-config-enable]] == Enabling WebFlux Config -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/enable.adoc[See equivalent in the Servlet stack]# You can use the `@EnableWebFlux` annotation in your Java config, as the following example shows: @@ -40,14 +40,14 @@ You can use the `@EnableWebFlux` annotation in your Java config, as the followin ---- The preceding example registers a number of Spring WebFlux -<> and adapts to dependencies +xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[infrastructure beans] and adapts to dependencies available on the classpath -- for JSON, XML, and others. [[webflux-config-customize]] == WebFlux config API -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/customize.adoc[See equivalent in the Servlet stack]# In your Java configuration, you can implement the `WebFluxConfigurer` interface, as the following example shows: @@ -78,7 +78,7 @@ class WebConfig : WebFluxConfigurer { [[webflux-config-conversion]] == Conversion, formatting -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/conversion.adoc[See equivalent in the Servlet stack]# By default, formatters for various number and date types are installed, along with support for customization via `@NumberFormat` and `@DateTimeFormat` on fields. @@ -147,7 +147,7 @@ in the HTML spec. For such cases date and time formatting can be customized as f } ---- -NOTE: See <> +NOTE: See xref:core/validation/format.adoc#format-FormatterRegistrar-SPI[`FormatterRegistrar` SPI] and the `FormattingConversionServiceFactoryBean` for more information on when to use `FormatterRegistrar` implementations. @@ -155,11 +155,11 @@ use `FormatterRegistrar` implementations. [[webflux-config-validation]] == Validation -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/validation.adoc[See equivalent in the Servlet stack]# -By default, if <> is present +By default, if xref:core/validation/beanvalidation.adoc#validation-beanvalidation-overview[Bean Validation] is present on the classpath (for example, the Hibernate Validator), the `LocalValidatorFactoryBean` -is registered as a global <> for use with `@Valid` and +is registered as a global xref:core/validation/validator.adoc[validator] for use with `@Valid` and `@Validated` on `@Controller` method arguments. In your Java configuration, you can customize the global `Validator` instance, @@ -230,7 +230,7 @@ mark it with `@Primary` in order to avoid conflict with the one declared in the [[webflux-config-content-negotiation]] == Content Type Resolvers -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/content-negotiation.adoc[See equivalent in the Servlet stack]# You can configure how Spring WebFlux determines the requested media types for `@Controller` instances from the request. By default, only the `Accept` header is checked, @@ -268,7 +268,7 @@ The following example shows how to customize the requested content type resoluti [[webflux-config-message-codecs]] == HTTP message codecs -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/message-converters.adoc[See equivalent in the Servlet stack]# The following example shows how to customize how the request and response body are read and written: @@ -319,7 +319,7 @@ It also automatically registers the following well-known modules if they are det [[webflux-config-view-resolvers]] == View Resolvers -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/view-resolvers.adoc[See equivalent in the Servlet stack]# The following example shows how to configure view resolution: @@ -427,10 +427,10 @@ You can also plug in any `ViewResolver` implementation, as the following example } ---- -To support <> and rendering other formats +To support xref:web/webflux/dispatcher-handler.adoc#webflux-multiple-representations[Content Negotiation] and rendering other formats through view resolution (besides HTML), you can configure one or more default views based on the `HttpMessageWriterView` implementation, which accepts any of the available -<> from `spring-web`. The following example shows how to do so: +xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] from `spring-web`. The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -470,13 +470,13 @@ on the `HttpMessageWriterView` implementation, which accepts any of the availabl } ---- -See <> for more on the view technologies that are integrated with Spring WebFlux. +See xref:web/webflux-view.adoc[View Technologies] for more on the view technologies that are integrated with Spring WebFlux. [[webflux-config-static-resources]] == Static Resources -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/static-resources.adoc[See equivalent in the Servlet stack]# This option provides a convenient way to serve static resources from a list of {api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. @@ -519,7 +519,7 @@ the example: } ---- -See also <>. +See also xref:web/webflux/caching.adoc#webflux-caching-static-resources[HTTP caching support for static resources]. The resource handler also supports a chain of {api-spring-framework}/web/reactive/resource/ResourceResolver.html[`ResourceResolver`] implementations and @@ -600,7 +600,7 @@ for fine-grained control, e.g. last-modified behavior and optimized resource res [[webflux-config-path-matching]] == Path Matching -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/path-matching.adoc[See equivalent in the Servlet stack]# You can customize options related to path matching. For details on the individual options, see the {api-spring-framework}/web/reactive/config/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc. @@ -646,7 +646,7 @@ whether to decode the request path nor whether to remove semicolon content for path matching purposes. Spring WebFlux also does not support suffix pattern matching, unlike in Spring MVC, where we -are also <> moving away from +are also xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-suffix-pattern-match[recommend] moving away from reliance on it. ==== @@ -701,7 +701,7 @@ For example: [[webflux-config-advanced-java]] == Advanced Configuration Mode -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/advanced-java.adoc[See equivalent in the Servlet stack]# `@EnableWebFlux` imports `DelegatingWebFluxConfiguration` that: diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc index 2f8e72ac0e1b..32d1a1fb60f6 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc @@ -1,7 +1,7 @@ [[webflux-controller]] = Annotated Controllers -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller.adoc[See equivalent in the Servlet stack]# Spring WebFlux provides an annotation-based programming model, where `@Controller` and `@RestController` components use annotations to express request mappings, request input, diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc index 0af8667d8aff..0be31002a66e 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc @@ -1,7 +1,7 @@ [[webflux-ann-controller-advice]] = Controller Advice -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-advice.adoc[See equivalent in the Servlet stack]# Typically, the `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply within the `@Controller` class (or class hierarchy) in which they are declared. If you @@ -9,8 +9,8 @@ want such methods to apply more globally (across controllers), you can declare t class annotated with `@ControllerAdvice` or `@RestControllerAdvice`. `@ControllerAdvice` is annotated with `@Component`, which means that such classes can be -registered as Spring beans through <>. `@RestControllerAdvice` is a composed annotation that is annotated +registered as Spring beans through xref:core/beans/java/instantiating-container.adoc#beans-java-instantiating-container-scan[component scanning] +. `@RestControllerAdvice` is a composed annotation that is annotated with both `@ControllerAdvice` and `@ResponseBody`, which essentially means `@ExceptionHandler` methods are rendered to the response body through message conversion (versus view resolution or template rendering). diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc index fd0d2779f8d7..ab7c3ea2e364 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc @@ -1,9 +1,9 @@ [[webflux-ann-controller-exceptions]] = Exceptions -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc[See equivalent in the Servlet stack]# -`@Controller` and <> classes can have +`@Controller` and xref:web/webflux/controller/ann-advice.adoc[@ControllerAdvice] classes can have `@ExceptionHandler` methods to handle exceptions from controller methods. The following example includes such a handler method: @@ -49,32 +49,32 @@ as shown in the preceding example. Alternatively, the annotation declaration can exception types to match. We generally recommend being as specific as possible in the argument signature and to declare your primary root exception mappings on a `@ControllerAdvice` prioritized with a corresponding order. -See <> for details. +See xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc[the MVC section] for details. NOTE: An `@ExceptionHandler` method in WebFlux supports the same method arguments and return values as a `@RequestMapping` method, with the exception of request body- and `@ModelAttribute`-related method arguments. Support for `@ExceptionHandler` methods in Spring WebFlux is provided by the -`HandlerAdapter` for `@RequestMapping` methods. See <> +`HandlerAdapter` for `@RequestMapping` methods. See xref:web/webflux/dispatcher-handler.adoc[`DispatcherHandler`] for more detail. [[webflux-ann-exceptionhandler-args]] == Method Arguments -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc#mvc-ann-exceptionhandler-args[See equivalent in the Servlet stack]# -`@ExceptionHandler` methods support the same <> +`@ExceptionHandler` methods support the same xref:web/webflux/controller/ann-methods/arguments.adoc[method arguments] as `@RequestMapping` methods, except the request body might have been consumed already. [[webflux-ann-exceptionhandler-return-values]] == Return Values -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc#mvc-ann-exceptionhandler-return-values[See equivalent in the Servlet stack]# -`@ExceptionHandler` methods support the same <> +`@ExceptionHandler` methods support the same xref:web/webflux/controller/ann-methods/return-types.adoc[return values] as `@RequestMapping` methods. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc index 6ffe7b6e54bd..d3f5cb6b946f 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc @@ -1,7 +1,7 @@ [[webflux-ann-initbinder]] = `DataBinder` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-initbinder.adoc[See equivalent in the Servlet stack]# `@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods, to initialize instances of `WebDataBinder`. Those, in turn, are used to: @@ -13,7 +13,7 @@ headers, cookies, and others) to the target type of controller method arguments. `@InitBinder` methods can register controller-specific `java.beans.PropertyEditor` or Spring `Converter` and `Formatter` components. In addition, you can use the -<> to register `Converter` and +xref:web/webflux/config.adoc#webflux-config-conversion[WebFlux Java configuration] to register `Converter` and `Formatter` types in a globally shared `FormattingConversionService`. `@InitBinder` methods support many of the same arguments that `@RequestMapping` methods @@ -100,7 +100,7 @@ controller-specific `Formatter` instances, as the following example shows: [[webflux-ann-initbinder-model-design]] == Model Design -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-initbinder.adoc#mvc-ann-initbinder-model-design[See equivalent in the Servlet stack]# include:../../:web-data-binding-model-design.adoc[] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc index 6389dada1e4d..7c073797e8b1 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc @@ -1,7 +1,7 @@ [[webflux-ann-methods]] = Handler Methods -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods.adoc[See equivalent in the Servlet stack]# `@RequestMapping` handler methods have a flexible signature and can choose from a range of supported controller method arguments and return values. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc index 9ac95fa05eee..87cb4522b2aa 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc @@ -1,11 +1,11 @@ [[webflux-ann-arguments]] = Method Arguments -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/arguments.adoc[See equivalent in the Servlet stack]# The following table shows the supported controller method arguments. -Reactive types (Reactor, RxJava, <>) are +Reactive types (Reactor, RxJava, xref:web-reactive.adoc#webflux-reactive-libraries[or other]) are supported on arguments that require blocking I/O (for example, reading the request body) to be resolved. This is marked in the Description column. Reactive types are not expected on arguments that do not require blocking. @@ -44,38 +44,38 @@ and others) and is equivalent to `required=false`. | The time zone associated with the current request, as determined by a `LocaleContextResolver`. | `@PathVariable` -| For access to URI template variables. See <>. +| For access to URI template variables. See xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-uri-templates[URI Patterns]. | `@MatrixVariable` -| For access to name-value pairs in URI path segments. See <>. +| For access to name-value pairs in URI path segments. See xref:web/webflux/controller/ann-methods/matrix-variables.adoc[Matrix Variables]. | `@RequestParam` | For access to query parameters. Parameter values are converted to the declared method argument - type. See <>. + type. See xref:web/webflux/controller/ann-methods/requestparam.adoc[`@RequestParam`]. Note that use of `@RequestParam` is optional -- for example, to set its attributes. See "`Any other argument`" later in this table. | `@RequestHeader` | For access to request headers. Header values are converted to the declared method argument - type. See <>. + type. See xref:web/webflux/controller/ann-methods/requestheader.adoc[`@RequestHeader`]. | `@CookieValue` | For access to cookies. Cookie values are converted to the declared method argument type. - See <>. + See xref:web/webflux/controller/ann-methods/cookievalue.adoc[`@CookieValue`]. | `@RequestBody` | For access to the HTTP request body. Body content is converted to the declared method argument type by using `HttpMessageReader` instances. Supports reactive types. - See <>. + See xref:web/webflux/controller/ann-methods/requestbody.adoc[`@RequestBody`]. | `HttpEntity` | For access to request headers and body. The body is converted with `HttpMessageReader` instances. - Supports reactive types. See <>. + Supports reactive types. See xref:web/webflux/controller/ann-methods/httpentity.adoc[`HttpEntity`]. | `@RequestPart` | For access to a part in a `multipart/form-data` request. Supports reactive types. - See <> and <>. + See xref:web/webflux/controller/ann-methods/multipart-forms.adoc[Multipart Content] and xref:web/webflux/reactive-spring.adoc#webflux-multipart[Multipart Data]. | `java.util.Map`, `org.springframework.ui.Model`, and `org.springframework.ui.ModelMap`. | For access to the model that is used in HTML controllers and is exposed to templates as @@ -83,8 +83,8 @@ and others) and is equivalent to `required=false`. | `@ModelAttribute` | For access to an existing attribute in the model (instantiated if not present) with - data binding and validation applied. See <> as well - as <> and <>. + data binding and validation applied. See xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[`@ModelAttribute`] as well + as xref:web/webflux/controller/ann-modelattrib-methods.adoc[`Model`] and xref:web/webflux/controller/ann-initbinder.adoc[`DataBinder`]. Note that use of `@ModelAttribute` is optional -- for example, to set its attributes. See "`Any other argument`" later in this table. @@ -97,19 +97,19 @@ and others) and is equivalent to `required=false`. | `SessionStatus` + class-level `@SessionAttributes` | For marking form processing complete, which triggers cleanup of session attributes declared through a class-level `@SessionAttributes` annotation. - See <> for more details. + See xref:web/webflux/controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`] for more details. | `UriComponentsBuilder` | For preparing a URL relative to the current request's host, port, scheme, and - context path. See <>. + context path. See xref:web/webflux/uri-building.adoc[URI Links]. | `@SessionAttribute` | For access to any session attribute -- in contrast to model attributes stored in the session as a result of a class-level `@SessionAttributes` declaration. See - <> for more details. + xref:web/webflux/controller/ann-methods/sessionattribute.adoc[`@SessionAttribute`] for more details. | `@RequestAttribute` -| For access to request attributes. See <> for more details. +| For access to request attributes. See xref:web/webflux/controller/ann-methods/requestattrib.adoc[`@RequestAttribute`] for more details. | Any other argument | If a method argument is not matched to any of the above, it is, by default, resolved as diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc index 92abcfe6bc40..a90cf11ad71a 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc @@ -1,7 +1,7 @@ [[webflux-ann-cookievalue]] = `@CookieValue` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/cookievalue.adoc[See equivalent in the Servlet stack]# You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument in a controller. @@ -37,6 +37,6 @@ The following code sample demonstrates how to get the cookie value: Type conversion is applied automatically if the target method parameter type is not -`String`. See <>. +`String`. See xref:web/webflux/controller/ann-methods/typeconversion.adoc[Type Conversion]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc index d43d137f8e3e..1b326645c8b0 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc @@ -1,9 +1,9 @@ [[webflux-ann-httpentity]] = `HttpEntity` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/httpentity.adoc[See equivalent in the Servlet stack]# -`HttpEntity` is more or less identical to using <> but is based on a +`HttpEntity` is more or less identical to using xref:web/webflux/controller/ann-methods/requestbody.adoc[`@RequestBody`] but is based on a container object that exposes request headers and the body. The following example uses an `HttpEntity`: diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc index 36930e54d4e4..ee443c1d7b0e 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc @@ -5,7 +5,7 @@ Spring offers support for the Jackson JSON library. [[webflux-ann-jsonview]] == JSON Views -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/jackson.adoc[See equivalent in the Servlet stack]# Spring WebFlux provides built-in support for https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc index 439260713738..f37d3830f560 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc @@ -1,7 +1,7 @@ [[webflux-ann-matrix-variables]] = Matrix Variables -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc[See equivalent in the Servlet stack]# https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in path segments. In Spring WebFlux, we refer to those as "`matrix variables`" based on an diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc index 140b5d68e320..f2d234a0b1dc 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc @@ -1,7 +1,7 @@ [[webflux-ann-modelattrib-method-args]] = `@ModelAttribute` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[See equivalent in the Servlet stack]# You can use the `@ModelAttribute` annotation on a method argument to access an attribute from the model or have it instantiated if not present. The model attribute is also overlaid with @@ -27,8 +27,8 @@ converting individual query parameters and form fields. The following example bi The `Pet` instance in the preceding example is resolved as follows: -* From the model if already added through <>. -* From the HTTP session through <>. +* From the model if already added through xref:web/webflux/controller/ann-modelattrib-methods.adoc[`Model`]. +* From the HTTP session through xref:web/webflux/controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`]. * From the invocation of a default constructor. * From the invocation of a "`primary constructor`" with arguments that match query parameters or form fields. Argument names are determined through JavaBeans @@ -38,8 +38,8 @@ After the model attribute instance is obtained, data binding is applied. The `WebExchangeDataBinder` class matches names of query parameters and form fields to field names on the target `Object`. Matching fields are populated after type conversion is applied where necessary. For more on data binding (and validation), see -<>. For more on customizing data binding, see -<>. +xref:web/webmvc/mvc-config/validation.adoc[Validation]. For more on customizing data binding, see +xref:web/webflux/controller/ann-initbinder.adoc[`DataBinder`]. Data binding can result in errors. By default, a `WebExchangeBindException` is raised, but, to check for such errors in the controller method, you can add a `BindingResult` argument @@ -73,8 +73,8 @@ immediately next to the `@ModelAttribute`, as the following example shows: You can automatically apply validation after data binding by adding the `jakarta.validation.Valid` annotation or Spring's `@Validated` annotation (see also -<> and -<>). The following example uses the `@Valid` annotation: +xref:core/validation/beanvalidation.adoc[Bean Validation] and +xref:web/webmvc/mvc-config/validation.adoc[Spring validation]). The following example uses the `@Valid` annotation: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc index a89f22184dda..489c6ec2d8f7 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc @@ -1,11 +1,11 @@ [[webflux-multipart-forms]] = Multipart Content -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[See equivalent in the Servlet stack]# -As explained in <>, `ServerWebExchange` provides access to multipart +As explained in xref:web/webflux/reactive-spring.adoc#webflux-multipart[Multipart Data], `ServerWebExchange` provides access to multipart content. The best way to handle a file upload form (for example, from a browser) in a controller -is through data binding to a <>, +is through data binding to a xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[command object], as the following example shows: -- @@ -274,6 +274,6 @@ file upload. <6> The body contents must be completely consumed, relayed, or released to avoid memory leaks. Received part events can also be relayed to another service by using the `WebClient`. -See <>. +See xref:web/webflux-webclient/client-body.adoc#webflux-client-body-multipart[Multipart Data]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc index bcd9cfcc16ed..b91d1d18bcc3 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc @@ -1,7 +1,7 @@ [[webflux-ann-requestattrib]] = `@RequestAttribute` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/requestattrib.adoc[See equivalent in the Servlet stack]# Similarly to `@SessionAttribute`, you can use the `@RequestAttribute` annotation to access pre-existing request attributes created earlier (for example, by a `WebFilter`), diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc index 3349acccf556..40e79bf6ba22 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc @@ -1,10 +1,10 @@ [[webflux-ann-requestbody]] = `@RequestBody` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[See equivalent in the Servlet stack]# You can use the `@RequestBody` annotation to have the request body read and deserialized into an -`Object` through an <>. +`Object` through an xref:web/webflux/reactive-spring.adoc#webflux-codecs[HttpMessageReader]. The following example uses a `@RequestBody` argument: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -45,7 +45,7 @@ and fully non-blocking reading and (client-to-server) streaming. } ---- -You can use the <> option of the <> to +You can use the xref:web/webflux/config.adoc#webflux-config-message-codecs[HTTP message codecs] option of the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] to configure or customize message readers. You can use `@RequestBody` in combination with `jakarta.validation.Valid` or Spring's diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc index 7c29618b73a0..cf08bc245316 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc @@ -1,7 +1,7 @@ [[webflux-ann-requestheader]] = `@RequestHeader` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/requestheader.adoc[See equivalent in the Servlet stack]# You can use the `@RequestHeader` annotation to bind a request header to a method argument in a controller. @@ -48,7 +48,7 @@ The following example gets the value of the `Accept-Encoding` and `Keep-Alive` h <2> Get the value of the `Keep-Alive` header. Type conversion is applied automatically if the target method parameter type is not -`String`. See <>. +`String`. See xref:web/webflux/controller/ann-methods/typeconversion.adoc[Type Conversion]. When a `@RequestHeader` annotation is used on a `Map`, `MultiValueMap`, or `HttpHeaders` argument, the map is populated diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc index 59b7a1d45c88..64bad1fd03a7 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc @@ -1,7 +1,7 @@ [[webflux-ann-requestparam]] = `@RequestParam` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/requestparam.adoc[See equivalent in the Servlet stack]# You can use the `@RequestParam` annotation to bind query parameters to a method argument in a controller. The following code snippet shows the usage: @@ -54,7 +54,7 @@ TIP: The Servlet API "`request parameter`" concept conflates query parameters, f data, and multiparts into one. However, in WebFlux, each is accessed individually through `ServerWebExchange`. While `@RequestParam` binds to query parameters only, you can use data binding to apply query parameters, form data, and multiparts to a -<>. +xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[command object]. Method parameters that use the `@RequestParam` annotation are required by default, but you can specify that a method parameter is optional by setting the required flag of a `@RequestParam` @@ -62,7 +62,7 @@ to `false` or by declaring the argument with a `java.util.Optional` wrapper. Type conversion is applied automatically if the target method parameter type is not -`String`. See <>. +`String`. See xref:web/webflux/controller/ann-methods/typeconversion.adoc[Type Conversion]. When a `@RequestParam` annotation is declared on a `Map` or `MultiValueMap` argument, the map is populated with all query parameters. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc index 212343784d11..ce69b696b018 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc @@ -1,10 +1,10 @@ [[webflux-ann-responsebody]] = `@ResponseBody` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[See equivalent in the Servlet stack]# You can use the `@ResponseBody` annotation on a method to have the return serialized -to the response body through an <>. The following +to the response body through an xref:web/webflux/reactive-spring.adoc#webflux-codecs[HttpMessageWriter]. The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -32,13 +32,13 @@ than a meta-annotation marked with `@Controller` and `@ResponseBody`. `@ResponseBody` supports reactive types, which means you can return Reactor or RxJava types and have the asynchronous values they produce rendered to the response. -For additional details, see <> and -<>. +For additional details, see xref:web/webflux/reactive-spring.adoc#webflux-codecs-streaming[Streaming] and +xref:web/webflux/reactive-spring.adoc#webflux-codecs-jackson[JSON rendering]. You can combine `@ResponseBody` methods with JSON serialization views. -See <> for details. +See xref:web/webflux/controller/ann-methods/jackson.adoc[Jackson JSON] for details. -You can use the <> option of the <> to +You can use the xref:web/webflux/config.adoc#webflux-config-message-codecs[HTTP message codecs] option of the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] to configure or customize message writing. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc index 317a49d5fd45..06c68e11125d 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc @@ -1,9 +1,9 @@ [[webflux-ann-responseentity]] = `ResponseEntity` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/responseentity.adoc[See equivalent in the Servlet stack]# -`ResponseEntity` is like <> but with status and headers. For example: +`ResponseEntity` is like xref:web/webflux/controller/ann-methods/responsebody.adoc[`@ResponseBody`] but with status and headers. For example: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -26,7 +26,7 @@ } ---- -WebFlux supports using a single value <> to +WebFlux supports using a single value xref:web-reactive.adoc#webflux-reactive-libraries[reactive type] to produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive types for the body. This allows a variety of async responses with `ResponseEntity` as follows: diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc index 499ac55f501e..7752ee485377 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc @@ -1,10 +1,10 @@ [[webflux-ann-return-types]] = Return Values -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/return-types.adoc[See equivalent in the Servlet stack]# The following table shows the supported controller method return values. Note that reactive -types from libraries such as Reactor, RxJava, <> are +types from libraries such as Reactor, RxJava, xref:web-reactive.adoc#webflux-reactive-libraries[or other] are generally supported for all return values. [cols="1,2", options="header"] @@ -13,35 +13,35 @@ generally supported for all return values. | `@ResponseBody` | The return value is encoded through `HttpMessageWriter` instances and written to the response. - See <>. + See xref:web/webflux/controller/ann-methods/responsebody.adoc[`@ResponseBody`]. | `HttpEntity`, `ResponseEntity` | The return value specifies the full response, including HTTP headers, and the body is encoded through `HttpMessageWriter` instances and written to the response. - See <>. + See xref:web/webflux/controller/ann-methods/responseentity.adoc[`ResponseEntity`]. | `HttpHeaders` | For returning a response with headers and no body. | `ErrorResponse` | To render an RFC 7807 error response with details in the body, - see <> + see xref:web/webflux/ann-rest-exceptions.adoc[Error Responses] | `ProblemDetail` | To render an RFC 7807 error response with details in the body, - see <> + see xref:web/webflux/ann-rest-exceptions.adoc[Error Responses] | `String` | A view name to be resolved with `ViewResolver` instances and used together with the implicit model -- determined through command objects and `@ModelAttribute` methods. The handler method can also programmatically enrich the model by declaring a `Model` argument - (described <>). + (described xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution-handling[earlier]). | `View` | A `View` instance to use for rendering together with the implicit model -- determined through command objects and `@ModelAttribute` methods. The handler method can also programmatically enrich the model by declaring a `Model` argument - (described <>). + (described xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution-handling[earlier]). | `java.util.Map`, `org.springframework.ui.Model` | Attributes to be added to the implicit model, with the view name implicitly determined @@ -62,7 +62,7 @@ generally supported for all return values. value) is considered to have fully handled the response if it also has a `ServerHttpResponse`, a `ServerWebExchange` argument, or an `@ResponseStatus` annotation. The same is also true if the controller has made a positive ETag or `lastModified` timestamp check. - See <> for details. + See xref:web/webflux/caching.adoc#webflux-caching-etag-lastmodified[Controllers] for details. If none of the above is true, a `void` return type can also indicate "`no response body`" for REST controllers or default view name selection for HTML controllers. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc index e570ac477381..a205bd26c44b 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc @@ -1,7 +1,7 @@ [[webflux-ann-sessionattribute]] = `@SessionAttribute` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc[See equivalent in the Servlet stack]# If you need access to pre-existing session attributes that are managed globally (that is, outside the controller -- for example, by a filter) and may or may not be present, @@ -32,6 +32,6 @@ For use cases that require adding or removing session attributes, consider injec For temporary storage of model attributes in the session as part of a controller workflow, consider using `SessionAttributes`, as described in -<>. +xref:web/webflux/controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc index 8cdb3758306e..72fd242c82d3 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc @@ -1,7 +1,7 @@ [[webflux-ann-sessionattributes]] = `@SessionAttributes` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc[See equivalent in the Servlet stack]# `@SessionAttributes` is used to store model attributes in the `WebSession` between requests. It is a type-level annotation that declares session attributes used by a diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc index 7d83d27e28b3..c1b58f2bdd59 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc @@ -1,7 +1,7 @@ [[webflux-ann-typeconversion]] = Type Conversion -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[See equivalent in the Servlet stack]# Some annotated controller method arguments that represent String-based request input (for example, `@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) @@ -9,8 +9,8 @@ can require type conversion if the argument is declared as something other than For such cases, type conversion is automatically applied based on the configured converters. By default, simple types (such as `int`, `long`, `Date`, and others) are supported. Type conversion -can be customized through a `WebDataBinder` (see <>) or by registering -`Formatters` with the `FormattingConversionService` (see <>). +can be customized through a `WebDataBinder` (see xref:web/webflux/controller/ann-initbinder.adoc[`DataBinder`]) or by registering +`Formatters` with the `FormattingConversionService` (see xref:core/validation/format.adoc[Spring Field Formatting]). A practical issue in type conversion is the treatment of an empty String source value. Such a value is treated as missing if it becomes `null` as a result of type conversion. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc index a04b99f8c19c..654d0fc9a940 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc @@ -1,11 +1,11 @@ [[webflux-ann-modelattrib-methods]] = `Model` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-modelattrib-methods.adoc[See equivalent in the Servlet stack]# You can use the `@ModelAttribute` annotation: -* On a <> in `@RequestMapping` methods +* On a xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[method argument] in `@RequestMapping` methods to create or access an Object from the model and to bind it to the request through a `WebDataBinder`. * As a method-level annotation in `@Controller` or `@ControllerAdvice` classes, helping @@ -16,7 +16,7 @@ This section discusses `@ModelAttribute` methods, or the second item from the pr A controller can have any number of `@ModelAttribute` methods. All such methods are invoked before `@RequestMapping` methods in the same controller. A `@ModelAttribute` method can also be shared across controllers through `@ControllerAdvice`. See the section on -<> for more details. +xref:web/webflux/controller/ann-advice.adoc[Controller Advice] for more details. `@ModelAttribute` methods have flexible method signatures. They support many of the same arguments as `@RequestMapping` methods (except for `@ModelAttribute` itself and anything diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc index 743d015c5ec8..053b79565919 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc @@ -1,7 +1,7 @@ [[webflux-ann-requestmapping]] = Request Mapping -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc[See equivalent in the Servlet stack]# The `@RequestMapping` annotation is used to map requests to controllers methods. It has various attributes to match by URL, HTTP method, request parameters, headers, and media @@ -16,7 +16,7 @@ There are also HTTP method specific shortcut variants of `@RequestMapping`: * `@DeleteMapping` * `@PatchMapping` -The preceding annotations are <> that are provided +The preceding annotations are xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-composed[Custom Annotations] that are provided because, arguably, most controller methods should be mapped to a specific HTTP method versus using `@RequestMapping`, which, by default, matches to all HTTP methods. At the same time, a `@RequestMapping` is still needed at the class level to express shared mappings. @@ -65,7 +65,7 @@ The following example uses type and method level mappings: [[webflux-ann-requestmapping-uri-templates]] == URI Patterns -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-uri-templates[See equivalent in the Servlet stack]# You can map requests by using glob patterns and wildcards: @@ -164,7 +164,7 @@ You can declare URI variables at the class and method levels, as the following e URI variables are automatically converted to the appropriate type or a `TypeMismatchException` is raised. Simple types (`int`, `long`, `Date`, and so on) are supported by default and you can register support for any other data type. -See <> and <>. +See xref:web/webflux/controller/ann-methods/typeconversion.adoc[Type Conversion] and xref:web/webflux/controller/ann-initbinder.adoc[`DataBinder`]. URI variables can be named explicitly (for example, `@PathVariable("customId")`), but you can leave that detail out if the names are the same and you compile your code with the `-parameters` @@ -214,7 +214,7 @@ explicit, and less vulnerable to URL path based exploits. [[webflux-ann-requestmapping-pattern-comparison]] == Pattern Comparison -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-pattern-comparison[See equivalent in the Servlet stack]# When multiple patterns match a URL, they must be compared to find the best match. This is done with `PathPattern.SPECIFICITY_COMPARATOR`, which looks for patterns that are more specific. @@ -229,7 +229,7 @@ sorted last instead. If two patterns are both catch-all, the longer is chosen. [[webflux-ann-requestmapping-consumes]] == Consumable Media Types -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-consumes[See equivalent in the Servlet stack]# You can narrow the request mapping based on the `Content-Type` of the request, as the following example shows: @@ -264,7 +264,7 @@ TIP: `MediaType` provides constants for commonly used media types -- for example [[webflux-ann-requestmapping-produces]] == Producible Media Types -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-produces[See equivalent in the Servlet stack]# You can narrow the request mapping based on the `Accept` request header and the list of content types that a controller method produces, as the following example shows: @@ -301,7 +301,7 @@ TIP: `MediaType` provides constants for commonly used media types -- e.g. [[webflux-ann-requestmapping-params-and-headers]] == Parameters and Headers -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-params-and-headers[See equivalent in the Servlet stack]# You can narrow request mappings based on query parameter conditions. You can test for the presence of a query parameter (`myParam`), for its absence (`!myParam`), or for a @@ -353,7 +353,7 @@ You can also use the same with request header conditions, as the following examp [[webflux-ann-requestmapping-head-options]] == HTTP HEAD, OPTIONS -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-head-options[See equivalent in the Servlet stack]# `@GetMapping` and `@RequestMapping(method=HttpMethod.GET)` support HTTP HEAD transparently for request mapping purposes. Controller methods need not change. @@ -374,9 +374,9 @@ is not necessary in the common case. [[webflux-ann-requestmapping-composed]] == Custom Annotations -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-composed[See equivalent in the Servlet stack]# -Spring WebFlux supports the use of <> +Spring WebFlux supports the use of xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[composed annotations] for request mapping. Those are annotations that are themselves meta-annotated with `@RequestMapping` and composed to redeclare a subset (or all) of the `@RequestMapping` attributes with a narrower, more specific purpose. @@ -395,7 +395,7 @@ you can check the custom attribute and return your own `RequestCondition`. [[webflux-ann-requestmapping-registration]] == Explicit Registrations -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-registration[See equivalent in the Servlet stack]# You can programmatically register Handler methods, which can be used for dynamic registrations or for advanced cases, such as different instances of the same handler diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc index 555a8a5876ae..c44f42c332dd 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc @@ -1,7 +1,7 @@ [[webflux-ann-controller]] = `@Controller` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann.adoc[See equivalent in the Servlet stack]# You can define controller beans by using a standard Spring bean definition. The `@Controller` stereotype allows for auto-detection and is aligned with Spring general support @@ -36,7 +36,7 @@ your Java configuration, as the following example shows: ---- <1> Scan the `org.example.web` package. -`@RestController` is a <> that is +`@RestController` is a xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[composed annotation] that is itself meta-annotated with `@Controller` and `@ResponseBody`, indicating a controller whose every method inherits the type-level `@ResponseBody` annotation and, therefore, writes directly to the response body versus view resolution and rendering with an HTML template. @@ -45,7 +45,7 @@ directly to the response body versus view resolution and rendering with an HTML [[webflux-ann-requestmapping-proxying]] == AOP Proxies -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann.adoc#mvc-ann-requestmapping-proxying[See equivalent in the Servlet stack]# In some cases, you may need to decorate a controller with an AOP proxy at runtime. One example is if you choose to have `@Transactional` annotations directly on the diff --git a/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc b/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc index 8afcc14d7e0f..46250c6f6895 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc @@ -1,7 +1,7 @@ [[webflux-dispatcher-handler]] = `DispatcherHandler` -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet.adoc[See equivalent in the Servlet stack]# Spring WebFlux, similarly to Spring MVC, is designed around the front controller pattern, where a central `WebHandler`, the `DispatcherHandler`, provides a shared algorithm for @@ -13,13 +13,13 @@ It is also designed to be a Spring bean itself and implements `ApplicationContex for access to the context in which it runs. If `DispatcherHandler` is declared with a bean name of `webHandler`, it is, in turn, discovered by {api-spring-framework}/web/server/adapter/WebHttpHandlerBuilder.html[`WebHttpHandlerBuilder`], -which puts together a request-processing chain, as described in <>. +which puts together a request-processing chain, as described in xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API]. Spring configuration in a WebFlux application typically contains: * `DispatcherHandler` with the bean name `webHandler` * `WebFilter` and `WebExceptionHandler` beans -* <> +* xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[`DispatcherHandler` special beans] * Others The configuration is given to `WebHttpHandlerBuilder` to build the processing chain, @@ -38,13 +38,13 @@ as the following example shows: val handler = WebHttpHandlerBuilder.applicationContext(context).build() ---- -The resulting `HttpHandler` is ready for use with a <>. +The resulting `HttpHandler` is ready for use with a xref:web/webflux/reactive-spring.adoc#webflux-httphandler[server adapter]. [[webflux-special-bean-types]] == Special Bean Types -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/special-bean-types.adoc[See equivalent in the Servlet stack]# The `DispatcherHandler` delegates to special beans to process requests and render the appropriate responses. By "`special beans,`" we mean Spring-managed `Object` instances that @@ -53,7 +53,7 @@ you can customize their properties, extend them, or replace them. The following table lists the special beans detected by the `DispatcherHandler`. Note that there are also some other beans detected at a lower level (see -<> in the Web Handler API). +xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[Special bean types] in the Web Handler API). [[webflux-special-beans-table]] [cols="1,2", options="header"] @@ -78,7 +78,7 @@ there are also some other beans detected at a lower level (see | `HandlerResultHandler` | Process the result from the handler invocation and finalize the response. - See <>. + See xref:web/webflux/dispatcher-handler.adoc#webflux-resulthandling[Result Handling]. |=== @@ -86,12 +86,12 @@ there are also some other beans detected at a lower level (see [[webflux-framework-config]] == WebFlux Config -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/config.adoc[See equivalent in the Servlet stack]# Applications can declare the infrastructure beans (listed under -<> and -<>) that are required to process requests. -However, in most cases, the <> is the best starting point. It declares the +xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[Web Handler API] and +xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[`DispatcherHandler`]) that are required to process requests. +However, in most cases, the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] is the best starting point. It declares the required beans and provides a higher-level configuration callback API to customize it. NOTE: Spring Boot relies on the WebFlux config to configure Spring WebFlux and also provides @@ -101,7 +101,7 @@ many extra convenient options. [[webflux-dispatcher-handler-sequence]] == Processing -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/sequence.adoc[See equivalent in the Servlet stack]# `DispatcherHandler` processes requests as follows: @@ -119,7 +119,7 @@ processing by writing to the response directly or by using a view to render. The return value from the invocation of a handler, through a `HandlerAdapter`, is wrapped as a `HandlerResult`, along with some additional context, and passed to the first `HandlerResultHandler` that claims support for it. The following table shows the available -`HandlerResultHandler` implementations, all of which are declared in the <>: +`HandlerResultHandler` implementations, all of which are declared in the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config]: [cols="1,2,1", options="header"] |=== @@ -143,7 +143,7 @@ as a `HandlerResult`, along with some additional context, and passed to the firs {api-spring-framework}/web/reactive/result/view/Rendering.html[Rendering], or any other `Object` is treated as a model attribute. - See also <>. + See also xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution[View Resolution]. | `Integer.MAX_VALUE` |=== @@ -152,7 +152,7 @@ as a `HandlerResult`, along with some additional context, and passed to the firs [[webflux-dispatcher-exceptions]] == Exceptions -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[See equivalent in the Servlet stack]# `HandlerAdapter` implementations can handle internally exceptions from invoking a request handler, such as a controller method. However, an exception may be deferred if the request @@ -166,25 +166,25 @@ A `HandlerAdapter` may also choose to implement `DispatchExceptionHandler`. In t `DispatcherHandler` will apply it to exceptions that arise before a handler is mapped, e.g. during handler mapping, or earlier, e.g. in a `WebFilter`. -See also <> in the "`Annotated Controller`" section or -<> in the WebHandler API section. +See also xref:web/webflux/controller/ann-exceptions.adoc[Exceptions] in the "`Annotated Controller`" section or +xref:web/webflux/reactive-spring.adoc#webflux-exception-handler[Exceptions] in the WebHandler API section. [[webflux-viewresolution]] == View Resolution -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/viewresolver.adoc[See equivalent in the Servlet stack]# View resolution enables rendering to a browser with an HTML template and a model without tying you to a specific view technology. In Spring WebFlux, view resolution is -supported through a dedicated <> that uses +supported through a dedicated xref:web/webflux/dispatcher-handler.adoc#webflux-resulthandling[HandlerResultHandler] that uses `ViewResolver` instances to map a String (representing a logical view name) to a `View` instance. The `View` is then used to render the response. [[webflux-viewresolution-handling]] === Handling -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/viewresolver.adoc#mvc-viewresolver-handling[See equivalent in the Servlet stack]# The `HandlerResult` passed into `ViewResolutionResultHandler` contains the return value from the handler and the model that contains attributes added during request @@ -212,15 +212,15 @@ value or no value (if empty), while multi-value reactive types (for example, `Fl collected and resolved to `List`. To configure view resolution is as simple as adding a `ViewResolutionResultHandler` bean -to your Spring configuration. <> provides a +to your Spring configuration. xref:web/webflux/config.adoc#webflux-config-view-resolvers[WebFlux Config] provides a dedicated configuration API for view resolution. -See <> for more on the view technologies integrated with Spring WebFlux. +See xref:web/webflux-view.adoc[View Technologies] for more on the view technologies integrated with Spring WebFlux. [[webflux-redirecting-redirect-prefix]] === Redirecting -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/viewresolver.adoc#mvc-redirecting-redirect-prefix[See equivalent in the Servlet stack]# The special `redirect:` prefix in a view name lets you perform a redirect. The `UrlBasedViewResolver` (and sub-classes) recognize this as an instruction that a @@ -235,7 +235,7 @@ operate in terms of logical view names. A view name such as [[webflux-multiple-representations]] === Content Negotiation -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/viewresolver.adoc#mvc-multiple-representations[See equivalent in the Servlet stack]# `ViewResolutionResultHandler` supports content negotiation. It compares the request media types with the media types supported by each selected `View`. The first `View` @@ -243,8 +243,8 @@ that supports the requested media type(s) is used. In order to support media types such as JSON and XML, Spring WebFlux provides `HttpMessageWriterView`, which is a special `View` that renders through an -<>. Typically, you would configure these as default -views through the <>. Default views are +xref:web/webflux/reactive-spring.adoc#webflux-codecs[HttpMessageWriter]. Typically, you would configure these as default +views through the xref:web/webflux/config.adoc#webflux-config-view-resolvers[WebFlux Configuration]. Default views are always selected and used if they match the requested media type. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc b/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc index ac8879e0d262..0ae23f06610a 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc @@ -1,7 +1,7 @@ [[webflux-http2]] = HTTP/2 -[.small]#<># +[.small]#xref:web/webmvc/mvc-http2.adoc[See equivalent in the Servlet stack]# HTTP/2 is supported with Reactor Netty, Tomcat, Jetty, and Undertow. However, there are considerations related to server configuration. For more details, see the diff --git a/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc b/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc index 70e6be40dbd3..93c9fdcabdb1 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc @@ -79,10 +79,10 @@ as input, adapts it to a Reactor type internally, uses that, and returns either `Flux` or a `Mono` as output. So, you can pass any `Publisher` as input and you can apply operations on the output, but you need to adapt the output for use with another reactive library. Whenever feasible (for example, annotated controllers), WebFlux adapts transparently to the use -of RxJava or another reactive library. See <> for more details. +of RxJava or another reactive library. See xref:web-reactive.adoc#webflux-reactive-libraries[Reactive Libraries] for more details. NOTE: In addition to Reactive APIs, WebFlux can also be used with -<> APIs in Kotlin which provides a more imperative style of programming. +xref:languages/kotlin/coroutines.adoc[Coroutines] APIs in Kotlin which provides a more imperative style of programming. The following Kotlin code samples will be provided with Coroutines APIs. @@ -91,13 +91,13 @@ The following Kotlin code samples will be provided with Coroutines APIs. == Programming Models The `spring-web` module contains the reactive foundation that underlies Spring WebFlux, -including HTTP abstractions, Reactive Streams <> for supported -servers, <>, and a core <> comparable to +including HTTP abstractions, Reactive Streams xref:web/webflux/reactive-spring.adoc#webflux-httphandler[adapters] for supported +servers, xref:web/webflux/reactive-spring.adoc#webflux-codecs[codecs], and a core xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API] comparable to the Servlet API but with non-blocking contracts. On that foundation, Spring WebFlux provides a choice of two programming models: -* <>: Consistent with Spring MVC and based on the same annotations +* xref:web/webflux/controller.adoc[Annotated Controllers]: Consistent with Spring MVC and based on the same annotations from the `spring-web` module. Both Spring MVC and WebFlux controllers support reactive (Reactor and RxJava) return types, and, as a result, it is not easy to tell them apart. One notable difference is that WebFlux also supports reactive `@RequestBody` arguments. @@ -151,7 +151,7 @@ RxJava to perform blocking calls on a separate thread but you would not be makin most of a non-blocking web stack. * If you have a Spring MVC application with calls to remote services, try the reactive `WebClient`. -You can return reactive types (Reactor, RxJava, <>) +You can return reactive types (Reactor, RxJava, xref:web-reactive.adoc#webflux-reactive-libraries[or other]) directly from Spring MVC controller methods. The greater the latency per call or the interdependency among calls, the more dramatic the benefits. Spring MVC controllers can call other reactive components too. @@ -170,12 +170,12 @@ unsure what benefits to look for, start by learning about how non-blocking I/O w Spring WebFlux is supported on Tomcat, Jetty, Servlet containers, as well as on non-Servlet runtimes such as Netty and Undertow. All servers are adapted to a low-level, -<> so that higher-level -<> can be supported across servers. +xref:web/webflux/reactive-spring.adoc#webflux-httphandler[common API] so that higher-level +xref:web/webflux/new-framework.adoc#webflux-programming-models[programming models] can be supported across servers. Spring WebFlux does not have built-in support to start or stop a server. However, it is -easy to <> an application from Spring configuration and -<> and <> with a few +easy to xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[assemble] an application from Spring configuration and +xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux infrastructure] and xref:web/webflux/reactive-spring.adoc#webflux-httphandler[run it] with a few lines of code. Spring Boot has a WebFlux starter that automates these steps. By default, the starter uses @@ -275,10 +275,10 @@ of their own. === Configuring The Spring Framework does not provide support for starting and stopping -<>. To configure the threading model for a server, +xref:web/webflux/new-framework.adoc#webflux-server-choice[servers]. To configure the threading model for a server, you need to use server-specific configuration APIs, or, if you use Spring Boot, check the Spring Boot configuration options for each server. You can -<> the `WebClient` directly. +xref:web/webflux-webclient/client-builder.adoc[configure] the `WebClient` directly. For all other libraries, see their respective documentation. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc index cfef50ee7424..052378f29a99 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc @@ -5,10 +5,10 @@ The `spring-web` module contains the following foundational support for reactive applications: * For server request processing there are two levels of support. -** <>: Basic contract for HTTP request handling with +** xref:web/webflux/reactive-spring.adoc#webflux-httphandler[HttpHandler]: Basic contract for HTTP request handling with non-blocking I/O and Reactive Streams back pressure, along with adapters for Reactor Netty, Undertow, Tomcat, Jetty, and any Servlet container. -** <>: Slightly higher level, general-purpose web API for +** xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API]: Slightly higher level, general-purpose web API for request handling, on top of which concrete programming models such as annotated controllers and functional endpoints are built. * For the client side, there is a basic `ClientHttpConnector` contract to perform HTTP @@ -16,9 +16,9 @@ requests with non-blocking I/O and Reactive Streams back pressure, along with ad https://github.com/reactor/reactor-netty[Reactor Netty], reactive https://github.com/jetty-project/jetty-reactive-httpclient[Jetty HttpClient] and https://hc.apache.org/[Apache HttpComponents]. -The higher level <> used in applications +The higher level xref:web/webflux-webclient.adoc[WebClient] used in applications builds on this basic contract. -* For client and server, <> for serialization and +* For client and server, xref:web/webflux/reactive-spring.adoc#webflux-codecs[codecs] for serialization and deserialization of HTTP request and response content. @@ -198,14 +198,14 @@ that as a `Servlet`. [[webflux-web-handler-api]] == `WebHandler` API -The `org.springframework.web.server` package builds on the <> contract +The `org.springframework.web.server` package builds on the xref:web/webflux/reactive-spring.adoc#webflux-httphandler[`HttpHandler`] contract to provide a general-purpose web API for processing requests through a chain of multiple {api-spring-framework}/web/server/WebExceptionHandler.html[`WebExceptionHandler`], multiple {api-spring-framework}/web/server/WebFilter.html[`WebFilter`], and a single {api-spring-framework}/web/server/WebHandler.html[`WebHandler`] component. The chain can be put together with `WebHttpHandlerBuilder` by simply pointing to a Spring `ApplicationContext` where components are -<>, and/or by registering components +xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[auto-detected], and/or by registering components with the builder. While `HttpHandler` has a simple goal to abstract the use of different HTTP servers, the @@ -233,13 +233,13 @@ Spring ApplicationContext, or that can be registered directly with it: | `WebExceptionHandler` | 0..N | Provide handling for exceptions from the chain of `WebFilter` instances and the target - `WebHandler`. For more details, see <>. + `WebHandler`. For more details, see xref:web/webflux/reactive-spring.adoc#webflux-exception-handler[Exceptions]. | | `WebFilter` | 0..N | Apply interception style logic to before and after the rest of the filter chain and - the target `WebHandler`. For more details, see <>. + the target `WebHandler`. For more details, see xref:web/webflux/reactive-spring.adoc#webflux-filters[Filters]. | `webHandler` | `WebHandler` @@ -291,12 +291,12 @@ Spring ApplicationContext, or that can be registered directly with it: The `DefaultServerWebExchange` uses the configured `HttpMessageReader` to parse form data (`application/x-www-form-urlencoded`) into a `MultiValueMap`. By default, `FormHttpMessageReader` is configured for use by the `ServerCodecConfigurer` bean -(see the <>). +(see the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[Web Handler API]). [[webflux-multipart]] === Multipart Data -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/multipart.adoc[See equivalent in the Servlet stack]# `ServerWebExchange` exposes the following method for accessing multipart data: @@ -319,7 +319,7 @@ dependencies. Alternatively, the `SynchronossPartHttpMessageReader` can be used, which is based on the https://github.com/synchronoss/nio-multipart[Synchronoss NIO Multipart] library. Both are configured through the `ServerCodecConfigurer` bean -(see the <>). +(see the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[Web Handler API]). To parse multipart data in streaming fashion, you can use the `Flux` returned from the `PartEventHttpMessageReader` instead of using `@RequestPart`, as that implies `Map`-like access @@ -330,7 +330,7 @@ collecting to a `MultiValueMap`. [[webflux-forwarded-headers]] === Forwarded Headers -[.small]#<># +[.small]#xref:web/webmvc/filters.adoc#filters-forwarded-headers[See equivalent in the Servlet stack]# As a request goes through proxies (such as load balancers), the host, port, and scheme may change. That makes it a challenge, from a client perspective, to create links that point to the correct @@ -344,7 +344,7 @@ non-standard headers, too, including `X-Forwarded-Host`, `X-Forwarded-Port`, `ForwardedHeaderTransformer` is a component that modifies the host, port, and scheme of the request, based on forwarded headers, and then removes those headers. If you declare it as a bean with the name `forwardedHeaderTransformer`, it will be -<> and used. +xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[detected] and used. There are security considerations for forwarded headers, since an application cannot know if the headers were added by a proxy, as intended, or by a malicious client. This is why @@ -361,33 +361,33 @@ filters, and `ForwardedHeaderTransformer` is used instead. [[webflux-filters]] == Filters -[.small]#<># +[.small]#xref:web/webmvc/filters.adoc[See equivalent in the Servlet stack]# -In the <>, you can use a `WebFilter` to apply interception-style +In the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API], you can use a `WebFilter` to apply interception-style logic before and after the rest of the processing chain of filters and the target -`WebHandler`. When using the <>, registering a `WebFilter` is as simple +`WebHandler`. When using the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config], registering a `WebFilter` is as simple as declaring it as a Spring bean and (optionally) expressing precedence by using `@Order` on the bean declaration or by implementing `Ordered`. [[webflux-filters-cors]] === CORS -[.small]#<># +[.small]#xref:web/webmvc/filters.adoc#filters-cors[See equivalent in the Servlet stack]# Spring WebFlux provides fine-grained support for CORS configuration through annotations on controllers. However, when you use it with Spring Security, we advise relying on the built-in `CorsFilter`, which must be ordered ahead of Spring Security's chain of filters. -See the section on <> and the <> for more details. +See the section on xref:web/webflux-cors.adoc[CORS] and the xref:web/webflux-cors.adoc#webflux-cors-webfilter[CORS `WebFilter`] for more details. [[webflux-exception-handler]] == Exceptions -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc#mvc-ann-customer-servlet-container-error-page[See equivalent in the Servlet stack]# -In the <>, you can use a `WebExceptionHandler` to handle +In the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API], you can use a `WebExceptionHandler` to handle exceptions from the chain of `WebFilter` instances and the target `WebHandler`. When using the -<>, registering a `WebExceptionHandler` is as simple as declaring it as a +xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config], registering a `WebExceptionHandler` is as simple as declaring it as a Spring bean and (optionally) expressing precedence by using `@Order` on the bean declaration or by implementing `Ordered`. @@ -406,7 +406,7 @@ The following table describes the available `WebExceptionHandler` implementation | Extension of `ResponseStatusExceptionHandler` that can also determine the HTTP status code of a `@ResponseStatus` annotation on any exception. - This handler is declared in the <>. + This handler is declared in the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config]. |=== @@ -414,7 +414,7 @@ The following table describes the available `WebExceptionHandler` implementation [[webflux-codecs]] == Codecs -[.small]#<># +[.small]#xref:integration/rest-clients.adoc#rest-message-conversion[See equivalent in the Servlet stack]# The `spring-web` and `spring-core` modules provide support for serializing and deserializing byte content to and from higher level objects through non-blocking I/O with @@ -430,7 +430,7 @@ to encode and decode HTTP message content. application, while a `Decoder` can be wrapped with `DecoderHttpMessageReader`. * {api-spring-framework}/core/io/buffer/DataBuffer.html[`DataBuffer`] abstracts different byte buffer representations (e.g. Netty `ByteBuf`, `java.nio.ByteBuffer`, etc.) and is -what all codecs work on. See <> in the +what all codecs work on. See xref:core/databuffer-codec.adoc[Data Buffers and Codecs] in the "Spring Core" section for more on this topic. The `spring-core` module provides `byte[]`, `ByteBuffer`, `DataBuffer`, `Resource`, and @@ -441,7 +441,7 @@ server-sent events, and others. `ClientCodecConfigurer` and `ServerCodecConfigurer` are typically used to configure and customize the codecs to use in an application. See the section on configuring -<>. +xref:web/webflux/config.adoc#webflux-config-message-codecs[HTTP message codecs]. [[webflux-codecs-jackson]] === Jackson JSON @@ -493,7 +493,7 @@ encode a `Mono>`. On the server side where form content often needs to be accessed from multiple places, `ServerWebExchange` provides a dedicated `getFormData()` method that parses the content through `FormHttpMessageReader` and then caches the result for repeated access. -See <> in the <> section. +See xref:web/webflux/reactive-spring.adoc#webflux-form-data[Form Data] in the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API] section. Once `getFormData()` is used, the original raw content can no longer be read from the request body. For this reason, applications are expected to go through `ServerWebExchange` @@ -515,7 +515,7 @@ For more information about the `DefaultPartHttpMessageReader`, refer to the On the server side where multipart form content may need to be accessed from multiple places, `ServerWebExchange` provides a dedicated `getMultipartData()` method that parses the content through `MultipartHttpMessageReader` and then caches the result for repeated access. -See <> in the <> section. +See xref:web/webflux/reactive-spring.adoc#webflux-multipart[Multipart Data] in the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API] section. Once `getMultipartData()` is used, the original raw content can no longer be read from the request body. For this reason applications have to consistently use `getMultipartData()` @@ -538,11 +538,11 @@ with one object in the stream. To configure buffer sizes, you can check if a given `Decoder` or `HttpMessageReader` exposes a `maxInMemorySize` property and if so the Javadoc will have details about default values. On the server side, `ServerCodecConfigurer` provides a single place from where to -set all codecs, see <>. On the client side, the limit for +set all codecs, see xref:web/webflux/config.adoc#webflux-config-message-codecs[HTTP message codecs]. On the client side, the limit for all codecs can be changed in -<>. +xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-maxinmemorysize[WebClient.Builder]. -For <> the `maxInMemorySize` property limits +For xref:web/webflux/reactive-spring.adoc#webflux-codecs-multipart[Multipart parsing] the `maxInMemorySize` property limits the size of non-file parts. For file parts, it determines the threshold at which the part is written to disk. For file parts written to disk, there is an additional `maxDiskUsagePerPart` property to limit the amount of disk space per part. There is also @@ -554,7 +554,7 @@ To configure all three in WebFlux, you'll need to supply a pre-configured instan [[webflux-codecs-streaming]] === Streaming -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-http-streaming[See equivalent in the Servlet stack]# When streaming to the HTTP response (for example, `text/event-stream`, `application/x-ndjson`), it is important to send data periodically, in order to @@ -568,21 +568,21 @@ a heartbeat. `DataBuffer` is the representation for a byte buffer in WebFlux. The Spring Core part of this reference has more on that in the section on -<>. The key point to understand is that on some +xref:core/databuffer-codec.adoc[Data Buffers and Codecs]. The key point to understand is that on some servers like Netty, byte buffers are pooled and reference counted, and must be released when consumed to avoid memory leaks. WebFlux applications generally do not need to be concerned with such issues, unless they consume or produce data buffers directly, as opposed to relying on codecs to convert to and from higher level objects, or unless they choose to create custom codecs. For such -cases please review the information in <>, -especially the section on <>. +cases please review the information in xref:core/databuffer-codec.adoc[Data Buffers and Codecs], +especially the section on xref:core/databuffer-codec.adoc#databuffers-using[Using DataBuffer]. [[webflux-logging]] == Logging -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/logging.adoc[See equivalent in the Servlet stack]# `DEBUG` level logging in Spring WebFlux is designed to be compact, minimal, and human-friendly. It focuses on high value bits of information that are useful over and @@ -614,7 +614,7 @@ while a fully formatted prefix based on that ID is available from [[webflux-logging-sensitive-data]] === Sensitive Data -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/logging.adoc#mvc-logging-sensitive-data[See equivalent in the Servlet stack]# `DEBUG` and `TRACE` logging can log sensitive information. This is why form parameters and headers are masked by default and you must explicitly enable their logging in full. @@ -688,8 +688,8 @@ or specific behaviors that are not supported by the default codecs. Some configuration options expressed by developers are enforced on default codecs. Custom codecs might want to get a chance to align with those preferences, -like <> -or <>. +like xref:web/webflux/reactive-spring.adoc#webflux-codecs-limits[enforcing buffering limits] +or xref:web/webflux/reactive-spring.adoc#webflux-logging-sensitive-data[logging sensitive data]. The following example shows how to do so for client-side requests: diff --git a/framework-docs/modules/ROOT/pages/web/webflux/security.adoc b/framework-docs/modules/ROOT/pages/web/webflux/security.adoc index c198e3540c07..9f0e759098ac 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/security.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/security.adoc @@ -1,7 +1,7 @@ [[webflux-web-security]] = Web Security -[.small]#<># +[.small]#xref:web/webmvc/mvc-security.adoc[See equivalent in the Servlet stack]# The https://spring.io/projects/spring-security[Spring Security] project provides support for protecting web applications from malicious exploits. See the Spring Security diff --git a/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc index 92f579e974f3..4df300151050 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc @@ -1,7 +1,7 @@ [[webflux-uri-building]] = URI Links -[.small]#<># +[.small]#xref:web/webmvc/mvc-uri-building.adoc[See equivalent in the Servlet stack]# This section describes various options available in the Spring Framework to prepare URIs. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc index 0936a06ce0b6..6ea33120fd8c 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc @@ -15,10 +15,10 @@ libraries. NOTE: As of 5.0 the `RestTemplate` is in maintenance mode, with only requests for minor changes and bugs to be accepted. Please, consider using the -<> which offers a more modern API and +xref:web/webflux-webclient.adoc[WebClient] which offers a more modern API and supports sync, async, and streaming scenarios. -See <> for details. +See xref:integration/rest-clients.adoc[REST Endpoints] for details. @@ -39,7 +39,7 @@ In contrast to `RestTemplate`, `WebClient` supports the following: * Synchronous and asynchronous interactions. * Streaming up to or streaming down from a server. -See <> for more details. +See xref:web/webflux-webclient.adoc[WebClient] for more details. @@ -52,4 +52,4 @@ exchange methods. You can then generate a proxy that implements this interface a performs the exchanges. This helps to simplify HTTP remote access and provides additional flexibility for to choose an API style such as synchronous or reactive. -See <> for details. +See xref:integration/rest-clients.adoc#rest-http-interface[REST Endpoints] for details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc index d5a3334a965a..c41e79bfcb7a 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc @@ -1,6 +1,6 @@ [[mvc-cors]] = CORS -[.small]#<># +[.small]#xref:web/webflux-cors.adoc[See equivalent in the Reactive stack]# Spring MVC lets you handle CORS (Cross-Origin Resource Sharing). This section describes how to do so. @@ -10,7 +10,7 @@ describes how to do so. [[mvc-cors-intro]] == Introduction -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-intro[See equivalent in the Reactive stack]# For security reasons, browsers prohibit AJAX calls to resources outside the current origin. For example, you could have your bank account in one tab and evil.com in another. Scripts @@ -27,7 +27,7 @@ powerful workarounds based on IFRAME or JSONP. [[mvc-cors-processing]] == Processing -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-processing[See equivalent in the Reactive stack]# The CORS specification distinguishes between preflight, simple, and actual requests. To learn how CORS works, you can read @@ -77,7 +77,7 @@ To learn more from the source or make advanced customizations, check the code be [[mvc-cors-controller]] == `@CrossOrigin` -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-controller[See equivalent in the Reactive stack]# The {api-spring-framework}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`] annotation enables cross-origin requests on annotated controller methods, @@ -226,7 +226,7 @@ as the following example shows: [[mvc-cors-global]] == Global Configuration -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-global[See equivalent in the Reactive stack]# In addition to fine-grained, controller method level configuration, you probably want to define some global CORS configuration, too. You can set URL-based `CorsConfiguration` @@ -252,7 +252,7 @@ the `allowOriginPatterns` property may be used to match to a dynamic set of orig [[mvc-cors-global-java]] === Java Configuration -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-global[See equivalent in the Reactive stack]# To enable CORS in the MVC Java config, you can use the `CorsRegistry` callback, as the following example shows: @@ -329,7 +329,7 @@ as the following example shows: [[mvc-cors-filter]] == CORS Filter -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-webfilter[See equivalent in the Reactive stack]# You can apply CORS support through the built-in {api-spring-framework}/web/filter/CorsFilter.html[`CorsFilter`]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc index 2dc31aa9b7d9..988a1d795f7a 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc @@ -5,14 +5,14 @@ Spring Web MVC includes WebMvc.fn, a lightweight functional programming model in which functions are used to route and handle requests and contracts are designed for immutability. It is an alternative to the annotation-based programming model but otherwise runs on -the same <>. +the same xref:web/webmvc/mvc-servlet.adoc[DispatcherServlet]. [[webmvc-fn-overview]] == Overview -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-overview[See equivalent in the Reactive stack]# In WebMvc.fn, an HTTP request is handled with a `HandlerFunction`: a function that takes `ServerRequest` and returns a `ServerResponse`. @@ -104,14 +104,14 @@ as the following example shows: If you register the `RouterFunction` as a bean, for instance by exposing it in a -`@Configuration` class, it will be auto-detected by the servlet, as explained in <>. +`@Configuration` class, it will be auto-detected by the servlet, as explained in xref:web/webmvc-functional.adoc#webmvc-fn-running[Running a Server]. [[webmvc-fn-handler-functions]] == HandlerFunction -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-handler-functions[See equivalent in the Reactive stack]# `ServerRequest` and `ServerResponse` are immutable interfaces that offer JDK 8-friendly access to the HTTP request and response, including headers, body, method, and status code. @@ -393,9 +393,9 @@ found. If it is not found, we return a 404 Not Found response. [[webmvc-fn-handler-validation]] === Validation -A functional endpoint can use Spring's <> to +A functional endpoint can use Spring's xref:web/webmvc/mvc-config/validation.adoc[validation facilities] to apply validation to the request body. For example, given a custom Spring -<> implementation for a `Person`: +xref:web/webmvc/mvc-config/validation.adoc[Validator] implementation for a `Person`: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -457,13 +457,13 @@ apply validation to the request body. For example, given a custom Spring Handlers can also use the standard bean validation API (JSR-303) by creating and injecting a global `Validator` instance based on `LocalValidatorFactoryBean`. -See <>. +See xref:core/validation/beanvalidation.adoc[Spring Validation]. [[webmvc-fn-router-functions]] == `RouterFunction` -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-router-functions[See equivalent in the Reactive stack]# Router functions are used to route the requests to the corresponding `HandlerFunction`. Typically, you do not write router functions yourself, but rather use a method on the @@ -673,15 +673,15 @@ We can further improve by using the `nest` method together with `accept`: [[webmvc-fn-running]] == Running a Server -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-running[See equivalent in the Reactive stack]# -You typically run router functions in a <>-based setup through the -<>, which uses Spring configuration to declare the +You typically run router functions in a xref:web/webmvc/mvc-servlet.adoc[`DispatcherHandler`]-based setup through the +xref:web/webmvc/mvc-config.adoc[MVC Config], which uses Spring configuration to declare the components required to process requests. The MVC Java configuration declares the following infrastructure components to support functional endpoints: * `RouterFunctionMapping`: Detects one or more `RouterFunction` beans in the Spring -configuration, <>, combines them through +configuration, xref:core/beans/annotation-config/autowired.adoc#beans-factory-ordered[orders them], combines them through `RouterFunction.andOther`, and routes requests to the resulting composed `RouterFunction`. * `HandlerFunctionAdapter`: Simple adapter that lets `DispatcherHandler` invoke a `HandlerFunction` that was mapped to a request. @@ -766,7 +766,7 @@ The following example shows a WebFlux Java configuration: [[webmvc-fn-handler-filter-function]] == Filtering Handler Functions -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-handler-filter-function[See equivalent in the Reactive stack]# You can filter handler functions by using the `before`, `after`, or `filter` methods on the routing function builder. @@ -879,4 +879,4 @@ Besides using the `filter` method on the router function builder, it is possible filter to an existing router function via `RouterFunction.filter(HandlerFilterFunction)`. NOTE: CORS support for functional endpoints is provided through a dedicated -<>. +xref:web/webmvc-cors.adoc#mvc-cors-filter[`CorsFilter`]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc index d59d546fa5c2..3a5d565e1ea8 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc @@ -1,28 +1,28 @@ [[webmvc.test]] = Testing -[.small]#<># +[.small]#xref:web-reactive.adoc#webflux-test[See equivalent in the Reactive stack]# This section summarizes the options available in `spring-test` for Spring MVC applications. * Servlet API Mocks: Mock implementations of Servlet API contracts for unit testing controllers, -filters, and other web components. See <> +filters, and other web components. See xref:testing/unit.adoc#mock-objects-servlet[Servlet API] mock objects for more details. * TestContext Framework: Support for loading Spring configuration in JUnit and TestNG tests, including efficient caching of the loaded configuration across test methods and support for loading a `WebApplicationContext` with a `MockServletContext`. -See <> for more details. +See xref:testing/testcontext-framework.adoc[TestContext Framework] for more details. * Spring MVC Test: A framework, also known as `MockMvc`, for testing annotated controllers through the `DispatcherServlet` (that is, supporting annotations), complete with the Spring MVC infrastructure but without an HTTP server. -See <> for more details. +See xref:testing/spring-mvc-test-framework.adoc[Spring MVC Test] for more details. * Client-side REST: `spring-test` provides a `MockRestServiceServer` that you can use as a mock server for testing client-side code that internally uses the `RestTemplate`. -See <> for more details. +See xref:testing/spring-mvc-test-client.adoc[Client REST Tests] for more details. * `WebTestClient`: Built for testing WebFlux applications, but it can also be used for end-to-end integration testing, to any server, over an HTTP connection. It is a non-blocking, reactive client and is well suited for testing asynchronous and streaming -scenarios. See <> for more details. +scenarios. See xref:testing/webtestclient.adoc[`WebTestClient`] for more details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc index 0017d91c4e3f..d0547f6fa6df 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc @@ -1,11 +1,11 @@ [[mvc-view]] = View Technologies -[.small]#<># +[.small]#xref:web/webflux-view.adoc[See equivalent in the Reactive stack]# The use of view technologies in Spring MVC is pluggable. Whether you decide to use Thymeleaf, Groovy Markup Templates, JSPs, or other technologies is primarily a matter of a configuration change. This chapter covers view technologies integrated with Spring MVC. -We assume you are already familiar with <>. +We assume you are already familiar with xref:web/webmvc/mvc-servlet/viewresolver.adoc[View Resolution]. WARNING: The views of a Spring MVC application live within the internal trust boundaries of that application. Views have access to all the beans of your application context. As diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc index 38ffb009f4c9..dbd748170658 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc @@ -1,7 +1,7 @@ [[mvc-view-freemarker]] = FreeMarker -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-freemarker[See equivalent in the Reactive stack]# https://freemarker.apache.org/[Apache FreeMarker] is a template engine for generating any kind of text output from HTML to email and others. The Spring Framework has built-in @@ -11,7 +11,7 @@ integration for using Spring MVC with FreeMarker templates. [[mvc-view-freemarker-contextconfig]] == View Configuration -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-freemarker-contextconfig[See equivalent in the Reactive stack]# The following example shows how to configure FreeMarker as a view technology: @@ -92,7 +92,7 @@ returns a view name of `welcome`, the resolver looks for the [[mvc-views-freemarker]] == FreeMarker Configuration -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-views-freemarker[See equivalent in the Reactive stack]# You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker `Configuration` object (which is managed by Spring) by setting the appropriate bean @@ -131,7 +131,7 @@ with additional convenience macros for generating form input elements themselves [[mvc-view-bind-macros]] === The Bind Macros -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-bind-macros[See equivalent in the Reactive stack]# A standard set of macros are maintained within the `spring-webmvc.jar` file for FreeMarker, so they are always available to a suitably configured application. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc index 674fc94faec8..fd8f53404349 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc @@ -1,7 +1,7 @@ [[mvc-view-jackson]] = Jackson -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-httpmessagewriter[See equivalent in the Reactive stack]# Spring offers support for the Jackson JSON library. @@ -9,7 +9,7 @@ Spring offers support for the Jackson JSON library. [[mvc-view-json-mapping]] == Jackson-based JSON MVC Views -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-httpmessagewriter[See equivalent in the Reactive stack]# The `MappingJackson2JsonView` uses the Jackson library's `ObjectMapper` to render the response content as JSON. By default, the entire contents of the model map (with the exception of @@ -28,7 +28,7 @@ serializers and deserializers for specific types. [[mvc-view-xml-mapping]] == Jackson-based XML Views -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-httpmessagewriter[See equivalent in the Reactive stack]# `MappingJackson2XmlView` uses the https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML extension's] `XmlMapper` diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc index 8c5ec476c086..5284dc012600 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc @@ -173,7 +173,7 @@ following example shows: === The `input` Tag This tag renders an HTML `input` element with the bound value and `type='text'` by default. -For an example of this tag, see <>. You can also use +For an example of this tag, see xref:web/webmvc-view/mvc-jsp.adoc#mvc-view-jsp-formtaglib-formtag[The Form Tag]. You can also use HTML5-specific types, such as `email`, `tel`, `date`, and others. @@ -362,7 +362,7 @@ but with different values, as the following example shows: This tag renders multiple HTML `input` elements with the `type` set to `radio`. -As with the <>, you might want to +As with the xref:web/webmvc-view/mvc-jsp.adoc#mvc-view-jsp-formtaglib-checkboxestag[`checkboxes` tag], you might want to pass in the available options as a runtime variable. For this usage, you can use the `radiobuttons` tag. You pass in an `Array`, a `List`, or a `Map` that contains the available options in the `items` property. If you use a `Map`, the map entry key is diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc index 9d5c0e0c7236..8cb6e1b12490 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc @@ -1,7 +1,7 @@ [[mvc-view-script]] = Script Views -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-script[See equivalent in the Reactive stack]# The Spring Framework has a built-in integration for using Spring MVC with any templating library that can run on top of the @@ -27,7 +27,7 @@ TIP: The basic rule for integrating any other script engine is that it must impl [[mvc-view-script-dependencies]] == Requirements -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-script-dependencies[See equivalent in the Reactive stack]# You need to have the script engine on your classpath, the details of which vary by script engine: @@ -47,7 +47,7 @@ through https://www.webjars.org/[WebJars]. [[mvc-view-script-integrate]] == Script Templates -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-script[See equivalent in the Reactive stack]# You can declare a `ScriptTemplateConfigurer` bean to specify the script engine to use, the script files to load, what function to call to render templates, and so on. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc index e6ea3d7894d4..53c69f2a37a1 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc @@ -1,7 +1,7 @@ [[mvc-view-thymeleaf]] = Thymeleaf -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-thymeleaf[See equivalent in the Reactive stack]# Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML templates that can be previewed in a browser by double-clicking, which is very helpful diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc index 374172dfdc04..2b8ccd547db5 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc @@ -6,7 +6,7 @@ package) to render the response content as XML. You can explicitly set the objec marshalled by using a `MarshallingView` instance's `modelKey` bean property. Alternatively, the view iterates over all model properties and marshals the first type that is supported by the `Marshaller`. For more information on the functionality in the -`org.springframework.oxm` package, see <>. +`org.springframework.oxm` package, see xref:data-access/oxm.adoc[Marshalling XML using O/X Mappers]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc index 8586a50bbb6d..b139bad0deee 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc @@ -9,7 +9,7 @@ XSLT in a Spring Web MVC application. This example is a trivial Spring application that creates a list of words in the `Controller` and adds them to the model map. The map is returned, along with the view -name of our XSLT view. See <> for details of Spring Web MVC's +name of our XSLT view. See xref:web/webmvc/mvc-controller.adoc[Annotated Controllers] for details of Spring Web MVC's `Controller` interface. The XSLT controller turns the list of words into a simple XML document ready for transformation. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc.adoc b/framework-docs/modules/ROOT/pages/web/webmvc.adoc index 8c6fa01c2f33..4578acc9528b 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc.adoc @@ -12,7 +12,7 @@ but it is more commonly known as "Spring MVC". Parallel to Spring Web MVC, Spring Framework 5.0 introduced a reactive-stack web framework whose name, "Spring WebFlux," is also based on its source module ({spring-framework-main-code}/spring-webflux[`spring-webflux`]). -This chapter covers Spring Web MVC. The <> +This chapter covers Spring Web MVC. The xref:testing/unit.adoc#mock-objects-web-reactive[next chapter] covers Spring WebFlux. For baseline information and compatibility with Servlet container and Jakarta EE version diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc index b00b961187af..c6097bb03d5d 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc @@ -1,14 +1,14 @@ [[filters]] = Filters -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-filters[See equivalent in the Reactive stack]# The `spring-web` module provides some useful filters: -* <> -* <> -* <> -* <> +* xref:web/webmvc/filters.adoc#filters-http-put[Form Data] +* xref:web/webmvc/filters.adoc#filters-forwarded-headers[Forwarded Headers] +* xref:web/webmvc/filters.adoc#filters-shallow-etag[Shallow ETag] +* xref:web/webmvc/filters.adoc#filters-cors[CORS] @@ -28,7 +28,7 @@ available through the `ServletRequest.getParameter{asterisk}()` family of method [[filters-forwarded-headers]] == Forwarded Headers -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-forwarded-headers[See equivalent in the Reactive stack]# As a request goes through proxies (such as load balancers) the host, port, and scheme may change, and that makes it a challenge to create links that point to the correct @@ -51,10 +51,10 @@ a proxy at the boundary of trust should be configured to remove untrusted `Forwa headers that come from the outside. You can also configure the `ForwardedHeaderFilter` with `removeOnly=true`, in which case it removes but does not use the headers. -In order to support <> and error dispatches this +In order to support xref:web/webmvc/mvc-ann-async.adoc[asynchronous requests] and error dispatches this filter should be mapped with `DispatcherType.ASYNC` and also `DispatcherType.ERROR`. If using Spring Framework's `AbstractAnnotationConfigDispatcherServletInitializer` -(see <>) all filters are automatically registered for all dispatch +(see xref:web/webmvc/mvc-servlet/container-config.adoc[Servlet Config]) all filters are automatically registered for all dispatch types. However if registering the filter via `web.xml` or in Spring Boot via a `FilterRegistrationBean` be sure to include `DispatcherType.ASYNC` and `DispatcherType.ERROR` in addition to `DispatcherType.REQUEST`. @@ -71,16 +71,16 @@ request header and, if the two are equal, returns a 304 (NOT_MODIFIED). This strategy saves network bandwidth but not CPU, as the full response must be computed for each request. Other strategies at the controller level, described earlier, can avoid -the computation. See <>. +the computation. See xref:web/webmvc/mvc-caching.adoc[HTTP Caching]. This filter has a `writeWeakETag` parameter that configures the filter to write weak ETags similar to the following: `W/"02a2d595e6ed9a0b24f027f2b63b134d6"` (as defined in https://tools.ietf.org/html/rfc7232#section-2.3[RFC 7232 Section 2.3]). -In order to support <> this filter must be mapped +In order to support xref:web/webmvc/mvc-ann-async.adoc[asynchronous requests] this filter must be mapped with `DispatcherType.ASYNC` so that the filter can delay and successfully generate an ETag to the end of the last async dispatch. If using Spring Framework's -`AbstractAnnotationConfigDispatcherServletInitializer` (see <>) +`AbstractAnnotationConfigDispatcherServletInitializer` (see xref:web/webmvc/mvc-servlet/container-config.adoc[Servlet Config]) all filters are automatically registered for all dispatch types. However if registering the filter via `web.xml` or in Spring Boot via a `FilterRegistrationBean` be sure to include `DispatcherType.ASYNC`. @@ -89,13 +89,13 @@ the filter via `web.xml` or in Spring Boot via a `FilterRegistrationBean` be sur [[filters-cors]] == CORS -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-filters-cors[See equivalent in the Reactive stack]# Spring MVC provides fine-grained support for CORS configuration through annotations on controllers. However, when used with Spring Security, we advise relying on the built-in `CorsFilter` that must be ordered ahead of Spring Security's chain of filters. -See the sections on <> and the <> for more details. +See the sections on xref:web/webmvc-cors.adoc[CORS] and the xref:web/webmvc-cors.adoc#mvc-cors-filter[CORS Filter] for more details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc index b6e47669799e..4fd42b9f7144 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc @@ -2,22 +2,22 @@ = Asynchronous Requests Spring MVC has an extensive integration with Servlet asynchronous request -<>: +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-processing[processing]: -* <> and <> +* xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-deferredresult[`DeferredResult`] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-callable[`Callable`] return values in controller methods provide basic support for a single asynchronous return value. -* Controllers can <> multiple values, including -<> and <>. +* Controllers can xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-http-streaming[stream] multiple values, including +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-sse[SSE] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-output-stream[raw data]. * Controllers can use reactive clients and return -<> for response handling. +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[reactive types] for response handling. -For an overview of how this differs from Spring WebFlux, see the <> section below. +For an overview of how this differs from Spring WebFlux, see the xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-vs-webflux[Async Spring MVC compared to WebFlux] section below. [[mvc-ann-async-deferredresult]] == `DeferredResult` -Once the asynchronous request processing feature is <> +Once the asynchronous request processing feature is xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration[enabled] in the Servlet container, controller methods can wrap any supported controller method return value with `DeferredResult`, as the following example shows: @@ -80,7 +80,7 @@ as the following example shows: ---- The return value can then be obtained by running the given task through the -<> `TaskExecutor`. +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration-spring-mvc[configured] `TaskExecutor`. @@ -180,7 +180,7 @@ handling is built into all framework contracts and is intrinsically supported th stages of request processing. From a programming model perspective, both Spring MVC and Spring WebFlux support -asynchronous and <> as return values in controller methods. +asynchronous and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types] as return values in controller methods. Spring MVC even supports streaming, including reactive back pressure. However, individual writes to the response remain blocking (and are performed on a separate thread), unlike WebFlux, which relies on non-blocking I/O and does not need an extra thread for each write. @@ -191,12 +191,12 @@ nor does it have any explicit support for asynchronous and reactive types as mod Spring WebFlux does support all that. Finally, from a configuration perspective the asynchronous request processing feature must be -<>. +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration[enabled at the Servlet container level]. [[mvc-ann-async-http-streaming]] == HTTP Streaming -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs-streaming[See equivalent in the Reactive stack]# You can use `DeferredResult` and `Callable` for a single asynchronous return value. What if you want to produce multiple asynchronous values and have those written to the @@ -208,7 +208,7 @@ response? This section describes how to do so. You can use the `ResponseBodyEmitter` return value to produce a stream of objects, where each object is serialized with an -<> and written to the +xref:integration/rest-clients.adoc#rest-message-conversion[`HttpMessageConverter`] and written to the response, as the following example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -306,11 +306,11 @@ stream from a controller, return `SseEmitter`, as the following example shows: While SSE is the main option for streaming into browsers, note that Internet Explorer does not support Server-Sent Events. Consider using Spring's -<> with -<> transports (including SSE) that target +xref:web/websocket.adoc[WebSocket messaging] with +xref:web/websocket/fallback.adoc[SockJS fallback] transports (including SSE) that target a wide range of browsers. -See also <> for notes on exception handling. +See also xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-objects[previous section] for notes on exception handling. [[mvc-ann-async-output-stream]] @@ -349,10 +349,10 @@ customize the status and headers of the response. [[mvc-ann-async-reactive-types]] == Reactive Types -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs-streaming[See equivalent in the Reactive stack]# Spring MVC supports use of reactive client libraries in a controller (also read -<> in the WebFlux section). +xref:web-reactive.adoc#webflux-reactive-libraries[Reactive Libraries] in the WebFlux section). This includes the `WebClient` from `spring-webflux` and others, such as Spring Data reactive data repositories. In such scenarios, it is convenient to be able to return reactive types from the controller method. @@ -374,11 +374,11 @@ TIP: Spring MVC supports Reactor and RxJava through the For streaming to the response, reactive back pressure is supported, but writes to the response are still blocking and are run on a separate thread through the -<> `TaskExecutor`, to avoid +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration-spring-mvc[configured] `TaskExecutor`, to avoid blocking the upstream source (such as a `Flux` returned from `WebClient`). By default, `SimpleAsyncTaskExecutor` is used for the blocking writes, but that is not suitable under load. If you plan to stream with a reactive type, you should use the -<> to configure a task executor. +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration-spring-mvc[MVC configuration] to configure a task executor. @@ -396,7 +396,7 @@ GraphQL Java https://www.graphql-java.com/documentation/concerns/#context-object and others. If Micrometer Context Propagation is present on the classpath, when a controller method -returns a <> such as `Flux` or `Mono`, all +returns a xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[reactive type] such as `Flux` or `Mono`, all `ThreadLocal` values, for which there is a registered `io.micrometer.ThreadLocalAccessor`, are written to the Reactor `Context` as key-value pairs, using the key assigned by the `ThreadLocalAccessor`. @@ -424,17 +424,17 @@ Propagation library. [[mvc-ann-async-disconnects]] == Disconnects -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs-streaming[See equivalent in the Reactive stack]# The Servlet API does not provide any notification when a remote client goes away. -Therefore, while streaming to the response, whether through <> -or <>, it is important to send data periodically, +Therefore, while streaming to the response, whether through xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-sse[SseEmitter] +or xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[reactive types], it is important to send data periodically, since the write fails if the client has disconnected. The send could take the form of an empty (comment-only) SSE event or any other data that the other side would have to interpret as a heartbeat and ignore. Alternatively, consider using web messaging solutions (such as -<> or WebSocket with <>) +xref:web/websocket/stomp.adoc[STOMP over WebSocket] or WebSocket with xref:web/websocket/fallback.adoc[SockJS]) that have a built-in heartbeat mechanism. @@ -474,7 +474,7 @@ You can configure the following: * Default timeout value for async requests, which if not set, depends on the underlying Servlet container. * `AsyncTaskExecutor` to use for blocking writes when streaming with -<> and for executing `Callable` instances returned from +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types] and for executing `Callable` instances returned from controller methods. We highly recommended configuring this property if you stream with reactive types or have controller methods that return `Callable`, since by default, it is a `SimpleAsyncTaskExecutor`. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc index 65bac5f96bec..2769c1f1b541 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc @@ -1,7 +1,7 @@ [[mvc-ann-rest-exceptions]] = Error Responses -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc[See equivalent in the Reactive stack]# A common requirement for REST services is to include details in the body of error responses. The Spring Framework supports the "Problem Details for HTTP APIs" @@ -18,14 +18,14 @@ exceptions implement this. - `ErrorResponseException` -- basic `ErrorResponse` implementation that others can use as a convenient base class. - `ResponseEntityExceptionHandler` -- convenient base class for an -<> that handles all Spring MVC exceptions, +xref:web/webmvc/mvc-controller/ann-advice.adoc[@ControllerAdvice] that handles all Spring MVC exceptions, and any `ErrorResponseException`, and renders an error response with a body. [[mvc-ann-rest-exceptions-render]] == Render -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-render[See equivalent in the Reactive stack]# You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from any `@RequestMapping` method to render an RFC 7807 response. This is processed as follows: @@ -39,7 +39,7 @@ and also falls back on it if no compatible media type is found. To enable RFC 7807 responses for Spring WebFlux exceptions and for any `ErrorResponseException`, extend `ResponseEntityExceptionHandler` and declare it as an -<> in Spring configuration. The handler +xref:web/webmvc/mvc-controller/ann-advice.adoc[@ControllerAdvice] in Spring configuration. The handler has an `@ExceptionHandler` method that handles any `ErrorResponse` exception, which includes all built-in web exceptions. You can add more exception handling methods, and use a protected method to map any exception to a `ProblemDetail`. @@ -48,7 +48,7 @@ use a protected method to map any exception to a `ProblemDetail`. [[mvc-ann-rest-exceptions-non-standard]] == Non-Standard Fields -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-non-standard[See equivalent in the Reactive stack]# You can extend an RFC 7807 response with non-standard fields in one of two ways. @@ -68,13 +68,13 @@ from an existing `ProblemDetail`. This could be done centrally, e.g. from an [[mvc-ann-rest-exceptions-i18n]] == Internationalization -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-i18n[See equivalent in the Reactive stack]# It is a common requirement to internationalize error response details, and good practice to customize the problem details for Spring MVC exceptions. This is supported as follows: - Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field -through a <>. +through a xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSource]. The actual message code value is parameterized with placeholders, e.g. `"HTTP method {0} not supported"` to be expanded from the arguments. - Each `ErrorResponse` also exposes a message code to resolve the "title" field. @@ -178,7 +178,7 @@ qualified exception class name. [[mvc-ann-rest-exceptions-client]] == Client Handling -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-client[See equivalent in the Reactive stack]# A client application can catch `WebClientResponseException`, when using the `WebClient`, or `RestClientResponseException` when using the `RestTemplate`, and use their diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc index 35f5ef7add26..f84647c9a7f6 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc @@ -1,7 +1,7 @@ [[mvc-caching]] = HTTP Caching -[.small]#<># +[.small]#xref:web/webflux/caching.adoc[See equivalent in the Reactive stack]# HTTP caching can significantly improve the performance of a web application. HTTP caching revolves around the `Cache-Control` response header and, subsequently, conditional request @@ -17,7 +17,7 @@ This section describes the HTTP caching-related options that are available in Sp [[mvc-caching-cachecontrol]] == `CacheControl` -[.small]#<># +[.small]#xref:web/webflux/caching.adoc#webflux-caching-cachecontrol[See equivalent in the Reactive stack]# {api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for configuring settings related to the `Cache-Control` header and is accepted as an argument @@ -25,8 +25,8 @@ in a number of places: * {api-spring-framework}/web/servlet/mvc/WebContentInterceptor.html[`WebContentInterceptor`] * {api-spring-framework}/web/servlet/support/WebContentGenerator.html[`WebContentGenerator`] -* <> -* <> +* xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[Controllers] +* xref:web/webmvc/mvc-caching.adoc#mvc-caching-static-resources[Static Resources] While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all possible directives for the `Cache-Control` response header, the `CacheControl` type takes a @@ -73,7 +73,7 @@ works as follows: [[mvc-caching-etag-lastmodified]] == Controllers -[.small]#<># +[.small]#xref:web/webflux/caching.adoc#webflux-caching-etag-lastmodified[See equivalent in the Reactive stack]# Controllers can add explicit support for HTTP caching. We recommended doing so, since the `lastModified` or `ETag` value for a resource needs to be calculated before it can be compared @@ -174,10 +174,10 @@ to 412 (PRECONDITION_FAILED), to prevent concurrent modification. [[mvc-caching-static-resources]] == Static Resources -[.small]#<># +[.small]#xref:web/webflux/caching.adoc#webflux-caching-static-resources[See equivalent in the Reactive stack]# You should serve static resources with a `Cache-Control` and conditional response headers -for optimal performance. See the section on configuring <>. +for optimal performance. See the section on configuring xref:web/webmvc/mvc-config/static-resources.adoc[Static Resources]. @@ -185,7 +185,7 @@ for optimal performance. See the section on configuring <>. +response content and, thus, save bandwidth but not CPU time. See xref:web/webmvc/filters.adoc#filters-shallow-etag[Shallow ETag]. include:../:webmvc-view.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc index 2b43f6232625..0b3446d50661 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc @@ -1,17 +1,17 @@ [[mvc-config]] = MVC Config -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[See equivalent in the Reactive stack]# The MVC Java configuration and the MVC XML namespace provide default configuration suitable for most applications and a configuration API to customize it. For more advanced customizations, which are not available in the configuration API, -see <> and <>. +see xref:web/webmvc/mvc-config/advanced-java.adoc[Advanced Java Config] and xref:web/webmvc/mvc-config/advanced-xml.adoc[Advanced XML Config]. You do not need to understand the underlying beans created by the MVC Java configuration -and the MVC namespace. If you want to learn more, see <> -and <>. +and the MVC namespace. If you want to learn more, see xref:web/webmvc/mvc-servlet/special-bean-types.adoc[Special Bean Types] +and xref:web/webmvc/mvc-servlet/config.adoc[Web MVC Config]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc index e469a02b8f89..edf120d60135 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc @@ -1,7 +1,7 @@ [[mvc-config-advanced-java]] = Advanced Java Config -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-advanced-java[See equivalent in the Reactive stack]# `@EnableWebMvc` imports `DelegatingWebMvcConfiguration`, which: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc index 95c139265750..2848ad42b110 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc @@ -1,7 +1,7 @@ [[mvc-config-content-negotiation]] = Content Types -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-content-negotiation[See equivalent in the Reactive stack]# You can configure how Spring MVC determines the requested media types from the request (for example, `Accept` header, URL path extension, query parameter, and others). @@ -10,7 +10,7 @@ By default, only the `Accept` header is checked. If you must use URL-based content type resolution, consider using the query parameter strategy over path extensions. See -<> and <> for +xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-suffix-pattern-match[Suffix Match] and xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-rfd[Suffix Match and RFD] for more details. In Java configuration, you can customize requested content type resolution, as the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc index 9ac7ec9ddbbe..2de0ddc856e7 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc @@ -1,7 +1,7 @@ [[mvc-config-conversion]] = Type Conversion -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-conversion[See equivalent in the Reactive stack]# By default, formatters for various number and date types are installed, along with support for customization via `@NumberFormat` and `@DateTimeFormat` on fields. @@ -108,7 +108,7 @@ in the HTML spec. For such cases date and time formatting can be customized as f } ---- -NOTE: See <> +NOTE: See xref:core/validation/format.adoc#format-FormatterRegistrar-SPI[the `FormatterRegistrar` SPI] and the `FormattingConversionServiceFactoryBean` for more information on when to use FormatterRegistrar implementations. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc index 66261c7616e8..f9126edd1f21 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc @@ -1,7 +1,7 @@ [[mvc-config-customize]] = MVC Config API -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-customize[See equivalent in the Reactive stack]# In Java configuration, you can implement the `WebMvcConfigurer` interface, as the following example shows: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc index d1bdaacc48f7..e7300178a1e9 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc @@ -1,7 +1,7 @@ [[mvc-config-enable]] = Enable MVC Configuration -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-enable[See equivalent in the Reactive stack]# In Java configuration, you can use the `@EnableWebMvc` annotation to enable MVC configuration, as the following example shows: @@ -43,7 +43,7 @@ configuration, as the following example shows: ---- The preceding example registers a number of Spring MVC -<> and adapts to dependencies +xref:web/webmvc/mvc-servlet/special-bean-types.adoc[infrastructure beans] and adapts to dependencies available on the classpath (for example, payload converters for JSON, XML, and others). diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc index 2182ccdf98df..c8c861157931 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc @@ -1,7 +1,7 @@ [[mvc-config-message-converters]] = Message Converters -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-message-codecs[See equivalent in the Reactive stack]# You can customize `HttpMessageConverter` in Java configuration by overriding {api-spring-framework}/web/servlet/config/annotation/WebMvcConfigurer.html#configureMessageConverters-java.util.List-[`configureMessageConverters()`] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc index cde874c9ec65..a3318bc15b94 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc @@ -1,7 +1,7 @@ [[mvc-config-path-matching]] = Path Matching -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-path-matching[See equivalent in the Reactive stack]# You can customize options related to path matching and treatment of the URL. For details on the individual options, see the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc index e1f162c8734f..7620f00ec714 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc @@ -1,7 +1,7 @@ [[mvc-config-static-resources]] = Static Resources -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-static-resources[See equivalent in the Reactive stack]# This option provides a convenient way to serve static resources from a list of {api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. @@ -55,7 +55,7 @@ The following example shows how to achieve the same configuration in XML: ---- See also -<>. +xref:web/webmvc/mvc-caching.adoc#mvc-caching-static-resources[HTTP caching support for static resources]. The resource handler also supports a chain of {api-spring-framework}/web/servlet/resource/ResourceResolver.html[`ResourceResolver`] implementations and diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc index d5791c3519da..82a89a8e1303 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc @@ -1,11 +1,11 @@ [[mvc-config-validation]] = Validation -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-validation[See equivalent in the Reactive stack]# -By default, if <> is present +By default, if xref:core/validation/beanvalidation.adoc#validation-beanvalidation-overview[Bean Validation] is present on the classpath (for example, Hibernate Validator), the `LocalValidatorFactoryBean` is -registered as a global <> for use with `@Valid` and +registered as a global xref:core/validation/validator.adoc[Validator] for use with `@Valid` and `Validated` on controller method arguments. In Java configuration, you can customize the global `Validator` instance, as the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc index 950afe58684b..da2227b20ec4 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc @@ -1,7 +1,7 @@ [[mvc-config-view-resolvers]] = View Resolvers -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-view-resolvers[See equivalent in the Reactive stack]# The MVC configuration simplifies the registration of view resolvers. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc index f3363d0aa0dc..7af5f14a5586 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc @@ -1,7 +1,7 @@ [[mvc-controller]] = Annotated Controllers -[.small]#<># +[.small]#xref:web/webflux/controller.adoc[See equivalent in the Reactive stack]# Spring MVC provides an annotation-based programming model where `@Controller` and `@RestController` components use annotations to express request mappings, request input, diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc index 67132df5eff7..1f50964cf4fd 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc @@ -1,7 +1,7 @@ [[mvc-ann-controller-advice]] = Controller Advice -[.small]#<># +[.small]#xref:web/webflux/controller/ann-advice.adoc[See equivalent in the Reactive stack]# `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply only to the `@Controller` class, or class hierarchy, in which they are declared. If, instead, they @@ -10,8 +10,8 @@ to any controller. Moreover, as of 5.3, `@ExceptionHandler` methods in `@Control can be used to handle exceptions from any `@Controller` or any other handler. `@ControllerAdvice` is meta-annotated with `@Component` and therefore can be registered as -a Spring bean through <>. `@RestControllerAdvice` is meta-annotated with `@ControllerAdvice` +a Spring bean through xref:core/beans/java/instantiating-container.adoc#beans-java-instantiating-container-scan[component scanning] +. `@RestControllerAdvice` is meta-annotated with `@ControllerAdvice` and `@ResponseBody`, and that means `@ExceptionHandler` methods will have their return value rendered via response body message conversion, rather than via HTML views. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc index 4b3b141ed32c..89f7aeff9a02 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc @@ -1,9 +1,9 @@ [[mvc-ann-exceptionhandler]] = Exceptions -[.small]#<># +[.small]#xref:web/webflux/controller/ann-exceptions.adoc[See equivalent in the Reactive stack]# -`@Controller` and <> classes can have +`@Controller` and xref:web/webmvc/mvc-controller/ann-advice.adoc[@ControllerAdvice] classes can have `@ExceptionHandler` methods to handle exceptions from controller methods, as the following example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -122,12 +122,12 @@ exception is propagated through the remaining resolution chain, as though the given `@ExceptionHandler` method would not have matched in the first place. Support for `@ExceptionHandler` methods in Spring MVC is built on the `DispatcherServlet` -level, <> mechanism. +level, xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[HandlerExceptionResolver] mechanism. [[mvc-ann-exceptionhandler-args]] == Method Arguments -[.small]#<># +[.small]#xref:web/webflux/controller/ann-exceptions.adoc#webflux-ann-exceptionhandler-args[See equivalent in the Reactive stack]# `@ExceptionHandler` methods support the following arguments: @@ -177,22 +177,22 @@ level, <> mechanism. | `RedirectAttributes` | Specify attributes to use in case of a redirect -- (that is to be appended to the query string) and flash attributes to be stored temporarily until the request after the redirect. - See <> and <>. + See xref:web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc[Redirect Attributes] and xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[Flash Attributes]. | `@SessionAttribute` | For access to any session attribute, in contrast to model attributes stored in the session as a result of a class-level `@SessionAttributes` declaration. - See <> for more details. + See xref:web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc[`@SessionAttribute`] for more details. | `@RequestAttribute` -| For access to request attributes. See <> for more details. +| For access to request attributes. See xref:web/webmvc/mvc-controller/ann-methods/requestattrib.adoc[`@RequestAttribute`] for more details. |=== [[mvc-ann-exceptionhandler-return-values]] == Return Values -[.small]#<># +[.small]#xref:web/webflux/controller/ann-exceptions.adoc#webflux-ann-exceptionhandler-return-values[See equivalent in the Reactive stack]# `@ExceptionHandler` methods support the following return values: @@ -202,20 +202,20 @@ level, <> mechanism. | `@ResponseBody` | The return value is converted through `HttpMessageConverter` instances and written to the - response. See <>. + response. See xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[`@ResponseBody`]. | `HttpEntity`, `ResponseEntity` | The return value specifies that the full response (including the HTTP headers and the body) be converted through `HttpMessageConverter` instances and written to the response. - See <>. + See xref:web/webmvc/mvc-controller/ann-methods/responseentity.adoc[ResponseEntity]. | `ErrorResponse` | To render an RFC 7807 error response with details in the body, -see <> +see xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses] | `ProblemDetail` | To render an RFC 7807 error response with details in the body, -see <> +see xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses] | `String` | A view name to be resolved with `ViewResolver` implementations and used together with the @@ -246,7 +246,7 @@ see <> | A method with a `void` return type (or `null` return value) is considered to have fully handled the response if it also has a `ServletResponse` an `OutputStream` argument, or a `@ResponseStatus` annotation. The same is also true if the controller has made a positive - `ETag` or `lastModified` timestamp check (see <> for details). + `ETag` or `lastModified` timestamp check (see xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[Controllers] for details). If none of the above is true, a `void` return type can also indicate "`no response body`" for REST controllers or default view name selection for HTML controllers. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc index 6d025b36656d..ded39846ce0c 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc @@ -1,7 +1,7 @@ [[mvc-ann-initbinder]] = `DataBinder` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-initbinder.adoc[See equivalent in the Reactive stack]# `@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods that initialize instances of `WebDataBinder`, and those, in turn, can: @@ -13,7 +13,7 @@ headers, cookies, and others) to the target type of controller method arguments. `@InitBinder` methods can register controller-specific `java.beans.PropertyEditor` or Spring `Converter` and `Formatter` components. In addition, you can use the -<> to register `Converter` and `Formatter` +xref:web/webmvc/mvc-config/conversion.adoc[MVC config] to register `Converter` and `Formatter` types in a globally shared `FormattingConversionService`. `@InitBinder` methods support many of the same arguments that `@RequestMapping` methods @@ -95,7 +95,7 @@ controller-specific `Formatter` implementations, as the following example shows: [[mvc-ann-initbinder-model-design]] == Model Design -[.small]#<># +[.small]#xref:web/webflux/controller/ann-initbinder.adoc#webflux-ann-initbinder-model-design[See equivalent in the Reactive stack]# include:../../:web-data-binding-model-design.adoc[] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc index ee2178aa14d2..d5717e459c14 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc @@ -1,7 +1,7 @@ [[mvc-ann-methods]] = Handler Methods -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods.adoc[See equivalent in the Reactive stack]# `@RequestMapping` handler methods have a flexible signature and can choose from a range of supported controller method arguments and return values. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc index b0fb31911f98..d1509896fea8 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc @@ -1,7 +1,7 @@ [[mvc-ann-arguments]] = Method Arguments -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/arguments.adoc[See equivalent in the Reactive stack]# The next table describes the supported controller method arguments. Reactive types are not supported for any arguments. @@ -59,38 +59,38 @@ and others) and is equivalent to `required=false`. | For access to the raw response body as exposed by the Servlet API. | `@PathVariable` -| For access to URI template variables. See <>. +| For access to URI template variables. See xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-uri-templates[URI patterns]. | `@MatrixVariable` -| For access to name-value pairs in URI path segments. See <>. +| For access to name-value pairs in URI path segments. See xref:web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc[Matrix Variables]. | `@RequestParam` | For access to the Servlet request parameters, including multipart files. Parameter values - are converted to the declared method argument type. See <> as well - as <>. + are converted to the declared method argument type. See xref:web/webmvc/mvc-controller/ann-methods/requestparam.adoc[`@RequestParam`] as well + as xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[Multipart]. Note that use of `@RequestParam` is optional for simple parameter values. See "`Any other argument`", at the end of this table. | `@RequestHeader` | For access to request headers. Header values are converted to the declared method argument - type. See <>. + type. See xref:web/webmvc/mvc-controller/ann-methods/requestheader.adoc[`@RequestHeader`]. | `@CookieValue` | For access to cookies. Cookies values are converted to the declared method argument - type. See <>. + type. See xref:web/webmvc/mvc-controller/ann-methods/cookievalue.adoc[`@CookieValue`]. | `@RequestBody` | For access to the HTTP request body. Body content is converted to the declared method - argument type by using `HttpMessageConverter` implementations. See <>. + argument type by using `HttpMessageConverter` implementations. See xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[`@RequestBody`]. | `HttpEntity` | For access to request headers and body. The body is converted with an `HttpMessageConverter`. - See <>. + See xref:web/webmvc/mvc-controller/ann-methods/httpentity.adoc[HttpEntity]. | `@RequestPart` | For access to a part in a `multipart/form-data` request, converting the part's body - with an `HttpMessageConverter`. See <>. + with an `HttpMessageConverter`. See xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[Multipart]. | `java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap` | For access to the model that is used in HTML controllers and exposed to templates as @@ -99,12 +99,12 @@ and others) and is equivalent to `required=false`. | `RedirectAttributes` | Specify attributes to use in case of a redirect (that is, to be appended to the query string) and flash attributes to be stored temporarily until the request after redirect. - See <> and <>. + See xref:web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc[Redirect Attributes] and xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[Flash Attributes]. | `@ModelAttribute` | For access to an existing attribute in the model (instantiated if not present) with - data binding and validation applied. See <> as well as - <> and <>. + data binding and validation applied. See xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[`@ModelAttribute`] as well as + xref:web/webmvc/mvc-controller/ann-modelattrib-methods.adoc[Model] and xref:web/webmvc/mvc-controller/ann-initbinder.adoc[`DataBinder`]. Note that use of `@ModelAttribute` is optional (for example, to set its attributes). See "`Any other argument`" at the end of this table. @@ -118,19 +118,19 @@ and others) and is equivalent to `required=false`. | `SessionStatus` + class-level `@SessionAttributes` | For marking form processing complete, which triggers cleanup of session attributes declared through a class-level `@SessionAttributes` annotation. See - <> for more details. + xref:web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`] for more details. | `UriComponentsBuilder` | For preparing a URL relative to the current request's host, port, scheme, context path, and - the literal part of the servlet mapping. See <>. + the literal part of the servlet mapping. See xref:web/webmvc/mvc-uri-building.adoc[URI Links]. | `@SessionAttribute` | For access to any session attribute, in contrast to model attributes stored in the session as a result of a class-level `@SessionAttributes` declaration. See - <> for more details. + xref:web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc[`@SessionAttribute`] for more details. | `@RequestAttribute` -| For access to request attributes. See <> for more details. +| For access to request attributes. See xref:web/webmvc/mvc-controller/ann-methods/requestattrib.adoc[`@RequestAttribute`] for more details. | Any other argument | If a method argument is not matched to any of the earlier values in this table and it is diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc index c66603740752..953953f51eec 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc @@ -1,7 +1,7 @@ [[mvc-ann-cookievalue]] = `@CookieValue` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/cookievalue.adoc[See equivalent in the Reactive stack]# You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument in a controller. @@ -36,6 +36,6 @@ The following example shows how to get the cookie value: <1> Get the value of the `JSESSIONID` cookie. If the target method parameter type is not `String`, type conversion is applied automatically. -See <>. +See xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[Type Conversion]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc index ae9ffe0d08c1..9ed54e0d6f29 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc @@ -1,9 +1,9 @@ [[mvc-ann-httpentity]] = HttpEntity -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/httpentity.adoc[See equivalent in the Reactive stack]# -`HttpEntity` is more or less identical to using <> but is based on a +`HttpEntity` is more or less identical to using xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[`@RequestBody`] but is based on a container object that exposes request headers and body. The following listing shows an example: [source,java,indent=0,subs="verbatim,quotes",role="primary"] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc index 83d9bc3385c5..c8a44324c281 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc @@ -5,7 +5,7 @@ Spring offers support for the Jackson JSON library. [[mvc-ann-jsonview]] == JSON Views -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/jackson.adoc#webflux-ann-jsonview[See equivalent in the Reactive stack]# Spring MVC provides built-in support for https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc index 0fb3135050c6..927cf90a718f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc @@ -1,7 +1,7 @@ [[mvc-ann-matrix-variables]] = Matrix Variables -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/matrix-variables.adoc[See equivalent in the Reactive stack]# https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in path segments. In Spring MVC, we refer to those as "`matrix variables`" based on an @@ -135,7 +135,7 @@ To get all matrix variables, you can use a `MultiValueMap`, as the following exa Note that you need to enable the use of matrix variables. In the MVC Java configuration, you need to set a `UrlPathHelper` with `removeSemicolonContent=false` through -<>. In the MVC XML namespace, you can set +xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching]. In the MVC XML namespace, you can set ``. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc index bd26f9a1af7e..8140ea15dc2d 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc @@ -1,7 +1,7 @@ [[mvc-ann-modelattrib-method-args]] = `@ModelAttribute` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[See equivalent in the Reactive stack]# You can use the `@ModelAttribute` annotation on a method argument to access an attribute from the model or have it be instantiated if not present. The model attribute is also overlain with @@ -32,9 +32,9 @@ fun processSubmit(@ModelAttribute pet: Pet): String { // <1> The `Pet` instance above is sourced in one of the following ways: * Retrieved from the model where it may have been added by a - <>. + xref:web/webmvc/mvc-controller/ann-modelattrib-methods.adoc[@ModelAttribute method]. * Retrieved from the HTTP session if the model attribute was listed in - the class-level <> annotation. + the class-level xref:web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`] annotation. * Obtained through a `Converter` where the model attribute name matches the name of a request value such as a path variable or a request parameter (see next example). * Instantiated using its default constructor. @@ -42,7 +42,7 @@ The `Pet` instance above is sourced in one of the following ways: request parameters. Argument names are determined through JavaBeans `@ConstructorProperties` or through runtime-retained parameter names in the bytecode. -One alternative to using a <> to +One alternative to using a xref:web/webmvc/mvc-controller/ann-modelattrib-methods.adoc[@ModelAttribute method] to supply it or relying on the framework to create the model attribute, is to have a `Converter` to provide the instance. This is applied when the model attribute name matches to the name of a request value such as a path variable or a request @@ -75,8 +75,8 @@ After the model attribute instance is obtained, data binding is applied. The `WebDataBinder` class matches Servlet request parameter names (query parameters and form fields) to field names on the target `Object`. Matching fields are populated after type conversion is applied, where necessary. For more on data binding (and validation), see -<>. For more on customizing data binding, see -<>. +xref:web/webmvc/mvc-config/validation.adoc[Validation]. For more on customizing data binding, see +xref:web/webmvc/mvc-controller/ann-initbinder.adoc[`DataBinder`]. Data binding can result in errors. By default, a `BindException` is raised. However, to check for such errors in the controller method, you can add a `BindingResult` argument immediately next @@ -156,8 +156,8 @@ alternatively, set `@ModelAttribute(binding=false)`, as the following example sh You can automatically apply validation after data binding by adding the `jakarta.validation.Valid` annotation or Spring's `@Validated` annotation -(<> and -<>). The following example shows how to do so: +(xref:core/validation/beanvalidation.adoc[Bean Validation] and +xref:web/webmvc/mvc-config/validation.adoc[Spring validation]). The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc index 59ca68e20e95..5348bc47508a 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc @@ -1,9 +1,9 @@ [[mvc-multipart-forms]] = Multipart -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/multipart-forms.adoc[See equivalent in the Reactive stack]# -After a `MultipartResolver` has been <>, the content of POST +After a `MultipartResolver` has been xref:web/webmvc/mvc-servlet/multipart.adoc[enabled], the content of POST requests with `multipart/form-data` is parsed and accessible as regular request parameters. The following example accesses one regular form field and one uploaded file: @@ -58,7 +58,7 @@ NOTE: With Servlet multipart parsing, you may also declare `jakarta.servlet.http instead of Spring's `MultipartFile`, as a method argument or collection value type. You can also use multipart content as part of data binding to a -<>. For example, the form field +xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[command object]. For example, the form field and file from the preceding example could be fields on a form object, as the following example shows: @@ -135,7 +135,7 @@ Content-Transfer-Encoding: 8bit You can access the "meta-data" part with `@RequestParam` as a `String` but you'll probably want it deserialized from JSON (similar to `@RequestBody`). Use the `@RequestPart` annotation to access a multipart after converting it with an -<>: +xref:integration/rest-clients.adoc#rest-message-conversion[HttpMessageConverter]: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc index 135e27908786..d32331c410f2 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc @@ -47,6 +47,6 @@ through `Model` or `RedirectAttributes`. The following example shows how to defi Another way of passing data to the redirect target is by using flash attributes. Unlike other redirect attributes, flash attributes are saved in the HTTP session (and, hence, do -not appear in the URL). See <> for more information. +not appear in the URL). See xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[Flash Attributes] for more information. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc index 35f921cc9179..30858af1c966 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc @@ -1,7 +1,7 @@ [[mvc-ann-requestattrib]] = `@RequestAttribute` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/requestattrib.adoc[See equivalent in the Reactive stack]# Similar to `@SessionAttribute`, you can use the `@RequestAttribute` annotations to access pre-existing request attributes created earlier (for example, by a Servlet `Filter` diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc index e19db56d7dab..b5cc27f47ec0 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc @@ -1,10 +1,10 @@ [[mvc-ann-requestbody]] = `@RequestBody` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/requestbody.adoc[See equivalent in the Reactive stack]# You can use the `@RequestBody` annotation to have the request body read and deserialized into an -`Object` through an <>. +`Object` through an xref:integration/rest-clients.adoc#rest-message-conversion[`HttpMessageConverter`]. The following example uses a `@RequestBody` argument: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -25,7 +25,7 @@ The following example uses a `@RequestBody` argument: ---- -You can use the <> option of the <> to +You can use the xref:web/webmvc/mvc-config/message-converters.adoc[Message Converters] option of the xref:web/webmvc/mvc-config.adoc[MVC Config] to configure or customize message conversion. You can use `@RequestBody` in combination with `jakarta.validation.Valid` or Spring's diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc index b41391ca5ba9..d4ce20b0f8b3 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc @@ -1,7 +1,7 @@ [[mvc-ann-requestheader]] = `@RequestHeader` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/requestheader.adoc[See equivalent in the Reactive stack]# You can use the `@RequestHeader` annotation to bind a request header to a method argument in a controller. @@ -48,7 +48,7 @@ The following example gets the value of the `Accept-Encoding` and `Keep-Alive` h <2> Get the value of the `Keep-Alive` header. If the target method parameter type is not -`String`, type conversion is automatically applied. See <>. +`String`, type conversion is automatically applied. See xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[Type Conversion]. When an `@RequestHeader` annotation is used on a `Map`, `MultiValueMap`, or `HttpHeaders` argument, the map is populated diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc index 3d124f4ee0e6..41b66fe9fa13 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc @@ -1,7 +1,7 @@ [[mvc-ann-requestparam]] = `@RequestParam` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/requestparam.adoc[See equivalent in the Reactive stack]# You can use the `@RequestParam` annotation to bind Servlet request parameters (that is, query parameters or form data) to a method argument in a controller. @@ -59,7 +59,7 @@ a method parameter is optional by setting the `@RequestParam` annotation's `requ `false` or by declaring the argument with an `java.util.Optional` wrapper. Type conversion is automatically applied if the target method parameter type is not -`String`. See <>. +`String`. See xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[Type Conversion]. Declaring the argument type as an array or list allows for resolving multiple parameter values for the same parameter name. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc index 9e16a49a1b10..7462334c47cc 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc @@ -1,11 +1,11 @@ [[mvc-ann-responsebody]] = `@ResponseBody` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/responsebody.adoc[See equivalent in the Reactive stack]# You can use the `@ResponseBody` annotation on a method to have the return serialized to the response body through an -<>. +xref:integration/rest-clients.adoc#rest-message-conversion[HttpMessageConverter]. The following listing shows an example: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -32,12 +32,12 @@ all controller methods. This is the effect of `@RestController`, which is nothin than a meta-annotation marked with `@Controller` and `@ResponseBody`. You can use `@ResponseBody` with reactive types. -See <> and <> for more details. +See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types] for more details. -You can use the <> option of the <> to +You can use the xref:web/webmvc/mvc-config/message-converters.adoc[Message Converters] option of the xref:web/webmvc/mvc-config.adoc[MVC Config] to configure or customize message conversion. You can combine `@ResponseBody` methods with JSON serialization views. -See <> for details. +See xref:web/webmvc/mvc-controller/ann-methods/jackson.adoc[Jackson JSON] for details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc index 46a78dccd7e3..9fb12986a292 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc @@ -1,9 +1,9 @@ [[mvc-ann-responseentity]] = ResponseEntity -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/responseentity.adoc[See equivalent in the Reactive stack]# -`ResponseEntity` is like <> but with status and headers. For example: +`ResponseEntity` is like xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[`@ResponseBody`] but with status and headers. For example: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -26,7 +26,7 @@ } ---- -Spring MVC supports using a single value <> +Spring MVC supports using a single value xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[reactive type] to produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive types for the body. This allows the following types of async responses: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc index 4ac29378d55f..266d6ee1aaae 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc @@ -1,7 +1,7 @@ [[mvc-ann-return-types]] = Return Values -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/return-types.adoc[See equivalent in the Reactive stack]# The next table describes the supported controller method return values. Reactive types are supported for all return values. @@ -12,35 +12,35 @@ supported for all return values. | `@ResponseBody` | The return value is converted through `HttpMessageConverter` implementations and written to the - response. See <>. + response. See xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[`@ResponseBody`]. | `HttpEntity`, `ResponseEntity` | The return value that specifies the full response (including HTTP headers and body) is to be converted through `HttpMessageConverter` implementations and written to the response. - See <>. + See xref:web/webmvc/mvc-controller/ann-methods/responseentity.adoc[ResponseEntity]. | `HttpHeaders` | For returning a response with headers and no body. | `ErrorResponse` | To render an RFC 7807 error response with details in the body, - see <> + see xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses] | `ProblemDetail` | To render an RFC 7807 error response with details in the body, - see <> + see xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses] | `String` | A view name to be resolved with `ViewResolver` implementations and used together with the implicit model -- determined through command objects and `@ModelAttribute` methods. The handler method can also programmatically enrich the model by declaring a `Model` argument - (see <>). + (see xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-registration[Explicit Registrations]). | `View` | A `View` instance to use for rendering together with the implicit model -- determined through command objects and `@ModelAttribute` methods. The handler method can also programmatically enrich the model by declaring a `Model` argument - (see <>). + (see xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-registration[Explicit Registrations]). | `java.util.Map`, `org.springframework.ui.Model` | Attributes to be added to the implicit model, with the view name implicitly determined @@ -60,18 +60,18 @@ supported for all return values. | A method with a `void` return type (or `null` return value) is considered to have fully handled the response if it also has a `ServletResponse`, an `OutputStream` argument, or an `@ResponseStatus` annotation. The same is also true if the controller has made a positive - `ETag` or `lastModified` timestamp check (see <> for details). + `ETag` or `lastModified` timestamp check (see xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[Controllers] for details). If none of the above is true, a `void` return type can also indicate "`no response body`" for REST controllers or a default view name selection for HTML controllers. | `DeferredResult` | Produce any of the preceding return values asynchronously from any thread -- for example, as a - result of some event or callback. See <> and <>. + result of some event or callback. See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-deferredresult[`DeferredResult`]. | `Callable` | Produce any of the above return values asynchronously in a Spring MVC-managed thread. - See <> and <>. + See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-callable[`Callable`]. | `ListenableFuture`, `java.util.concurrent.CompletionStage`, @@ -82,18 +82,18 @@ supported for all return values. | `ResponseBodyEmitter`, `SseEmitter` | Emit a stream of objects asynchronously to be written to the response with `HttpMessageConverter` implementations. Also supported as the body of a `ResponseEntity`. - See <> and <>. + See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-http-streaming[HTTP Streaming]. | `StreamingResponseBody` | Write to the response `OutputStream` asynchronously. Also supported as the body of a - `ResponseEntity`. See <> and <>. + `ResponseEntity`. See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-http-streaming[HTTP Streaming]. | Reactor and other reactive types registered via `ReactiveAdapterRegistry` | A single value type, e.g. `Mono`, is comparable to returning `DeferredResult`. A multi-value type, e.g. `Flux`, may be treated as a stream depending on the requested media type, e.g. "text/event-stream", "application/json+stream", or otherwise is - collected to a List and rendered as a single value. See <> and - <>. + collected to a List and rendered as a single value. See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and + xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types]. | Other return values | If a return value remains unresolved in any other way, it is treated as a model diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc index a205b2ec2ff8..3e5fcad06f6f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc @@ -1,7 +1,7 @@ [[mvc-ann-sessionattribute]] = `@SessionAttribute` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/sessionattribute.adoc[See equivalent in the Reactive stack]# If you need access to pre-existing session attributes that are managed globally (that is, outside the controller -- for example, by a filter) and may or may not be present, @@ -34,6 +34,6 @@ For use cases that require adding or removing session attributes, consider injec For temporary storage of model attributes in the session as part of a controller workflow, consider using `@SessionAttributes` as described in -<>. +xref:web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc index 1163d77211d7..3dcbf3a6d831 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc @@ -1,7 +1,7 @@ [[mvc-ann-sessionattributes]] = `@SessionAttributes` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/sessionattributes.adoc[See equivalent in the Reactive stack]# `@SessionAttributes` is used to store model attributes in the HTTP Servlet session between requests. It is a type-level annotation that declares the session attributes used by a diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc index d876bd7e7f11..fbaf33f89955 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc @@ -1,7 +1,7 @@ [[mvc-ann-typeconversion]] = Type Conversion -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/typeconversion.adoc[See equivalent in the Reactive stack]# Some annotated controller method arguments that represent `String`-based request input (such as `@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) @@ -9,9 +9,9 @@ can require type conversion if the argument is declared as something other than For such cases, type conversion is automatically applied based on the configured converters. By default, simple types (`int`, `long`, `Date`, and others) are supported. You can customize -type conversion through a `WebDataBinder` (see <>) or by registering +type conversion through a `WebDataBinder` (see xref:web/webmvc/mvc-controller/ann-initbinder.adoc[`DataBinder`]) or by registering `Formatters` with the `FormattingConversionService`. -See <>. +See xref:core/validation/format.adoc[Spring Field Formatting]. A practical issue in type conversion is the treatment of an empty String source value. Such a value is treated as missing if it becomes `null` as a result of type conversion. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc index 08a54deef469..fec596077f66 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc @@ -1,11 +1,11 @@ [[mvc-ann-modelattrib-methods]] = Model -[.small]#<># +[.small]#xref:web/webflux/controller/ann-modelattrib-methods.adoc[See equivalent in the Reactive stack]# You can use the `@ModelAttribute` annotation: -* On a <> in `@RequestMapping` methods +* On a xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[method argument] in `@RequestMapping` methods to create or access an `Object` from the model and to bind it to the request through a `WebDataBinder`. * As a method-level annotation in `@Controller` or `@ControllerAdvice` classes that help @@ -16,7 +16,7 @@ This section discusses `@ModelAttribute` methods -- the second item in the prece A controller can have any number of `@ModelAttribute` methods. All such methods are invoked before `@RequestMapping` methods in the same controller. A `@ModelAttribute` method can also be shared across controllers through `@ControllerAdvice`. See the section on -<> for more details. +xref:web/webmvc/mvc-controller/ann-advice.adoc[Controller Advice] for more details. `@ModelAttribute` methods have flexible method signatures. They support many of the same arguments as `@RequestMapping` methods, except for `@ModelAttribute` itself or anything diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc index 30969a6a156c..36b81824db3d 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc @@ -1,7 +1,7 @@ [[mvc-ann-requestmapping]] = Request Mapping -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc[See equivalent in the Reactive stack]# You can use the `@RequestMapping` annotation to map requests to controllers methods. It has various attributes to match by URL, HTTP method, request parameters, headers, and media @@ -16,7 +16,7 @@ There are also HTTP method specific shortcut variants of `@RequestMapping`: * `@DeleteMapping` * `@PatchMapping` -The shortcuts are <> that are provided because, +The shortcuts are xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-composed[Custom Annotations] that are provided because, arguably, most controller methods should be mapped to a specific HTTP method versus using `@RequestMapping`, which, by default, matches to all HTTP methods. A `@RequestMapping` is still needed at the class level to express shared mappings. @@ -66,7 +66,7 @@ The following example has type and method level mappings: [[mvc-ann-requestmapping-uri-templates]] == URI patterns -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-uri-templates[See equivalent in the Reactive stack]# `@RequestMapping` methods can be mapped using URL patterns. There are two alternatives: @@ -80,7 +80,7 @@ challenge for dealing effectively with encoding and other issues with URLs. `PathPattern` is the recommended solution for web applications and it is the only choice in Spring WebFlux. It was enabled for use in Spring MVC from version 5.3 and is enabled by -default from version 6.0. See <> for +default from version 6.0. See xref:web/webmvc/mvc-config/path-matching.adoc[MVC config] for customizations of path matching options. `PathPattern` supports the same pattern syntax as `AntPathMatcher`. In addition, it also @@ -152,7 +152,7 @@ You can declare URI variables at the class and method levels, as the following e URI variables are automatically converted to the appropriate type, or `TypeMismatchException` is raised. Simple types (`int`, `long`, `Date`, and so on) are supported by default and you can register support for any other data type. -See <> and <>. +See xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[Type Conversion] and xref:web/webmvc/mvc-controller/ann-initbinder.adoc[`DataBinder`]. You can explicitly name URI variables (for example, `@PathVariable("customId")`), but you can leave that detail out if the names are the same and your code is compiled with the `-parameters` @@ -188,7 +188,7 @@ some external configuration. [[mvc-ann-requestmapping-pattern-comparison]] == Pattern Comparison -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-pattern-comparison[See equivalent in the Reactive stack]# When multiple patterns match a URL, the best match must be selected. This is done with one of the following depending on whether use of parsed `PathPattern` is enabled for use or not: @@ -229,14 +229,14 @@ and security (see next section for more details) also becomes more difficult. To completely disable the use of path extensions in versions prior to 5.3, set the following: -* `useSuffixPatternMatching(false)`, see <> -* `favorPathExtension(false)`, see <> +* `useSuffixPatternMatching(false)`, see xref:web/webmvc/mvc-config/path-matching.adoc[PathMatchConfigurer] +* `favorPathExtension(false)`, see xref:web/webmvc/mvc-config/content-negotiation.adoc[ContentNegotiationConfigurer] Having a way to request content types other than through the `"Accept"` header can still be useful, e.g. when typing a URL in a browser. A safe alternative to path extensions is to use the query parameter strategy. If you must use file extensions, consider restricting them to a list of explicitly registered extensions through the `mediaTypes` property of -<>. +xref:web/webmvc/mvc-config/content-negotiation.adoc[ContentNegotiationConfigurer]. [[mvc-ann-requestmapping-rfd]] @@ -261,7 +261,7 @@ potentially have side effects when URLs are typed directly into a browser. Many common path extensions are allowed as safe by default. Applications with custom `HttpMessageConverter` implementations can explicitly register file extensions for content negotiation to avoid having a `Content-Disposition` header added for those extensions. -See <>. +See xref:web/webmvc/mvc-config/content-negotiation.adoc[Content Types]. See https://pivotal.io/security/cve-2015-5211[CVE-2015-5211] for additional recommendations related to RFD. @@ -269,7 +269,7 @@ recommendations related to RFD. [[mvc-ann-requestmapping-consumes]] == Consumable Media Types -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-consumes[See equivalent in the Reactive stack]# You can narrow the request mapping based on the `Content-Type` of the request, as the following example shows: @@ -307,7 +307,7 @@ TIP: `MediaType` provides constants for commonly used media types, such as [[mvc-ann-requestmapping-produces]] == Producible Media Types -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-produces[See equivalent in the Reactive stack]# You can narrow the request mapping based on the `Accept` request header and the list of content types that a controller method produces, as the following example shows: @@ -347,7 +347,7 @@ TIP: `MediaType` provides constants for commonly used media types, such as [[mvc-ann-requestmapping-params-and-headers]] == Parameters, headers -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-params-and-headers[See equivalent in the Reactive stack]# You can narrow request mappings based on request parameter conditions. You can test for the presence of a request parameter (`myParam`), for the absence of one (`!myParam`), or for a @@ -396,13 +396,13 @@ You can also use the same with request header conditions, as the following examp <1> Testing whether `myHeader` equals `myValue`. TIP: You can match `Content-Type` and `Accept` with the headers condition, but it is better to use -<> and <> +xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-consumes[consumes] and xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-produces[produces] instead. [[mvc-ann-requestmapping-head-options]] == HTTP HEAD, OPTIONS -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-head-options[See equivalent in the Reactive stack]# `@GetMapping` (and `@RequestMapping(method=HttpMethod.GET)`) support HTTP HEAD transparently for request mapping. Controller methods do not need to change. @@ -428,9 +428,9 @@ is not necessary in the common case. [[mvc-ann-requestmapping-composed]] == Custom Annotations -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-head-options[See equivalent in the Reactive stack]# -Spring MVC supports the use of <> +Spring MVC supports the use of xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[composed annotations] for request mapping. Those are annotations that are themselves meta-annotated with `@RequestMapping` and composed to redeclare a subset (or all) of the `@RequestMapping` attributes with a narrower, more specific purpose. @@ -449,7 +449,7 @@ you can check the custom attribute and return your own `RequestCondition`. [[mvc-ann-requestmapping-registration]] == Explicit Registrations -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-registration[See equivalent in the Reactive stack]# You can programmatically register handler methods, which you can use for dynamic registrations or for advanced cases, such as different instances of the same handler diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc index 3af293ea7ffd..502a3587ad41 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc @@ -1,7 +1,7 @@ [[mvc-ann-controller]] = Declaration -[.small]#<># +[.small]#xref:web/webflux/controller/ann.adoc[See equivalent in the Reactive stack]# You can define controller beans by using a standard Spring bean definition in the Servlet's `WebApplicationContext`. The `@Controller` stereotype allows for auto-detection, @@ -55,7 +55,7 @@ The following example shows the XML configuration equivalent of the preceding ex ---- -`@RestController` is a <> that is +`@RestController` is a xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[composed annotation] that is itself meta-annotated with `@Controller` and `@ResponseBody` to indicate a controller whose every method inherits the type-level `@ResponseBody` annotation and, therefore, writes directly to the response body versus view resolution and rendering with an HTML template. @@ -63,7 +63,7 @@ directly to the response body versus view resolution and rendering with an HTML [[mvc-ann-requestmapping-proxying]] == AOP Proxies -[.small]#<># +[.small]#xref:web/webflux/controller/ann.adoc#webflux-ann-requestmapping-proxying[See equivalent in the Reactive stack]# In some cases, you may need to decorate a controller with an AOP proxy at runtime. One example is if you choose to have `@Transactional` annotations directly on the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc index 2c6f1eb15ae9..429b619ac641 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc @@ -1,7 +1,7 @@ [[mvc-http2]] = HTTP/2 -[.small]#<># +[.small]#xref:web/webflux/http2.adoc[See equivalent in the Reactive stack]# Servlet 4 containers are required to support HTTP/2, and Spring Framework 5 is compatible with Servlet API 4. From a programming model perspective, there is nothing specific that @@ -11,4 +11,4 @@ https://github.com/spring-projects/spring-framework/wiki/HTTP-2-support[HTTP/2 w The Servlet API does expose one construct related to HTTP/2. You can use the `jakarta.servlet.http.PushBuilder` to proactively push resources to clients, and it -is supported as a <> to `@RequestMapping` methods. +is supported as a xref:web/webmvc/mvc-controller/ann-methods/arguments.adoc[method argument] to `@RequestMapping` methods. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc index d7a43f998812..d704b7e176cc 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc @@ -1,7 +1,7 @@ [[mvc-web-security]] = Web Security -[.small]#<># +[.small]#xref:web/webflux/security.adoc[See equivalent in the Reactive stack]# The https://spring.io/projects/spring-security[Spring Security] project provides support for protecting web applications from malicious exploits. See the Spring Security diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc index 4cff137d2671..388084fda2f8 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc @@ -1,7 +1,7 @@ [[mvc-servlet]] = DispatcherServlet -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc[See equivalent in the Reactive stack]# Spring MVC, as many other web frameworks, is designed around the front controller pattern where a central `Servlet`, the `DispatcherServlet`, provides a shared algorithm @@ -12,11 +12,11 @@ The `DispatcherServlet`, as any `Servlet`, needs to be declared and mapped accor to the Servlet specification by using Java configuration or in `web.xml`. In turn, the `DispatcherServlet` uses Spring configuration to discover the delegate components it needs for request mapping, view resolution, exception -handling, <>. +handling, xref:web/webmvc/mvc-servlet/special-bean-types.adoc[and more]. The following example of the Java configuration registers and initializes the `DispatcherServlet`, which is auto-detected by the Servlet container -(see <>): +(see xref:web/webmvc/mvc-servlet/container-config.adoc[Servlet Config]): [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -60,7 +60,7 @@ the `DispatcherServlet`, which is auto-detected by the Servlet container NOTE: In addition to using the ServletContext API directly, you can also extend `AbstractAnnotationConfigDispatcherServletInitializer` and override specific methods -(see the example under <>). +(see the example under xref:web/webmvc/mvc-servlet/context-hierarchy.adoc[Context Hierarchy]). NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an alternative to `AnnotationConfigWebApplicationContext`. See the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc index 86f7aaf0d75a..8a2303344458 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc @@ -1,15 +1,15 @@ [[mvc-servlet-config]] = Web MVC Config -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[See equivalent in the Reactive stack]# -Applications can declare the infrastructure beans listed in <> +Applications can declare the infrastructure beans listed in xref:web/webmvc/mvc-servlet/special-bean-types.adoc[Special Bean Types] that are required to process requests. The `DispatcherServlet` checks the `WebApplicationContext` for each special bean. If there are no matching bean types, it falls back on the default types listed in {spring-framework-main-code}/spring-webmvc/src/main/resources/org/springframework/web/servlet/DispatcherServlet.properties[`DispatcherServlet.properties`]. -In most cases, the <> is the best starting point. It declares the required +In most cases, the xref:web/webmvc/mvc-config.adoc[MVC Config] is the best starting point. It declares the required beans in either Java or XML and provides a higher-level configuration callback API to customize it. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc index 149ab98daf5f..8884cfacc891 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc @@ -11,7 +11,7 @@ For many applications, having a single `WebApplicationContext` is simple and suf It is also possible to have a context hierarchy where one root `WebApplicationContext` is shared across multiple `DispatcherServlet` (or other `Servlet`) instances, each with its own child `WebApplicationContext` configuration. -See <> +See xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`] for more on the context hierarchy feature. The root `WebApplicationContext` typically contains infrastructure beans, such as data repositories and diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc index 2c527e974022..c839fb111529 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc @@ -1,7 +1,7 @@ [[mvc-exceptionhandlers]] = Exceptions -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-dispatcher-exceptions[See equivalent in the Reactive stack]# If an exception occurs during request mapping or is thrown from a request handler (such as a `@Controller`), the `DispatcherServlet` delegates to a chain of `HandlerExceptionResolver` @@ -21,7 +21,7 @@ The following table lists the available `HandlerExceptionResolver` implementatio | {api-spring-framework}/web/servlet/mvc/support/DefaultHandlerExceptionResolver.html[`DefaultHandlerExceptionResolver`] | Resolves exceptions raised by Spring MVC and maps them to HTTP status codes. - See also alternative `ResponseEntityExceptionHandler` and <>. + See also alternative `ResponseEntityExceptionHandler` and xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses]. | `ResponseStatusExceptionResolver` | Resolves exceptions with the `@ResponseStatus` annotation and maps them to HTTP status @@ -29,7 +29,7 @@ The following table lists the available `HandlerExceptionResolver` implementatio | `ExceptionHandlerExceptionResolver` | Resolves exceptions by invoking an `@ExceptionHandler` method in a `@Controller` or a - `@ControllerAdvice` class. See <>. + `@ControllerAdvice` class. See xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc[@ExceptionHandler methods]. |=== @@ -47,7 +47,7 @@ The contract of `HandlerExceptionResolver` specifies that it can return: * `null` if the exception remains unresolved, for subsequent resolvers to try, and, if the exception remains at the end, it is allowed to bubble up to the Servlet container. -The <> automatically declares built-in resolvers for default Spring MVC +The xref:web/webmvc/mvc-config.adoc[MVC Config] automatically declares built-in resolvers for default Spring MVC exceptions, for `@ResponseStatus` annotated exceptions, and for support of `@ExceptionHandler` methods. You can customize that list or replace it. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc index dcf5bc86cdab..95aa38fbd334 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc @@ -18,7 +18,7 @@ assumes the interceptor itself has taken care of requests (and, for example, ren appropriate view) and does not continue executing the other interceptors and the actual handler in the execution chain. -See <> in the section on MVC configuration for examples of how to +See xref:web/webmvc/mvc-config/interceptors.adoc[Interceptors] in the section on MVC configuration for examples of how to configure interceptors. You can also register them directly by using setters on individual `HandlerMapping` implementations. @@ -26,7 +26,7 @@ configure interceptors. You can also register them directly by using setters on which the response is written and committed within the `HandlerAdapter` and before `postHandle`. That means it is too late to make any changes to the response, such as adding an extra header. For such scenarios, you can implement `ResponseBodyAdvice` and either -declare it as an <> bean or configure it directly on +declare it as an xref:web/webmvc/mvc-controller/ann-advice.adoc[Controller Advice] bean or configure it directly on `RequestMappingHandlerAdapter`. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc index 49b35ffda75c..3627ca857e25 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc @@ -22,7 +22,7 @@ default Servlet with `"/"` or otherwise without a prefix with `"/*"` and the Ser container is 4.0+ then Spring MVC is able to detect the Servlet mapping type and avoid use of the `servletPath` and `pathInfo` altogether. On a 3.1 Servlet container, assuming the same Servlet mapping types, the equivalent can be achieved by providing -a `UrlPathHelper` with `alwaysUseFullPath=true` via <> in +a `UrlPathHelper` with `alwaysUseFullPath=true` via xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching] in the MVC config. Fortunately the default Servlet mapping `"/"` is a good choice. However, there is still @@ -45,7 +45,7 @@ sanitizing path segment values individually without the risk of altering the str of the path. Parsed `PathPattern` also supports the use of `servletPath` prefix mapping as long as a Servlet path mapping is used and the prefix is kept simple, i.e. it has no encoded characters. For pattern syntax details and comparison, see -<>. +xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-pattern-comparison[Pattern Comparison]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc index 168385e9dc6a..b489b453149b 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc @@ -10,7 +10,7 @@ finds one, it tries to use it to set the locale. By using the `RequestContext.ge method, you can always retrieve the locale that was resolved by the locale resolver. In addition to automatic locale resolution, you can also attach an interceptor to the -handler mapping (see <> for more information on handler +handler mapping (see xref:web/webmvc/mvc-servlet/handlermapping-interceptor.adoc[Interception] for more information on handler mapping interceptors) to change the locale under specific circumstances (for example, based on a parameter in the request). @@ -19,11 +19,11 @@ Locale resolvers and interceptors are defined in the context in the normal way. The following selection of locale resolvers is included in Spring. -* <> -* <> -* <> -* <> -* <> +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-timezone[Time Zone] +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-localeresolver-acceptheader[Header Resolver] +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-localeresolver-cookie[Cookie Resolver] +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-localeresolver-session[Session Resolver] +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-localeresolver-interceptor[Locale Interceptor] [[mvc-timezone]] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc index d09b90c4dc74..d3ab01eb37eb 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc @@ -1,7 +1,7 @@ [[mvc-logging]] = Logging -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-logging[See equivalent in the Reactive stack]# DEBUG-level logging in Spring MVC is designed to be compact, minimal, and human-friendly. It focuses on high-value bits of information that are useful over and @@ -17,7 +17,7 @@ not meet the stated goals, please let us know. [[mvc-logging-sensitive-data]] == Sensitive Data -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-logging-sensitive-data[See equivalent in the Reactive stack]# DEBUG and TRACE logging may log sensitive information. This is why request parameters and headers are masked by default and their logging in full must be enabled explicitly diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc index d9eec04f118f..a0dfe886c6dd 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc @@ -1,7 +1,7 @@ [[mvc-multipart]] = Multipart Resolver -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-multipart[See equivalent in the Reactive stack]# `MultipartResolver` from the `org.springframework.web.multipart` package is a strategy for parsing multipart requests including file uploads. There is a container-based diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc index e1577db64538..a640ef3fd869 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc @@ -1,7 +1,7 @@ [[mvc-servlet-sequence]] = Processing -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-dispatcher-handler-sequence[See equivalent in the Reactive stack]# The `DispatcherServlet` processes requests as follows: @@ -15,7 +15,7 @@ The `DispatcherServlet` processes requests as follows: which theme to use. If you do not use themes, you can ignore it. * If you specify a multipart file resolver, the request is inspected for multiparts. If multiparts are found, the request is wrapped in a `MultipartHttpServletRequest` for - further processing by other elements in the process. See <> for further + further processing by other elements in the process. See xref:web/webmvc/mvc-servlet/multipart.adoc[Multipart Resolver] for further information about multipart handling. * An appropriate handler is searched for. If a handler is found, the execution chain associated with the handler (preprocessors, postprocessors, and controllers) is @@ -28,11 +28,11 @@ The `DispatcherServlet` processes requests as follows: The `HandlerExceptionResolver` beans declared in the `WebApplicationContext` are used to resolve exceptions thrown during request processing. Those exception resolvers allow -customizing the logic to address exceptions. See <> for more details. +customizing the logic to address exceptions. See xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[Exceptions] for more details. For HTTP caching support, handlers can use the `checkNotModified` methods of `WebRequest`, along with further options for annotated controllers as described in -<>. +xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[HTTP Caching for Controllers]. You can customize individual `DispatcherServlet` instances by adding Servlet initialization parameters (`init-param` elements) to the Servlet declaration in the @@ -65,7 +65,7 @@ initialization parameters (`init-param` elements) to the Servlet declaration in By default, this is set to `false`, in which case the `DispatcherServlet` sets the response status to 404 (NOT_FOUND) without raising an exception. - Note that, if <> is + Note that, if xref:web/webmvc/mvc-config/default-servlet-handler.adoc[default servlet handling] is also configured, unresolved requests are always forwarded to the default servlet and a 404 is never raised. |=== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc index c9a650490f59..edb52264bead 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc @@ -1,7 +1,7 @@ [[mvc-servlet-special-bean-types]] = Special Bean Types -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[See equivalent in the Reactive stack]# The `DispatcherServlet` delegates to special beans to process requests and render the appropriate responses. By "`special beans`" we mean Spring-managed `Object` instances that @@ -17,7 +17,7 @@ The following table lists the special beans detected by the `DispatcherServlet`: | `HandlerMapping` | Map a request to a handler along with a list of - <> for pre- and post-processing. + xref:web/webmvc/mvc-servlet/handlermapping-interceptor.adoc[interceptors] for pre- and post-processing. The mapping is based on some criteria, the details of which vary by `HandlerMapping` implementation. @@ -31,30 +31,30 @@ The following table lists the special beans detected by the `DispatcherServlet`: requires resolving annotations. The main purpose of a `HandlerAdapter` is to shield the `DispatcherServlet` from such details. -| <> +| xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[`HandlerExceptionResolver`] | Strategy to resolve exceptions, possibly mapping them to handlers, to HTML error - views, or other targets. See <>. + views, or other targets. See xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[Exceptions]. -| <> +| xref:web/webmvc/mvc-servlet/viewresolver.adoc[`ViewResolver`] | Resolve logical `String`-based view names returned from a handler to an actual `View` - with which to render to the response. See <> and <>. + with which to render to the response. See xref:web/webmvc/mvc-servlet/viewresolver.adoc[View Resolution] and xref:web/webmvc-view.adoc[View Technologies]. -| <>, <> +| xref:web/webmvc/mvc-servlet/localeresolver.adoc[`LocaleResolver`], xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-timezone[LocaleContextResolver] | Resolve the `Locale` a client is using and possibly their time zone, in order to be able - to offer internationalized views. See <>. + to offer internationalized views. See xref:web/webmvc/mvc-servlet/localeresolver.adoc[Locale]. -| <> +| xref:web/webmvc/mvc-servlet/themeresolver.adoc[`ThemeResolver`] | Resolve themes your web application can use -- for example, to offer personalized layouts. - See <>. + See xref:web/webmvc/mvc-servlet/themeresolver.adoc[Themes]. -| <> +| xref:web/webmvc/mvc-servlet/multipart.adoc[`MultipartResolver`] | Abstraction for parsing a multi-part request (for example, browser form file upload) with - the help of some multipart parsing library. See <>. + the help of some multipart parsing library. See xref:web/webmvc/mvc-servlet/multipart.adoc[Multipart Resolver]. -| <> +| xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[`FlashMapManager`] | Store and retrieve the "`input`" and the "`output`" `FlashMap` that can be used to pass attributes from one request to another, usually across a redirect. - See <>. + See xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[Flash Attributes]. |=== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc index 83f9f81a8eba..fc4bc9a10301 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc @@ -62,7 +62,7 @@ background image with Dutch text on it. [[mvc-themeresolver-resolving]] == Resolving Themes -After you define themes, as described in the <>, +After you define themes, as described in the xref:web/webmvc/mvc-servlet/themeresolver.adoc#mvc-themeresolver-defining[preceding section], you decide which theme to use. The `DispatcherServlet` looks for a bean named `themeResolver` to find out which `ThemeResolver` implementation to use. A theme resolver works in much the same way as a `LocaleResolver`. It detects the theme to use for a particular request and can also diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc index f4bf8270ceb0..96d9ceb063e1 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc @@ -1,7 +1,7 @@ [[mvc-viewresolver]] = View Resolution -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution[See equivalent in the Reactive stack]# Spring MVC defines the `ViewResolver` and `View` interfaces that let you render models in a browser without tying you to a specific view technology. `ViewResolver` @@ -41,7 +41,7 @@ The following table provides more details on the `ViewResolver` hierarchy: | `ContentNegotiatingViewResolver` | Implementation of the `ViewResolver` interface that resolves a view based on the - request file name or `Accept` header. See <>. + request file name or `Accept` header. See xref:web/webmvc/mvc-servlet/viewresolver.adoc#mvc-multiple-representations[Content Negotiation]. | `BeanNameViewResolver` | Implementation of the `ViewResolver` interface that interprets a view name as a @@ -53,7 +53,7 @@ The following table provides more details on the `ViewResolver` hierarchy: [[mvc-viewresolver-handling]] == Handling -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution-handling[See equivalent in the Reactive stack]# You can chain view resolvers by declaring more than one resolver bean and, if necessary, by setting the `order` property to specify ordering. Remember, the higher the order property, @@ -66,15 +66,15 @@ the only way to figure out if a JSP exists is to perform a dispatch through to be last in the overall order of view resolvers. Configuring view resolution is as simple as adding `ViewResolver` beans to your Spring -configuration. The <> provides a dedicated configuration API for -<> and for adding logic-less -<> which are useful for HTML template +configuration. The xref:web/webmvc/mvc-config.adoc[MVC Config] provides a dedicated configuration API for +xref:web/webmvc/mvc-config/view-resolvers.adoc[View Resolvers] and for adding logic-less +xref:web/webmvc/mvc-config/view-controller.adoc[View Controllers] which are useful for HTML template rendering without controller logic. [[mvc-redirecting-redirect-prefix]] == Redirecting -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-redirecting-redirect-prefix[See equivalent in the Reactive stack]# The special `redirect:` prefix in a view name lets you perform a redirect. The `UrlBasedViewResolver` (and its subclasses) recognize this as an instruction that a @@ -104,7 +104,7 @@ Servlet/JSP engine. Note that you may also chain multiple view resolvers, instea [[mvc-multiple-representations]] == Content Negotiation -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-multiple-representations[See equivalent in the Reactive stack]# {api-spring-framework}/web/servlet/view/ContentNegotiatingViewResolver.html[`ContentNegotiatingViewResolver`] does not resolve views itself but rather delegates @@ -123,7 +123,7 @@ representation of the current resource regardless of the logical view name. The header can include wildcards (for example `text/{asterisk}`), in which case a `View` whose `Content-Type` is `text/xml` is a compatible match. -See <> under <> for configuration details. +See xref:web/webmvc/mvc-config/view-resolvers.adoc[View Resolvers] under xref:web/webmvc/mvc-config.adoc[MVC Config] for configuration details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc index e2cadde805bf..235652b98492 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc @@ -1,7 +1,7 @@ [[mvc-uri-building]] = URI Links -[.small]#<># +[.small]#xref:web/webflux/uri-building.adoc[See equivalent in the Reactive stack]# This section describes various options available in the Spring Framework to work with URI's. @@ -95,7 +95,7 @@ as the following example shows: NOTE: As of 5.1, `ServletUriComponentsBuilder` ignores information from the `Forwarded` and `X-Forwarded-*` headers, which specify the client-originated address. Consider using the -<> to extract and use or to discard +xref:web/webmvc/filters.adoc#filters-forwarded-headers[`ForwardedHeaderFilter`] to extract and use or to discard such headers. @@ -221,7 +221,7 @@ following listing uses `withMethodCall`: NOTE: As of 5.1, `MvcUriComponentsBuilder` ignores information from the `Forwarded` and `X-Forwarded-*` headers, which specify the client-originated address. Consider using the -<> to extract and use or to discard +xref:web/webmvc/filters.adoc#filters-forwarded-headers[ForwardedHeaderFilter] to extract and use or to discard such headers. diff --git a/framework-docs/modules/ROOT/pages/web/websocket.adoc b/framework-docs/modules/ROOT/pages/web/websocket.adoc index c429f5fe70ac..79665ef428b9 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket.adoc @@ -1,6 +1,6 @@ [[websocket]] = WebSockets -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc[See equivalent in the Reactive stack]# This part of the reference documentation covers support for Servlet stack, WebSocket messaging that includes raw WebSocket interactions, WebSocket emulation through SockJS, and diff --git a/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc b/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc index 477f291c6835..f565c2250a10 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc @@ -127,7 +127,7 @@ The following example shows the XML configuration equivalent of the preceding ex ---- The preceding example is for use in Spring MVC applications and should be included in the -configuration of a <>. However, Spring's WebSocket +configuration of a xref:web/webmvc/mvc-servlet.adoc[`DispatcherServlet`]. However, Spring's WebSocket and SockJS support does not depend on Spring MVC. It is relatively simple to integrate into other HTTP serving environments with the help of {api-spring-framework}/web/socket/sockjs/support/SockJsHttpRequestHandler.html[`SockJsHttpRequestHandler`]. @@ -273,7 +273,7 @@ log category to TRACE. [[websocket-fallback-cors]] == SockJS and CORS -If you allow cross-origin requests (see <>), the SockJS protocol +If you allow cross-origin requests (see xref:web/websocket/server.adoc#websocket-server-allowed-origins[Allowed Origins]), the SockJS protocol uses CORS for cross-domain support in the XHR streaming and polling transports. Therefore, CORS headers are added automatically, unless the presence of CORS headers in the response is detected. So, if an application is already configured to provide CORS support (for example, diff --git a/framework-docs/modules/ROOT/pages/web/websocket/server.adoc b/framework-docs/modules/ROOT/pages/web/websocket/server.adoc index a67bbac5fa2f..653f944dfc08 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/server.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/server.adoc @@ -1,7 +1,7 @@ [[websocket-server]] = WebSocket API -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server[See equivalent in the Reactive stack]# The Spring Framework provides a WebSocket API that you can use to write client- and server-side applications that handle WebSocket messages. @@ -10,7 +10,7 @@ server-side applications that handle WebSocket messages. [[websocket-server-handler]] == `WebSocketHandler` -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-handler[See equivalent in the Reactive stack]# Creating a WebSocket server is as simple as implementing `WebSocketHandler` or, more likely, extending either `TextWebSocketHandler` or `BinaryWebSocketHandler`. The following @@ -81,13 +81,13 @@ The following example shows the XML configuration equivalent of the preceding ex ---- The preceding example is for use in Spring MVC applications and should be included -in the configuration of a <>. However, Spring's +in the configuration of a xref:web/webmvc/mvc-servlet.adoc[`DispatcherServlet`]. However, Spring's WebSocket support does not depend on Spring MVC. It is relatively simple to integrate a `WebSocketHandler` into other HTTP-serving environments with the help of {api-spring-framework}/web/socket/server/support/WebSocketHttpRequestHandler.html[`WebSocketHttpRequestHandler`]. When using the `WebSocketHandler` API directly vs indirectly, e.g. through the -<> messaging, the application must synchronize the sending of messages +xref:web/websocket/stomp.adoc[STOMP] messaging, the application must synchronize the sending of messages since the underlying standard WebSocket session (JSR-356) does not allow concurrent sending. One option is to wrap the `WebSocketSession` with {api-spring-framework}/web/socket/handler/ConcurrentWebSocketSessionDecorator.html[`ConcurrentWebSocketSessionDecorator`]. @@ -96,7 +96,7 @@ sending. One option is to wrap the `WebSocketSession` with [[websocket-server-handshake]] == WebSocket Handshake -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-handshake[See equivalent in the Reactive stack]# The easiest way to customize the initial HTTP WebSocket handshake request is through a `HandshakeInterceptor`, which exposes methods for "`before`" and "`after`" the handshake. @@ -149,7 +149,7 @@ the steps of the WebSocket handshake, including validating the client origin, negotiating a sub-protocol, and other details. An application may also need to use this option if it needs to configure a custom `RequestUpgradeStrategy` in order to adapt to a WebSocket server engine and version that is not yet supported -(see <> for more on this subject). +(see xref:web/websocket/server.adoc#websocket-server-deployment[Deployment] for more on this subject). Both the Java configuration and XML namespace make it possible to configure a custom `HandshakeHandler`. @@ -230,7 +230,7 @@ Java initialization API. The following example shows how to do so: [[websocket-server-runtime-configuration]] == Server Configuration -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-config[See equivalent in the Reactive stack]# Each underlying WebSocket engine exposes configuration properties that control runtime characteristics, such as the size of message buffer sizes, idle timeout, @@ -353,7 +353,7 @@ The following example shows the XML configuration equivalent of the preceding ex [[websocket-server-allowed-origins]] == Allowed Origins -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-cors[See equivalent in the Reactive stack]# As of Spring Framework 4.1.5, the default behavior for WebSocket and SockJS is to accept only same-origin requests. It is also possible to allow all or a specified list of origins. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc index 49c95b8f0d89..a4bcb1fdff13 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc @@ -7,7 +7,7 @@ made about HTTP versus raw TCP and how it lets Spring MVC and other web framewor provide rich functionality. The following is a list of benefits: * No need to invent a custom messaging protocol and message format. -* STOMP clients, including a <> +* STOMP clients, including a xref:web/websocket/stomp/client.adoc[Java client] in the Spring Framework, are available. * You can (optionally) use message brokers (such as RabbitMQ, ActiveMQ, and others) to manage subscriptions and broadcast messages. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc index 03b7a0c283d7..1eae09021206 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc @@ -16,7 +16,7 @@ To begin, you can create and configure `WebSocketStompClient`, as the following In the preceding example, you could replace `StandardWebSocketClient` with `SockJsClient`, since that is also an implementation of `WebSocketClient`. The `SockJsClient` can use WebSocket or HTTP-based transport as a fallback. For more details, see -<>. +xref:web/websocket/fallback.adoc#websocket-fallback-sockjs-client[`SockJsClient`]. Next, you can establish a connection and provide a handler for the STOMP session, as the following example shows: @@ -80,7 +80,7 @@ closes the connection). other messages are sent. This can present a challenge when using an external broker since messages with a non-broker destination represent activity but aren't actually forwarded to the broker. In that case you can configure a `TaskScheduler` -when initializing the <> which ensures a +when initializing the xref:web/websocket/stomp/handle-broker-relay.adoc[External Broker] which ensures a heartbeat is forwarded to the broker also when only messages with a non-broker destination are sent. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc index c15c6c4f4070..aa0017e093dc 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc @@ -11,7 +11,7 @@ on how to reason about scaling. In a messaging application, messages are passed through channels for asynchronous executions that are backed by thread pools. Configuring such an application requires good knowledge of the channels and the flow of messages. Therefore, it is -recommended to review <>. +recommended to review xref:web/websocket/stomp/message-flow.adoc[Flow of Messages]. The obvious place to start is to configure the thread pools that back the `clientInboundChannel` and the `clientOutboundChannel`. By default, both diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc index 10a3dc470f78..16dc4ce382eb 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc @@ -3,7 +3,7 @@ STOMP over WebSocket support is available in the `spring-messaging` and `spring-websocket` modules. Once you have those dependencies, you can expose a STOMP -endpoints, over WebSocket with <>, as the following example shows: +endpoints, over WebSocket with xref:web/websocket/fallback.adoc[SockJS Fallback], as the following example shows: [source,java,indent=0,subs="verbatim,quotes"] ---- @@ -95,8 +95,8 @@ Alternatively, if you connect through WebSocket (without SockJS), you can use th Note that `stompClient` in the preceding example does not need to specify `login` and `passcode` headers. Even if it did, they would be ignored (or, rather, -overridden) on the server side. See <> -and <> for more information on authentication. +overridden) on the server side. See xref:web/websocket/stomp/handle-broker-relay-configure.adoc[Connecting to a Broker] +and xref:web/websocket/stomp/authentication.adoc[Authentication] for more information on authentication. For more example code see: diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc index 6eaf09f96bf4..7479fd6dc979 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc @@ -5,9 +5,9 @@ Applications can use annotated `@Controller` classes to handle messages from cli Such classes can declare `@MessageMapping`, `@SubscribeMapping`, and `@ExceptionHandler` methods, as described in the following topics: -* <> -* <> -* <> +* xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-message-mapping[`@MessageMapping`] +* xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-subscribe-mapping[`@SubscribeMapping`] +* xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-exception-handler[`@MessageExceptionHandler`] [[websocket-stomp-message-mapping]] @@ -22,7 +22,7 @@ By default, the mapping values are Ant-style path patterns (for example `/thing* including support for template variables (for example, pass:q[`/thing/{id}`]). The values can be referenced through `@DestinationVariable` method arguments. Applications can also switch to a dot-separated destination convention for mappings, as explained in -<>. +xref:web/websocket/stomp/destination-separator.adoc[Dots as Separators]. [[supported-method-arguments]] === Supported Method Arguments @@ -80,7 +80,7 @@ same as that of the inbound message but prefixed with `/topic`. You can use the `@SendTo` and `@SendToUser` annotations to customize the destination of the output message. `@SendTo` is used to customize the target destination or to specify multiple destinations. `@SendToUser` is used to direct the output message -to only the user associated with the input message. See <>. +to only the user associated with the input message. See xref:web/websocket/stomp/user-destination.adoc[User Destinations]. You can use both `@SendTo` and `@SendToUser` at the same time on the same method, and both are supported at the class level, in which case they act as a default for methods in the @@ -94,7 +94,7 @@ Note that `@SendTo` and `@SendToUser` are merely a convenience that amounts to u `SimpMessagingTemplate` to send messages. If necessary, for more advanced scenarios, `@MessageMapping` methods can fall back on using the `SimpMessagingTemplate` directly. This can be done instead of, or possibly in addition to, returning a value. -See <>. +See xref:web/websocket/stomp/handle-send.adoc[Sending Messages]. [[websocket-stomp-subscribe-mapping]] @@ -102,7 +102,7 @@ See <>. `@SubscribeMapping` is similar to `@MessageMapping` but narrows the mapping to subscription messages only. It supports the same -<> as `@MessageMapping`. However +xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-message-mapping[method arguments] as `@MessageMapping`. However for the return value, by default, a message is sent directly to the client (through `clientOutboundChannel`, in response to the subscription) and not to the broker (through `brokerChannel`, as a broadcast to matching subscriptions). Adding `@SendTo` or @@ -123,7 +123,7 @@ for some reason. Inbound messages are handled in parallel. There are no guarante a broker or a controller processes a given message first. If the goal is to be notified when a subscription is stored and ready for broadcasts, a client should ask for a receipt if the server supports it (simple broker does not). For example, with the Java -<>, you could do the following to add a receipt: +xref:web/websocket/stomp/client.adoc[STOMP client], you could do the following to add a receipt: [source,java,indent=0,subs="verbatim,quotes"] ---- @@ -143,7 +143,7 @@ receipt if the server supports it (simple broker does not). For example, with th }); ---- -A server side option is <> an +A server side option is xref:web/websocket/stomp/interceptors.adoc[to register] an `ExecutorChannelInterceptor` on the `brokerChannel` and implement the `afterMessageHandled` method that is invoked after messages, including subscriptions, have been handled. @@ -173,13 +173,13 @@ The following example declares an exception through a method argument: `@MessageExceptionHandler` methods support flexible method signatures and support the same method argument types and return values as -<> methods. +xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-message-mapping[`@MessageMapping`] methods. Typically, `@MessageExceptionHandler` methods apply within the `@Controller` class (or class hierarchy) in which they are declared. If you want such methods to apply more globally (across controllers), you can declare them in a class marked with `@ControllerAdvice`. This is comparable to the -<> available in Spring MVC. +xref:web/webmvc/mvc-controller/ann-advice.adoc[similar support] available in Spring MVC. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc index 84d61cc03a48..853732b6000d 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc @@ -16,7 +16,7 @@ values of `guest` and `guest`. NOTE: The STOMP broker relay always sets the `login` and `passcode` headers on every `CONNECT` frame that it forwards to the broker on behalf of clients. Therefore, WebSocket clients -need not set those headers. They are ignored. As the <> +need not set those headers. They are ignored. As the xref:web/websocket/stomp/authentication.adoc[Authentication] section explains, WebSocket clients should instead rely on HTTP authentication to protect the WebSocket endpoint and establish the client identity. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc index 245c85b5871a..8db28f6dd504 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc @@ -71,7 +71,7 @@ dependencies to your project for TCP connection management. Furthermore, application components (such as HTTP request handling methods, business services, and others) can also send messages to the broker relay, as described -in <>, to broadcast messages to subscribed WebSocket clients. +in xref:web/websocket/stomp/handle-send.adoc[Sending Messages], to broadcast messages to subscribed WebSocket clients. In effect, the broker relay enables robust and scalable message broadcasting. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc index d8803a980236..5be3fdb6ae22 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc @@ -7,7 +7,7 @@ destinations. The broker supports path-like destinations, including subscription to Ant-style destination patterns. NOTE: Applications can also use dot-separated (rather than slash-separated) destinations. -See <>. +See xref:web/websocket/stomp/destination-separator.adoc[Dots as Separators]. If configured with a task scheduler, the simple broker supports https://stomp.github.io/stomp-specification-1.2.html#Heart-beating[STOMP heartbeats]. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc index 8c6d0db145e9..7a21a1b8d40d 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc @@ -1,7 +1,7 @@ [[websocket-stomp-interceptors]] = Interception -<> provide notifications for the lifecycle +xref:web/websocket/stomp/application-context-events.adoc[Events] provide notifications for the lifecycle of a STOMP connection but not for every client message. Applications can also register a `ChannelInterceptor` to intercept any message and in any part of the processing chain. The following example shows how to intercept inbound messages from clients: diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc index 119db2b62b91..92538177177f 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc @@ -2,7 +2,7 @@ = WebSocket Server To configure the underlying WebSocket server, the information in -<> applies. For Jetty, however you need to set +xref:web/websocket/server.adoc#websocket-server-runtime-configuration[Server Configuration] applies. For Jetty, however you need to set the `HandshakeHandler` and `WebSocketPolicy` through the `StompEndpointRegistry`: [source,java,indent=0,subs="verbatim,quotes"] diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc index 7dd0ceb1189a..84fef9ffb797 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc @@ -11,7 +11,7 @@ at the same time, ensuring no collisions with other users who subscribe to the s destination so that each user can receive unique stock position updates. TIP: When working with user destinations, it is important to configure broker and -application destination prefixes as shown in <>, or otherwise the +application destination prefixes as shown in xref:web/websocket/stomp/enable.adoc[Enable STOMP], or otherwise the broker would handle "/user" prefixed messages that should only be handled by `UserDestinationMessageHandler`. From 8ed12453c6402fd0591613f36e88dace266cc9e8 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:26:17 -0500 Subject: [PATCH 15/31] Enable Section Summary TOC for small pages --- framework-docs/modules/ROOT/pages/core/aop-api.adoc | 1 + framework-docs/modules/ROOT/pages/core/aop-api/advisor.adoc | 1 + .../modules/ROOT/pages/core/aop-api/extensibility.adoc | 1 + framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc | 1 + .../modules/ROOT/pages/core/aop/introduction-proxies.adoc | 1 + framework-docs/modules/ROOT/pages/core/aop/mixing-styles.adoc | 1 + framework-docs/modules/ROOT/pages/core/aop/resources.adoc | 1 + framework-docs/modules/ROOT/pages/core/appendix.adoc | 1 + framework-docs/modules/ROOT/pages/core/beans.adoc | 1 + framework-docs/modules/ROOT/pages/core/beans/dependencies.adoc | 1 + framework-docs/modules/ROOT/pages/core/beans/java.adoc | 1 + .../modules/ROOT/pages/core/expressions/language-ref.adoc | 1 + framework-docs/modules/ROOT/pages/data-access.adoc | 1 + framework-docs/modules/ROOT/pages/data-access/orm.adoc | 1 + .../modules/ROOT/pages/data-access/transaction/resources.adoc | 1 + .../data-access/transaction/solutions-to-common-problems.adoc | 1 + .../ROOT/pages/data-access/transaction/tx-decl-vs-prog.adoc | 1 + framework-docs/modules/ROOT/pages/integration.adoc | 1 + framework-docs/modules/ROOT/pages/integration/cache.adoc | 1 + framework-docs/modules/ROOT/pages/integration/cache/plug.adoc | 1 + .../modules/ROOT/pages/integration/cache/specific-config.adoc | 1 + framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc | 1 + framework-docs/modules/ROOT/pages/languages.adoc | 1 + framework-docs/modules/ROOT/pages/languages/groovy.adoc | 1 + framework-docs/modules/ROOT/pages/languages/kotlin.adoc | 1 + .../modules/ROOT/pages/languages/kotlin/classes-interfaces.adoc | 1 + .../modules/ROOT/pages/languages/kotlin/requirements.adoc | 1 + framework-docs/modules/ROOT/pages/testing.adoc | 1 + framework-docs/modules/ROOT/pages/testing/annotations.adoc | 1 + .../annotations/integration-spring/annotation-bootstrapwith.adoc | 1 + .../integration-spring/annotation-recordapplicationevents.adoc | 1 + framework-docs/modules/ROOT/pages/testing/appendix.adoc | 1 + framework-docs/modules/ROOT/pages/testing/introduction.adoc | 1 + .../modules/ROOT/pages/testing/spring-mvc-test-framework.adoc | 1 + .../pages/testing/spring-mvc-test-framework/server-filters.adoc | 1 + .../pages/testing/spring-mvc-test-framework/server-htmlunit.adoc | 1 + .../testing/spring-mvc-test-framework/server-resources.adoc | 1 + .../testing/spring-mvc-test-framework/server-static-imports.adoc | 1 + .../ROOT/pages/testing/spring-mvc-test-framework/server.adoc | 1 + .../modules/ROOT/pages/testing/testcontext-framework.adoc | 1 + framework-docs/modules/ROOT/pages/web.adoc | 1 + framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc | 1 + .../modules/ROOT/pages/web/webflux-webclient/client-testing.adoc | 1 + framework-docs/modules/ROOT/pages/web/webflux.adoc | 1 + .../modules/ROOT/pages/web/webflux/controller/ann-methods.adoc | 1 + .../pages/web/webflux/controller/ann-methods/typeconversion.adoc | 1 + framework-docs/modules/ROOT/pages/web/webflux/http2.adoc | 1 + framework-docs/modules/ROOT/pages/web/webflux/security.adoc | 1 + framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc | 1 + framework-docs/modules/ROOT/pages/web/webmvc-view.adoc | 1 + .../modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc | 1 + .../modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc | 1 + framework-docs/modules/ROOT/pages/web/webmvc.adoc | 1 + framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc | 1 + .../ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc | 1 + framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc | 1 + framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc | 1 + .../modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc | 1 + framework-docs/modules/ROOT/pages/web/websocket.adoc | 1 + framework-docs/modules/ROOT/pages/web/websocket/stomp.adoc | 1 + .../modules/ROOT/pages/web/websocket/stomp/authorization.adoc | 1 + .../modules/ROOT/pages/web/websocket/stomp/benefits.adoc | 1 + 62 files changed, 62 insertions(+) diff --git a/framework-docs/modules/ROOT/pages/core/aop-api.adoc b/framework-docs/modules/ROOT/pages/core/aop-api.adoc index c3c3e571f8fe..e159cf1867df 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api.adoc @@ -1,5 +1,6 @@ [[aop-api]] = Spring AOP APIs +:page-section-summary-toc: 1 The previous chapter described the Spring's support for AOP with @AspectJ and schema-based aspect definitions. In this chapter, we discuss the lower-level Spring AOP APIs. For common diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/advisor.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/advisor.adoc index 8bdccc6a73f3..2eac05210854 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/advisor.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/advisor.adoc @@ -1,5 +1,6 @@ [[aop-api-advisor]] = The Advisor API in Spring +:page-section-summary-toc: 1 In Spring, an Advisor is an aspect that contains only a single advice object associated with a pointcut expression. diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/extensibility.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/extensibility.adoc index b6b9eb683059..8882dfd2da52 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/extensibility.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/extensibility.adoc @@ -1,5 +1,6 @@ [[aop-extensibility]] = Defining New Advice Types +:page-section-summary-toc: 1 Spring AOP is designed to be extensible. While the interception implementation strategy is presently used internally, it is possible to support arbitrary advice types in diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc index 7adfe44de78f..952aca1f76c3 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc @@ -1,5 +1,6 @@ [[aop-ataspectj]] = @AspectJ support +:page-section-summary-toc: 1 @AspectJ refers to a style of declaring aspects as regular Java classes annotated with annotations. The @AspectJ style was introduced by the diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc index de27700eaa3b..d13db9196853 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc @@ -1,5 +1,6 @@ [[aop-introduction-proxies]] = AOP Proxies +:page-section-summary-toc: 1 Spring AOP defaults to using standard JDK dynamic proxies for AOP proxies. This enables any interface (or set of interfaces) to be proxied. diff --git a/framework-docs/modules/ROOT/pages/core/aop/mixing-styles.adoc b/framework-docs/modules/ROOT/pages/core/aop/mixing-styles.adoc index 5b1bb3201882..84bb7c41ada0 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/mixing-styles.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/mixing-styles.adoc @@ -1,5 +1,6 @@ [[aop-mixing-styles]] = Mixing Aspect Types +:page-section-summary-toc: 1 It is perfectly possible to mix @AspectJ style aspects by using the auto-proxying support, schema-defined `` aspects, `` declared advisors, and even proxies diff --git a/framework-docs/modules/ROOT/pages/core/aop/resources.adoc b/framework-docs/modules/ROOT/pages/core/aop/resources.adoc index 8de6cc35808a..e95cb1f99559 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/resources.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/resources.adoc @@ -1,5 +1,6 @@ [[aop-resources]] = Further Resources +:page-section-summary-toc: 1 More information on AspectJ can be found on the https://www.eclipse.org/aspectj[AspectJ website]. diff --git a/framework-docs/modules/ROOT/pages/core/appendix.adoc b/framework-docs/modules/ROOT/pages/core/appendix.adoc index 5993dea520cc..deaf39c5c680 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix.adoc @@ -1,5 +1,6 @@ [[core.appendix]] = Appendix +:page-section-summary-toc: 1 diff --git a/framework-docs/modules/ROOT/pages/core/beans.adoc b/framework-docs/modules/ROOT/pages/core/beans.adoc index f5b17d5fe462..7def6a8c23a0 100644 --- a/framework-docs/modules/ROOT/pages/core/beans.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans.adoc @@ -1,5 +1,6 @@ [[beans]] = The IoC Container +:page-section-summary-toc: 1 This chapter covers Spring's Inversion of Control (IoC) container. diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies.adoc index aa670335d810..e22058a1ff3b 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies.adoc @@ -1,5 +1,6 @@ [[beans-dependencies]] = Dependencies +:page-section-summary-toc: 1 A typical enterprise application does not consist of a single object (or bean in the Spring parlance). Even the simplest application has a few objects that work together to diff --git a/framework-docs/modules/ROOT/pages/core/beans/java.adoc b/framework-docs/modules/ROOT/pages/core/beans/java.adoc index 146880ab0523..9cb9f492b6e7 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java.adoc @@ -1,5 +1,6 @@ [[beans-java]] = Java-based Container Configuration +:page-section-summary-toc: 1 This section covers how to use annotations in your Java code to configure the Spring container. It includes the following topics: diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc index c6c7e138d039..f920ac60470e 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc @@ -1,5 +1,6 @@ [[expressions-language-ref]] = Language Reference +:page-section-summary-toc: 1 This section describes how the Spring Expression Language works. It covers the following topics: diff --git a/framework-docs/modules/ROOT/pages/data-access.adoc b/framework-docs/modules/ROOT/pages/data-access.adoc index 0c13876f245c..df232e910faf 100644 --- a/framework-docs/modules/ROOT/pages/data-access.adoc +++ b/framework-docs/modules/ROOT/pages/data-access.adoc @@ -1,5 +1,6 @@ [[spring-data-tier]] = Data Access +:page-section-summary-toc: 1 This part of the reference documentation is concerned with data access and the interaction between the data access layer and the business or service layer. diff --git a/framework-docs/modules/ROOT/pages/data-access/orm.adoc b/framework-docs/modules/ROOT/pages/data-access/orm.adoc index 5bf7a8ea176f..c4f0acb9c867 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm.adoc @@ -1,5 +1,6 @@ [[orm]] = Object Relational Mapping (ORM) Data Access +:page-section-summary-toc: 1 This section covers data access when you use Object Relational Mapping (ORM). diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/resources.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/resources.adoc index 62672974575f..ca14bac7e4e4 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/resources.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/resources.adoc @@ -1,5 +1,6 @@ [[transaction-resources]] = Further Resources +:page-section-summary-toc: 1 For more information about the Spring Framework's transaction support, see: diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc index 2c5ecd6e66ec..669760b534fb 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc @@ -1,5 +1,6 @@ [[transaction-solutions-to-common-problems]] = Solutions to Common Problems +:page-section-summary-toc: 1 This section describes solutions to some common problems. diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/tx-decl-vs-prog.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/tx-decl-vs-prog.adoc index b90bd9b0ff17..ece5dd419cf9 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/tx-decl-vs-prog.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/tx-decl-vs-prog.adoc @@ -1,5 +1,6 @@ [[tx-decl-vs-prog]] = Choosing Between Programmatic and Declarative Transaction Management +:page-section-summary-toc: 1 Programmatic transaction management is usually a good idea only if you have a small number of transactional operations. For example, if you have a web application that diff --git a/framework-docs/modules/ROOT/pages/integration.adoc b/framework-docs/modules/ROOT/pages/integration.adoc index e4de8269afd0..4ab4774f7551 100644 --- a/framework-docs/modules/ROOT/pages/integration.adoc +++ b/framework-docs/modules/ROOT/pages/integration.adoc @@ -1,5 +1,6 @@ [[spring-integration]] = Integration +:page-section-summary-toc: 1 This part of the reference documentation covers Spring Framework's integration with a number of technologies. diff --git a/framework-docs/modules/ROOT/pages/integration/cache.adoc b/framework-docs/modules/ROOT/pages/integration/cache.adoc index 689a031b22c4..2f763a709d32 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache.adoc @@ -1,5 +1,6 @@ [[cache]] = Cache Abstraction +:page-section-summary-toc: 1 Since version 3.1, the Spring Framework provides support for transparently adding caching to an existing Spring application. Similar to the xref:data-access/transaction.adoc[transaction] diff --git a/framework-docs/modules/ROOT/pages/integration/cache/plug.adoc b/framework-docs/modules/ROOT/pages/integration/cache/plug.adoc index a4fb38ebb886..56e3aa482ca1 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/plug.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/plug.adoc @@ -1,5 +1,6 @@ [[cache-plug]] = Plugging-in Different Back-end Caches +:page-section-summary-toc: 1 Clearly, there are plenty of caching products out there that you can use as a backing store. For those that do not support JSR-107 you need to provide a `CacheManager` and a diff --git a/framework-docs/modules/ROOT/pages/integration/cache/specific-config.adoc b/framework-docs/modules/ROOT/pages/integration/cache/specific-config.adoc index ddddb0ea1478..c05c6bda3bd7 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/specific-config.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/specific-config.adoc @@ -1,5 +1,6 @@ [[cache-specific-config]] = How can I Set the TTL/TTI/Eviction policy/XXX feature? +:page-section-summary-toc: 1 Directly through your cache provider. The cache abstraction is an abstraction, not a cache implementation. The solution you use might support various data diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc index 8c38b77fd46b..369ccbf2c19c 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc @@ -1,5 +1,6 @@ [[jmx-resources]] = Further Resources +:page-section-summary-toc: 1 This section contains links to further resources about JMX: diff --git a/framework-docs/modules/ROOT/pages/languages.adoc b/framework-docs/modules/ROOT/pages/languages.adoc index b41773c13e00..ec451606e984 100644 --- a/framework-docs/modules/ROOT/pages/languages.adoc +++ b/framework-docs/modules/ROOT/pages/languages.adoc @@ -1,5 +1,6 @@ [[languages]] = Language Support +:page-section-summary-toc: 1 diff --git a/framework-docs/modules/ROOT/pages/languages/groovy.adoc b/framework-docs/modules/ROOT/pages/languages/groovy.adoc index d0833c2e801c..745101a99374 100644 --- a/framework-docs/modules/ROOT/pages/languages/groovy.adoc +++ b/framework-docs/modules/ROOT/pages/languages/groovy.adoc @@ -1,5 +1,6 @@ [[groovy]] = Apache Groovy +:page-section-summary-toc: 1 Groovy is a powerful, optionally typed, and dynamic language, with static-typing and static compilation capabilities. It offers a concise syntax and integrates smoothly with any diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin.adoc index 3a6b2482076e..c6beb7f4a6ca 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin.adoc @@ -1,5 +1,6 @@ [[kotlin]] = Kotlin +:page-section-summary-toc: 1 https://kotlinlang.org[Kotlin] is a statically typed language that targets the JVM (and other platforms) which allows writing concise and elegant code while providing diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/classes-interfaces.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/classes-interfaces.adoc index 63a87b346512..5dd4520dd9f5 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/classes-interfaces.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/classes-interfaces.adoc @@ -1,5 +1,6 @@ [[kotlin-classes-interfaces]] = Classes and Interfaces +:page-section-summary-toc: 1 The Spring Framework supports various Kotlin constructs, such as instantiating Kotlin classes through primary constructors, immutable classes data binding, and function optional parameters diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/requirements.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/requirements.adoc index 6c453db075ae..80a2b48fc15a 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/requirements.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/requirements.adoc @@ -1,5 +1,6 @@ [[kotlin-requirements]] = Requirements +:page-section-summary-toc: 1 Spring Framework supports Kotlin 1.3+ and requires https://search.maven.org/artifact/org.jetbrains.kotlin/kotlin-stdlib[`kotlin-stdlib`] diff --git a/framework-docs/modules/ROOT/pages/testing.adoc b/framework-docs/modules/ROOT/pages/testing.adoc index 6339dbbe14bc..ee17a98bb368 100644 --- a/framework-docs/modules/ROOT/pages/testing.adoc +++ b/framework-docs/modules/ROOT/pages/testing.adoc @@ -1,5 +1,6 @@ [[testing]] = Testing +:page-section-summary-toc: 1 This chapter covers Spring's support for integration testing and best practices for unit testing. The Spring team advocates test-driven development (TDD). The Spring team has diff --git a/framework-docs/modules/ROOT/pages/testing/annotations.adoc b/framework-docs/modules/ROOT/pages/testing/annotations.adoc index 6e0ce2f52cd2..ba8c15c9b304 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations.adoc @@ -1,5 +1,6 @@ [[integration-testing-annotations]] = Annotations +:page-section-summary-toc: 1 This section covers annotations that you can use when you test Spring applications. It includes the following topics: diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc index be83db1212f3..5769b3d3d3f3 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc @@ -1,5 +1,6 @@ [[spring-testing-annotation-bootstrapwith]] = `@BootstrapWith` +:page-section-summary-toc: 1 `@BootstrapWith` is a class-level annotation that you can use to configure how the Spring TestContext Framework is bootstrapped. Specifically, you can use `@BootstrapWith` to diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc index 51a1c2100021..fbd7f0cf03f2 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc @@ -1,5 +1,6 @@ [[spring-testing-annotation-recordapplicationevents]] = `@RecordApplicationEvents` +:page-section-summary-toc: 1 `@RecordApplicationEvents` is a class-level annotation that is used to instruct the _Spring TestContext Framework_ to record all application events that are published in the diff --git a/framework-docs/modules/ROOT/pages/testing/appendix.adoc b/framework-docs/modules/ROOT/pages/testing/appendix.adoc index 580253377df9..b831676c579b 100644 --- a/framework-docs/modules/ROOT/pages/testing/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/testing/appendix.adoc @@ -1,4 +1,5 @@ [[testing.appendix]] = Appendix +:page-section-summary-toc: 1 diff --git a/framework-docs/modules/ROOT/pages/testing/introduction.adoc b/framework-docs/modules/ROOT/pages/testing/introduction.adoc index 71bf53da3676..8618c99a44c6 100644 --- a/framework-docs/modules/ROOT/pages/testing/introduction.adoc +++ b/framework-docs/modules/ROOT/pages/testing/introduction.adoc @@ -1,5 +1,6 @@ [[testing-introduction]] = Introduction to Spring Testing +:page-section-summary-toc: 1 Testing is an integral part of enterprise software development. This chapter focuses on the value added by the IoC principle to xref:testing/unit.adoc[unit testing] and on the benefits diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc index 19ed89221550..ec1900709d29 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc @@ -1,5 +1,6 @@ [[spring-mvc-test-framework]] = MockMvc +:page-section-summary-toc: 1 The Spring MVC Test framework, also known as MockMvc, provides support for testing Spring MVC applications. It performs full Spring MVC request handling but via mock request and diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc index 4dd5c1abd347..ad3c33b5192f 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc @@ -1,5 +1,6 @@ [[spring-mvc-test-server-filters]] = Filter Registrations +:page-section-summary-toc: 1 When setting up a `MockMvc` instance, you can register one or more Servlet `Filter` instances, as the following example shows: diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc index fda2259ef345..03895dfa44e7 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc @@ -1,5 +1,6 @@ [[spring-mvc-test-server-htmlunit]] = HtmlUnit Integration +:page-section-summary-toc: 1 Spring provides integration between xref:testing/spring-mvc-test-framework/server.adoc[MockMvc] and https://htmlunit.sourceforge.io/[HtmlUnit]. This simplifies performing end-to-end testing diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-resources.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-resources.adoc index 21a6592973e9..7444c1038fb1 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-resources.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-resources.adoc @@ -1,5 +1,6 @@ [[spring-mvc-test-server-resources]] = Further Examples +:page-section-summary-toc: 1 The framework's own tests include {spring-framework-main-code}/spring-test/src/test/java/org/springframework/test/web/servlet/samples[ diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc index a082636a620f..21ccea19311e 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc @@ -1,5 +1,6 @@ [[spring-mvc-test-server-static-imports]] = Static Imports +:page-section-summary-toc: 1 When using MockMvc directly to perform requests, you'll need static imports for: diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc index f319cabb9acc..2368a5a96c41 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc @@ -1,5 +1,6 @@ [[spring-mvc-test-server]] = Overview +:page-section-summary-toc: 1 You can write plain unit tests for Spring MVC by instantiating a controller, injecting it with dependencies, and calling its methods. However such tests do not verify request diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc index 0acb1ddcb736..0cf24faa9aa1 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc @@ -1,5 +1,6 @@ [[testcontext-framework]] = Spring TestContext Framework +:page-section-summary-toc: 1 The Spring TestContext Framework (located in the `org.springframework.test.context` package) provides generic, annotation-driven unit and integration testing support that is diff --git a/framework-docs/modules/ROOT/pages/web.adoc b/framework-docs/modules/ROOT/pages/web.adoc index 2cfb7be73e59..76ebcfc90689 100644 --- a/framework-docs/modules/ROOT/pages/web.adoc +++ b/framework-docs/modules/ROOT/pages/web.adoc @@ -1,5 +1,6 @@ [[spring-web]] = Web on Servlet Stack +:page-section-summary-toc: 1 This part of the documentation covers support for Servlet-stack web applications built on the Servlet API and deployed to Servlet containers. Individual chapters include xref:web/webmvc.adoc#mvc[Spring MVC], diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc index 4b4a7c845b5e..effa703ab605 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc @@ -1,5 +1,6 @@ [[webflux-client]] = WebClient +:page-section-summary-toc: 1 Spring WebFlux includes a client to perform HTTP requests with. `WebClient` has a functional, fluent API based on Reactor, see xref:web-reactive.adoc#webflux-reactive-libraries[Reactive Libraries], diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-testing.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-testing.adoc index 756e5172c513..8b1393cc52b6 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-testing.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-testing.adoc @@ -1,5 +1,6 @@ [[webflux-client-testing]] = Testing +:page-section-summary-toc: 1 To test code that uses the `WebClient`, you can use a mock web server, such as the https://github.com/square/okhttp#mockwebserver[OkHttp MockWebServer]. To see an example diff --git a/framework-docs/modules/ROOT/pages/web/webflux.adoc b/framework-docs/modules/ROOT/pages/web/webflux.adoc index 57b07ca6a165..a9487c93739b 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux.adoc @@ -2,6 +2,7 @@ :chapter: webflux [[spring-webflux]] = Spring WebFlux +:page-section-summary-toc: 1 The original web framework included in the Spring Framework, Spring Web MVC, was purpose-built for the Servlet API and Servlet containers. The reactive-stack web framework, diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc index 7c073797e8b1..6930c9dbda11 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc @@ -1,5 +1,6 @@ [[webflux-ann-methods]] = Handler Methods +:page-section-summary-toc: 1 [.small]#xref:web/webmvc/mvc-controller/ann-methods.adoc[See equivalent in the Servlet stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc index c1b58f2bdd59..ca61ec37c5c2 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc @@ -1,5 +1,6 @@ [[webflux-ann-typeconversion]] = Type Conversion +:page-section-summary-toc: 1 [.small]#xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[See equivalent in the Servlet stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc b/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc index 0ae23f06610a..39f080c10178 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc @@ -1,5 +1,6 @@ [[webflux-http2]] = HTTP/2 +:page-section-summary-toc: 1 [.small]#xref:web/webmvc/mvc-http2.adoc[See equivalent in the Servlet stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webflux/security.adoc b/framework-docs/modules/ROOT/pages/web/webflux/security.adoc index 9f0e759098ac..4c448e3cba7b 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/security.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/security.adoc @@ -1,5 +1,6 @@ [[webflux-web-security]] = Web Security +:page-section-summary-toc: 1 [.small]#xref:web/webmvc/mvc-security.adoc[See equivalent in the Servlet stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc index 4df300151050..559fcd2479ee 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc @@ -1,5 +1,6 @@ [[webflux-uri-building]] = URI Links +:page-section-summary-toc: 1 [.small]#xref:web/webmvc/mvc-uri-building.adoc[See equivalent in the Servlet stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc index d0547f6fa6df..e6af04b7fe26 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc @@ -1,5 +1,6 @@ [[mvc-view]] = View Technologies +:page-section-summary-toc: 1 [.small]#xref:web/webflux-view.adoc[See equivalent in the Reactive stack]# The use of view technologies in Spring MVC is pluggable. Whether you decide to use diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc index 53c69f2a37a1..48cf0c6d5ab6 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc @@ -1,5 +1,6 @@ [[mvc-view-thymeleaf]] = Thymeleaf +:page-section-summary-toc: 1 [.small]#xref:web/webflux-view.adoc#webflux-view-thymeleaf[See equivalent in the Reactive stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc index 2b8ccd547db5..74f65108f212 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc @@ -1,5 +1,6 @@ [[mvc-view-xml-marshalling]] = XML Marshalling +:page-section-summary-toc: 1 The `MarshallingView` uses an XML `Marshaller` (defined in the `org.springframework.oxm` package) to render the response content as XML. You can explicitly set the object to be diff --git a/framework-docs/modules/ROOT/pages/web/webmvc.adoc b/framework-docs/modules/ROOT/pages/web/webmvc.adoc index 4578acc9528b..d75c3c842500 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc.adoc @@ -2,6 +2,7 @@ :chapter: mvc [[spring-web-mvc]] = Spring Web MVC +:page-section-summary-toc: 1 Spring Web MVC is the original web framework built on the Servlet API and has been included in the Spring Framework from the very beginning. The formal name, "Spring Web MVC," diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc index 0b3446d50661..a29ad9a6e2bd 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc @@ -1,5 +1,6 @@ [[mvc-config]] = MVC Config +:page-section-summary-toc: 1 [.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[See equivalent in the Reactive stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc index d5717e459c14..853e26607d90 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc @@ -1,5 +1,6 @@ [[mvc-ann-methods]] = Handler Methods +:page-section-summary-toc: 1 [.small]#xref:web/webflux/controller/ann-methods.adoc[See equivalent in the Reactive stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc index 429b619ac641..17a10e537f7f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc @@ -1,5 +1,6 @@ [[mvc-http2]] = HTTP/2 +:page-section-summary-toc: 1 [.small]#xref:web/webflux/http2.adoc[See equivalent in the Reactive stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc index d704b7e176cc..5b6aca1f70ad 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc @@ -1,5 +1,6 @@ [[mvc-web-security]] = Web Security +:page-section-summary-toc: 1 [.small]#xref:web/webflux/security.adoc[See equivalent in the Reactive stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc index 8a2303344458..64fcc6e1be63 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc @@ -1,5 +1,6 @@ [[mvc-servlet-config]] = Web MVC Config +:page-section-summary-toc: 1 [.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[See equivalent in the Reactive stack]# diff --git a/framework-docs/modules/ROOT/pages/web/websocket.adoc b/framework-docs/modules/ROOT/pages/web/websocket.adoc index 79665ef428b9..d9fd668f0303 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket.adoc @@ -1,5 +1,6 @@ [[websocket]] = WebSockets +:page-section-summary-toc: 1 [.small]#xref:web/webflux-websocket.adoc[See equivalent in the Reactive stack]# This part of the reference documentation covers support for Servlet stack, WebSocket diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp.adoc index cc66fcb400e3..405d956c8a13 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp.adoc @@ -1,5 +1,6 @@ [[websocket-stomp]] = STOMP +:page-section-summary-toc: 1 The WebSocket protocol defines two types of messages (text and binary), but their content is undefined. The protocol defines a mechanism for client and server to negotiate a diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/authorization.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/authorization.adoc index 38ba93b459fc..5866ec3dc521 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/authorization.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/authorization.adoc @@ -1,5 +1,6 @@ [[websocket-stomp-authorization]] = Authorization +:page-section-summary-toc: 1 Spring Security provides {docs-spring-security}/servlet/integrations/websocket.html#websocket-authorization[WebSocket sub-protocol authorization] diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc index a4bcb1fdff13..31e3e7f32240 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc @@ -1,5 +1,6 @@ [[websocket-stomp-benefits]] = Benefits +:page-section-summary-toc: 1 Using STOMP as a sub-protocol lets the Spring Framework and Spring Security provide a richer programming model versus using raw WebSockets. The same point can be From 987ebed0468590a780ecf45f0cc183bd809f1843 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 15:12:18 -0500 Subject: [PATCH 16/31] fix framework-docs.gradle --- build.gradle | 1 + framework-docs/framework-docs.gradle | 24 ++++++++++++++++++------ 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/build.gradle b/build.gradle index a80f74f2e495..2bd350ca85f1 100644 --- a/build.gradle +++ b/build.gradle @@ -155,6 +155,7 @@ configure(rootProject) { nohttp { source.exclude "**/test-output/**" + source.exclude "**/.gradle/**" allowlistFile = project.file("src/nohttp/allowlist.lines") def rootPath = file(rootDir).toPath() def projectDirs = allprojects.collect { it.projectDir } + "${rootDir}/buildSrc" diff --git a/framework-docs/framework-docs.gradle b/framework-docs/framework-docs.gradle index 5c26a91b428f..59c29569a4ef 100644 --- a/framework-docs/framework-docs.gradle +++ b/framework-docs/framework-docs.gradle @@ -36,12 +36,18 @@ antora { tasks.named("generateAntoraYml") { - dependsOn dependencyVersions asciidocAttributes = project.provider( { return ["spring-version": project.version ] } ) } +tasks.create("generateAntoraResources") { + dependsOn 'generateAntoraYml' +} + +tasks.named("check") { + dependsOn 'antora' +} jar { enabled = false @@ -57,6 +63,15 @@ repositories { } } +dependencies { + api(project(":spring-context")) + api(project(":spring-web")) + api("jakarta.servlet:jakarta.servlet-api") + + implementation(project(":spring-core-test")) + implementation("org.assertj:assertj-core") +} + /** * Produce Javadoc for all Spring Framework modules in "build/docs/javadoc" */ @@ -109,9 +124,9 @@ rootProject.tasks.dokkaHtmlMultiModule.configure { } /** - * Zip all docs (API and reference) into a single archive + * Zip all Java docs (javadoc & kdoc) into a single archive */ -task docsZip(type: Zip, dependsOn: ['api', 'antora', rootProject.tasks.dokkaHtmlMultiModule]) { +task docsZip(type: Zip, dependsOn: ['api', rootProject.tasks.dokkaHtmlMultiModule]) { group = "Distribution" description = "Builds -${archiveClassifier} archive containing api and reference " + "for deployment at https://docs.spring.io/spring-framework/docs/." @@ -124,9 +139,6 @@ task docsZip(type: Zip, dependsOn: ['api', 'antora', rootProject.tasks.dokkaHtml from (api) { into "javadoc-api" } - from ("build/site") { - into "reference/html" - } from (rootProject.tasks.dokkaHtmlMultiModule.outputDirectory) { into "kdoc-api" } From d3de8866dff4fffb9852772502d5d83f9ee5e179 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 15:12:40 -0500 Subject: [PATCH 17/31] Fix antora.yml gradle command --- framework-docs/antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework-docs/antora.yml b/framework-docs/antora.yml index cc7d6eb1638b..a087242a22b4 100644 --- a/framework-docs/antora.yml +++ b/framework-docs/antora.yml @@ -6,7 +6,7 @@ nav: ext: collector: run: - command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-boot-project:spring-boot-docs:generateAntoraResources + command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :framework-docs:generateAntoraResources local: true scan: dir: ./build/generated-antora-resources From 894c6e0cdd2629afc7ccf9c835f0043345b8c231 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 15:12:53 -0500 Subject: [PATCH 18/31] fix antora.yml attributes --- framework-docs/antora.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/framework-docs/antora.yml b/framework-docs/antora.yml index a087242a22b4..f1ee0f1104bd 100644 --- a/framework-docs/antora.yml +++ b/framework-docs/antora.yml @@ -21,12 +21,12 @@ asciidoc: spring-framework-main-code: 'https://github.com/spring-projects/spring-framework/tree/main' docs-site: 'https://docs.spring.io' docs-spring: "{docs-site}/spring-framework/docs/{spring-version}" - docs-spring-framework: '{docs_site}/spring-framework/docs/{spring-version}' + docs-spring-framework: '{docs-site}/spring-framework/docs/{spring-version}' api-spring-framework: '{docs-spring-framework}/javadoc-api/org/springframework' docs-graalvm: 'https://www.graalvm.org/22.3/reference-manual' docs-spring-boot: '{docs-site}/spring-boot/docs/current/reference' - docs-spring-gemfire: '{docs_site}/spring-gemfire/docs/current/reference' - docs-spring-security: '{docs_site}/spring-security/reference' + docs-spring-gemfire: '{docs-site}/spring-gemfire/docs/current/reference' + docs-spring-security: '{docs-site}/spring-security/reference' gh-rsocket: 'https://github.com/rsocket' gh-rsocket-extensions: '{gh-rsocket}/rsocket/blob/master/Extensions' gh-rsocket-java: '{gh-rsocket}/rsocket-java{gh-rsocket}/rsocket-java' \ No newline at end of file From 198b054df1a2975eed27d214d8c88c10cfb14727 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 16:37:25 -0500 Subject: [PATCH 19/31] Fix invalid attributes --- .../modules/ROOT/pages/web/web-uris.adoc | 5 +--- .../web/webflux/ann-rest-exceptions.adoc | 16 +++++------ .../web/webmvc/mvc-ann-rest-exceptions.adoc | 28 +++++++++---------- .../ROOT/pages/web/websocket-intro.adoc | 3 -- 4 files changed, 23 insertions(+), 29 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/web/web-uris.adoc b/framework-docs/modules/ROOT/pages/web/web-uris.adoc index 05b427a99ab1..b644cd2e1709 100644 --- a/framework-docs/modules/ROOT/pages/web/web-uris.adoc +++ b/framework-docs/modules/ROOT/pages/web/web-uris.adoc @@ -1,4 +1,3 @@ -[id={chapter}.web-uricomponents] [[uricomponents]] = UriComponents [.small]#Spring MVC and Spring WebFlux# @@ -102,12 +101,11 @@ You can shorten it further still with a full URI template, as the following exam -[id={chapter}.web-uribuilder] [[uribuilder]] = UriBuilder [.small]#Spring MVC and Spring WebFlux# -<<{chapter}.web-uricomponents, `UriComponentsBuilder`>> implements `UriBuilder`. You can create a +<> implements `UriBuilder`. You can create a `UriBuilder`, in turn, with a `UriBuilderFactory`. Together, `UriBuilderFactory` and `UriBuilder` provide a pluggable mechanism to build URIs from URI templates, based on shared configuration, such as a base URL, encoding preferences, and other details. @@ -195,7 +193,6 @@ that holds configuration and preferences, as the following example shows: ---- -[id={chapter}.web-uri-encoding] [[uri-encoding]] = URI Encoding [.small]#Spring MVC and Spring WebFlux# diff --git a/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc index b9e731e9b585..188d58a1ad72 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc @@ -76,7 +76,7 @@ to customize the problem details for Spring WebFlux exceptions. This is supporte - Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field through a xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSource]. The actual message code value is parameterized with placeholders, e.g. -`"HTTP method {0} not supported"` to be expanded from the arguments. +`+"HTTP method {0} not supported"+` to be expanded from the arguments. - Each `ErrorResponse` also exposes a message code to resolve the "title" field. - `ResponseEntityExceptionHandler` uses the message code and arguments to resolve the "detail" and the "title" fields. @@ -93,7 +93,7 @@ arguments and codes for Spring WebFlux exceptions: | `UnsupportedMediaTypeStatusException` | (default) -| `{0}` the media type that is not supported, `{1}` list of supported media types +| `+{0}+` the media type that is not supported, `+{1}+` list of supported media types | `UnsupportedMediaTypeStatusException` | (default) + ".parseError" @@ -101,21 +101,21 @@ arguments and codes for Spring WebFlux exceptions: | `MissingRequestValueException` | (default) -| `{0}` a label for the value (e.g. "request header", "cookie value", ...), `{1}` the value name +| `+{0}+` a label for the value (e.g. "request header", "cookie value", ...), `+{1}+` the value name | `UnsatisfiedRequestParameterException` | (default) -| `{0}` the list of parameter conditions +| `+{0}+` the list of parameter conditions | `WebExchangeBindException` | (default) -| `{0}` the list of global errors, `{1}` the list of field errors. +| `+{0}+` the list of global errors, `+{1}+` the list of field errors. Message codes and arguments for each error within the `BindingResult` are also resolved via `MessageSource`. | `NotAcceptableStatusException` | (default) -| `{0}` list of supported media types +| `+{0}+` list of supported media types | `NotAcceptableStatusException` | (default) + ".parseError" @@ -123,11 +123,11 @@ via `MessageSource`. | `ServerErrorException` | (default) -| `{0}` the failure reason provided to the class constructor +| `+{0}+` the failure reason provided to the class constructor | `MethodNotAllowedException` | (default) -| `{0}` the current HTTP method, `{1}` the list of supported HTTP methods +| `+{0}+` the current HTTP method, `+{1}+` the list of supported HTTP methods |=== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc index 2769c1f1b541..183e49b0aeb4 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc @@ -76,7 +76,7 @@ to customize the problem details for Spring MVC exceptions. This is supported as - Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field through a xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSource]. The actual message code value is parameterized with placeholders, e.g. -`"HTTP method {0} not supported"` to be expanded from the arguments. +`+"HTTP method {0} not supported"+` to be expanded from the arguments. - Each `ErrorResponse` also exposes a message code to resolve the "title" field. - `ResponseEntityExceptionHandler` uses the message code and arguments to resolve the "detail" and the "title" fields. @@ -97,11 +97,11 @@ arguments and codes for Spring MVC exceptions: | `ConversionNotSupportedException` | (default) -| `{0}` property name, `{1}` property value +| `+{0}+` property name, `+{1}+` property value | `HttpMediaTypeNotAcceptableException` | (default) -| `{0}` list of supported media types +| `+{0}+` list of supported media types | `HttpMediaTypeNotAcceptableException` | (default) + ".parseError" @@ -109,7 +109,7 @@ arguments and codes for Spring MVC exceptions: | `HttpMediaTypeNotSupportedException` | (default) -| `{0}` the media type that is not supported, `{1}` list of supported media types +| `+{0}+` the media type that is not supported, `+{1}+` list of supported media types | `HttpMediaTypeNotSupportedException` | (default) + ".parseError" @@ -125,37 +125,37 @@ arguments and codes for Spring MVC exceptions: | `HttpRequestMethodNotSupportedException` | (default) -| `{0}` the current HTTP method, `{1}` the list of supported HTTP methods +| `+{0}+` the current HTTP method, `+{1}+` the list of supported HTTP methods | `MethodArgumentNotValidException` | (default) -| `{0}` the list of global errors, `{1}` the list of field errors. +| `+{0}+` the list of global errors, `+{1}+` the list of field errors. Message codes and arguments for each error within the `BindingResult` are also resolved via `MessageSource`. | `MissingRequestHeaderException` | (default) -| `{0}` the header name +| `+{0}+` the header name | `MissingServletRequestParameterException` | (default) -| `{0}` the request parameter name +| `+{0}+` the request parameter name | `MissingMatrixVariableException` | (default) -| `{0}` the matrix variable name +| `+{0}+` the matrix variable name | `MissingPathVariableException` | (default) -| `{0}` the path variable name +| `+{0}+` the path variable name | `MissingRequestCookieException` | (default) -| `{0}` the cookie name +| `+{0}+` the cookie name | `MissingServletRequestPartException` | (default) -| `{0}` the part name +| `+{0}+` the part name | `NoHandlerFoundException` | (default) @@ -163,11 +163,11 @@ arguments and codes for Spring MVC exceptions: | `TypeMismatchException` | (default) -| `{0}` property name, `{1}` property value +| `+{0}+` property name, `+{1}+` property value | `UnsatisfiedServletRequestParameterException` | (default) -| `{0}` the list of parameter conditions +| `+{0}+` the list of parameter conditions |=== diff --git a/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc b/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc index 0b06b00b7244..339aea089be8 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc @@ -1,4 +1,3 @@ -[id={chapter}.websocket-intro] [[introduction-to-websocket]] = Introduction to WebSocket @@ -55,7 +54,6 @@ instructions of the cloud provider related to WebSocket support. -[id={chapter}.websocket-intro-architecture] [[http-versus-websocket]] == HTTP Versus WebSocket @@ -82,7 +80,6 @@ In the absence of that, they need to come up with their own conventions. -[id={chapter}.websocket-intro-when-to-use] [[when-to-use-websockets]] == When to Use WebSockets From 7b1cdae47268a9a31aeeda7245bdec6916a7c6d1 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:31:30 -0500 Subject: [PATCH 20/31] Fix index Overview link --- framework-docs/modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework-docs/modules/ROOT/pages/index.adoc b/framework-docs/modules/ROOT/pages/index.adoc index b6897ab17616..67998e243bbf 100644 --- a/framework-docs/modules/ROOT/pages/index.adoc +++ b/framework-docs/modules/ROOT/pages/index.adoc @@ -3,7 +3,7 @@ = Spring Framework Documentation [horizontal] -xref:web/websocket/stomp/overview.adoc[Overview] :: History, Design Philosophy, Feedback, +xref:overview.adoc[Overview] :: History, Design Philosophy, Feedback, Getting Started. xref:core.adoc[Core] :: IoC Container, Events, Resources, i18n, Validation, Data Binding, Type Conversion, SpEL, AOP, AOT. From 616cdd38e0c3dd6ede701d5d1f2f4c457595aa06 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 22:52:25 -0500 Subject: [PATCH 21/31] Fix invalid nav elements --- framework-docs/modules/ROOT/nav.adoc | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/framework-docs/modules/ROOT/nav.adoc b/framework-docs/modules/ROOT/nav.adoc index 770eb6a3d7fd..3f7a6e2ba07a 100644 --- a/framework-docs/modules/ROOT/nav.adoc +++ b/framework-docs/modules/ROOT/nav.adoc @@ -1,8 +1,5 @@ -* xref:index.adoc[] -* xref:attributes.adoc[] -* xref:overview.adoc[] +* xref:overview.adoc[Overview] * xref:core.adoc[] -* xref:page-layout.adoc[] ** xref:core/beans.adoc[] *** xref:core/beans/introduction.adoc[] *** xref:core/beans/basics.adoc[] From a26fde0b8f2d61e1b4d4c5483c072bb104bc7bb3 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 18 Apr 2023 23:09:25 -0500 Subject: [PATCH 22/31] Use include-code Macro --- framework-docs/antora-playbook.yml | 1 + framework-docs/antora.yml | 2 +- framework-docs/modules/ROOT/examples/docs-src | 1 + framework-docs/modules/ROOT/pages/core/aot.adoc | 12 ++++++------ .../ROOT/pages/integration/observability.adoc | 10 +++++----- 5 files changed, 14 insertions(+), 12 deletions(-) create mode 120000 framework-docs/modules/ROOT/examples/docs-src diff --git a/framework-docs/antora-playbook.yml b/framework-docs/antora-playbook.yml index ffae717c22bc..82eec9dc73d0 100644 --- a/framework-docs/antora-playbook.yml +++ b/framework-docs/antora-playbook.yml @@ -24,6 +24,7 @@ asciidoc: extensions: - '@asciidoctor/tabs' - '@springio/asciidoctor-extensions' + - '@springio/asciidoctor-extensions/include-code-extension' sourcemap: true urls: latest_version_segment: '' diff --git a/framework-docs/antora.yml b/framework-docs/antora.yml index f1ee0f1104bd..607c9f925f6f 100644 --- a/framework-docs/antora.yml +++ b/framework-docs/antora.yml @@ -17,7 +17,7 @@ asciidoc: # FIXME: the copyright is not removed # FIXME: The package is not renamed chomp: 'all' - import-java: 'example$docs-src/main/java/org/springframework/docs' + include-java: 'example$docs-src/main/java/org/springframework/docs' spring-framework-main-code: 'https://github.com/spring-projects/spring-framework/tree/main' docs-site: 'https://docs.spring.io' docs-spring: "{docs-site}/spring-framework/docs/{spring-version}" diff --git a/framework-docs/modules/ROOT/examples/docs-src b/framework-docs/modules/ROOT/examples/docs-src new file mode 120000 index 000000000000..dabb0e15a991 --- /dev/null +++ b/framework-docs/modules/ROOT/examples/docs-src @@ -0,0 +1 @@ +../../../src \ No newline at end of file diff --git a/framework-docs/modules/ROOT/pages/core/aot.adoc b/framework-docs/modules/ROOT/pages/core/aot.adoc index 9a1553db5b80..14f947fd67cd 100644 --- a/framework-docs/modules/ROOT/pages/core/aot.adoc +++ b/framework-docs/modules/ROOT/pages/core/aot.adoc @@ -54,13 +54,13 @@ An application context is created with any number of entry points, usually in th Let's look at a basic example: -include::code:AotProcessingSample[tag=myapplication] +include-code::AotProcessingSample[tag=myapplication] Starting this application with the regular runtime involves a number of steps including classpath scanning, configuration class parsing, bean instantiation, and lifecycle callback handling. Refresh for AOT processing only applies a subset of what happens with a xref:core/beans/introduction.adoc[regular `refresh`]. AOT processing can be triggered as follows: -include::code:AotProcessingSample[tag=aotcontext] +include-code::AotProcessingSample[tag=aotcontext] In this mode, xref:core/beans/factory-extension.adoc#beans-factory-extension-factory-postprocessors[`BeanFactoryPostProcessor` implementations] are invoked as usual. This includes configuration class parsing, import selectors, classpath scanning, etc. @@ -217,7 +217,7 @@ A number of convenient annotations are also provided for common use cases. Implementations of this interface can be registered using `@ImportRuntimeHints` on any Spring bean or `@Bean` factory method. `RuntimeHintsRegistrar` implementations are detected and invoked at build time. -include::code:SpellCheckService[] +include-code::SpellCheckService[] If at all possible, `@ImportRuntimeHints` should be used as close as possible to the component that requires the hints. This way, if the component is not contributed to the `BeanFactory`, the hints won't be contributed either. @@ -269,7 +269,7 @@ Spring Core also ships `RuntimeHintsPredicates`, a utility for checking that exi This can be used in your own tests to validate that a `RuntimeHintsRegistrar` contains the expected results. We can write a test for our `SpellCheckService` and ensure that we will be able to load a dictionary at runtime: -include::code:SpellCheckServiceTests[tag=hintspredicates] +include-code::SpellCheckServiceTests[tag=hintspredicates] With `RuntimeHintsPredicates`, we can check for reflection, resource, serialization, or proxy generation hints. This approach works well for unit tests but implies that the runtime behavior of a component is well known. @@ -281,11 +281,11 @@ For more targeted discovery and testing, Spring Framework ships a dedicated modu This module contains the RuntimeHints Agent, a Java agent that records all method invocations that are related to runtime hints and helps you to assert that a given `RuntimeHints` instance covers all recorded invocations. Let's consider a piece of infrastructure for which we'd like to test the hints we're contributing during the AOT processing phase. -include::code:SampleReflection[] +include-code::SampleReflection[] We can then write a unit test (no native compilation required) that checks our contributed hints: -include::code:SampleReflectionRuntimeHintsTests[] +include-code::SampleReflectionRuntimeHintsTests[] If you forgot to contribute a hint, the test will fail and provide some details about the invocation: diff --git a/framework-docs/modules/ROOT/pages/integration/observability.adoc b/framework-docs/modules/ROOT/pages/integration/observability.adoc index b7453decaa88..ccb8a6b78440 100644 --- a/framework-docs/modules/ROOT/pages/integration/observability.adoc +++ b/framework-docs/modules/ROOT/pages/integration/observability.adoc @@ -66,16 +66,16 @@ Let's take the example of the Spring MVC "http.server.requests" metrics instrume This observation is using a `ServerRequestObservationConvention` with a `ServerRequestObservationContext`; custom conventions can be configured on the Servlet filter. If you would like to customize the metadata produced with the observation, you can extend the `DefaultServerRequestObservationConvention` for your requirements: -include::code:ExtendedServerRequestObservationConvention[] +include-code::ExtendedServerRequestObservationConvention[] If you want full control, you can then implement the entire convention contract for the observation you're interested in: -include::code:CustomServerRequestObservationConvention[] +include-code::CustomServerRequestObservationConvention[] You can also achieve similar goals using a custom `ObservationFilter` - adding or removing key values for an observation. Filters do not replace the default convention and are used as a post-processing component. -include::code:ServerRequestObservationFilter[] +include-code::ServerRequestObservationFilter[] You can configure `ObservationFilter` instances on the `ObservationRegistry`. @@ -95,7 +95,7 @@ This will only record an observation as an error if the `Exception` has not been Typically, all exceptions handled by Spring MVC's `@ExceptionHandler` and xref:web/webmvc/mvc-ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: -include::code:UserController[] +include-code::UserController[] By default, the following `KeyValues` are created: @@ -128,7 +128,7 @@ This will only record an observation as an error if the `Exception` has not been Typically, all exceptions handled by Spring WebFlux's `@ExceptionHandler` and xref:web/webflux/ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: -include::code:UserController[] +include-code::UserController[] By default, the following `KeyValues` are created: From e95e907423ff0460ed30a298ecaf1cbda8c49713 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 09:13:31 -0500 Subject: [PATCH 23/31] Fix Title in antora.yml --- framework-docs/antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework-docs/antora.yml b/framework-docs/antora.yml index 607c9f925f6f..642ecd19f6cd 100644 --- a/framework-docs/antora.yml +++ b/framework-docs/antora.yml @@ -1,6 +1,6 @@ name: framework version: true -title: Spring Framework Documentation +title: Spring Framework nav: - modules/ROOT/nav.adoc ext: From 2ed58ecd4cae2184f6c87410f574fc5e074be226 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 09:13:43 -0500 Subject: [PATCH 24/31] Make local build (temporary) --- framework-docs/antora-playbook.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/framework-docs/antora-playbook.yml b/framework-docs/antora-playbook.yml index 82eec9dc73d0..656621102b62 100644 --- a/framework-docs/antora-playbook.yml +++ b/framework-docs/antora-playbook.yml @@ -11,8 +11,8 @@ site: url: https://https://rwinch.github.io/spring-framework/ content: sources: - - url: https://github.com/rwinch/spring-framework - branches: ./.. + - url: ../. + branches: HEAD start_path: framework-docs worktrees: true asciidoc: From ac270ec97b506df43adbf33e1f94e5e7a0c3fa65 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Thu, 20 Apr 2023 09:03:56 -0500 Subject: [PATCH 25/31] Trim IDs with parent --- .../core/aop/ataspectj/aspectj-support.adoc | 2 +- .../modules/ROOT/pages/core/aop/schema.adoc | 2 +- .../ROOT/pages/core/aop/using-aspectj.adoc | 2 +- .../modules/ROOT/pages/core/aot.adoc | 34 ++++++++--------- .../modules/ROOT/pages/core/appendix.adoc | 2 +- .../appendix/application-startup-steps.adoc | 2 +- .../ROOT/pages/core/appendix/xml-custom.adoc | 24 ++++++------ .../ROOT/pages/core/appendix/xsd-schemas.adoc | 38 +++++++++---------- .../ROOT/pages/data-access/appendix.adoc | 4 +- .../data-access/transaction/strategies.adoc | 2 +- .../ROOT/pages/integration/appendix.adoc | 26 ++++++------- .../ROOT/pages/integration/observability.adoc | 36 +++++++++--------- .../ROOT/pages/integration/rest-clients.adoc | 2 +- .../modules/ROOT/pages/testing/appendix.adoc | 2 +- .../testing/testcontext-framework/aot.adoc | 4 +- .../web/webflux-webclient/client-builder.adoc | 4 +- .../modules/ROOT/pages/web/webmvc-test.adoc | 2 +- 17 files changed, 94 insertions(+), 94 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc index c75a21e7e4ee..458d4fb118b8 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc @@ -48,7 +48,7 @@ element, as the following example shows: This assumes that you use schema support as described in xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration]. -See xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-aop[the AOP schema] for how to +See xref:core/appendix/xsd-schemas.adoc#aop[the AOP schema] for how to import the tags in the `aop` namespace. diff --git a/framework-docs/modules/ROOT/pages/core/aop/schema.adoc b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc index 875bcc2d80ea..7e702016fcaa 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/schema.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc @@ -10,7 +10,7 @@ of advice parameters. To use the aop namespace tags described in this section, you need to import the `spring-aop` schema, as described in xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration] -. See xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-aop[the AOP schema] +. See xref:core/appendix/xsd-schemas.adoc#aop[the AOP schema] for how to import the tags in the `aop` namespace. Within your Spring configurations, all aspect and advisor elements must be placed within diff --git a/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc index ea8cf920a26f..ced4a2afe250 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc @@ -182,7 +182,7 @@ use Java-based configuration, you can add `@EnableSpringConfigured` to any ---- If you prefer XML based configuration, the Spring -xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-context[`context` namespace] +xref:core/appendix/xsd-schemas.adoc#context[`context` namespace] defines a convenient `context:spring-configured` element, which you can use as follows: [source,xml,indent=0,subs="verbatim"] diff --git a/framework-docs/modules/ROOT/pages/core/aot.adoc b/framework-docs/modules/ROOT/pages/core/aot.adoc index 14f947fd67cd..5a569ca85faa 100644 --- a/framework-docs/modules/ROOT/pages/core/aot.adoc +++ b/framework-docs/modules/ROOT/pages/core/aot.adoc @@ -1,11 +1,11 @@ -[[core.aot]] +[[aot]] = Ahead of Time Optimizations This chapter covers Spring's Ahead of Time (AOT) optimizations. For AOT support specific to integration tests, see xref:testing/testcontext-framework/aot.adoc[Ahead of Time Support for Tests]. -[[core.aot.introduction]] +[[aot.introduction]] == Introduction to Ahead of Time Optimizations Spring's support for AOT optimizations is meant to inspect an `ApplicationContext` at build time and apply decisions and discovery logic that usually happens at runtime. @@ -30,7 +30,7 @@ A Spring AOT processed application typically generates: NOTE: At the moment, AOT is focused on allowing Spring applications to be deployed as native images using GraalVM. We intend to support more JVM-based use cases in future generations. -[[core.aot.basics]] +[[aot.basics]] == AOT engine overview The entry point of the AOT engine for processing an `ApplicationContext` arrangement is `ApplicationContextAotGenerator`. It takes care of the following steps, based on a `GenericApplicationContext` that represents the application to optimize and a {api-spring-framework}/aot/generate/GenerationContext.html[`GenerationContext`]: @@ -46,7 +46,7 @@ The `RuntimeHints` instance can also be used to generate the relevant GraalVM na Those steps are covered in greater detail in the sections below. -[[core.aot.refresh]] +[[aot.refresh]] == Refresh for AOT Processing Refresh for AOT processing is supported on all `GenericApplicationContext` implementations. @@ -54,13 +54,13 @@ An application context is created with any number of entry points, usually in th Let's look at a basic example: -include-code::AotProcessingSample[tag=myapplication] +include-code::./AotProcessingSample[tag=myapplication] Starting this application with the regular runtime involves a number of steps including classpath scanning, configuration class parsing, bean instantiation, and lifecycle callback handling. Refresh for AOT processing only applies a subset of what happens with a xref:core/beans/introduction.adoc[regular `refresh`]. AOT processing can be triggered as follows: -include-code::AotProcessingSample[tag=aotcontext] +include-code::./AotProcessingSample[tag=aotcontext] In this mode, xref:core/beans/factory-extension.adoc#beans-factory-extension-factory-postprocessors[`BeanFactoryPostProcessor` implementations] are invoked as usual. This includes configuration class parsing, import selectors, classpath scanning, etc. @@ -76,7 +76,7 @@ This makes sure to create any proxy that will be required at runtime. Once this part completes, the `BeanFactory` contains the bean definitions that are necessary for the application to run. It does not trigger bean instantiation but allows the AOT engine to inspect the beans that will be created at runtime. -[[core.aot.bean-factory-initialization-contributions]] +[[aot.bean-factory-initialization-contributions]] == Bean Factory Initialization AOT Contributions Components that want to participate in this step can implement the {api-spring-framework}/beans/factory/aot/BeanFactoryInitializationAotProcessor.html[`BeanFactoryInitializationAotProcessor`] interface. @@ -99,7 +99,7 @@ If such a bean is registered using an `@Bean` factory method, ensure the method ==== -[[core.aot.bean-registration-contributions]] +[[aot.bean-registration-contributions]] === Bean Registration AOT Contributions A core `BeanFactoryInitializationAotProcessor` implementation is responsible for collecting the necessary contributions for each candidate `BeanDefinition`. @@ -186,7 +186,7 @@ When a `datasource` instance is required, a `BeanInstanceSupplier` is called. This supplier invokes the `dataSource()` method on the `dataSourceConfiguration` bean. -[[core.aot.hints]] +[[aot.hints]] == Runtime Hints Running an application as a native image requires additional information compared to a regular JVM runtime. @@ -210,14 +210,14 @@ For cases that the core container cannot infer, you can register such hints prog A number of convenient annotations are also provided for common use cases. -[[core.aot.hints.import-runtime-hints]] +[[aot.hints.import-runtime-hints]] === `@ImportRuntimeHints` `RuntimeHintsRegistrar` implementations allow you to get a callback to the `RuntimeHints` instance managed by the AOT engine. Implementations of this interface can be registered using `@ImportRuntimeHints` on any Spring bean or `@Bean` factory method. `RuntimeHintsRegistrar` implementations are detected and invoked at build time. -include-code::SpellCheckService[] +include-code::./SpellCheckService[] If at all possible, `@ImportRuntimeHints` should be used as close as possible to the component that requires the hints. This way, if the component is not contributed to the `BeanFactory`, the hints won't be contributed either. @@ -225,7 +225,7 @@ This way, if the component is not contributed to the `BeanFactory`, the hints wo It is also possible to register an implementation statically by adding an entry in `META-INF/spring/aot.factories` with a key equal to the fully qualified name of the `RuntimeHintsRegistrar` interface. -[[core.aot.hints.reflective]] +[[aot.hints.reflective]] === `@Reflective` {api-spring-framework}/aot/hint/annotation/Reflective.html[`@Reflective`] provides an idiomatic way to flag the need for reflection on an annotated element. @@ -239,7 +239,7 @@ Library authors can reuse this annotation for their own purposes. If components other than Spring beans need to be processed, a `BeanFactoryInitializationAotProcessor` can detect the relevant types and use `ReflectiveRuntimeHintsRegistrar` to process them. -[[core.aot.hints.register-reflection-for-binding]] +[[aot.hints.register-reflection-for-binding]] === `@RegisterReflectionForBinding` {api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`] is a specialization of `@Reflective` that registers the need for serializing arbitrary types. @@ -262,14 +262,14 @@ The following example registers `Account` for serialization. } ---- -[[core.aot.hints.testing]] +[[aot.hints.testing]] === Testing Runtime Hints Spring Core also ships `RuntimeHintsPredicates`, a utility for checking that existing hints match a particular use case. This can be used in your own tests to validate that a `RuntimeHintsRegistrar` contains the expected results. We can write a test for our `SpellCheckService` and ensure that we will be able to load a dictionary at runtime: -include-code::SpellCheckServiceTests[tag=hintspredicates] +include-code::./SpellCheckServiceTests[tag=hintspredicates] With `RuntimeHintsPredicates`, we can check for reflection, resource, serialization, or proxy generation hints. This approach works well for unit tests but implies that the runtime behavior of a component is well known. @@ -281,11 +281,11 @@ For more targeted discovery and testing, Spring Framework ships a dedicated modu This module contains the RuntimeHints Agent, a Java agent that records all method invocations that are related to runtime hints and helps you to assert that a given `RuntimeHints` instance covers all recorded invocations. Let's consider a piece of infrastructure for which we'd like to test the hints we're contributing during the AOT processing phase. -include-code::SampleReflection[] +include-code::./SampleReflection[] We can then write a unit test (no native compilation required) that checks our contributed hints: -include-code::SampleReflectionRuntimeHintsTests[] +include-code::./SampleReflectionRuntimeHintsTests[] If you forgot to contribute a hint, the test will fail and provide some details about the invocation: diff --git a/framework-docs/modules/ROOT/pages/core/appendix.adoc b/framework-docs/modules/ROOT/pages/core/appendix.adoc index deaf39c5c680..5cae57dc7d05 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix.adoc @@ -1,4 +1,4 @@ -[[core.appendix]] +[[appendix]] = Appendix :page-section-summary-toc: 1 diff --git a/framework-docs/modules/ROOT/pages/core/appendix/application-startup-steps.adoc b/framework-docs/modules/ROOT/pages/core/appendix/application-startup-steps.adoc index df05df7f7c70..7e33dda19a7a 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix/application-startup-steps.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix/application-startup-steps.adoc @@ -1,4 +1,4 @@ -[[core.appendix.application-startup-steps]] +[[application-startup-steps]] = Application Startup Steps This part of the appendix lists the existing `StartupSteps` that the core container is instrumented with. diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc index aa7f4fda1997..691bfe63ae37 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc @@ -1,7 +1,7 @@ -[[core.appendix.xml-custom]] +[[xml-custom]] = XML Schema Authoring -[[core.appendix.xsd-custom-introduction]] +[[xsd-custom-introduction]] Since version 2.0, Spring has featured a mechanism for adding schema-based extensions to the basic Spring XML format for defining and configuring beans. This section covers how to write your own custom XML bean definition parsers and @@ -39,7 +39,7 @@ through the basic steps of making a custom extension.) -[[core.appendix.xsd-custom-schema]] +[[xsd-custom-schema]] == Authoring the Schema Creating an XML configuration extension for use with Spring's IoC container starts with @@ -111,7 +111,7 @@ defined in the enumeration. -[[core.appendix.xsd-custom-namespacehandler]] +[[xsd-custom-namespacehandler]] == Coding a `NamespaceHandler` In addition to the schema, we need a `NamespaceHandler` to parse all elements of @@ -182,7 +182,7 @@ custom element, as we can see in the next step. -[[core.appendix.xsd-custom-parser]] +[[xsd-custom-parser]] == Using `BeanDefinitionParser` A `BeanDefinitionParser` is used if the `NamespaceHandler` encounters an XML @@ -272,7 +272,7 @@ is the extraction and setting of the bean definition's unique identifier. -[[core.appendix.xsd-custom-registration]] +[[xsd-custom-registration]] == Registering the Handler and the Schema The coding is finished. All that remains to be done is to make the Spring XML @@ -284,7 +284,7 @@ XML parsing infrastructure automatically picks up your new extension by consumin these special properties files, the formats of which are detailed in the next two sections. -[[core.appendix.xsd-custom-registration-spring-handlers]] +[[xsd-custom-registration-spring-handlers]] === Writing `META-INF/spring.handlers` The properties file called `spring.handlers` contains a mapping of XML Schema URIs to @@ -303,7 +303,7 @@ namespace extension and needs to exactly match exactly the value of the `targetN attribute, as specified in your custom XSD schema. -[[core.appendix.xsd-custom-registration-spring-schemas]] +[[xsd-custom-registration-spring-schemas]] === Writing 'META-INF/spring.schemas' The properties file called `spring.schemas` contains a mapping of XML Schema locations @@ -327,7 +327,7 @@ the `NamespaceHandler` and `BeanDefinitionParser` classes on the classpath. -[[core.appendix.xsd-custom-using]] +[[xsd-custom-using]] == Using a Custom Extension in Your Spring XML Configuration Using a custom extension that you yourself have implemented is no different from using @@ -361,13 +361,13 @@ in a Spring XML configuration file: -[[core.appendix.xsd-custom-meat]] +[[xsd-custom-meat]] == More Detailed Examples This section presents some more detailed examples of custom XML extensions. -[[core.appendix.xsd-custom-custom-nested]] +[[xsd-custom-custom-nested]] === Nesting Custom Elements within Custom Elements The example presented in this section shows how you to write the various artifacts required @@ -719,7 +719,7 @@ http\://www.foo.example/schema/component/component.xsd=com/foo/component.xsd ---- -[[core.appendix.xsd-custom-custom-just-attributes]] +[[xsd-custom-custom-just-attributes]] === Custom Attributes on "`Normal`" Elements Writing your own custom parser and the associated artifacts is not hard. However, diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc index a948355129a1..0eef8fbfc0d1 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc @@ -1,11 +1,11 @@ -[[core.appendix.xsd-schemas]] +[[xsd-schemas]] = XML Schemas This part of the appendix lists XML schemas related to the core container. -[[core.appendix.xsd-schemas-util]] +[[xsd-schemas-util]] == The `util` Schema As the name implies, the `util` tags deal with common, utility configuration @@ -30,7 +30,7 @@ correct schema so that the tags in the `util` namespace are available to you): ---- -[[core.appendix.xsd-schemas-util-constant]] +[[xsd-schemas-util-constant]] === Using `` Consider the following bean definition: @@ -63,7 +63,7 @@ developer's intent ("`inject this constant value`"), and it reads better: ---- -[[core.appendix.xsd-schemas-util-frfb]] +[[xsd-schemas-util-frfb]] ==== Setting a Bean Property or Constructor Argument from a Field Value {api-spring-framework}/beans/factory/config/FieldRetrievingFactoryBean.html[`FieldRetrievingFactoryBean`] @@ -175,7 +175,7 @@ Now consider the following setter of type `PersistenceContextType` and the corre ---- -[[core.appendix.xsd-schemas-util-property-path]] +[[xsd-schemas-util-property-path]] === Using `` Consider the following example: @@ -222,7 +222,7 @@ The value of the `path` attribute of the `` element follows the `beanName.beanProperty`. In this case, it picks up the `age` property of the bean named `testBean`. The value of that `age` property is `10`. -[[core.appendix.xsd-schemas-util-property-path-dependency]] +[[xsd-schemas-util-property-path-dependency]] ==== Using `` to Set a Bean Property or Constructor Argument `PropertyPathFactoryBean` is a `FactoryBean` that evaluates a property path on a given @@ -297,7 +297,7 @@ for most use cases, but it can sometimes be useful. See the javadoc for more inf this feature. -[[core.appendix.xsd-schemas-util-properties]] +[[xsd-schemas-util-properties]] === Using `` Consider the following example: @@ -323,7 +323,7 @@ The following example uses a `util:properties` element to make a more concise re ---- -[[core.appendix.xsd-schemas-util-list]] +[[xsd-schemas-util-list]] === Using `` Consider the following example: @@ -378,7 +378,7 @@ following configuration: If no `list-class` attribute is supplied, the container chooses a `List` implementation. -[[core.appendix.xsd-schemas-util-map]] +[[xsd-schemas-util-map]] === Using `` Consider the following example: @@ -433,7 +433,7 @@ following configuration: If no `'map-class'` attribute is supplied, the container chooses a `Map` implementation. -[[core.appendix.xsd-schemas-util-set]] +[[xsd-schemas-util-set]] === Using `` Consider the following example: @@ -489,7 +489,7 @@ If no `set-class` attribute is supplied, the container chooses a `Set` implement -[[core.appendix.xsd-schemas-aop]] +[[xsd-schemas-aop]] == The `aop` Schema The `aop` tags deal with configuring all things AOP in Spring, including Spring's @@ -519,7 +519,7 @@ are available to you): -[[core.appendix.xsd-schemas-context]] +[[xsd-schemas-context]] == The `context` Schema The `context` tags deal with `ApplicationContext` configuration that relates to plumbing @@ -544,7 +544,7 @@ available to you: ---- -[[core.appendix.xsd-schemas-context-pphc]] +[[xsd-schemas-context-pphc]] === Using `` This element activates the replacement of `${...}` placeholders, which are resolved against a @@ -554,7 +554,7 @@ is a convenience mechanism that sets up a xref:core/beans/factory-extension.adoc `PropertySourcesPlaceholderConfigurer` setup, you can explicitly define it as a bean yourself. -[[core.appendix.xsd-schemas-context-ac]] +[[xsd-schemas-context-ac]] === Using `` This element activates the Spring infrastructure to detect annotations in bean classes: @@ -577,28 +577,28 @@ xref:integration/cache/annotations.adoc[caching annotations] need to be explicit xref:integration/cache/annotations.adoc#cache-annotation-enable[enabled] as well. -[[core.appendix.xsd-schemas-context-component-scan]] +[[xsd-schemas-context-component-scan]] === Using `` This element is detailed in the section on xref:core/beans/annotation-config.adoc[annotation-based container configuration] . -[[core.appendix.xsd-schemas-context-ltw]] +[[xsd-schemas-context-ltw]] === Using `` This element is detailed in the section on xref:core/aop/using-aspectj.adoc#aop-aj-ltw[load-time weaving with AspectJ in the Spring Framework] . -[[core.appendix.xsd-schemas-context-sc]] +[[xsd-schemas-context-sc]] === Using `` This element is detailed in the section on xref:core/aop/using-aspectj.adoc#aop-atconfigurable[using AspectJ to dependency inject domain objects with Spring] . -[[core.appendix.xsd-schemas-context-mbe]] +[[xsd-schemas-context-mbe]] === Using `` This element is detailed in the section on xref:integration/jmx/naming.adoc#jmx-context-mbeanexport[configuring annotation-based MBean export] @@ -606,7 +606,7 @@ This element is detailed in the section on xref:integration/jmx/naming.adoc#jmx- -[[core.appendix.xsd-schemas-beans]] +[[xsd-schemas-beans]] == The Beans Schema Last but not least, we have the elements in the `beans` schema. These elements diff --git a/framework-docs/modules/ROOT/pages/data-access/appendix.adoc b/framework-docs/modules/ROOT/pages/data-access/appendix.adoc index 3bd4f80fdeea..4374af3b7e26 100644 --- a/framework-docs/modules/ROOT/pages/data-access/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/appendix.adoc @@ -1,10 +1,10 @@ -[[data.access.appendix]] +[[appendix]] = Appendix -[[data.access.xsd-schemas]] +[[xsd-schemas]] == XML Schemas This part of the appendix lists XML schemas for data access, including the following: diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc index 52a2ddb264fe..d64cef5a2bf3 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc @@ -179,7 +179,7 @@ infrastructure. NOTE: The preceding definition of the `dataSource` bean uses the `` tag from the `jee` namespace. For more information see -xref:integration/appendix.adoc#integration.appendix.xsd-schemas-jee[The JEE Schema]. +xref:integration/appendix.adoc#xsd-schemas-jee[The JEE Schema]. NOTE: If you use JTA, your transaction manager definition should look the same, regardless of what data access technology you use, be it JDBC, Hibernate JPA, or any other supported diff --git a/framework-docs/modules/ROOT/pages/integration/appendix.adoc b/framework-docs/modules/ROOT/pages/integration/appendix.adoc index b07294bdbaf1..78f99fc50ba6 100644 --- a/framework-docs/modules/ROOT/pages/integration/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/integration/appendix.adoc @@ -1,17 +1,17 @@ -[[integration.appendix]] +[[appendix]] = Appendix -[[integration.appendix.xsd-schemas]] +[[appendix.xsd-schemas]] == XML Schemas This part of the appendix lists XML schemas related to integration technologies. -[[integration.appendix.xsd-schemas-jee]] +[[appendix.xsd-schemas-jee]] === The `jee` Schema The `jee` elements deal with issues related to Jakarta EE (Enterprise Edition) configuration, @@ -40,7 +40,7 @@ correct schema so that the elements in the `jee` namespace are available to you: -[[integration.appendix.xsd-schemas-jee-jndi-lookup]] +[[appendix.xsd-schemas-jee-jndi-lookup]] ==== (simple) The following example shows how to use JNDI to look up a data source without the `jee` schema: @@ -71,7 +71,7 @@ schema: -[[integration.appendix.xsd-schemas-jee-jndi-lookup-environment-single]] +[[appendix.xsd-schemas-jee-jndi-lookup-environment-single]] ==== `` (with Single JNDI Environment Setting) The following example shows how to use JNDI to look up an environment variable without @@ -99,7 +99,7 @@ The following example shows how to use JNDI to look up an environment variable w ---- -[[integration.appendix.xsd-schemas-jee-jndi-lookup-environment-multiple]] +[[appendix.xsd-schemas-jee-jndi-lookup-environment-multiple]] ==== `` (with Multiple JNDI Environment Settings) The following example shows how to use JNDI to look up multiple environment variables @@ -133,7 +133,7 @@ The following example shows how to use JNDI to look up multiple environment vari ---- -[[integration.appendix.xsd-schemas-jee-jndi-lookup-complex]] +[[appendix.xsd-schemas-jee-jndi-lookup-complex]] ==== `` (Complex) The following example shows how to use JNDI to look up a data source and a number of @@ -167,7 +167,7 @@ different properties with `jee`: -[[integration.appendix.xsd-schemas-jee-local-slsb]] +[[appendix.xsd-schemas-jee-local-slsb]] ==== `` (Simple) The `` element configures a reference to a local EJB Stateless Session Bean. @@ -195,7 +195,7 @@ with `jee`: -[[integration.appendix.xsd-schemas-jee-local-slsb-complex]] +[[appendix.xsd-schemas-jee-local-slsb-complex]] ==== `` (Complex) The `` element configures a reference to a local EJB Stateless Session Bean. @@ -229,7 +229,7 @@ and a number of properties with `jee`: ---- -[[integration.appendix.xsd-schemas-jee-remote-slsb]] +[[appendix.xsd-schemas-jee-remote-slsb]] ==== The `` element configures a reference to a `remote` EJB Stateless Session Bean. @@ -268,7 +268,7 @@ with `jee`: -[[integration.appendix.xsd-schemas-jms]] +[[appendix.xsd-schemas-jms]] === The `jms` Schema The `jms` elements deal with configuring JMS-related beans, such as Spring's @@ -301,7 +301,7 @@ are available to you: -[[integration.appendix.xsd-schemas-context-mbe]] +[[appendix.xsd-schemas-context-mbe]] === Using `` This element is detailed in @@ -309,7 +309,7 @@ xref:integration/jmx/naming.adoc#jmx-context-mbeanexport[Configuring Annotation- -[[integration.appendix.xsd-schemas-cache]] +[[appendix.xsd-schemas-cache]] === The `cache` Schema You can use the `cache` elements to enable support for Spring's `@CacheEvict`, `@CachePut`, diff --git a/framework-docs/modules/ROOT/pages/integration/observability.adoc b/framework-docs/modules/ROOT/pages/integration/observability.adoc index ccb8a6b78440..0fe7a1a8b7de 100644 --- a/framework-docs/modules/ROOT/pages/integration/observability.adoc +++ b/framework-docs/modules/ROOT/pages/integration/observability.adoc @@ -1,4 +1,4 @@ -[[integration.observability]] +[[observability]] = Observability Support Micrometer defines an https://micrometer.io/docs/observation[Observation concept that enables both Metrics and Traces] in applications. @@ -10,7 +10,7 @@ Spring Framework instruments various parts of its own codebase to publish observ You can learn more about {docs-spring-boot}/html/actuator.html#actuator.metrics[configuring the observability infrastructure in Spring Boot]. -[[integration.observability.list]] +[[observability.list]] == List of produced Observations Spring Framework instruments various features for observability. @@ -21,10 +21,10 @@ As outlined xref:integration/observability.adoc[at the beginning of this section |=== |Observation name |Description -|xref:integration/observability.adoc#integration.observability.http-client[`"http.client.requests"`] +|xref:integration/observability.adoc#http-client[`"http.client.requests"`] |Time spent for HTTP client exchanges -|xref:integration/observability.adoc#integration.observability.http-server[`"http.server.requests"`] +|xref:integration/observability.adoc#http-server[`"http.server.requests"`] |Processing time for HTTP server exchanges at the Framework level |=== @@ -33,7 +33,7 @@ https://micrometer.io/docs/concepts#_naming_meters[to the format preferred by th (Prometheus, Atlas, Graphite, InfluxDB...). -[[integration.observability.concepts]] +[[observability.concepts]] == Micrometer Observation concepts If you are not familiar with Micrometer Observation, here's a quick summary of the new concepts you should know about. @@ -49,7 +49,7 @@ If you are not familiar with Micrometer Observation, here's a quick summary of t * An `ObservationDocumentation` documents all observations in a particular domain, listing the expected key names and their meaning. -[[integration.observability.config]] +[[observability.config]] == Configuring Observations Global configuration options are available at the `ObservationRegistry#observationConfig()` level. @@ -59,33 +59,33 @@ Each instrumented component will provide two extension points: * providing a custom `ObservationConvention` to change the default observation name and extracted `KeyValues` -[[integration.observability.config.conventions]] +[[observability.config.conventions]] === Using custom Observation conventions Let's take the example of the Spring MVC "http.server.requests" metrics instrumentation with the `ServerHttpObservationFilter`. This observation is using a `ServerRequestObservationConvention` with a `ServerRequestObservationContext`; custom conventions can be configured on the Servlet filter. If you would like to customize the metadata produced with the observation, you can extend the `DefaultServerRequestObservationConvention` for your requirements: -include-code::ExtendedServerRequestObservationConvention[] +include-code::./ExtendedServerRequestObservationConvention[] If you want full control, you can then implement the entire convention contract for the observation you're interested in: -include-code::CustomServerRequestObservationConvention[] +include-code::./CustomServerRequestObservationConvention[] You can also achieve similar goals using a custom `ObservationFilter` - adding or removing key values for an observation. Filters do not replace the default convention and are used as a post-processing component. -include-code::ServerRequestObservationFilter[] +include-code::./ServerRequestObservationFilter[] You can configure `ObservationFilter` instances on the `ObservationRegistry`. -[[integration.observability.http-server]] +[[observability.http-server]] == HTTP Server instrumentation HTTP server exchanges observations are created with the name `"http.server.requests"` for Servlet and Reactive applications. -[[integration.observability.http-server.servlet]] +[[observability.http-server.servlet]] === Servlet applications Applications need to configure the `org.springframework.web.filter.ServerHttpObservationFilter` Servlet filter in their application. @@ -95,7 +95,7 @@ This will only record an observation as an error if the `Exception` has not been Typically, all exceptions handled by Spring MVC's `@ExceptionHandler` and xref:web/webmvc/mvc-ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: -include-code::UserController[] +include-code::./UserController[] By default, the following `KeyValues` are created: @@ -118,7 +118,7 @@ By default, the following `KeyValues` are created: |=== -[[integration.observability.http-server.reactive]] +[[observability.http-server.reactive]] === Reactive applications Applications need to configure the `org.springframework.web.filter.reactive.ServerHttpObservationFilter` reactive `WebFilter` in their application. @@ -128,7 +128,7 @@ This will only record an observation as an error if the `Exception` has not been Typically, all exceptions handled by Spring WebFlux's `@ExceptionHandler` and xref:web/webflux/ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: -include-code::UserController[] +include-code::./UserController[] By default, the following `KeyValues` are created: @@ -152,13 +152,13 @@ By default, the following `KeyValues` are created: -[[integration.observability.http-client]] +[[observability.http-client]] == HTTP Client instrumentation HTTP client exchanges observations are created with the name `"http.client.requests"` for blocking and reactive clients. Unlike their server counterparts, the instrumentation is implemented directly in the client so the only required step is to configure an `ObservationRegistry` on the client. -[[integration.observability.http-client.resttemplate]] +[[observability.http-client.resttemplate]] === RestTemplate Applications must configure an `ObservationRegistry` on `RestTemplate` instances to enable the instrumentation; without that, observations are "no-ops". @@ -187,7 +187,7 @@ Instrumentation is using the `org.springframework.http.client.observation.Client -[[integration.observability.http-client.webclient]] +[[observability.http-client.webclient]] === WebClient Applications must configure an `ObservationRegistry` on the `WebClient` builder to enable the instrumentation; without that, observations are "no-ops". diff --git a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc index b34aa4c85d09..1e256a061dc1 100644 --- a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc +++ b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc @@ -118,7 +118,7 @@ accessing the status of a response that represents an error (such as 401). If th issue, switch to another HTTP client library. NOTE: `RestTemplate` can be instrumented for observability, in order to produce metrics and traces. -See the xref:integration/observability.adoc#integration.observability.http-client.resttemplate[RestTemplate Observability support] section. +See the xref:integration/observability.adoc#http-client.resttemplate[RestTemplate Observability support] section. [[rest-resttemplate-uri]] ==== URIs diff --git a/framework-docs/modules/ROOT/pages/testing/appendix.adoc b/framework-docs/modules/ROOT/pages/testing/appendix.adoc index b831676c579b..0f1591ce97ad 100644 --- a/framework-docs/modules/ROOT/pages/testing/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/testing/appendix.adoc @@ -1,4 +1,4 @@ -[[testing.appendix]] +[[appendix]] = Appendix :page-section-summary-toc: 1 diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc index 88487c500217..5f9c7c97f669 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc @@ -14,7 +14,7 @@ following features. testing annotations -- as long as the tests are run using a JUnit Platform `TestEngine` that is registered for the current project. * Build-time AOT processing: each unique test `ApplicationContext` in the current project - will be xref:core/aot.adoc#core.aot.refresh[refreshed for AOT processing]. + will be xref:core/aot.adoc#refresh[refreshed for AOT processing]. * Runtime AOT support: when executing in AOT runtime mode, a Spring integration test will use an AOT-optimized `ApplicationContext` that participates transparently with the xref:testing/testcontext-framework/ctx-management/caching.adoc[context cache]. @@ -35,7 +35,7 @@ the following options. via {api-spring-framework}/context/annotation/ImportRuntimeHints.html[`@ImportRuntimeHints`]. * Annotate a test class with {api-spring-framework}/aot/hint/annotation/Reflective.html[`@Reflective`] or {api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`]. -* See xref:core/aot.adoc#core.aot.hints[Runtime Hints] for details on Spring's core runtime hints +* See xref:core/aot.adoc#hints[Runtime Hints] for details on Spring's core runtime hints and annotation support. [TIP] diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc index 608d2cc117c7..3b4b44e64d63 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc @@ -16,8 +16,8 @@ You can also use `WebClient.builder()` with further options: * `filter`: Client filter for every request. * `exchangeStrategies`: HTTP message reader/writer customizations. * `clientConnector`: HTTP client library settings. -* `observationRegistry`: the registry to use for enabling xref:integration/observability.adoc#integration.observability.http-client.webclient[Observability support]. -* `observationConvention`: xref:integration/observability.adoc#integration.observability.config[an optional, custom convention to extract metadata] for recorded observations. +* `observationRegistry`: the registry to use for enabling xref:integration/observability.adoc#http-client.webclient[Observability support]. +* `observationConvention`: xref:integration/observability.adoc#config[an optional, custom convention to extract metadata] for recorded observations. For example: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc index 3a5d565e1ea8..e5633bcea279 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc @@ -1,4 +1,4 @@ -[[webmvc.test]] +[[test]] = Testing [.small]#xref:web-reactive.adoc#webflux-test[See equivalent in the Reactive stack]# From e23d2fa6fca095b84932e77783d20dd47464199a Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Thu, 20 Apr 2023 09:51:32 -0500 Subject: [PATCH 26/31] Structural Fixes --- framework-docs/modules/ROOT/nav.adoc | 91 ++++++++++--------- .../modules/ROOT/pages/data-access/oxm.adoc | 3 - .../pages/languages/kotlin/coroutines.adoc | 2 +- .../modules/ROOT/pages/web-reactive.adoc | 62 ------------- .../web/webflux-http-interface-client.adoc | 10 ++ .../pages/web/webflux-reactive-libraries.adoc | 29 ++++++ .../modules/ROOT/pages/web/webflux-test.adoc | 12 +++ .../ROOT/pages/web/webflux-websocket.adoc | 4 +- .../ROOT/pages/web/webflux/caching.adoc | 4 - .../web/webflux/controller/ann-advice.adoc | 5 - .../webflux/controller/ann-initbinder.adoc | 2 - .../ROOT/pages/web/webflux/uri-building.adoc | 4 +- .../ROOT/pages/web/webmvc/mvc-ann-async.adoc | 4 - .../ROOT/pages/web/webmvc/mvc-caching.adoc | 5 - .../web/webmvc/mvc-controller/ann-advice.adoc | 1 - .../webmvc/mvc-controller/ann-initbinder.adoc | 2 +- .../pages/web/webmvc/mvc-uri-building.adoc | 2 +- .../modules/ROOT/pages/web/websocket.adoc | 3 +- .../web/web-data-binding-model-design.adoc | 0 .../{pages => partials}/web/web-uris.adoc | 0 .../web/websocket-intro.adoc | 0 21 files changed, 103 insertions(+), 142 deletions(-) create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-http-interface-client.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-reactive-libraries.adoc create mode 100644 framework-docs/modules/ROOT/pages/web/webflux-test.adoc rename framework-docs/modules/ROOT/{pages => partials}/web/web-data-binding-model-design.adoc (100%) rename framework-docs/modules/ROOT/{pages => partials}/web/web-uris.adoc (100%) rename framework-docs/modules/ROOT/{pages => partials}/web/websocket-intro.adoc (100%) diff --git a/framework-docs/modules/ROOT/nav.adoc b/framework-docs/modules/ROOT/nav.adoc index 3f7a6e2ba07a..c0aa14fcb7eb 100644 --- a/framework-docs/modules/ROOT/nav.adoc +++ b/framework-docs/modules/ROOT/nav.adoc @@ -158,31 +158,31 @@ **** xref:testing/spring-mvc-test-framework/server-htmlunit/geb.adoc[] ** xref:testing/spring-mvc-test-client.adoc[] ** xref:testing/appendix.adoc[] -** xref:testing/annotations.adoc[] -*** xref:testing/annotations/integration-standard.adoc[] -*** xref:testing/annotations/integration-spring.adoc[] -**** xref:testing/annotations/integration-spring/annotation-bootstrapwith.adoc[] -**** xref:testing/annotations/integration-spring/annotation-contextconfiguration.adoc[] -**** xref:testing/annotations/integration-spring/annotation-webappconfiguration.adoc[] -**** xref:testing/annotations/integration-spring/annotation-contexthierarchy.adoc[] -**** xref:testing/annotations/integration-spring/annotation-activeprofiles.adoc[] -**** xref:testing/annotations/integration-spring/annotation-testpropertysource.adoc[] -**** xref:testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc[] -**** xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[] -**** xref:testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc[] -**** xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[] -**** xref:testing/annotations/integration-spring/annotation-commit.adoc[] -**** xref:testing/annotations/integration-spring/annotation-rollback.adoc[] -**** xref:testing/annotations/integration-spring/annotation-beforetransaction.adoc[] -**** xref:testing/annotations/integration-spring/annotation-aftertransaction.adoc[] -**** xref:testing/annotations/integration-spring/annotation-sql.adoc[] -**** xref:testing/annotations/integration-spring/annotation-sqlconfig.adoc[] -**** xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[] -**** xref:testing/annotations/integration-spring/annotation-sqlgroup.adoc[] -*** xref:testing/annotations/integration-junit4.adoc[] -*** xref:testing/annotations/integration-junit-jupiter.adoc[] -*** xref:testing/annotations/integration-meta.adoc[] -** xref:testing/resources.adoc[] +*** xref:testing/annotations.adoc[] +**** xref:testing/annotations/integration-standard.adoc[] +**** xref:testing/annotations/integration-spring.adoc[] +***** xref:testing/annotations/integration-spring/annotation-bootstrapwith.adoc[] +***** xref:testing/annotations/integration-spring/annotation-contextconfiguration.adoc[] +***** xref:testing/annotations/integration-spring/annotation-webappconfiguration.adoc[] +***** xref:testing/annotations/integration-spring/annotation-contexthierarchy.adoc[] +***** xref:testing/annotations/integration-spring/annotation-activeprofiles.adoc[] +***** xref:testing/annotations/integration-spring/annotation-testpropertysource.adoc[] +***** xref:testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc[] +***** xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[] +***** xref:testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc[] +***** xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[] +***** xref:testing/annotations/integration-spring/annotation-commit.adoc[] +***** xref:testing/annotations/integration-spring/annotation-rollback.adoc[] +***** xref:testing/annotations/integration-spring/annotation-beforetransaction.adoc[] +***** xref:testing/annotations/integration-spring/annotation-aftertransaction.adoc[] +***** xref:testing/annotations/integration-spring/annotation-sql.adoc[] +***** xref:testing/annotations/integration-spring/annotation-sqlconfig.adoc[] +***** xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[] +***** xref:testing/annotations/integration-spring/annotation-sqlgroup.adoc[] +**** xref:testing/annotations/integration-junit4.adoc[] +**** xref:testing/annotations/integration-junit-jupiter.adoc[] +**** xref:testing/annotations/integration-meta.adoc[] +*** xref:testing/resources.adoc[] * xref:data-access.adoc[] ** xref:data-access/transaction.adoc[] *** xref:data-access/transaction/motivation.adoc[] @@ -268,11 +268,24 @@ **** xref:web/webmvc/mvc-controller/ann-initbinder.adoc[] **** xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc[] **** xref:web/webmvc/mvc-controller/ann-advice.adoc[] +*** xref:web/webmvc-functional.adoc[] *** xref:web/webmvc/mvc-uri-building.adoc[] *** xref:web/webmvc/mvc-ann-async.adoc[] +*** xref:web/webmvc-cors.adoc[] *** xref:web/webmvc/mvc-ann-rest-exceptions.adoc[] *** xref:web/webmvc/mvc-security.adoc[] *** xref:web/webmvc/mvc-caching.adoc[] +*** xref:web/webmvc-view.adoc[] +**** xref:web/webmvc-view/mvc-thymeleaf.adoc[] +**** xref:web/webmvc-view/mvc-freemarker.adoc[] +**** xref:web/webmvc-view/mvc-groovymarkup.adoc[] +**** xref:web/webmvc-view/mvc-script.adoc[] +**** xref:web/webmvc-view/mvc-jsp.adoc[] +**** xref:web/webmvc-view/mvc-feeds.adoc[] +**** xref:web/webmvc-view/mvc-document.adoc[] +**** xref:web/webmvc-view/mvc-jackson.adoc[] +**** xref:web/webmvc-view/mvc-xml-marshalling.adoc[] +**** xref:web/webmvc-view/mvc-xslt.adoc[] *** xref:web/webmvc/mvc-config.adoc[] **** xref:web/webmvc/mvc-config/enable.adoc[] **** xref:web/webmvc/mvc-config/customize.adoc[] @@ -289,21 +302,6 @@ **** xref:web/webmvc/mvc-config/advanced-java.adoc[] **** xref:web/webmvc/mvc-config/advanced-xml.adoc[] *** xref:web/webmvc/mvc-http2.adoc[] -** xref:web/web-data-binding-model-design.adoc[] -** xref:web/webmvc-functional.adoc[] -** xref:web/web-uris.adoc[] -** xref:web/webmvc-cors.adoc[] -** xref:web/webmvc-view.adoc[] -*** xref:web/webmvc-view/mvc-thymeleaf.adoc[] -*** xref:web/webmvc-view/mvc-freemarker.adoc[] -*** xref:web/webmvc-view/mvc-groovymarkup.adoc[] -*** xref:web/webmvc-view/mvc-script.adoc[] -*** xref:web/webmvc-view/mvc-jsp.adoc[] -*** xref:web/webmvc-view/mvc-feeds.adoc[] -*** xref:web/webmvc-view/mvc-document.adoc[] -*** xref:web/webmvc-view/mvc-jackson.adoc[] -*** xref:web/webmvc-view/mvc-xml-marshalling.adoc[] -*** xref:web/webmvc-view/mvc-xslt.adoc[] ** xref:web/webmvc-client.adoc[] ** xref:web/webmvc-test.adoc[] ** xref:web/websocket.adoc[] @@ -333,7 +331,6 @@ **** xref:web/websocket/stomp/configuration-performance.adoc[] **** xref:web/websocket/stomp/stats.adoc[] **** xref:web/websocket/stomp/testing.adoc[] -** xref:web/websocket-intro.adoc[] ** xref:web/integration.adoc[] * xref:web-reactive.adoc[] ** xref:web/webflux.adoc[] @@ -365,15 +362,15 @@ **** xref:web/webflux/controller/ann-initbinder.adoc[] **** xref:web/webflux/controller/ann-exceptions.adoc[] **** xref:web/webflux/controller/ann-advice.adoc[] +*** xref:web/webflux-functional.adoc[] *** xref:web/webflux/uri-building.adoc[] +*** xref:web/webflux-cors.adoc[] *** xref:web/webflux/ann-rest-exceptions.adoc[] *** xref:web/webflux/security.adoc[] *** xref:web/webflux/caching.adoc[] +*** xref:web/webflux-view.adoc[] *** xref:web/webflux/config.adoc[] *** xref:web/webflux/http2.adoc[] -** xref:web/webflux-functional.adoc[] -** xref:web/webflux-cors.adoc[] -** xref:web/webflux-view.adoc[] ** xref:web/webflux-webclient.adoc[] *** xref:web/webflux-webclient/client-builder.adoc[] *** xref:web/webflux-webclient/client-retrieve.adoc[] @@ -384,8 +381,11 @@ *** xref:web/webflux-webclient/client-context.adoc[] *** xref:web/webflux-webclient/client-synchronous.adoc[] *** xref:web/webflux-webclient/client-testing.adoc[] +** xref:web/webflux-http-interface-client.adoc[] ** xref:web/webflux-websocket.adoc[] -* xref:rsocket.adoc[] +** xref:web/webflux-test.adoc[] +** xref:rsocket.adoc[] +** xref:web/webflux-reactive-libraries.adoc[] * xref:integration.adoc[] ** xref:integration/rest-clients.adoc[] ** xref:integration/jms.adoc[] @@ -431,3 +431,4 @@ ** xref:languages/groovy.adoc[] ** xref:languages/dynamic.adoc[] * xref:appendix.adoc[] +* https://github.com/spring-projects/spring-framework/wiki[Wiki] \ No newline at end of file diff --git a/framework-docs/modules/ROOT/pages/data-access/oxm.adoc b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc index 81aec53f134f..a1637cbff6a3 100644 --- a/framework-docs/modules/ROOT/pages/data-access/oxm.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc @@ -558,6 +558,3 @@ Therefore, it has limited namespace support. As a result, it is rather unsuitabl within Web Services. - - -include:../:data-access/appendix.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/coroutines.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/coroutines.adoc index 699ab8d43813..17becb7aa151 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/coroutines.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/coroutines.adoc @@ -39,7 +39,7 @@ Version `1.4.0` and above are supported. -[[how-reactive-translates-to-coroutines?]] +[[how-reactive-translates-to-coroutines]] == How Reactive translates to Coroutines? For return values, the translation from Reactive to Coroutines APIs is the following: diff --git a/framework-docs/modules/ROOT/pages/web-reactive.adoc b/framework-docs/modules/ROOT/pages/web-reactive.adoc index 4fc5fbe565c1..b7ef832ffa33 100644 --- a/framework-docs/modules/ROOT/pages/web-reactive.adoc +++ b/framework-docs/modules/ROOT/pages/web-reactive.adoc @@ -9,65 +9,3 @@ the reactive xref:web/webflux-webclient.adoc[`WebClient`], support for xref:web- and xref:web-reactive.adoc#webflux-reactive-libraries[reactive libraries]. For Servlet-stack web applications, see xref:web.adoc[Web on Servlet Stack]. - - - -[[webflux-http-interface-client]] -== HTTP Interface Client - -The Spring Frameworks lets you define an HTTP service as a Java interface with HTTP -exchange methods. You can then generate a proxy that implements this interface and -performs the exchanges. This helps to simplify HTTP remote access and provides additional -flexibility for to choose an API style such as synchronous or reactive. - -See xref:integration/rest-clients.adoc#rest-http-interface[REST Endpoints] for details. - - - - - -[[webflux-test]] -== Testing -[.small]#xref:web/webmvc-test.adoc[Same in Spring MVC]# - -The `spring-test` module provides mock implementations of `ServerHttpRequest`, -`ServerHttpResponse`, and `ServerWebExchange`. -See xref:testing/unit.adoc#mock-objects-web-reactive[Spring Web Reactive] for a -discussion of mock objects. - -xref:testing/webtestclient.adoc[`WebTestClient`] builds on these mock request and -response objects to provide support for testing WebFlux applications without an HTTP -server. You can use the `WebTestClient` for end-to-end integration tests, too. - - - - -[[webflux-reactive-libraries]] -== Reactive Libraries - -`spring-webflux` depends on `reactor-core` and uses it internally to compose asynchronous -logic and to provide Reactive Streams support. Generally, WebFlux APIs return `Flux` or -`Mono` (since those are used internally) and leniently accept any Reactive Streams -`Publisher` implementation as input. The use of `Flux` versus `Mono` is important, because -it helps to express cardinality -- for example, whether a single or multiple asynchronous -values are expected, and that can be essential for making decisions (for example, when -encoding or decoding HTTP messages). - -For annotated controllers, WebFlux transparently adapts to the reactive library chosen by -the application. This is done with the help of the -{api-spring-framework}/core/ReactiveAdapterRegistry.html[`ReactiveAdapterRegistry`], which -provides pluggable support for reactive library and other asynchronous types. The registry -has built-in support for RxJava 3, Kotlin coroutines and SmallRye Mutiny, but you can -register others, too. - -For functional APIs (such as <>, the `WebClient`, and others), the general rules -for WebFlux APIs apply -- `Flux` and `Mono` as return values and a Reactive Streams -`Publisher` as input. When a `Publisher`, whether custom or from another reactive library, -is provided, it can be treated only as a stream with unknown semantics (0..N). If, however, -the semantics are known, you can wrap it with `Flux` or `Mono.from(Publisher)` instead -of passing the raw `Publisher`. - -For example, given a `Publisher` that is not a `Mono`, the Jackson JSON message writer -expects multiple values. If the media type implies an infinite stream (for example, -`application/json+stream`), values are written and flushed individually. Otherwise, -values are buffered into a list and rendered as a JSON array. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-http-interface-client.adoc b/framework-docs/modules/ROOT/pages/web/webflux-http-interface-client.adoc new file mode 100644 index 000000000000..871667acaaa9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-http-interface-client.adoc @@ -0,0 +1,10 @@ +[[webflux-http-interface-client]] += HTTP Interface Client + +The Spring Frameworks lets you define an HTTP service as a Java interface with HTTP +exchange methods. You can then generate a proxy that implements this interface and +performs the exchanges. This helps to simplify HTTP remote access and provides additional +flexibility for to choose an API style such as synchronous or reactive. + +See xref:integration/rest-clients.adoc#rest-http-interface[REST Endpoints] for details. + diff --git a/framework-docs/modules/ROOT/pages/web/webflux-reactive-libraries.adoc b/framework-docs/modules/ROOT/pages/web/webflux-reactive-libraries.adoc new file mode 100644 index 000000000000..45ac4fcd581d --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-reactive-libraries.adoc @@ -0,0 +1,29 @@ +[[webflux-reactive-libraries]] += Reactive Libraries + +`spring-webflux` depends on `reactor-core` and uses it internally to compose asynchronous +logic and to provide Reactive Streams support. Generally, WebFlux APIs return `Flux` or +`Mono` (since those are used internally) and leniently accept any Reactive Streams +`Publisher` implementation as input. The use of `Flux` versus `Mono` is important, because +it helps to express cardinality -- for example, whether a single or multiple asynchronous +values are expected, and that can be essential for making decisions (for example, when +encoding or decoding HTTP messages). + +For annotated controllers, WebFlux transparently adapts to the reactive library chosen by +the application. This is done with the help of the +{api-spring-framework}/core/ReactiveAdapterRegistry.html[`ReactiveAdapterRegistry`], which +provides pluggable support for reactive library and other asynchronous types. The registry +has built-in support for RxJava 3, Kotlin coroutines and SmallRye Mutiny, but you can +register others, too. + +For functional APIs (such as <>, the `WebClient`, and others), the general rules +for WebFlux APIs apply -- `Flux` and `Mono` as return values and a Reactive Streams +`Publisher` as input. When a `Publisher`, whether custom or from another reactive library, +is provided, it can be treated only as a stream with unknown semantics (0..N). If, however, +the semantics are known, you can wrap it with `Flux` or `Mono.from(Publisher)` instead +of passing the raw `Publisher`. + +For example, given a `Publisher` that is not a `Mono`, the Jackson JSON message writer +expects multiple values. If the media type implies an infinite stream (for example, +`application/json+stream`), values are written and flushed individually. Otherwise, +values are buffered into a list and rendered as a JSON array. \ No newline at end of file diff --git a/framework-docs/modules/ROOT/pages/web/webflux-test.adoc b/framework-docs/modules/ROOT/pages/web/webflux-test.adoc new file mode 100644 index 000000000000..ed93058dac2b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webflux-test.adoc @@ -0,0 +1,12 @@ +[[webflux-test]] += Testing +[.small]#xref:web/webmvc-test.adoc[Same in Spring MVC]# + +The `spring-test` module provides mock implementations of `ServerHttpRequest`, +`ServerHttpResponse`, and `ServerWebExchange`. +See xref:testing/unit.adoc#mock-objects-web-reactive[Spring Web Reactive] for a +discussion of mock objects. + +xref:testing/webtestclient.adoc[`WebTestClient`] builds on these mock request and +response objects to provide support for testing WebFlux applications without an HTTP +server. You can use the `WebTestClient` for end-to-end integration tests, too. \ No newline at end of file diff --git a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc index e68b54067a66..01f1134dd852 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc @@ -5,9 +5,7 @@ This part of the reference documentation covers support for reactive-stack WebSocket messaging. - - - +include::partial$web/websocket-intro.adoc[leveloffset=+1] [[webflux-websocket-server]] == WebSocket API diff --git a/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc index 7586c31997ba..0c5c120714b1 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc @@ -171,7 +171,3 @@ to 412 (PRECONDITION_FAILED) to prevent concurrent modification. You should serve static resources with a `Cache-Control` and conditional response headers for optimal performance. See the section on configuring xref:web/webflux/config.adoc#webflux-config-static-resources[Static Resources]. - -include:../:webflux-view.adoc[leveloffset=+1] - - diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc index 0be31002a66e..1ad6529c0683 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc @@ -62,8 +62,3 @@ performance if used extensively. See the {api-spring-framework}/web/bind/annotation/ControllerAdvice.html[`@ControllerAdvice`] javadoc for more details. -include:../../:webflux-functional.adoc[leveloffset=+1] - - - - diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc index d3f5cb6b946f..2c523e925fd8 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc @@ -102,6 +102,4 @@ controller-specific `Formatter` instances, as the following example shows: == Model Design [.small]#xref:web/webmvc/mvc-controller/ann-initbinder.adoc#mvc-ann-initbinder-model-design[See equivalent in the Servlet stack]# -include:../../:web-data-binding-model-design.adoc[] - diff --git a/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc index 559fcd2479ee..8ca87a11f346 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc @@ -6,8 +6,6 @@ This section describes various options available in the Spring Framework to prepare URIs. -include:../:web-uris.adoc[leveloffset=+2] - -include:../:webflux-cors.adoc[leveloffset=+1] +include::partial$web/web-uris.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc index 4fd42b9f7144..8cad1a50b913 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc @@ -484,7 +484,3 @@ Note that you can also set the default timeout value on a `DeferredResult`, a `ResponseBodyEmitter`, and an `SseEmitter`. For a `Callable`, you can use `WebAsyncTask` to provide a timeout value. - -include:../:webmvc-cors.adoc[leveloffset=+1] - - diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc index f84647c9a7f6..da2ed1757f1f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc @@ -187,8 +187,3 @@ for optimal performance. See the section on configuring xref:web/webmvc/mvc-conf You can use the `ShallowEtagHeaderFilter` to add "`shallow`" `eTag` values that are computed from the response content and, thus, save bandwidth but not CPU time. See xref:web/webmvc/filters.adoc#filters-shallow-etag[Shallow ETag]. -include:../:webmvc-view.adoc[leveloffset=+1] - - - - diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc index 1f50964cf4fd..7cda8894f6ae 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc @@ -59,7 +59,6 @@ performance if used extensively. See the {api-spring-framework}/web/bind/annotation/ControllerAdvice.html[`@ControllerAdvice`] javadoc for more details. -include:../../:webmvc-functional.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc index ded39846ce0c..2c2a5ecce647 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc @@ -97,6 +97,6 @@ controller-specific `Formatter` implementations, as the following example shows: == Model Design [.small]#xref:web/webflux/controller/ann-initbinder.adoc#webflux-ann-initbinder-model-design[See equivalent in the Reactive stack]# -include:../../:web-data-binding-model-design.adoc[] +include::partial$web/web-data-binding-model-design.adoc[] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc index 235652b98492..ea5a7699957a 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc @@ -5,7 +5,7 @@ This section describes various options available in the Spring Framework to work with URI's. -include:../:web-uris.adoc[leveloffset=+2] +include::partial$web/web-uris.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/websocket.adoc b/framework-docs/modules/ROOT/pages/web/websocket.adoc index d9fd668f0303..726c9c2de3ed 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket.adoc @@ -7,7 +7,6 @@ This part of the reference documentation covers support for Servlet stack, WebSo messaging that includes raw WebSocket interactions, WebSocket emulation through SockJS, and publish-subscribe messaging through STOMP as a sub-protocol over WebSocket. - - +include::partial$web/websocket-intro.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/web-data-binding-model-design.adoc b/framework-docs/modules/ROOT/partials/web/web-data-binding-model-design.adoc similarity index 100% rename from framework-docs/modules/ROOT/pages/web/web-data-binding-model-design.adoc rename to framework-docs/modules/ROOT/partials/web/web-data-binding-model-design.adoc diff --git a/framework-docs/modules/ROOT/pages/web/web-uris.adoc b/framework-docs/modules/ROOT/partials/web/web-uris.adoc similarity index 100% rename from framework-docs/modules/ROOT/pages/web/web-uris.adoc rename to framework-docs/modules/ROOT/partials/web/web-uris.adoc diff --git a/framework-docs/modules/ROOT/pages/web/websocket-intro.adoc b/framework-docs/modules/ROOT/partials/web/websocket-intro.adoc similarity index 100% rename from framework-docs/modules/ROOT/pages/web/websocket-intro.adoc rename to framework-docs/modules/ROOT/partials/web/websocket-intro.adoc From 04433c552afaeaa6ceaa916a23fc8fbfb1e949fc Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Thu, 20 Apr 2023 16:06:19 -0500 Subject: [PATCH 27/31] Add ./github/workflow/deploy-docs.yml --- .github/workflows/deploy-docs.yml | 32 +++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/workflows/deploy-docs.yml diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000000..4b03c87d01af --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,32 @@ +name: Deploy Docs +on: + push: + branches-ignore: [ gh-pages ] + tags: '**' + repository_dispatch: + types: request-build-reference # legacy + schedule: + - cron: '0 10 * * *' # Once per day at 10am UTC + workflow_dispatch: +permissions: + actions: write +jobs: + build: + runs-on: ubuntu-latest + # if: github.repository_owner == 'spring-projects' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: docs-build + fetch-depth: 1 + - name: Dispatch (partial build) + if: github.ref_type == 'branch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} + - name: Dispatch (full build) + if: github.ref_type == 'tag' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) From a8ba7e79865ace3677b12b4345bab6088780137d Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Thu, 20 Apr 2023 16:21:36 -0500 Subject: [PATCH 28/31] Migrate to Asciidoctor Tabs --- framework-docs/antora-playbook.yml | 2 - .../ROOT/pages/core/aop-api/advice.adoc | 90 +++++-- .../ROOT/pages/core/aop-api/advised.adoc | 20 +- .../modules/ROOT/pages/core/aop-api/pfb.adoc | 10 +- .../ROOT/pages/core/aop-api/pointcuts.adoc | 10 +- .../modules/ROOT/pages/core/aop-api/prog.adoc | 10 +- .../ROOT/pages/core/aop-api/targetsource.adoc | 20 +- .../pages/core/aop/aspectj-programmatic.adoc | 10 +- .../ROOT/pages/core/aop/ataspectj/advice.adoc | 170 ++++++++++--- .../core/aop/ataspectj/aspectj-support.adoc | 10 +- .../pages/core/aop/ataspectj/at-aspectj.adoc | 10 +- .../pages/core/aop/ataspectj/example.adoc | 26 +- .../aop/ataspectj/instantiation-models.adoc | 10 +- .../core/aop/ataspectj/introductions.adoc | 20 +- .../pages/core/aop/ataspectj/pointcuts.adoc | 26 +- .../modules/ROOT/pages/core/aop/choosing.adoc | 10 +- .../modules/ROOT/pages/core/aop/proxying.adoc | 50 +++- .../modules/ROOT/pages/core/aop/schema.adoc | 110 ++++++-- .../ROOT/pages/core/aop/using-aspectj.adoc | 90 +++++-- .../modules/ROOT/pages/core/aot.adoc | 24 +- .../ROOT/pages/core/appendix/xml-custom.adoc | 86 +++++-- .../ROOT/pages/core/appendix/xsd-schemas.adoc | 20 +- .../annotation-config/autowired-primary.adoc | 20 +- .../autowired-qualifiers.adoc | 86 +++++-- .../beans/annotation-config/autowired.adoc | 102 ++++++-- .../generics-as-qualifiers.adoc | 30 ++- ...tconstruct-and-predestroy-annotations.adoc | 10 +- .../beans/annotation-config/resource.adoc | 22 +- .../annotation-config/value-annotations.adoc | 70 ++++-- .../modules/ROOT/pages/core/beans/basics.adoc | 50 +++- .../ROOT/pages/core/beans/beanfactory.adoc | 20 +- .../pages/core/beans/classpath-scanning.adoc | 196 ++++++++++++--- .../core/beans/context-introduction.adoc | 150 ++++++++--- .../core/beans/context-load-time-weaver.adoc | 10 +- .../ROOT/pages/core/beans/definition.adoc | 30 ++- .../dependencies/factory-collaborators.adoc | 80 ++++-- .../factory-method-injection.adoc | 60 ++++- .../factory-properties-detailed.adoc | 30 ++- .../ROOT/pages/core/beans/environment.adoc | 122 +++++++-- .../pages/core/beans/factory-extension.adoc | 20 +- .../ROOT/pages/core/beans/factory-nature.adoc | 60 ++++- .../ROOT/pages/core/beans/factory-scopes.adoc | 90 +++++-- .../pages/core/beans/java/basic-concepts.adoc | 10 +- .../core/beans/java/bean-annotation.adoc | 116 +++++++-- .../java/composing-configuration-classes.adoc | 110 ++++++-- .../beans/java/configuration-annotation.adoc | 40 ++- .../beans/java/instantiating-container.adoc | 46 +++- .../core/beans/standard-annotations.adoc | 70 ++++-- .../ROOT/pages/core/databuffer-codec.adoc | 10 +- .../ROOT/pages/core/expressions/beandef.adoc | 40 ++- .../pages/core/expressions/evaluation.adoc | 70 +++++- .../core/expressions/example-classes.adoc | 30 ++- .../language-ref/array-construction.adoc | 10 +- .../language-ref/bean-references.adoc | 20 +- .../language-ref/collection-projection.adoc | 10 +- .../language-ref/collection-selection.adoc | 20 +- .../language-ref/constructors.adoc | 10 +- .../expressions/language-ref/functions.adoc | 30 ++- .../language-ref/inline-lists.adoc | 10 +- .../expressions/language-ref/inline-maps.adoc | 10 +- .../expressions/language-ref/literal.adoc | 10 +- .../expressions/language-ref/methods.adoc | 10 +- .../language-ref/operator-elvis.adoc | 20 +- .../operator-safe-navigation.adoc | 10 +- .../language-ref/operator-ternary.adoc | 20 +- .../expressions/language-ref/operators.adoc | 50 +++- .../language-ref/properties-arrays.adoc | 30 ++- .../expressions/language-ref/templating.adoc | 20 +- .../core/expressions/language-ref/types.adoc | 10 +- .../expressions/language-ref/variables.adoc | 20 +- .../modules/ROOT/pages/core/resources.adoc | 180 +++++++++++--- .../modules/ROOT/pages/core/spring-jcl.adoc | 10 +- .../pages/core/validation/beans-beans.adoc | 80 ++++-- .../pages/core/validation/beanvalidation.adoc | 90 +++++-- .../ROOT/pages/core/validation/convert.adoc | 20 +- ...uring-formatting-globaldatetimeformat.adoc | 10 +- .../ROOT/pages/core/validation/format.adoc | 40 ++- .../ROOT/pages/core/validation/validator.adoc | 30 ++- .../modules/ROOT/pages/data-access/dao.adoc | 35 ++- .../ROOT/pages/data-access/jdbc/advanced.adoc | 40 ++- .../pages/data-access/jdbc/connections.adoc | 10 +- .../ROOT/pages/data-access/jdbc/core.adoc | 235 ++++++++++++++---- .../jdbc/embedded-database-support.adoc | 30 ++- .../ROOT/pages/data-access/jdbc/object.adoc | 100 ++++++-- .../data-access/jdbc/parameter-handling.adoc | 42 +++- .../ROOT/pages/data-access/jdbc/simple.adoc | 110 ++++++-- .../ROOT/pages/data-access/orm/general.adoc | 10 +- .../ROOT/pages/data-access/orm/hibernate.adoc | 30 ++- .../ROOT/pages/data-access/orm/jpa.adoc | 20 +- .../modules/ROOT/pages/data-access/oxm.adoc | 20 +- .../modules/ROOT/pages/data-access/r2dbc.adoc | 138 +++++++--- .../transaction/declarative/annotations.adoc | 60 ++++- .../applying-more-than-just-tx-advice.adoc | 10 +- .../transaction/declarative/aspectj.adoc | 10 +- .../declarative/first-example.adoc | 50 +++- .../transaction/declarative/rolling-back.adoc | 16 +- .../pages/data-access/transaction/event.adoc | 10 +- .../data-access/transaction/programmatic.adoc | 90 +++++-- .../languages/kotlin/bean-definition-dsl.adoc | 2 - .../languages/kotlin/spring-projects-in.adoc | 2 - .../modules/ROOT/pages/rsocket.adoc | 144 ++++++++--- .../integration-junit-jupiter.adoc | 43 +++- .../annotations/integration-junit4.adoc | 30 ++- .../testing/annotations/integration-meta.adoc | 76 ++++-- .../annotation-activeprofiles.adoc | 12 +- .../annotation-aftertransaction.adoc | 6 +- .../annotation-beforetransaction.adoc | 6 +- .../integration-spring/annotation-commit.adoc | 6 +- .../annotation-contextconfiguration.adoc | 24 +- .../annotation-contexthierarchy.adoc | 20 +- .../annotation-dirtiescontext.adoc | 42 +++- .../annotation-dynamicpropertysource.adoc | 6 +- .../annotation-rollback.adoc | 6 +- .../integration-spring/annotation-sql.adoc | 6 +- .../annotation-sqlconfig.adoc | 6 +- .../annotation-sqlgroup.adoc | 6 +- .../annotation-sqlmergemode.adoc | 12 +- .../annotation-testexecutionlisteners.adoc | 6 +- .../annotation-testpropertysource.adoc | 12 +- .../annotation-webappconfiguration.adoc | 12 +- .../pages/testing/spring-mvc-test-client.adoc | 50 +++- .../async-requests.adoc | 6 +- .../server-defining-expectations.adoc | 73 ++++-- .../server-filters.adoc | 10 +- .../server-htmlunit/mah.adoc | 66 +++-- .../server-htmlunit/webdriver.adoc | 120 +++++++-- .../server-htmlunit/why.adoc | 28 ++- .../server-performing-requests.adoc | 58 ++++- .../server-setup-options.adoc | 28 ++- .../server-setup-steps.adoc | 18 +- .../vs-streaming-response.adoc | 6 +- .../application-events.adoc | 6 +- .../testcontext-framework/ctx-management.adoc | 12 +- .../dynamic-property-sources.adoc | 10 +- .../ctx-management/env-profiles.adoc | 107 ++++++-- .../ctx-management/groovy.adoc | 22 +- .../ctx-management/hierarchies.adoc | 38 ++- .../ctx-management/inheritance.adoc | 18 +- .../ctx-management/initializers.adoc | 12 +- .../ctx-management/javaconfig.adoc | 12 +- .../ctx-management/property-sources.adoc | 41 ++- .../ctx-management/web-mocks.adoc | 10 +- .../ctx-management/web.adoc | 33 ++- .../ctx-management/xml.adoc | 18 +- .../testcontext-framework/executing-sql.adoc | 59 ++++- .../testcontext-framework/fixture-di.adoc | 27 +- .../support-classes.adoc | 90 +++++-- .../testcontext-framework/tel-config.adoc | 28 ++- .../testing/testcontext-framework/tx.adoc | 57 ++++- .../web-scoped-beans.adoc | 21 +- .../ROOT/pages/testing/webtestclient.adoc | 188 +++++++++++--- .../modules/ROOT/pages/web/webflux-cors.adoc | 46 +++- .../ROOT/pages/web/webflux-functional.adoc | 175 ++++++++++--- .../modules/ROOT/pages/web/webflux-view.adoc | 40 ++- .../webflux-webclient/client-attributes.adoc | 10 +- .../web/webflux-webclient/client-body.adoc | 90 +++++-- .../web/webflux-webclient/client-builder.adoc | 131 ++++++++-- .../web/webflux-webclient/client-context.adoc | 6 +- .../webflux-webclient/client-exchange.adoc | 10 +- .../web/webflux-webclient/client-filter.adoc | 40 ++- .../webflux-webclient/client-retrieve.adoc | 40 ++- .../webflux-webclient/client-synchronous.adoc | 20 +- .../ROOT/pages/web/webflux-websocket.adoc | 68 ++++- .../ROOT/pages/web/webflux/caching.adoc | 24 +- .../ROOT/pages/web/webflux/config.adoc | 168 ++++++++++--- .../ROOT/pages/web/webflux/controller.adoc | 10 +- .../web/webflux/controller/ann-advice.adoc | 9 +- .../webflux/controller/ann-exceptions.adoc | 6 +- .../webflux/controller/ann-initbinder.adoc | 12 +- .../controller/ann-methods/cookievalue.adoc | 6 +- .../controller/ann-methods/httpentity.adoc | 10 +- .../controller/ann-methods/jackson.adoc | 9 +- .../ann-methods/matrix-variables.adoc | 40 ++- .../ann-methods/modelattrib-method-args.adoc | 28 ++- .../ann-methods/multipart-forms.adoc | 43 +++- .../controller/ann-methods/requestattrib.adoc | 6 +- .../controller/ann-methods/requestbody.adoc | 29 ++- .../controller/ann-methods/requestheader.adoc | 6 +- .../controller/ann-methods/requestparam.adoc | 6 +- .../controller/ann-methods/responsebody.adoc | 10 +- .../ann-methods/responseentity.adoc | 10 +- .../ann-methods/sessionattribute.adoc | 6 +- .../ann-methods/sessionattributes.adoc | 12 +- .../controller/ann-modelattrib-methods.adoc | 40 ++- .../controller/ann-requestmapping.adoc | 74 ++++-- .../pages/web/webflux/controller/ann.adoc | 6 +- .../pages/web/webflux/dispatcher-handler.adoc | 10 +- .../pages/web/webflux/reactive-spring.adoc | 90 +++++-- .../modules/ROOT/pages/web/webmvc-cors.adoc | 50 +++- .../ROOT/pages/web/webmvc-functional.adoc | 162 +++++++++--- .../pages/web/webmvc-view/mvc-document.adoc | 10 +- .../ROOT/pages/web/webmvc-view/mvc-feeds.adoc | 20 +- .../pages/web/webmvc-view/mvc-freemarker.adoc | 20 +- .../web/webmvc-view/mvc-groovymarkup.adoc | 10 +- .../ROOT/pages/web/webmvc-view/mvc-jsp.adoc | 30 ++- .../pages/web/webmvc-view/mvc-script.adoc | 30 ++- .../ROOT/pages/web/webmvc-view/mvc-xslt.adoc | 20 +- .../ROOT/pages/web/webmvc/mvc-ann-async.adoc | 50 +++- .../ROOT/pages/web/webmvc/mvc-caching.adoc | 26 +- .../web/webmvc/mvc-config/advanced-java.adoc | 10 +- .../web/webmvc/mvc-config/advanced-xml.adoc | 10 +- .../mvc-config/content-negotiation.adoc | 10 +- .../web/webmvc/mvc-config/conversion.adoc | 20 +- .../web/webmvc/mvc-config/customize.adoc | 10 +- .../mvc-config/default-servlet-handler.adoc | 20 +- .../pages/web/webmvc/mvc-config/enable.adoc | 10 +- .../web/webmvc/mvc-config/interceptors.adoc | 10 +- .../webmvc/mvc-config/message-converters.adoc | 10 +- .../web/webmvc/mvc-config/path-matching.adoc | 10 +- .../webmvc/mvc-config/static-resources.adoc | 20 +- .../web/webmvc/mvc-config/validation.adoc | 20 +- .../webmvc/mvc-config/view-controller.adoc | 10 +- .../web/webmvc/mvc-config/view-resolvers.adoc | 20 +- .../ROOT/pages/web/webmvc/mvc-controller.adoc | 10 +- .../web/webmvc/mvc-controller/ann-advice.adoc | 10 +- .../mvc-controller/ann-exceptionhandler.adoc | 30 ++- .../webmvc/mvc-controller/ann-initbinder.adoc | 12 +- .../ann-methods/cookievalue.adoc | 6 +- .../ann-methods/httpentity.adoc | 10 +- .../mvc-controller/ann-methods/jackson.adoc | 30 ++- .../ann-methods/matrix-variables.adoc | 40 ++- .../ann-methods/modelattrib-method-args.adoc | 30 ++- .../ann-methods/multipart-forms.adoc | 40 ++- .../ann-methods/redirecting-passing-data.adoc | 10 +- .../ann-methods/requestattrib.adoc | 6 +- .../ann-methods/requestbody.adoc | 20 +- .../ann-methods/requestheader.adoc | 6 +- .../ann-methods/requestparam.adoc | 6 +- .../ann-methods/responsebody.adoc | 10 +- .../ann-methods/responseentity.adoc | 10 +- .../ann-methods/sessionattribute.adoc | 6 +- .../ann-methods/sessionattributes.adoc | 12 +- .../ann-modelattrib-methods.adoc | 30 ++- .../mvc-controller/ann-requestmapping.adoc | 70 +++++- .../pages/web/webmvc/mvc-controller/ann.adoc | 10 +- .../ROOT/pages/web/webmvc/mvc-servlet.adoc | 10 +- .../webmvc/mvc-servlet/container-config.adoc | 40 ++- .../webmvc/mvc-servlet/context-hierarchy.adoc | 10 +- .../webmvc/mvc-servlet/exceptionhandlers.adoc | 10 +- .../pages/web/webmvc/mvc-servlet/logging.adoc | 10 +- .../web/webmvc/mvc-servlet/multipart.adoc | 10 +- .../pages/web/webmvc/mvc-uri-building.adoc | 80 ++++-- .../modules/ROOT/partials/web/web-uris.adoc | 106 ++++++-- 243 files changed, 7118 insertions(+), 1773 deletions(-) diff --git a/framework-docs/antora-playbook.yml b/framework-docs/antora-playbook.yml index 656621102b62..6e9e4308e612 100644 --- a/framework-docs/antora-playbook.yml +++ b/framework-docs/antora-playbook.yml @@ -4,8 +4,6 @@ antora: extensions: - '@antora/collector-extension' - - require: '@springio/antora-extensions/tabs-migration-extension' - unwrap_example_block: always site: title: Spring Framework Reference url: https://https://rwinch.github.io/spring-framework/ diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/advice.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/advice.adoc index fc026e81cba1..fd9ecd219a2a 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/advice.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/advice.adoc @@ -54,8 +54,11 @@ point. The following example shows a simple `MethodInterceptor` implementation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class DebugInterceptor implements MethodInterceptor { @@ -67,8 +70,10 @@ The following example shows a simple `MethodInterceptor` implementation: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class DebugInterceptor : MethodInterceptor { @@ -80,6 +85,7 @@ The following example shows a simple `MethodInterceptor` implementation: } } ---- +====== Note the call to the `proceed()` method of `MethodInvocation`. This proceeds down the interceptor chain towards the join point. Most interceptors invoke this method and @@ -129,8 +135,11 @@ wrapped in an unchecked exception by the AOP proxy. The following example shows a before advice in Spring, which counts all method invocations: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class CountingBeforeAdvice implements MethodBeforeAdvice { @@ -145,8 +154,10 @@ The following example shows a before advice in Spring, which counts all method i } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class CountingBeforeAdvice : MethodBeforeAdvice { @@ -157,6 +168,7 @@ The following example shows a before advice in Spring, which counts all method i } } ---- +====== TIP: Before advice can be used with any pointcut. @@ -181,8 +193,11 @@ arguments. The next two listing show classes that are examples of throws advice. The following advice is invoked if a `RemoteException` is thrown (including from subclasses): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class RemoteThrowsAdvice implements ThrowsAdvice { @@ -191,8 +206,10 @@ The following advice is invoked if a `RemoteException` is thrown (including from } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class RemoteThrowsAdvice : ThrowsAdvice { @@ -201,13 +218,17 @@ The following advice is invoked if a `RemoteException` is thrown (including from } } ---- +====== Unlike the preceding advice, the next example declares four arguments, so that it has access to the invoked method, method arguments, and target object. The following advice is invoked if a `ServletException` is thrown: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ServletThrowsAdviceWithArguments implements ThrowsAdvice { @@ -216,8 +237,10 @@ arguments, and target object. The following advice is invoked if a `ServletExcep } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ServletThrowsAdviceWithArguments : ThrowsAdvice { @@ -226,13 +249,17 @@ arguments, and target object. The following advice is invoked if a `ServletExcep } } ---- +====== The final example illustrates how these two methods could be used in a single class that handles both `RemoteException` and `ServletException`. Any number of throws advice methods can be combined in a single class. The following listing shows the final example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static class CombinedThrowsAdvice implements ThrowsAdvice { @@ -245,8 +272,10 @@ methods can be combined in a single class. The following listing shows the final } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class CombinedThrowsAdvice : ThrowsAdvice { @@ -259,6 +288,7 @@ methods can be combined in a single class. The following listing shows the final } } ---- +====== NOTE: If a throws-advice method throws an exception itself, it overrides the original exception (that is, it changes the exception thrown to the user). The overriding @@ -292,8 +322,11 @@ the invoked method, the method's arguments, and the target. The following after returning advice counts all successful method invocations that have not thrown exceptions: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class CountingAfterReturningAdvice implements AfterReturningAdvice { @@ -309,8 +342,10 @@ not thrown exceptions: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class CountingAfterReturningAdvice : AfterReturningAdvice { @@ -322,6 +357,7 @@ not thrown exceptions: } } ---- +====== This advice does not change the execution path. If it throws an exception, it is thrown up the interceptor chain instead of the return value. @@ -380,8 +416,11 @@ introduced interfaces can be implemented by the configured `IntroductionIntercep Consider an example from the Spring test suite and suppose we want to introduce the following interface to one or more objects: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public interface Lockable { void lock(); @@ -389,8 +428,10 @@ introduce the following interface to one or more objects: boolean locked(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- interface Lockable { fun lock() @@ -398,6 +439,7 @@ introduce the following interface to one or more objects: fun locked(): Boolean } ---- +====== This illustrates a mixin. We want to be able to cast advised objects to `Lockable`, whatever their type and call lock and unlock methods. If we call the `lock()` method, we @@ -434,8 +476,11 @@ to that held in the target object. The following example shows the example `LockMixin` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class LockMixin extends DelegatingIntroductionInterceptor implements Lockable { @@ -462,8 +507,10 @@ The following example shows the example `LockMixin` class: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class LockMixin : DelegatingIntroductionInterceptor(), Lockable { @@ -490,6 +537,7 @@ The following example shows the example `LockMixin` class: } ---- +====== Often, you need not override the `invoke()` method. The `DelegatingIntroductionInterceptor` implementation (which calls the `delegate` method if @@ -504,8 +552,11 @@ interceptor (which would be defined as a prototype). In this case, there is no configuration relevant for a `LockMixin`, so we create it by using `new`. The following example shows our `LockMixinAdvisor` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class LockMixinAdvisor extends DefaultIntroductionAdvisor { @@ -514,11 +565,14 @@ The following example shows our `LockMixinAdvisor` class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class LockMixinAdvisor : DefaultIntroductionAdvisor(LockMixin(), Lockable::class.java) ---- +====== We can apply this advisor very simply, because it requires no configuration. (However, it is impossible to use an `IntroductionInterceptor` without an diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/advised.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/advised.adoc index f216c9b4d444..46932dfa85f4 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/advised.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/advised.adoc @@ -6,8 +6,11 @@ However you create AOP proxies, you can manipulate them BY using the interface, no matter which other interfaces it implements. This interface includes the following methods: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Advisor[] getAdvisors(); @@ -29,8 +32,10 @@ following methods: boolean isFrozen(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun getAdvisors(): Array @@ -59,6 +64,7 @@ following methods: fun isFrozen(): Boolean ---- +====== The `getAdvisors()` method returns an `Advisor` for every advisor, interceptor, or other advice type that has been added to the factory. If you added an `Advisor`, the @@ -80,8 +86,11 @@ change. (You can obtain a new proxy from the factory to avoid this problem.) The following example shows casting an AOP proxy to the `Advised` interface and examining and manipulating its advice: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Advised advised = (Advised) myObject; Advisor[] advisors = advised.getAdvisors(); @@ -98,8 +107,10 @@ manipulating its advice: assertEquals("Added two advisors", oldAdvisorCount + 2, advised.getAdvisors().length); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val advised = myObject as Advised val advisors = advised.advisors @@ -116,6 +127,7 @@ manipulating its advice: assertEquals("Added two advisors", oldAdvisorCount + 2, advised.advisors.size) ---- +====== NOTE: It is questionable whether it is advisable (no pun intended) to modify advice on a business object in production, although there are, no doubt, legitimate usage cases. diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc index 4ede450416fd..6927d1542739 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc @@ -192,16 +192,22 @@ an instance of the prototype from the factory. Holding a reference is not suffic The `person` bean definition shown earlier can be used in place of a `Person` implementation, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Person person = (Person) factory.getBean("person"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val person = factory.getBean("person") as Person; ---- +====== Other beans in the same IoC context can express a strongly typed dependency on it, as with an ordinary Java object. The following example shows how to do so: diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc index a99cfd000deb..aa1c2726932e 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc @@ -208,8 +208,11 @@ Because static pointcuts are most useful, you should probably subclass abstract method (although you can override other methods to customize behavior). The following example shows how to subclass `StaticMethodMatcherPointcut`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class TestStaticPointcut extends StaticMethodMatcherPointcut { @@ -218,8 +221,10 @@ following example shows how to subclass `StaticMethodMatcherPointcut`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class TestStaticPointcut : StaticMethodMatcherPointcut() { @@ -228,6 +233,7 @@ following example shows how to subclass `StaticMethodMatcherPointcut`: } } ---- +====== There are also superclasses for dynamic pointcuts. You can use custom pointcuts with any advice type. diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/prog.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/prog.adoc index 51be4bf6995e..0247e4a71c61 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/prog.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/prog.adoc @@ -8,22 +8,28 @@ The interfaces implemented by the target object are automatically proxied. The following listing shows creation of a proxy for a target object, with one interceptor and one advisor: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ProxyFactory factory = new ProxyFactory(myBusinessInterfaceImpl); factory.addAdvice(myMethodInterceptor); factory.addAdvisor(myAdvisor); MyBusinessInterface tb = (MyBusinessInterface) factory.getProxy(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val factory = ProxyFactory(myBusinessInterfaceImpl) factory.addAdvice(myMethodInterceptor) factory.addAdvisor(myAdvisor) val tb = factory.proxy as MyBusinessInterface ---- +====== The first step is to construct an object of type `org.springframework.aop.framework.ProxyFactory`. You can create this with a target diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/targetsource.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/targetsource.adoc index 91c1cf698ad4..fdb41e7b4d18 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/targetsource.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/targetsource.adoc @@ -34,18 +34,24 @@ Changing the target source's target takes effect immediately. The You can change the target by using the `swap()` method on HotSwappableTargetSource, as the follow example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HotSwappableTargetSource swapper = (HotSwappableTargetSource) beanFactory.getBean("swapper"); Object oldTarget = swapper.swap(newTarget); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val swapper = beanFactory.getBean("swapper") as HotSwappableTargetSource val oldTarget = swapper.swap(newTarget) ---- +====== The following example shows the required XML definitions: @@ -142,18 +148,24 @@ the `ProxyFactoryBean` that exposes the pooled object. The cast is defined as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- PoolingConfig conf = (PoolingConfig) beanFactory.getBean("businessObject"); System.out.println("Max pool size is " + conf.getMaxSize()); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val conf = beanFactory.getBean("businessObject") as PoolingConfig println("Max pool size is " + conf.maxSize) ---- +====== NOTE: Pooling stateless service objects is not usually necessary. We do not believe it should be the default choice, as most stateless objects are naturally thread safe, and instance diff --git a/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc b/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc index 66fbd2209b25..1a243d51c361 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc @@ -11,8 +11,11 @@ You can use the `org.springframework.aop.aspectj.annotation.AspectJProxyFactory` to create a proxy for a target object that is advised by one or more @AspectJ aspects. The basic usage for this class is very simple, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- // create a factory that can generate a proxy for the given target object AspectJProxyFactory factory = new AspectJProxyFactory(targetObject); @@ -28,8 +31,10 @@ The basic usage for this class is very simple, as the following example shows: // now get the proxy object... MyInterfaceType proxy = factory.getProxy(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- // create a factory that can generate a proxy for the given target object val factory = AspectJProxyFactory(targetObject) @@ -45,6 +50,7 @@ The basic usage for this class is very simple, as the following example shows: // now get the proxy object... val proxy = factory.getProxy() ---- +====== See the {api-spring-framework}/aop/aspectj/annotation/AspectJProxyFactory.html[javadoc] for more information. diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc index 856e66041256..e5ea40f51fef 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc @@ -13,8 +13,11 @@ You can declare before advice in an aspect by using the `@Before` annotation. The following example uses an inline pointcut expression. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.Before; @@ -28,8 +31,10 @@ The following example uses an inline pointcut expression. } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- import org.aspectj.lang.annotation.Aspect import org.aspectj.lang.annotation.Before @@ -43,12 +48,16 @@ The following example uses an inline pointcut expression. } } ---- +====== If we use a xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[named pointcut], we can rewrite the preceding example as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.Before; @@ -62,8 +71,10 @@ as follows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- import org.aspectj.lang.annotation.Aspect import org.aspectj.lang.annotation.Before @@ -77,6 +88,7 @@ as follows: } } ---- +====== [[aop-advice-after-returning]] @@ -85,8 +97,11 @@ as follows: After returning advice runs when a matched method execution returns normally. You can declare it by using the `@AfterReturning` annotation. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.AfterReturning; @@ -100,8 +115,10 @@ You can declare it by using the `@AfterReturning` annotation. } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- import org.aspectj.lang.annotation.Aspect import org.aspectj.lang.annotation.AfterReturning @@ -115,6 +132,7 @@ You can declare it by using the `@AfterReturning` annotation. } } ---- +====== NOTE: You can have multiple advice declarations (and other members as well), all inside the same aspect. We show only a single advice declaration in these @@ -124,8 +142,11 @@ Sometimes, you need access in the advice body to the actual value that was retur You can use the form of `@AfterReturning` that binds the return value to get that access, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.AfterReturning; @@ -141,8 +162,10 @@ access, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- import org.aspectj.lang.annotation.Aspect import org.aspectj.lang.annotation.AfterReturning @@ -158,6 +181,7 @@ access, as the following example shows: } } ---- +====== The name used in the `returning` attribute must correspond to the name of a parameter in the advice method. When a method execution returns, the return value is passed to @@ -176,8 +200,11 @@ After throwing advice runs when a matched method execution exits by throwing an exception. You can declare it by using the `@AfterThrowing` annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.AfterThrowing; @@ -191,8 +218,10 @@ following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- import org.aspectj.lang.annotation.Aspect import org.aspectj.lang.annotation.AfterThrowing @@ -206,6 +235,7 @@ following example shows: } } ---- +====== Often, you want the advice to run only when exceptions of a given type are thrown, and you also often need access to the thrown exception in the advice body. You can @@ -213,8 +243,11 @@ use the `throwing` attribute to both restrict matching (if desired -- use `Throw as the exception type otherwise) and bind the thrown exception to an advice parameter. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.AfterThrowing; @@ -230,8 +263,10 @@ The following example shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- import org.aspectj.lang.annotation.Aspect import org.aspectj.lang.annotation.AfterThrowing @@ -247,6 +282,7 @@ The following example shows how to do so: } } ---- +====== The name used in the `throwing` attribute must correspond to the name of a parameter in the advice method. When a method execution exits by throwing an exception, the exception @@ -271,8 +307,11 @@ using the `@After` annotation. After advice must be prepared to handle both norm exception return conditions. It is typically used for releasing resources and similar purposes. The following example shows how to use after finally advice: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.After; @@ -286,8 +325,10 @@ purposes. The following example shows how to use after finally advice: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- import org.aspectj.lang.annotation.Aspect import org.aspectj.lang.annotation.After @@ -301,6 +342,7 @@ purposes. The following example shows how to use after finally advice: } } ---- +====== [NOTE] ==== @@ -371,8 +413,11 @@ value depending on the use case. The following example shows how to use around advice: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.Around; @@ -390,8 +435,10 @@ The following example shows how to use around advice: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- import org.aspectj.lang.annotation.Aspect import org.aspectj.lang.annotation.Around @@ -409,6 +456,7 @@ The following example shows how to use around advice: } } ---- +====== [[aop-ataspectj-advice-params]] == Advice Parameters @@ -448,22 +496,28 @@ Suppose you want to advise the execution of DAO operations that take an `Account object as the first parameter, and you need access to the account in the advice body. You could write the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Before("execution(* com.xyz.dao.*.*(..)) && args(account,..)") public void validateAccount(Account account) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Before("execution(* com.xyz.dao.*.*(..)) && args(account,..)") fun validateAccount(account: Account) { // ... } ---- +====== The `args(account,..)` part of the pointcut expression serves two purposes. First, it restricts matching to only those method executions where the method takes at least one @@ -475,8 +529,11 @@ Another way of writing this is to declare a pointcut that "provides" the `Accoun object value when it matches a join point, and then refer to the named pointcut from the advice. This would look as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Pointcut("execution(* com.xyz.dao.*.*(..)) && args(account,..)") private void accountDataAccessOperation(Account account) {} @@ -486,8 +543,10 @@ from the advice. This would look as follows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Pointcut("execution(* com.xyz.dao.*.*(..)) && args(account,..)") private fun accountDataAccessOperation(account: Account) { @@ -498,6 +557,7 @@ from the advice. This would look as follows: // ... } ---- +====== See the AspectJ programming guide for more details. @@ -508,8 +568,11 @@ set of examples shows how to match the execution of methods annotated with an The following shows the definition of the `@Auditable` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @@ -517,18 +580,24 @@ The following shows the definition of the `@Auditable` annotation: AuditCode value(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Retention(AnnotationRetention.RUNTIME) @Target(AnnotationTarget.FUNCTION) annotation class Auditable(val value: AuditCode) ---- +====== The following shows the advice that matches the execution of `@Auditable` methods: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Before("com.xyz.Pointcuts.publicMethod() && @annotation(auditable)") // <1> public void audit(Auditable auditable) { @@ -536,6 +605,7 @@ The following shows the advice that matches the execution of `@Auditable` method // ... } ---- +====== <1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] @@ -555,62 +625,80 @@ The following shows the advice that matches the execution of `@Auditable` method Spring AOP can handle generics used in class declarations and method parameters. Suppose you have a generic type like the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public interface Sample { void sampleGenericMethod(T param); void sampleGenericCollectionMethod(Collection param); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- interface Sample { fun sampleGenericMethod(param: T) fun sampleGenericCollectionMethod(param: Collection) } ---- +====== You can restrict interception of method types to certain parameter types by tying the advice parameter to the parameter type for which you want to intercept the method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Before("execution(* ..Sample+.sampleGenericMethod(*)) && args(param)") public void beforeSampleMethod(MyType param) { // Advice implementation } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Before("execution(* ..Sample+.sampleGenericMethod(*)) && args(param)") fun beforeSampleMethod(param: MyType) { // Advice implementation } ---- +====== This approach does not work for generic collections. So you cannot define a pointcut as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Before("execution(* ..Sample+.sampleGenericCollectionMethod(*)) && args(param)") public void beforeSampleMethod(Collection param) { // Advice implementation } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Before("execution(* ..Sample+.sampleGenericCollectionMethod(*)) && args(param)") fun beforeSampleMethod(param: Collection) { // Advice implementation } ---- +====== To make this work, we would have to inspect every element of the collection, which is not reasonable, as we also cannot decide how to treat `null` values in general. To achieve @@ -668,8 +756,11 @@ needed information. The following example shows how to use the `argNames` attribute: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Before( value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> @@ -679,6 +770,7 @@ The following example shows how to use the `argNames` attribute: // ... use code and bean } ---- +====== <1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. @@ -701,8 +793,11 @@ If the first parameter is of type `JoinPoint`, `ProceedingJoinPoint`, or `argNames` attribute. For example, if you modify the preceding advice to receive the join point object, the `argNames` attribute does not need to include it: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Before( value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> @@ -712,6 +807,7 @@ point object, the `argNames` attribute does not need to include it: // ... use code, bean, and jp } ---- +====== <1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. @@ -735,14 +831,18 @@ methods that do not collect any other join point context. In such situations, yo omit the `argNames` attribute. For example, the following advice does not need to declare the `argNames` attribute: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Before("com.xyz.Pointcuts.publicMethod()") // <1> public void audit(JoinPoint jp) { // ... use jp } ---- +====== <1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] @@ -764,8 +864,11 @@ arguments that works consistently across Spring AOP and AspectJ. The solution is to ensure that the advice signature binds each of the method parameters in order. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Around("execution(List find*(..)) && " + "com.xyz.CommonPointcuts.inDataAccessLayer() && " + @@ -776,6 +879,7 @@ The following example shows how to do so: return pjp.proceed(new Object[] {newPattern}); } ---- +====== <1> References the `inDataAccessLayer` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc index 458d4fb118b8..6bbddeaddb80 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc @@ -19,21 +19,27 @@ classpath of your application (version 1.9 or later). This library is available To enable @AspectJ support with Java `@Configuration`, add the `@EnableAspectJAutoProxy` annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Configuration @EnableAspectJAutoProxy public class AppConfig { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configuration @EnableAspectJAutoProxy class AppConfig ---- +====== [[aop-enable-aspectj-xml]] == Enabling @AspectJ Support with XML Configuration diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/at-aspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/at-aspectj.adoc index c50f8aba6c3e..5e2e40176e6d 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/at-aspectj.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/at-aspectj.adoc @@ -19,8 +19,11 @@ that points to a bean class that is annotated with `@Aspect`: The second of the two examples shows the `NotVeryUsefulAspect` class definition, which is annotated with `@Aspect`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages",fold="none"] -.Java ---- package com.xyz; @@ -30,8 +33,10 @@ annotated with `@Aspect`: public class NotVeryUsefulAspect { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages",fold="none"] -.Kotlin ---- package com.xyz @@ -40,6 +45,7 @@ annotated with `@Aspect`: @Aspect class NotVeryUsefulAspect ---- +====== Aspects (classes annotated with `@Aspect`) can have methods and fields, the same as any other class. They can also contain pointcut, advice, and introduction (inter-type) diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc index d16aba8949d1..082de8ba3fc5 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc @@ -16,8 +16,11 @@ aspect. Because we want to retry the operation, we need to use around advice so that we can call `proceed` multiple times. The following listing shows the basic aspect implementation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Aspect public class ConcurrentOperationExecutor implements Ordered { @@ -56,6 +59,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl } } ---- +====== <1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] @@ -123,28 +127,37 @@ The corresponding Spring configuration follows: To refine the aspect so that it retries only idempotent operations, we might define the following `Idempotent` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Retention(RetentionPolicy.RUNTIME) // marker annotation public @interface Idempotent { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Retention(AnnotationRetention.RUNTIME) // marker annotation annotation class Idempotent ---- +====== We can then use the annotation to annotate the implementation of service operations. The change to the aspect to retry only idempotent operations involves refining the pointcut expression so that only `@Idempotent` operations match, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Around("execution(* com.xyz..service.*.*(..)) && " + "@annotation(com.xyz.service.Idempotent)") @@ -152,8 +165,10 @@ expression so that only `@Idempotent` operations match, as follows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Around("execution(* com.xyz..service.*.*(..)) && " + "@annotation(com.xyz.service.Idempotent)") @@ -161,6 +176,7 @@ expression so that only `@Idempotent` operations match, as follows: // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/instantiation-models.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/instantiation-models.adoc index 75c985d8112e..decfbc52e969 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/instantiation-models.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/instantiation-models.adoc @@ -13,8 +13,11 @@ supported. You can declare a `perthis` aspect by specifying a `perthis` clause in the `@Aspect` annotation. Consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Aspect("perthis(execution(* com.xyz..service.*.*(..)))") public class MyAspect { @@ -27,8 +30,10 @@ annotation. Consider the following example: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Aspect("perthis(execution(* com.xyz..service.*.*(..)))") class MyAspect { @@ -41,6 +46,7 @@ annotation. Consider the following example: } } ---- +====== In the preceding example, the effect of the `perthis` clause is that one aspect instance is created for each unique service object that performs a business service (each unique diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/introductions.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/introductions.adoc index d535ade9f49a..e8732d3cc3d9 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/introductions.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/introductions.adoc @@ -11,8 +11,11 @@ given an interface named `UsageTracked` and an implementation of that interface `DefaultUsageTracked`, the following aspect declares that all implementors of service interfaces also implement the `UsageTracked` interface (e.g. for statistics via JMX): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Aspect public class UsageTracking { @@ -27,8 +30,10 @@ interfaces also implement the `UsageTracked` interface (e.g. for statistics via } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Aspect class UsageTracking { @@ -45,6 +50,7 @@ interfaces also implement the `UsageTracked` interface (e.g. for statistics via } } ---- +====== The interface to be implemented is determined by the type of the annotated field. The `value` attribute of the `@DeclareParents` annotation is an AspectJ type pattern. Any @@ -53,15 +59,21 @@ before advice of the preceding example, service beans can be directly used as implementations of the `UsageTracked` interface. If accessing a bean programmatically, you would write the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- UsageTracked usageTracked = context.getBean("myService", UsageTracked.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- val usageTracked = context.getBean("myService", UsageTracked.class) ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc index 722405ef7618..b809e1f779f7 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc @@ -15,18 +15,24 @@ An example may help make this distinction between a pointcut signature and a poi expression clear. The following example defines a pointcut named `anyOldTransfer` that matches the execution of any method named `transfer`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Pointcut("execution(* transfer(..))") // the pointcut expression private void anyOldTransfer() {} // the pointcut signature ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Pointcut("execution(* transfer(..))") // the pointcut expression private fun anyOldTransfer() {} // the pointcut signature ---- +====== The pointcut expression that forms the value of the `@Pointcut` annotation is a regular AspectJ pointcut expression. For a full discussion of AspectJ's pointcut language, see @@ -140,8 +146,11 @@ it is natural and straightforward to identify specific beans by name. You can combine pointcut expressions by using `&&,` `||` and `!`. You can also refer to pointcut expressions by name. The following example shows three pointcut expressions: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ---- package com.xyz; @@ -158,6 +167,7 @@ pointcut expressions by name. The following example shows three pointcut express public void tradingOperation() {} // <3> } ---- +====== <1> `publicMethod` matches if a method execution join point represents the execution of any public method. <2> `inTrading` matches if a method execution is in the trading module. @@ -204,8 +214,11 @@ We recommend defining a dedicated aspect that captures commonly used _named poin expressions for this purpose. Such an aspect typically resembles the following `CommonPointcuts` example (though what you name the aspect is up to you): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages",fold="none"] -.Java ---- package com.xyz; @@ -266,8 +279,10 @@ expressions for this purpose. Such an aspect typically resembles the following } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages",fold="none"] -.Kotlin ---- package com.xyz @@ -328,6 +343,7 @@ expressions for this purpose. Such an aspect typically resembles the following } ---- +====== You can refer to the pointcuts defined in such an aspect anywhere you need a pointcut expression by referencing the fully-qualified name of the `@Aspect` class combined with diff --git a/framework-docs/modules/ROOT/pages/core/aop/choosing.adoc b/framework-docs/modules/ROOT/pages/core/aop/choosing.adoc index aed62baa1b1e..d5432fce394a 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/choosing.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/choosing.adoc @@ -55,8 +55,11 @@ it can express than the @AspectJ style: Only the "singleton" aspect instantiatio is supported, and it is not possible to combine named pointcuts declared in XML. For example, in the @AspectJ style you can write something like the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Pointcut("execution(* get*())") public void propertyAccess() {} @@ -67,8 +70,10 @@ For example, in the @AspectJ style you can write something like the following: @Pointcut("propertyAccess() && operationReturningAnAccount()") public void accountPropertyAccess() {} ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Pointcut("execution(* get*())") fun propertyAccess() {} @@ -79,6 +84,7 @@ For example, in the @AspectJ style you can write something like the following: @Pointcut("propertyAccess() && operationReturningAnAccount()") fun accountPropertyAccess() {} ---- +====== In the XML style you can declare the first two pointcuts: diff --git a/framework-docs/modules/ROOT/pages/core/aop/proxying.adoc b/framework-docs/modules/ROOT/pages/core/aop/proxying.adoc index 4ec0ae914520..0187cf3a59e6 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/proxying.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/proxying.adoc @@ -65,8 +65,11 @@ Consider first the scenario where you have a plain-vanilla, un-proxied, nothing-special-about-it, straight object reference, as the following code snippet shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public class SimplePojo implements Pojo { @@ -80,8 +83,10 @@ code snippet shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- class SimplePojo : Pojo { @@ -95,14 +100,18 @@ code snippet shows: } } ---- +====== If you invoke a method on an object reference, the method is invoked directly on that object reference, as the following image and listing show: image::aop-proxy-plain-pojo-call.png[] +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public class Main { @@ -113,8 +122,10 @@ image::aop-proxy-plain-pojo-call.png[] } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- fun main() { val pojo = SimplePojo() @@ -122,14 +133,18 @@ image::aop-proxy-plain-pojo-call.png[] pojo.foo() } ---- +====== Things change slightly when the reference that client code has is a proxy. Consider the following diagram and code snippet: image::aop-proxy-call.png[] +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public class Main { @@ -144,8 +159,10 @@ image::aop-proxy-call.png[] } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- fun main() { val factory = ProxyFactory(SimplePojo()) @@ -157,6 +174,7 @@ fun main() { pojo.foo() } ---- +====== The key thing to understand here is that the client code inside the `main(..)` method of the `Main` class has a reference to the proxy. This means that method calls on that @@ -175,8 +193,11 @@ The next approach is absolutely horrendous, and we hesitate to point it out, pre because it is so horrendous. You can (painful as it is to us) totally tie the logic within your class to Spring AOP, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public class SimplePojo implements Pojo { @@ -190,8 +211,10 @@ within your class to Spring AOP, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- class SimplePojo : Pojo { @@ -205,14 +228,18 @@ within your class to Spring AOP, as the following example shows: } } ---- +====== This totally couples your code to Spring AOP, and it makes the class itself aware of the fact that it is being used in an AOP context, which flies in the face of AOP. It also requires some additional configuration when the proxy is being created, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public class Main { @@ -228,8 +255,10 @@ following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- fun main() { val factory = ProxyFactory(SimplePojo()) @@ -242,6 +271,7 @@ following example shows: pojo.foo() } ---- +====== Finally, it must be noted that AspectJ does not have this self-invocation issue because it is not a proxy-based AOP framework. diff --git a/framework-docs/modules/ROOT/pages/core/aop/schema.adoc b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc index 7e702016fcaa..fd19d9ecc6f2 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/schema.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc @@ -132,20 +132,26 @@ collects the `this` object as the join point context and passes it to the advice The advice must be declared to receive the collected join point context by including parameters of the matching names, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public void monitor(Object service) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- fun monitor(service: Any) { // ... } ---- +====== When combining pointcut sub-expressions, `+&&+` is awkward within an XML document, so you can use the `and`, `or`, and `not` keywords in place of `+&&+`, @@ -272,16 +278,22 @@ The `doAccessCheck` method must declare a parameter named `retVal`. The type of parameter constrains matching in the same way as described for `@AfterReturning`. For example, you can declare the method signature as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public void doAccessCheck(Object retVal) {... ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- fun doAccessCheck(retVal: Any) {... ---- +====== [[aop-schema-advice-after-throwing]] @@ -324,16 +336,22 @@ The `doRecoveryActions` method must declare a parameter named `dataAccessEx`. The type of this parameter constrains matching in the same way as described for `@AfterThrowing`. For example, the method signature may be declared as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public void doRecoveryActions(DataAccessException dataAccessEx) {... ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- fun doRecoveryActions(dataAccessEx: DataAccessException) {... ---- +====== [[aop-schema-advice-after-finally]] @@ -399,8 +417,11 @@ The following example shows how to declare around advice in XML: The implementation of the `doBasicProfiling` advice can be exactly the same as in the @AspectJ example (minus the annotation, of course), as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public Object doBasicProfiling(ProceedingJoinPoint pjp) throws Throwable { // start stopwatch @@ -409,8 +430,10 @@ The implementation of the `doBasicProfiling` advice can be exactly the same as i return retVal; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- fun doBasicProfiling(pjp: ProceedingJoinPoint): Any { // start stopwatch @@ -419,6 +442,7 @@ The implementation of the `doBasicProfiling` advice can be exactly the same as i return pjp.proceed() } ---- +====== [[aop-schema-params]] @@ -447,8 +471,11 @@ The `arg-names` attribute accepts a comma-delimited list of parameter names. The following slightly more involved example of the XSD-based approach shows some around advice used in conjunction with a number of strongly typed parameters: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ---- package com.xyz.service; @@ -464,8 +491,10 @@ some around advice used in conjunction with a number of strongly typed parameter } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ---- package com.xyz.service @@ -481,14 +510,18 @@ some around advice used in conjunction with a number of strongly typed parameter } } ---- +====== Next up is the aspect. Notice the fact that the `profile(..)` method accepts a number of strongly-typed parameters, the first of which happens to be the join point used to proceed with the method call. The presence of this parameter is an indication that the `profile(..)` is to be used as `around` advice, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ---- package com.xyz; @@ -509,8 +542,10 @@ proceed with the method call. The presence of this parameter is an indication th } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ---- package com.xyz @@ -531,6 +566,7 @@ proceed with the method call. The presence of this parameter is an indication th } } ---- +====== Finally, the following example XML configuration effects the execution of the preceding advice for a particular join point: @@ -570,8 +606,11 @@ preceding advice for a particular join point: Consider the following driver script: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public class Boot { @@ -582,8 +621,10 @@ Consider the following driver script: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- fun main() { val ctx = ClassPathXmlApplicationContext("beans.xml") @@ -591,6 +632,7 @@ Consider the following driver script: person.getPerson("Pengo", 12) } ---- +====== With such a `Boot` class, we would get output similar to the following on standard output: @@ -668,20 +710,26 @@ through JMX for example.) The class that backs the `usageTracking` bean would then contain the following method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public void recordUsage(UsageTracked usageTracked) { usageTracked.incrementUseCount(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- fun recordUsage(usageTracked: UsageTracked) { usageTracked.incrementUseCount() } ---- +====== The interface to be implemented is determined by the `implement-interface` attribute. The value of the `types-matching` attribute is an AspectJ type pattern. Any bean of a @@ -690,16 +738,22 @@ advice of the preceding example, service beans can be directly used as implement the `UsageTracked` interface. To access a bean programmatically, you could write the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- UsageTracked usageTracked = context.getBean("myService", UsageTracked.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- val usageTracked = context.getBean("myService", UsageTracked.class) ---- +====== @@ -771,8 +825,11 @@ Because we want to retry the operation, we need to use around advice so that we call `proceed` multiple times. The following listing shows the basic aspect implementation (which is a regular Java class that uses the schema support): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- public class ConcurrentOperationExecutor implements Ordered { @@ -809,8 +866,10 @@ call `proceed` multiple times. The following listing shows the basic aspect impl } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- class ConcurrentOperationExecutor : Ordered { @@ -847,6 +906,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl } } ---- +====== Note that the aspect implements the `Ordered` interface so that we can set the precedence of the aspect higher than the transaction advice (we want a fresh transaction each time we @@ -889,21 +949,27 @@ this is not the case, we can refine the aspect so that it retries only genuinely idempotent operations, by introducing an `Idempotent` annotation and using the annotation to annotate the implementation of service operations, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Retention(RetentionPolicy.RUNTIME) // marker annotation public @interface Idempotent { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Retention(AnnotationRetention.RUNTIME) // marker annotation annotation class Idempotent ---- +====== The change to the aspect to retry only idempotent operations involves refining the diff --git a/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc index ced4a2afe250..10fdac6dcace 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc @@ -32,8 +32,11 @@ The `@Configurable` annotation marks a class as being eligible for Spring-driven configuration. In the simplest case, you can use purely it as a marker annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ---- package com.xyz.domain; @@ -44,8 +47,10 @@ following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ---- package com.xyz.domain @@ -56,6 +61,7 @@ following example shows: // ... } ---- +====== When used as a marker interface in this way, Spring configures new instances of the annotated type (`Account`, in this case) by using a bean definition (typically @@ -74,8 +80,11 @@ is to omit the `id` attribute, as the following example shows: If you want to explicitly specify the name of the prototype bean definition to use, you can do so directly in the annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ---- package com.xyz.domain; @@ -86,8 +95,10 @@ can do so directly in the annotation, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ---- package com.xyz.domain @@ -98,6 +109,7 @@ can do so directly in the annotation, as the following example shows: // ... } ---- +====== Spring now looks for a bean definition named `account` and uses that as the definition to configure new `Account` instances. @@ -137,16 +149,22 @@ dependencies to be injected before the constructor bodies run and thus be available for use in the body of the constructors, you need to define this on the `@Configurable` declaration, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Configurable(preConstruction = true) ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configurable(preConstruction = true) ---- +====== You can find more information about the language semantics of the various pointcut types in AspectJ @@ -164,22 +182,28 @@ a reference to the bean factory that is to be used to configure new objects). If use Java-based configuration, you can add `@EnableSpringConfigured` to any `@Configuration` class, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Configuration @EnableSpringConfigured public class AppConfig { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configuration @EnableSpringConfigured class AppConfig { } ---- +====== If you prefer XML based configuration, the Spring xref:core/appendix/xsd-schemas.adoc#context[`context` namespace] @@ -417,8 +441,11 @@ use @AspectJ with xref:core/beans/java.adoc[Java configuration]. Specifically, y The following example shows the profiling aspect, which is not fancy. It is a time-based profiler that uses the @AspectJ-style of aspect declaration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ---- package com.xyz; @@ -448,8 +475,10 @@ It is a time-based profiler that uses the @AspectJ-style of aspect declaration: public void methodsToBeProfiled(){} } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ---- package com.xyz @@ -480,6 +509,7 @@ It is a time-based profiler that uses the @AspectJ-style of aspect declaration: } } ---- +====== We also need to create an `META-INF/aop.xml` file, to inform the AspectJ weaver that we want to weave our `ProfilingAspect` into our classes. This file convention, namely @@ -537,8 +567,11 @@ Now that all the required artifacts (the aspect, the `META-INF/aop.xml` file, and the Spring configuration) are in place, we can create the following driver class with a `main(..)` method to demonstrate the LTW in action: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ---- package com.xyz; @@ -557,8 +590,10 @@ driver class with a `main(..)` method to demonstrate the LTW in action: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ---- package com.xyz @@ -573,6 +608,7 @@ driver class with a `main(..)` method to demonstrate the LTW in action: service.calculateEntitlement() } ---- +====== We have one last thing to do. The introduction to this section did say that one could switch on LTW selectively on a per-`ClassLoader` basis with Spring, and this is true. @@ -612,8 +648,11 @@ Since this LTW is effected by using full-blown AspectJ, we are not limited only Spring beans. The following slight variation on the `Main` program yields the same result: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"] -.Java ---- package com.xyz; @@ -632,8 +671,10 @@ result: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ---- package com.xyz @@ -648,6 +689,7 @@ result: service.calculateEntitlement() } ---- +====== Notice how, in the preceding program, we bootstrap the Spring container and then create a new instance of the `StubEntitlementCalculationService` totally outside @@ -721,22 +763,28 @@ enough because the LTW support uses `BeanFactoryPostProcessors`.) To enable the Spring Framework's LTW support, you need to configure a `LoadTimeWeaver`, which typically is done by using the `@EnableLoadTimeWeaving` annotation, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Configuration @EnableLoadTimeWeaving public class AppConfig { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configuration @EnableLoadTimeWeaving class AppConfig { } ---- +====== Alternatively, if you prefer XML-based configuration, use the `` element. Note that the element is defined in the @@ -804,8 +852,11 @@ To specify a specific `LoadTimeWeaver` with Java configuration, implement the `LoadTimeWeavingConfigurer` interface and override the `getLoadTimeWeaver()` method. The following example specifies a `ReflectiveLoadTimeWeaver`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Configuration @EnableLoadTimeWeaving @@ -817,8 +868,10 @@ The following example specifies a `ReflectiveLoadTimeWeaver`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configuration @EnableLoadTimeWeaving @@ -829,6 +882,7 @@ The following example specifies a `ReflectiveLoadTimeWeaver`: } } ---- +====== If you use XML-based configuration, you can specify the fully qualified class name as the value of the `weaver-class` attribute on the `` diff --git a/framework-docs/modules/ROOT/pages/core/aot.adoc b/framework-docs/modules/ROOT/pages/core/aot.adoc index 5a569ca85faa..32e2b32b48c7 100644 --- a/framework-docs/modules/ROOT/pages/core/aot.adoc +++ b/framework-docs/modules/ROOT/pages/core/aot.adoc @@ -124,8 +124,11 @@ This is the default behavior, since tuning the generated code for a bean definit Taking our previous example, let's assume that `DataSourceConfiguration` is as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration(proxyBeanMethods = false) public class DataSourceConfiguration { @@ -137,12 +140,16 @@ Taking our previous example, let's assume that `DataSourceConfiguration` is as f } ---- +====== Since there isn't any particular condition on this class, `dataSourceConfiguration` and `dataSource` are identified as candidates. The AOT engine will convert the configuration class above to code similar to the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,role="primary"] -.Java ---- /** * Bean definitions for {@link DataSourceConfiguration} @@ -177,6 +184,7 @@ The AOT engine will convert the configuration class above to code similar to the } } ---- +====== NOTE: The exact code generated may differ depending on the exact nature of your bean definitions. @@ -197,11 +205,15 @@ Consequently, if the application needs to load a resource, it must be referenced The {api-spring-framework}/aot/hint/RuntimeHints.html[`RuntimeHints`] API collects the need for reflection, resource loading, serialization, and JDK proxies at runtime. The following example makes sure that `config/app.properties` can be loaded from the classpath at runtime within a native image: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- runtimeHints.resources().registerPattern("config/app.properties"); ---- +====== A number of contracts are handled automatically during AOT processing. For instance, the return type of a `@Controller` method is inspected, and relevant reflection hints are added if Spring detects that the type should be serialized (typically to JSON). @@ -248,8 +260,11 @@ A typical use case is the use of DTOs that the container cannot infer, such as u `@RegisterReflectionForBinding` can be applied to any Spring bean at the class level, but it can also be applied directly to a method, field, or constructor to better indicate where the hints are actually required. The following example registers `Account` for serialization. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class OrderService { @@ -261,6 +276,7 @@ The following example registers `Account` for serialization. } ---- +====== [[aot.hints.testing]] === Testing Runtime Hints diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc index 691bfe63ae37..116fad995204 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc @@ -141,8 +141,11 @@ element results in a single `SimpleDateFormat` bean definition). Spring features number of convenience classes that support this scenario. In the following example, we use the `NamespaceHandlerSupport` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package org.springframework.samples.xml; @@ -155,8 +158,10 @@ use the `NamespaceHandlerSupport` class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package org.springframework.samples.xml @@ -169,6 +174,7 @@ use the `NamespaceHandlerSupport` class: } } ---- +====== You may notice that there is not actually a whole lot of parsing logic in this class. Indeed, the `NamespaceHandlerSupport` class has a built-in notion of @@ -192,8 +198,11 @@ responsible for parsing one distinct top-level XML element defined in the schema the parser, we' have access to the XML element (and thus to its subelements, too) so that we can parse our custom XML content, as you can see in the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package org.springframework.samples.xml; @@ -224,6 +233,7 @@ we can parse our custom XML content, as you can see in the following example: } ---- +====== <1> We use the Spring-provided `AbstractSingleBeanDefinitionParser` to handle a lot of the basic grunt work of creating a single `BeanDefinition`. <2> We supply the `AbstractSingleBeanDefinitionParser` superclass with the type that our @@ -401,8 +411,11 @@ setter method for the `components` property. This makes it hard (or rather impos to configure a bean definition for the `Component` class by using setter injection. The following listing shows the `Component` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package com.foo; @@ -432,8 +445,10 @@ The following listing shows the `Component` class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package com.foo @@ -454,13 +469,17 @@ The following listing shows the `Component` class: } } ---- +====== The typical solution to this issue is to create a custom `FactoryBean` that exposes a setter property for the `components` property. The following listing shows such a custom `FactoryBean`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package com.foo; @@ -499,8 +518,10 @@ setter property for the `components` property. The following listing shows such } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package com.foo @@ -538,6 +559,7 @@ setter property for the `components` property. The following listing shows such } } ---- +====== This works nicely, but it exposes a lot of Spring plumbing to the end user. What we are going to do is write a custom extension that hides away all of this Spring plumbing. @@ -571,8 +593,11 @@ listing shows: Again following xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-introduction[the process described earlier], we then create a custom `NamespaceHandler`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package com.foo; @@ -585,8 +610,10 @@ we then create a custom `NamespaceHandler`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package com.foo @@ -599,13 +626,17 @@ we then create a custom `NamespaceHandler`: } } ---- +====== Next up is the custom `BeanDefinitionParser`. Remember that we are creating a `BeanDefinition` that describes a `ComponentFactoryBean`. The following listing shows our custom `BeanDefinitionParser` implementation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package com.foo; @@ -653,8 +684,10 @@ listing shows our custom `BeanDefinitionParser` implementation: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package com.foo @@ -702,6 +735,7 @@ listing shows our custom `BeanDefinitionParser` implementation: } } ---- +====== Finally, the various artifacts need to be registered with the Spring XML infrastructure, by modifying the `META-INF/spring.handlers` and `META-INF/spring.schemas` files, as follows: @@ -748,8 +782,11 @@ the named JCache for us. We can also modify the existing `BeanDefinition` for th `'checkingAccountService'` so that it has a dependency on this new JCache-initializing `BeanDefinition`. The following listing shows our `JCacheInitializer`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package com.foo; @@ -766,8 +803,10 @@ JCache-initializing `BeanDefinition`. The following listing shows our `JCacheIni } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package com.foo @@ -778,6 +817,7 @@ JCache-initializing `BeanDefinition`. The following listing shows our `JCacheIni } } ---- +====== Now we can move onto the custom extension. First, we need to author the XSD schema that describes the custom attribute, as follows: @@ -798,8 +838,11 @@ the XSD schema that describes the custom attribute, as follows: Next, we need to create the associated `NamespaceHandler`, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package com.foo; @@ -814,8 +857,10 @@ Next, we need to create the associated `NamespaceHandler`, as follows: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package com.foo @@ -830,13 +875,17 @@ Next, we need to create the associated `NamespaceHandler`, as follows: } ---- +====== Next, we need to create the parser. Note that, in this case, because we are going to parse an XML attribute, we write a `BeanDefinitionDecorator` rather than a `BeanDefinitionParser`. The following listing shows our `BeanDefinitionDecorator` implementation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package com.foo; @@ -889,8 +938,10 @@ The following listing shows our `BeanDefinitionDecorator` implementation: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package com.foo @@ -939,6 +990,7 @@ The following listing shows our `BeanDefinitionDecorator` implementation: } } ---- +====== Finally, we need to register the various artifacts with the Spring XML infrastructure by modifying the `META-INF/spring.handlers` and `META-INF/spring.schemas` files, as follows: diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc index 0eef8fbfc0d1..28b79843a25a 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc @@ -117,8 +117,11 @@ easy to do in Spring. You do not actually have to do anything or know anything a the Spring internals (or even about classes such as the `FieldRetrievingFactoryBean`). The following example enumeration shows how easy injecting an enum value is: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package jakarta.persistence; @@ -128,8 +131,10 @@ The following example enumeration shows how easy injecting an enum value is: EXTENDED } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package jakarta.persistence @@ -139,11 +144,15 @@ The following example enumeration shows how easy injecting an enum value is: EXTENDED } ---- +====== Now consider the following setter of type `PersistenceContextType` and the corresponding bean definition: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package example; @@ -156,8 +165,10 @@ Now consider the following setter of type `PersistenceContextType` and the corre } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package example @@ -166,6 +177,7 @@ Now consider the following setter of type `PersistenceContextType` and the corre lateinit var persistenceContextType: PersistenceContextType } ---- +====== [source,xml,indent=0,subs="verbatim,quotes"] ---- diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-primary.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-primary.adoc index 7843d9835d65..dcaa7bce6234 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-primary.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-primary.adoc @@ -11,8 +11,11 @@ autowired value. Consider the following configuration that defines `firstMovieCatalog` as the primary `MovieCatalog`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class MovieConfiguration { @@ -27,8 +30,10 @@ primary `MovieCatalog`: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class MovieConfiguration { @@ -43,12 +48,16 @@ primary `MovieCatalog`: // ... } ---- +====== With the preceding configuration, the following `MovieRecommender` is autowired with the `firstMovieCatalog`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -58,8 +67,10 @@ With the preceding configuration, the following `MovieRecommender` is autowired // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -69,6 +80,7 @@ class MovieRecommender { // ... } ---- +====== The corresponding bean definitions follow: diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc index a63b5e8bbae1..9069fdad9da6 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc @@ -9,8 +9,11 @@ chosen for each argument. In the simplest case, this can be a plain descriptive shown in the following example: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -21,8 +24,10 @@ shown in the following example: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -33,14 +38,18 @@ shown in the following example: // ... } ---- +====== -- You can also specify the `@Qualifier` annotation on individual constructor arguments or method parameters, as shown in the following example: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -58,8 +67,10 @@ method parameters, as shown in the following example: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -77,6 +88,7 @@ method parameters, as shown in the following example: // ... } ---- +====== -- The following example shows corresponding bean definitions. @@ -194,8 +206,11 @@ You can create your own custom qualifier annotations. To do so, define an annota provide the `@Qualifier` annotation within your definition, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target({ElementType.FIELD, ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) @@ -205,22 +220,28 @@ provide the `@Qualifier` annotation within your definition, as the following exa String value(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER) @Retention(AnnotationRetention.RUNTIME) @Qualifier annotation class Genre(val value: String) ---- +====== -- Then you can provide the custom qualifier on autowired fields and parameters, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -238,8 +259,10 @@ following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -257,6 +280,7 @@ following example shows: // ... } ---- +====== -- Next, you can provide the information for the candidate bean definitions. You can add @@ -306,8 +330,11 @@ catalog that can be searched when no Internet connection is available. First, de the simple annotation, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target({ElementType.FIELD, ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) @@ -315,22 +342,28 @@ the simple annotation, as the following example shows: public @interface Offline { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER) @Retention(AnnotationRetention.RUNTIME) @Qualifier annotation class Offline ---- +====== -- Then add the annotation to the field or property to be autowired, as shown in the following example: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -341,6 +374,7 @@ following example: // ... } ---- +====== <1> This line adds the `@Offline` annotation. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -379,8 +413,11 @@ all such attribute values to be considered an autowire candidate. As an example, consider the following annotation definition: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target({ElementType.FIELD, ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) @@ -392,41 +429,53 @@ consider the following annotation definition: Format format(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER) @Retention(AnnotationRetention.RUNTIME) @Qualifier annotation class MovieQualifier(val genre: String, val format: Format) ---- +====== -- In this case `Format` is an enum, defined as follows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public enum Format { VHS, DVD, BLURAY } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- enum class Format { VHS, DVD, BLURAY } ---- +====== -- The fields to be autowired are annotated with the custom qualifier and include values for both attributes: `genre` and `format`, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -449,8 +498,10 @@ for both attributes: `genre` and `format`, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -473,6 +524,7 @@ for both attributes: `genre` and `format`, as the following example shows: // ... } ---- +====== -- Finally, the bean definitions should contain matching qualifier values. This example diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc index 2e5f36016b6c..595675cc2959 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc @@ -9,8 +9,11 @@ examples included in this section. See xref:core/beans/standard-annotations.adoc You can apply the `@Autowired` annotation to constructors, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -24,12 +27,15 @@ You can apply the `@Autowired` annotation to constructors, as the following exam // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender @Autowired constructor( private val customerPreferenceDao: CustomerPreferenceDao) ---- +====== [NOTE] ==== @@ -44,8 +50,11 @@ xref:core/beans/annotation-config/autowired.adoc#beans-autowired-annotation-cons You can also apply the `@Autowired` annotation to _traditional_ setter methods, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleMovieLister { @@ -59,8 +68,10 @@ as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SimpleMovieLister { @@ -71,12 +82,16 @@ as the following example shows: } ---- +====== You can also apply the annotation to methods with arbitrary names and multiple arguments, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -94,8 +109,10 @@ arguments, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -113,12 +130,16 @@ arguments, as the following example shows: // ... } ---- +====== You can apply `@Autowired` to fields as well and even mix it with constructors, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -135,8 +156,10 @@ following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender @Autowired constructor( private val customerPreferenceDao: CustomerPreferenceDao) { @@ -147,6 +170,7 @@ following example shows: // ... } ---- +====== [TIP] ==== @@ -166,8 +190,11 @@ You can also instruct Spring to provide all beans of a particular type from the `ApplicationContext` by adding the `@Autowired` annotation to a field or method that expects an array of that type, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -177,8 +204,10 @@ expects an array of that type, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -188,11 +217,15 @@ expects an array of that type, as the following example shows: // ... } ---- +====== The same applies for typed collections, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -206,8 +239,10 @@ The same applies for typed collections, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -217,6 +252,7 @@ The same applies for typed collections, as the following example shows: // ... } ---- +====== [[beans-factory-ordered]] [TIP] @@ -241,8 +277,11 @@ Even typed `Map` instances can be autowired as long as the expected key type is The map values contain all beans of the expected type, and the keys contain the corresponding bean names, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -256,8 +295,10 @@ corresponding bean names, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -267,6 +308,7 @@ corresponding bean names, as the following example shows: // ... } ---- +====== By default, autowiring fails when no matching candidate beans are available for a given injection point. In the case of a declared array, collection, or map, at least one @@ -277,8 +319,11 @@ dependencies. You can change this behavior as demonstrated in the following exam enabling the framework to skip a non-satisfiable injection point through marking it as non-required (i.e., by setting the `required` attribute in `@Autowired` to `false`): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleMovieLister { @@ -292,8 +337,10 @@ non-required (i.e., by setting the `required` attribute in `@Autowired` to `fals // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SimpleMovieLister { @@ -303,6 +350,7 @@ non-required (i.e., by setting the `required` attribute in `@Autowired` to `fals // ... } ---- +====== [NOTE] ==== @@ -317,8 +365,8 @@ that can be optionally overridden via dependency injection. ==== -[[beans-autowired-annotation-constructor-resolution]] +[[beans-autowired-annotation-constructor-resolution]] Injected constructor and factory method arguments are a special case since the `required` attribute in `@Autowired` has a somewhat different meaning due to Spring's constructor resolution algorithm that may potentially deal with multiple constructors. Constructor @@ -364,8 +412,11 @@ As of Spring Framework 5.0, you can also use a `@Nullable` annotation (of any ki in any package -- for example, `javax.annotation.Nullable` from JSR-305) or just leverage Kotlin built-in null-safety support: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleMovieLister { @@ -375,8 +426,10 @@ Kotlin built-in null-safety support: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SimpleMovieLister { @@ -386,6 +439,7 @@ Kotlin built-in null-safety support: // ... } ---- +====== You can also use `@Autowired` for interfaces that are well-known resolvable dependencies: `BeanFactory`, `ApplicationContext`, `Environment`, `ResourceLoader`, @@ -394,8 +448,11 @@ interfaces, such as `ConfigurableApplicationContext` or `ResourcePatternResolver automatically resolved, with no special setup necessary. The following example autowires an `ApplicationContext` object: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -408,8 +465,10 @@ an `ApplicationContext` object: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender { @@ -419,6 +478,7 @@ class MovieRecommender { // ... } ---- +====== [NOTE] ==== diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/generics-as-qualifiers.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/generics-as-qualifiers.adoc index 0f081e2d3be9..f4dac3a0461b 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/generics-as-qualifiers.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/generics-as-qualifiers.adoc @@ -5,8 +5,11 @@ In addition to the `@Qualifier` annotation, you can use Java generic types as an implicit form of qualification. For example, suppose you have the following configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class MyConfiguration { @@ -22,8 +25,10 @@ configuration: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class MyConfiguration { @@ -35,13 +40,17 @@ configuration: fun integerStore() = IntegerStore() } ---- +====== Assuming that the preceding beans implement a generic interface, (that is, `Store` and `Store`), you can `@Autowire` the `Store` interface and the generic is used as a qualifier, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Autowired private Store s1; // qualifier, injects the stringStore bean @@ -49,8 +58,10 @@ used as a qualifier, as the following example shows: @Autowired private Store s2; // qualifier, injects the integerStore bean ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Autowired private lateinit var s1: Store // qualifier, injects the stringStore bean @@ -58,26 +69,33 @@ used as a qualifier, as the following example shows: @Autowired private lateinit var s2: Store // qualifier, injects the integerStore bean ---- +====== Generic qualifiers also apply when autowiring lists, `Map` instances and arrays. The following example autowires a generic `List`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Inject all Store beans as long as they have an generic // Store beans will not appear in this list @Autowired private List> s; ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Inject all Store beans as long as they have an generic // Store beans will not appear in this list @Autowired private lateinit var s: List> ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc index 391158c84ab7..4c9a1bdcbf3a 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc @@ -13,8 +13,11 @@ as the corresponding Spring lifecycle interface method or explicitly declared ca method. In the following example, the cache is pre-populated upon initialization and cleared upon destruction: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class CachingMovieLister { @@ -29,8 +32,10 @@ cleared upon destruction: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class CachingMovieLister { @@ -45,6 +50,7 @@ cleared upon destruction: } } ---- +====== For details about the effects of combining various lifecycle mechanisms, see xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-combined-effects[Combining Lifecycle Mechanisms]. diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/resource.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/resource.adoc index 1a3f02af6cfc..a9622299440d 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/resource.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/resource.adoc @@ -11,8 +11,11 @@ the bean name to be injected. In other words, it follows by-name semantics, as demonstrated in the following example: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleMovieLister { @@ -24,6 +27,7 @@ as demonstrated in the following example: } } ---- +====== <1> This line injects a `@Resource`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -45,8 +49,11 @@ it takes the bean property name. The following example is going to have the bean named `movieFinder` injected into its setter method: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleMovieLister { @@ -58,8 +65,10 @@ named `movieFinder` injected into its setter method: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SimpleMovieLister { @@ -68,6 +77,7 @@ named `movieFinder` injected into its setter method: } ---- +====== -- NOTE: The name provided with the annotation is resolved as a bean name by the @@ -88,8 +98,11 @@ named "customerPreferenceDao" and then falls back to a primary type match for th `CustomerPreferenceDao`: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -105,6 +118,7 @@ named "customerPreferenceDao" and then falls back to a primary type match for th // ... } ---- +====== <1> The `context` field is injected based on the known resolvable dependency type: `ApplicationContext`. diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc index 006d8da85e3a..967e04af4e70 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc @@ -3,8 +3,11 @@ `@Value` is typically used to inject externalized properties: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class MovieRecommender { @@ -16,29 +19,38 @@ } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class MovieRecommender(@Value("\${catalog.name}") private val catalog: String) ---- +====== With the following configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @PropertySource("classpath:application.properties") public class AppConfig { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @PropertySource("classpath:application.properties") class AppConfig ---- +====== And the following `application.properties` file: @@ -55,8 +67,11 @@ will be injected as the value. If you want to maintain strict control over nonex values, you should declare a `PropertySourcesPlaceholderConfigurer` bean, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -67,8 +82,10 @@ example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -77,6 +94,7 @@ example shows: fun propertyPlaceholderConfigurer() = PropertySourcesPlaceholderConfigurer() } ---- +====== NOTE: When configuring a `PropertySourcesPlaceholderConfigurer` using JavaConfig, the `@Bean` method must be `static`. @@ -95,8 +113,11 @@ automatically converted to `String` array without extra effort. It is possible to provide a default value as following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class MovieRecommender { @@ -108,20 +129,26 @@ It is possible to provide a default value as following: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class MovieRecommender(@Value("\${catalog.name:defaultCatalog}") private val catalog: String) ---- +====== A Spring `BeanPostProcessor` uses a `ConversionService` behind the scenes to handle the process for converting the `String` value in `@Value` to the target type. If you want to provide conversion support for your own custom type, you can provide your own `ConversionService` bean instance as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -134,8 +161,10 @@ provide conversion support for your own custom type, you can provide your own } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -148,12 +177,16 @@ provide conversion support for your own custom type, you can provide your own } } ---- +====== When `@Value` contains a xref:core/expressions.adoc[`SpEL` expression] the value will be dynamically computed at runtime as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class MovieRecommender { @@ -165,18 +198,24 @@ computed at runtime as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class MovieRecommender( @Value("#{systemProperties['user.catalog'] + 'Catalog' }") private val catalog: String) ---- +====== SpEL also enables the use of more complex data structures: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class MovieRecommender { @@ -189,12 +228,15 @@ SpEL also enables the use of more complex data structures: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class MovieRecommender( @Value("#{{'Thriller': 100, 'Comedy': 300}}") private val countOfMoviesPerCatalog: Map) ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/beans/basics.adoc b/framework-docs/modules/ROOT/pages/core/beans/basics.adoc index c38218c32cf7..b3deb285d76a 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/basics.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/basics.adoc @@ -119,16 +119,22 @@ supplied to an `ApplicationContext` constructor are resource strings that let the container load configuration metadata from a variety of external resources, such as the local file system, the Java `CLASSPATH`, and so on. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext context = new ClassPathXmlApplicationContext("services.xml", "daos.xml"); ---- -.Kotlin + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] ---- val context = ClassPathXmlApplicationContext("services.xml", "daos.xml") ---- +====== [NOTE] ==== @@ -295,8 +301,11 @@ a registry of different beans and their dependencies. By using the method The `ApplicationContext` lets you read bean definitions and access them, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // create and configure beans ApplicationContext context = new ClassPathXmlApplicationContext("services.xml", "daos.xml"); @@ -307,7 +316,9 @@ example shows: // use configured instance List userList = service.getUsernameList(); ---- -.Kotlin + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] ---- import org.springframework.beans.factory.getBean @@ -321,58 +332,77 @@ example shows: // use configured instance var userList = service.getUsernameList() ---- +====== With Groovy configuration, bootstrapping looks very similar. It has a different context implementation class which is Groovy-aware (but also understands XML bean definitions). The following example shows Groovy configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext context = new GenericGroovyApplicationContext("services.groovy", "daos.groovy"); ---- -.Kotlin + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] ---- val context = GenericGroovyApplicationContext("services.groovy", "daos.groovy") ---- +====== The most flexible variant is `GenericApplicationContext` in combination with reader delegates -- for example, with `XmlBeanDefinitionReader` for XML files, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- GenericApplicationContext context = new GenericApplicationContext(); new XmlBeanDefinitionReader(context).loadBeanDefinitions("services.xml", "daos.xml"); context.refresh(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val context = GenericApplicationContext() XmlBeanDefinitionReader(context).loadBeanDefinitions("services.xml", "daos.xml") context.refresh() ---- +====== You can also use the `GroovyBeanDefinitionReader` for Groovy files, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- GenericApplicationContext context = new GenericApplicationContext(); new GroovyBeanDefinitionReader(context).loadBeanDefinitions("services.groovy", "daos.groovy"); context.refresh(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val context = GenericApplicationContext() GroovyBeanDefinitionReader(context).loadBeanDefinitions("services.groovy", "daos.groovy") context.refresh() ---- +====== You can mix and match such reader delegates on the same `ApplicationContext`, reading bean definitions from diverse configuration sources. diff --git a/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc b/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc index e88c5d196c7a..32837957748c 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc @@ -86,8 +86,11 @@ The following table lists features provided by the `BeanFactory` and To explicitly register a bean post-processor with a `DefaultListableBeanFactory`, you need to programmatically call `addBeanPostProcessor`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DefaultListableBeanFactory factory = new DefaultListableBeanFactory(); // populate the factory with bean definitions @@ -98,8 +101,10 @@ you need to programmatically call `addBeanPostProcessor`, as the following examp // now start using the factory ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val factory = DefaultListableBeanFactory() // populate the factory with bean definitions @@ -110,12 +115,16 @@ you need to programmatically call `addBeanPostProcessor`, as the following examp // now start using the factory ---- +====== To apply a `BeanFactoryPostProcessor` to a plain `DefaultListableBeanFactory`, you need to call its `postProcessBeanFactory` method, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DefaultListableBeanFactory factory = new DefaultListableBeanFactory(); XmlBeanDefinitionReader reader = new XmlBeanDefinitionReader(factory); @@ -128,8 +137,10 @@ you need to call its `postProcessBeanFactory` method, as the following example s // now actually do the replacement cfg.postProcessBeanFactory(factory); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val factory = DefaultListableBeanFactory() val reader = XmlBeanDefinitionReader(factory) @@ -142,6 +153,7 @@ you need to call its `postProcessBeanFactory` method, as the following example s // now actually do the replacement cfg.postProcessBeanFactory(factory) ---- +====== In both cases, the explicit registration steps are inconvenient, which is why the various `ApplicationContext` variants are preferred over a plain diff --git a/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc b/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc index e595b82d6080..e3f792392237 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc @@ -55,8 +55,11 @@ own code. A meta-annotation is an annotation that can be applied to another anno For example, the `@Service` annotation mentioned xref:core/beans/classpath-scanning.adoc#beans-stereotype-annotations[earlier] is meta-annotated with `@Component`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @@ -67,6 +70,7 @@ is meta-annotated with `@Component`, as the following example shows: // ... } ---- +====== <1> The `@Component` causes `@Service` to be treated in the same way as `@Component`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -94,8 +98,11 @@ want to only expose a subset of the meta-annotation's attributes. For example, S customization of the `proxyMode`. The following listing shows the definition of the `SessionScope` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @@ -112,8 +119,10 @@ customization of the `proxyMode`. The following listing shows the definition of } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION) @Retention(AnnotationRetention.RUNTIME) @@ -124,11 +133,15 @@ customization of the `proxyMode`. The following listing shows the definition of val proxyMode: ScopedProxyMode = ScopedProxyMode.TARGET_CLASS ) ---- +====== You can then use `@SessionScope` without declaring the `proxyMode` as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Service @SessionScope @@ -136,8 +149,10 @@ You can then use `@SessionScope` without declaring the `proxyMode` as follows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Service @SessionScope @@ -145,11 +160,15 @@ You can then use `@SessionScope` without declaring the `proxyMode` as follows: // ... } ---- +====== You can also override the value for the `proxyMode`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Service @SessionScope(proxyMode = ScopedProxyMode.INTERFACES) @@ -157,8 +176,10 @@ You can also override the value for the `proxyMode`, as the following example sh // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Service @SessionScope(proxyMode = ScopedProxyMode.INTERFACES) @@ -166,6 +187,7 @@ You can also override the value for the `proxyMode`, as the following example sh // ... } ---- +====== For further details, see the https://github.com/spring-projects/spring-framework/wiki/Spring-Annotation-Programming-Model[Spring Annotation Programming Model] @@ -180,8 +202,11 @@ Spring can automatically detect stereotyped classes and register corresponding `BeanDefinition` instances with the `ApplicationContext`. For example, the following two classes are eligible for such autodetection: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Service public class SimpleMovieLister { @@ -193,29 +218,38 @@ are eligible for such autodetection: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Service class SimpleMovieLister(private val movieFinder: MovieFinder) ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Repository public class JpaMovieFinder implements MovieFinder { // implementation elided for clarity } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Repository class JpaMovieFinder : MovieFinder { // implementation elided for clarity } ---- +====== To autodetect these classes and register the corresponding beans, you need to add @@ -223,8 +257,11 @@ To autodetect these classes and register the corresponding beans, you need to ad is a common parent package for the two classes. (Alternatively, you can specify a comma- or semicolon- or space-separated list that includes the parent package of each class.) +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ComponentScan(basePackages = "org.example") @@ -232,8 +269,10 @@ comma- or semicolon- or space-separated list that includes the parent package of // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @ComponentScan(basePackages = ["org.example"]) @@ -241,6 +280,7 @@ comma- or semicolon- or space-separated list that includes the parent package of // ... } ---- +====== NOTE: For brevity, the preceding example could have used the `value` attribute of the annotation (that is, `@ComponentScan("org.example")`). @@ -335,8 +375,11 @@ The following table describes the filtering options: The following example shows the configuration ignoring all `@Repository` annotations and using "`stub`" repositories instead: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ComponentScan(basePackages = "org.example", @@ -346,8 +389,10 @@ and using "`stub`" repositories instead: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @ComponentScan(basePackages = ["org.example"], @@ -357,6 +402,7 @@ and using "`stub`" repositories instead: // ... } ---- +====== The following listing shows the equivalent XML: @@ -387,8 +433,11 @@ Spring components can also contribute bean definition metadata to the container. this with the same `@Bean` annotation used to define bean metadata within `@Configuration` annotated classes. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class FactoryMethodComponent { @@ -404,8 +453,10 @@ annotated classes. The following example shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class FactoryMethodComponent { @@ -419,6 +470,7 @@ annotated classes. The following example shows how to do so: } } ---- +====== The preceding class is a Spring component that has application-specific code in its `doWork()` method. However, it also contributes a bean definition that has a factory @@ -436,8 +488,11 @@ with optional dependencies, we recommend `ObjectProvider` instead. Autowired fields and methods are supported, as previously discussed, with additional support for autowiring of `@Bean` methods. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class FactoryMethodComponent { @@ -473,8 +528,10 @@ support for autowiring of `@Bean` methods. The following example shows how to do } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class FactoryMethodComponent { @@ -504,6 +561,7 @@ support for autowiring of `@Bean` methods. The following example shows how to do fun requestScopedInstance() = TestBean("requestScopedInstance", 3) } ---- +====== The example autowires the `String` method parameter `country` to the value of the `age` property on another bean named `privateInstance`. A Spring Expression Language element @@ -522,8 +580,11 @@ injection point that triggered the creation of a new bean instance in the given You can use the provided injection point metadata with semantic care in such scenarios. The following example shows how to use `InjectionPoint`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class FactoryMethodComponent { @@ -534,8 +595,10 @@ The following example shows how to use `InjectionPoint`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class FactoryMethodComponent { @@ -546,6 +609,7 @@ The following example shows how to use `InjectionPoint`: TestBean("prototypeInstance for ${injectionPoint.member}") } ---- +====== The `@Bean` methods in a regular Spring component are processed differently than their counterparts inside a Spring `@Configuration` class. The difference is that `@Component` @@ -609,39 +673,51 @@ If such an annotation contains no name `value` or for any other detected compone the uncapitalized non-qualified class name. For example, if the following component classes were detected, the names would be `myMovieLister` and `movieFinderImpl`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Service("myMovieLister") public class SimpleMovieLister { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Service("myMovieLister") class SimpleMovieLister { // ... } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Repository public class MovieFinderImpl implements MovieFinder { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Repository class MovieFinderImpl : MovieFinder { // ... } ---- +====== If you do not want to rely on the default bean-naming strategy, you can provide a custom bean-naming strategy. First, implement the @@ -657,8 +733,11 @@ fully qualified class name for the generated bean name. As of Spring Framework 5 `FullyQualifiedAnnotationBeanNameGenerator` located in package `org.springframework.context.annotation` can be used for such purposes. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ComponentScan(basePackages = "org.example", nameGenerator = MyNameGenerator.class) @@ -666,8 +745,10 @@ fully qualified class name for the generated bean name. As of Spring Framework 5 // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @ComponentScan(basePackages = ["org.example"], nameGenerator = MyNameGenerator::class) @@ -675,6 +756,7 @@ fully qualified class name for the generated bean name. As of Spring Framework 5 // ... } ---- +====== [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -698,8 +780,11 @@ autodetected components is `singleton`. However, sometimes you need a different that can be specified by the `@Scope` annotation. You can provide the name of the scope within the annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Scope("prototype") @Repository @@ -707,8 +792,10 @@ scope within the annotation, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Scope("prototype") @Repository @@ -716,6 +803,7 @@ scope within the annotation, as the following example shows: // ... } ---- +====== NOTE: `@Scope` annotations are only introspected on the concrete bean class (for annotated components) or the factory method (for `@Bean` methods). In contrast to XML bean @@ -735,8 +823,11 @@ interface. Be sure to include a default no-arg constructor. Then you can provide fully qualified class name when configuring the scanner, as the following example of both an annotation and a bean definition shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ComponentScan(basePackages = "org.example", scopeResolver = MyScopeResolver.class) @@ -744,8 +835,10 @@ an annotation and a bean definition shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @ComponentScan(basePackages = ["org.example"], scopeResolver = MyScopeResolver::class) @@ -753,6 +846,7 @@ an annotation and a bean definition shows: // ... } ---- +====== [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -767,8 +861,11 @@ For this purpose, a scoped-proxy attribute is available on the component-scan element. The three possible values are: `no`, `interfaces`, and `targetClass`. For example, the following configuration results in standard JDK dynamic proxies: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ComponentScan(basePackages = "org.example", scopedProxy = ScopedProxyMode.INTERFACES) @@ -776,8 +873,10 @@ the following configuration results in standard JDK dynamic proxies: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @ComponentScan(basePackages = ["org.example"], scopedProxy = ScopedProxyMode.INTERFACES) @@ -785,6 +884,7 @@ the following configuration results in standard JDK dynamic proxies: // ... } ---- +====== [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -808,8 +908,11 @@ auto-detection of components, you can provide the qualifier metadata with type-l annotations on the candidate class. The following three examples demonstrate this technique: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component @Qualifier("Action") @@ -817,16 +920,22 @@ technique: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component @Qualifier("Action") class ActionMovieCatalog : MovieCatalog ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component @Genre("Action") @@ -834,8 +943,10 @@ technique: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component @Genre("Action") @@ -843,9 +954,13 @@ technique: // ... } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component @Offline @@ -853,8 +968,10 @@ technique: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component @Offline @@ -862,6 +979,7 @@ class CachingMovieCatalog : MovieCatalog { // ... } ---- +====== NOTE: As with most annotation-based alternatives, keep in mind that the annotation metadata is bound to the class definition itself, while the use of XML allows for multiple beans diff --git a/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc b/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc index 4caec82ef440..c77bc8a92358 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc @@ -98,8 +98,11 @@ The next example shows a program to run the `MessageSource` functionality. Remember that all `ApplicationContext` implementations are also `MessageSource` implementations and so can be cast to the `MessageSource` interface. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static void main(String[] args) { MessageSource resources = new ClassPathXmlApplicationContext("beans.xml"); @@ -107,8 +110,10 @@ implementations and so can be cast to the `MessageSource` interface. System.out.println(message); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun main() { val resources = ClassPathXmlApplicationContext("beans.xml") @@ -116,6 +121,7 @@ implementations and so can be cast to the `MessageSource` interface. println(message) } ---- +====== The resulting output from the above program is as follows: @@ -151,8 +157,11 @@ converted into `String` objects and inserted into placeholders in the lookup mes ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class Example { @@ -169,8 +178,10 @@ converted into `String` objects and inserted into placeholders in the lookup mes } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class Example { @@ -183,6 +194,7 @@ converted into `String` objects and inserted into placeholders in the lookup mes } } ---- +====== The resulting output from the invocation of the `execute()` method is as follows: @@ -208,8 +220,11 @@ resolved is specified manually: argument.required=Ebagum lad, the ''{0}'' argument is required, I say, required. ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static void main(final String[] args) { MessageSource resources = new ClassPathXmlApplicationContext("beans.xml"); @@ -218,8 +233,10 @@ argument.required=Ebagum lad, the ''{0}'' argument is required, I say, required. System.out.println(message); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun main() { val resources = ClassPathXmlApplicationContext("beans.xml") @@ -228,6 +245,7 @@ argument.required=Ebagum lad, the ''{0}'' argument is required, I say, required. println(message) } ---- +====== The resulting output from the running of the above program is as follows: @@ -322,8 +340,11 @@ The following table describes the standard events that Spring provides: You can also create and publish your own custom events. The following example shows a simple class that extends Spring's `ApplicationEvent` base class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class BlockedListEvent extends ApplicationEvent { @@ -339,21 +360,27 @@ simple class that extends Spring's `ApplicationEvent` base class: // accessor and other methods... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class BlockedListEvent(source: Any, val address: String, val content: String) : ApplicationEvent(source) ---- +====== To publish a custom `ApplicationEvent`, call the `publishEvent()` method on an `ApplicationEventPublisher`. Typically, this is done by creating a class that implements `ApplicationEventPublisherAware` and registering it as a Spring bean. The following example shows such a class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class EmailService implements ApplicationEventPublisherAware { @@ -377,8 +404,10 @@ example shows such a class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class EmailService : ApplicationEventPublisherAware { @@ -402,6 +431,7 @@ example shows such a class: } } ---- +====== At configuration time, the Spring container detects that `EmailService` implements `ApplicationEventPublisherAware` and automatically calls @@ -413,8 +443,11 @@ To receive the custom `ApplicationEvent`, you can create a class that implements `ApplicationListener` and register it as a Spring bean. The following example shows such a class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class BlockedListNotifier implements ApplicationListener { @@ -429,8 +462,10 @@ shows such a class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class BlockedListNotifier : ApplicationListener { @@ -441,6 +476,7 @@ shows such a class: } } ---- +====== Notice that `ApplicationListener` is generically parameterized with the type of your custom event (`BlockedListEvent` in the preceding example). This means that the @@ -497,8 +533,11 @@ architectures that build upon the well-known Spring programming model. You can register an event listener on any method of a managed bean by using the `@EventListener` annotation. The `BlockedListNotifier` can be rewritten as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class BlockedListNotifier { @@ -514,8 +553,10 @@ You can register an event listener on any method of a managed bean by using the } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class BlockedListNotifier { @@ -527,6 +568,7 @@ You can register an event listener on any method of a managed bean by using the } } ---- +====== The method signature once again declares the event type to which it listens, but, this time, with a flexible name and without implementing a specific listener interface. @@ -537,22 +579,28 @@ If your method should listen to several events or if you want to define it with parameter at all, the event types can also be specified on the annotation itself. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @EventListener({ContextStartedEvent.class, ContextRefreshedEvent.class}) public void handleContextStart() { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @EventListener(ContextStartedEvent::class, ContextRefreshedEvent::class) fun handleContextStart() { // ... } ---- +====== It is also possible to add additional runtime filtering by using the `condition` attribute of the annotation that defines a xref:core/expressions.adoc[`SpEL` expression], which should match @@ -561,22 +609,28 @@ to actually invoke the method for a particular event. The following example shows how our notifier can be rewritten to be invoked only if the `content` attribute of the event is equal to `my-event`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @EventListener(condition = "#blEvent.content == 'my-event'") public void processBlockedListEvent(BlockedListEvent blEvent) { // notify appropriate parties via notificationAddress... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @EventListener(condition = "#blEvent.content == 'my-event'") fun processBlockedListEvent(blEvent: BlockedListEvent) { // notify appropriate parties via notificationAddress... } ---- +====== Each `SpEL` expression evaluates against a dedicated context. The following table lists the items made available to the context so that you can use them for conditional event processing: @@ -611,8 +665,11 @@ signature actually refers to an arbitrary object that was published. If you need to publish an event as the result of processing another event, you can change the method signature to return the event that should be published, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @EventListener public ListUpdateEvent handleBlockedListEvent(BlockedListEvent event) { @@ -620,8 +677,10 @@ method signature to return the event that should be published, as the following // then publish a ListUpdateEvent... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @EventListener fun handleBlockedListEvent(event: BlockedListEvent): ListUpdateEvent { @@ -629,6 +688,7 @@ method signature to return the event that should be published, as the following // then publish a ListUpdateEvent... } ---- +====== NOTE: This feature is not supported for xref:core/beans/context-introduction.adoc#context-functionality-events-async[asynchronous listeners]. @@ -645,8 +705,11 @@ If you want a particular listener to process events asynchronously, you can reus xref:integration/scheduling.adoc#scheduling-annotation-support-async[regular `@Async` support]. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @EventListener @Async @@ -654,8 +717,10 @@ The following example shows how to do so: // BlockedListEvent is processed in a separate thread } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @EventListener @Async @@ -663,6 +728,7 @@ The following example shows how to do so: // BlockedListEvent is processed in a separate thread } ---- +====== Be aware of the following limitations when using asynchronous events: @@ -682,8 +748,11 @@ Be aware of the following limitations when using asynchronous events: If you need one listener to be invoked before another one, you can add the `@Order` annotation to the method declaration, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @EventListener @Order(42) @@ -691,8 +760,10 @@ annotation to the method declaration, as the following example shows: // notify appropriate parties via notificationAddress... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @EventListener @Order(42) @@ -700,6 +771,7 @@ annotation to the method declaration, as the following example shows: // notify appropriate parties via notificationAddress... } ---- +====== [[context-functionality-events-generics]] @@ -710,22 +782,28 @@ You can also use generics to further define the structure of your event. Conside can create the following listener definition to receive only `EntityCreatedEvent` for a `Person`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @EventListener public void onPersonCreated(EntityCreatedEvent event) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @EventListener fun onPersonCreated(event: EntityCreatedEvent) { // ... } ---- +====== Due to type erasure, this works only if the event that is fired resolves the generic parameters on which the event listener filters (that is, something like @@ -736,8 +814,11 @@ structure (as should be the case for the event in the preceding example). In suc you can implement `ResolvableTypeProvider` to guide the framework beyond what the runtime environment provides. The following event shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class EntityCreatedEvent extends ApplicationEvent implements ResolvableTypeProvider { @@ -751,8 +832,10 @@ environment provides. The following event shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class EntityCreatedEvent(entity: T) : ApplicationEvent(entity), ResolvableTypeProvider { @@ -761,6 +844,7 @@ environment provides. The following event shows how to do so: } } ---- +====== TIP: This works not only for `ApplicationEvent` but any arbitrary object that you send as an event. @@ -819,8 +903,11 @@ The `AbstractApplicationContext` (and its subclasses) is instrumented with an Here is an example of instrumentation in the `AnnotationConfigApplicationContext`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // create a startup step and start recording StartupStep scanPackages = this.getApplicationStartup().start("spring.context.base-packages.scan"); @@ -831,8 +918,10 @@ Here is an example of instrumentation in the `AnnotationConfigApplicationContext // end the current step scanPackages.end(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // create a startup step and start recording val scanPackages = this.getApplicationStartup().start("spring.context.base-packages.scan") @@ -843,6 +932,7 @@ Here is an example of instrumentation in the `AnnotationConfigApplicationContext // end the current step scanPackages.end() ---- +====== The application context is already instrumented with multiple steps. Once recorded, these startup steps can be collected, displayed and analyzed with specific tools. diff --git a/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc b/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc index c7280792b3ff..73579b414ded 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc @@ -7,21 +7,27 @@ loaded into the Java virtual machine (JVM). To enable load-time weaving, you can add the `@EnableLoadTimeWeaving` to one of your `@Configuration` classes, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableLoadTimeWeaving public class AppConfig { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableLoadTimeWeaving class AppConfig ---- +====== Alternatively, for XML configuration, you can use the `context:load-time-weaver` element: diff --git a/framework-docs/modules/ROOT/pages/core/beans/definition.adoc b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc index 48efa61acae9..97164897c99a 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/definition.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc @@ -260,8 +260,11 @@ specify a factory method: The following example shows a class that would work with the preceding bean definition: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ClientService { private static ClientService clientService = new ClientService(); @@ -272,8 +275,10 @@ The following example shows a class that would work with the preceding bean defi } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ClientService private constructor() { companion object { @@ -283,6 +288,7 @@ The following example shows a class that would work with the preceding bean defi } } ---- +====== For details about the mechanism for supplying (optional) arguments to the factory method and setting object instance properties after the object is returned from the factory, @@ -316,8 +322,11 @@ how to configure such a bean: The following example shows the corresponding class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class DefaultServiceLocator { @@ -328,8 +337,10 @@ The following example shows the corresponding class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class DefaultServiceLocator { companion object { @@ -340,6 +351,7 @@ The following example shows the corresponding class: } } ---- +====== One factory class can also hold more than one factory method, as the following example shows: @@ -360,8 +372,11 @@ One factory class can also hold more than one factory method, as the following e The following example shows the corresponding class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class DefaultServiceLocator { @@ -378,8 +393,10 @@ The following example shows the corresponding class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class DefaultServiceLocator { companion object { @@ -396,6 +413,7 @@ The following example shows the corresponding class: } } ---- +====== This approach shows that the factory bean itself can be managed and configured through dependency injection (DI). See xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail] diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc index becfead14bce..25bbaff2b63b 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc @@ -30,8 +30,11 @@ treats arguments to a constructor and to a `static` factory method similarly. Th following example shows a class that can only be dependency-injected with constructor injection: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleMovieLister { @@ -46,14 +49,17 @@ injection: // business logic that actually uses the injected MovieFinder is omitted... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // a constructor so that the Spring container can inject a MovieFinder class SimpleMovieLister(private val movieFinder: MovieFinder) { // business logic that actually uses the injected MovieFinder is omitted... } ---- +====== Notice that there is nothing special about this class. It is a POJO that has no dependencies on container specific interfaces, base classes, or annotations. @@ -67,8 +73,11 @@ order in which the constructor arguments are defined in a bean definition is the in which those arguments are supplied to the appropriate constructor when the bean is being instantiated. Consider the following class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package x.y; @@ -79,13 +88,16 @@ being instantiated. Consider the following class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package x.y class ThingOne(thingTwo: ThingTwo, thingThree: ThingThree) ---- +====== Assuming that the `ThingTwo` and `ThingThree` classes are not related by inheritance, no potential ambiguity exists. Thus, the following configuration works fine, and you do not @@ -111,8 +123,11 @@ case with the preceding example). When a simple type is used, such as `true`, Spring cannot determine the type of the value, and so cannot match by type without help. Consider the following class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package examples; @@ -130,8 +145,10 @@ by type without help. Consider the following class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package examples @@ -140,6 +157,7 @@ by type without help. Consider the following class: private val ultimateAnswer: String // The Answer to Life, the Universe, and Everything ) ---- +====== .[[beans-factory-ctor-arguments-type]]Constructor argument type matching -- @@ -195,8 +213,11 @@ https://download.oracle.com/javase/8/docs/api/java/beans/ConstructorProperties.h JDK annotation to explicitly name your constructor arguments. The sample class would then have to look as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package examples; @@ -211,8 +232,10 @@ then have to look as follows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package examples @@ -220,6 +243,7 @@ then have to look as follows: @ConstructorProperties("years", "ultimateAnswer") constructor(val years: Int, val ultimateAnswer: String) ---- +====== -- @@ -234,8 +258,11 @@ The following example shows a class that can only be dependency-injected by usin setter injection. This class is conventional Java. It is a POJO that has no dependencies on container specific interfaces, base classes, or annotations. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleMovieLister { @@ -250,8 +277,10 @@ on container specific interfaces, base classes, or annotations. // business logic that actually uses the injected MovieFinder is omitted... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SimpleMovieLister { @@ -261,6 +290,7 @@ class SimpleMovieLister { // business logic that actually uses the injected MovieFinder is omitted... } ---- +====== The `ApplicationContext` supports constructor-based and setter-based DI for the beans it @@ -403,8 +433,11 @@ part of a Spring XML configuration file specifies some bean definitions as follo The following example shows the corresponding `ExampleBean` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ExampleBean { @@ -427,8 +460,10 @@ The following example shows the corresponding `ExampleBean` class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ExampleBean { lateinit var beanOne: AnotherBean @@ -436,6 +471,7 @@ class ExampleBean { var i: Int = 0 } ---- +====== In the preceding example, setters are declared to match against the properties specified in the XML file. The following example uses constructor-based DI: @@ -460,8 +496,11 @@ in the XML file. The following example uses constructor-based DI: The following example shows the corresponding `ExampleBean` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ExampleBean { @@ -479,14 +518,17 @@ The following example shows the corresponding `ExampleBean` class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ExampleBean( private val beanOne: AnotherBean, private val beanTwo: YetAnotherBean, private val i: Int) ---- +====== The constructor arguments specified in the bean definition are used as arguments to the constructor of the `ExampleBean`. @@ -508,8 +550,11 @@ told to call a `static` factory method to return an instance of the object: The following example shows the corresponding `ExampleBean` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ExampleBean { @@ -530,8 +575,10 @@ The following example shows the corresponding `ExampleBean` class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ExampleBean private constructor() { companion object { @@ -547,6 +594,7 @@ The following example shows the corresponding `ExampleBean` class: } } ---- +====== Arguments to the `static` factory method are supplied by `` elements, exactly the same as if a constructor had actually been used. The type of the class being diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc index 18742fe6e1b8..108202c40ac7 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc @@ -17,8 +17,11 @@ and by xref:core/beans/basics.adoc#beans-factory-client[making a `getBean("B")` typically new) bean B instance every time bean A needs it. The following example shows this approach: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages",fold="none"] -.Java ---- package fiona.apple; @@ -54,8 +57,10 @@ shows this approach: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages",fold="none"] -.Kotlin ---- package fiona.apple @@ -86,6 +91,7 @@ shows this approach: } } ---- +====== The preceding is not desirable, because the business code is aware of and coupled to the Spring Framework. Method Injection, a somewhat advanced feature of the Spring IoC @@ -127,8 +133,11 @@ Spring container dynamically overrides the implementation of the `createCommand( method. The `CommandManager` class does not have any Spring dependencies, as the reworked example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages",fold="none"] -.Java ---- package fiona.apple; @@ -148,8 +157,10 @@ the reworked example shows: protected abstract Command createCommand(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages",fold="none"] -.Kotlin ---- package fiona.apple @@ -169,6 +180,7 @@ the reworked example shows: protected abstract fun createCommand(): Command } ---- +====== In the client class that contains the method to be injected (the `CommandManager` in this case), the method to be injected requires a signature of the following form: @@ -204,8 +216,11 @@ bean is returned each time. Alternatively, within the annotation-based component model, you can declare a lookup method through the `@Lookup` annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public abstract class CommandManager { @@ -219,8 +234,10 @@ method through the `@Lookup` annotation, as the following example shows: protected abstract Command createCommand(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- abstract class CommandManager { @@ -234,12 +251,16 @@ method through the `@Lookup` annotation, as the following example shows: protected abstract fun createCommand(): Command } ---- +====== Or, more idiomatically, you can rely on the target bean getting resolved against the declared return type of the lookup method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public abstract class CommandManager { @@ -253,8 +274,10 @@ declared return type of the lookup method: protected abstract Command createCommand(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- abstract class CommandManager { @@ -268,6 +291,7 @@ declared return type of the lookup method: protected abstract fun createCommand(): Command } ---- +====== Note that you should typically declare such annotated lookup methods with a concrete stub implementation, in order for them to be compatible with Spring's component @@ -296,8 +320,11 @@ With XML-based configuration metadata, you can use the `replaced-method` element replace an existing method implementation with another, for a deployed bean. Consider the following class, which has a method called `computeValue` that we want to override: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyValueCalculator { @@ -308,8 +335,10 @@ the following class, which has a method called `computeValue` that we want to ov // some other methods... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyValueCalculator { @@ -320,12 +349,16 @@ the following class, which has a method called `computeValue` that we want to ov // some other methods... } ---- +====== A class that implements the `org.springframework.beans.factory.support.MethodReplacer` interface provides the new method definition, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- /** * meant to be used to override the existing computeValue(String) @@ -341,8 +374,10 @@ interface provides the new method definition, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- /** * meant to be used to override the existing computeValue(String) @@ -358,6 +393,7 @@ interface provides the new method definition, as the following example shows: } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc index 25b41d07a76c..ae7874fa329f 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc @@ -350,8 +350,11 @@ type-conversion support such that the elements of your strongly-typed `Collectio instances are converted to the appropriate type prior to being added to the `Collection`. The following Java class and bean definition show how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SomeClass { @@ -362,13 +365,16 @@ The following Java class and bean definition show how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SomeClass { lateinit var accounts: Map } ---- +====== [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -408,16 +414,22 @@ following XML-based configuration metadata snippet sets the `email` property to The preceding example is equivalent to the following Java code: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- exampleBean.setEmail(""); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- exampleBean.email = "" ---- +====== The `` element handles `null` values. The following listing shows an example: @@ -433,16 +445,22 @@ The `` element handles `null` values. The following listing shows an exam The preceding configuration is equivalent to the following Java code: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- exampleBean.setEmail(null); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- exampleBean.email = null ---- +====== [[beans-p-namespace]] diff --git a/framework-docs/modules/ROOT/pages/core/beans/environment.adoc b/framework-docs/modules/ROOT/pages/core/beans/environment.adoc index 137e0c32b4e8..441fdb49b56b 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/environment.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/environment.adoc @@ -39,8 +39,11 @@ B deployments. Consider the first use case in a practical application that requires a `DataSource`. In a test environment, the configuration might resemble the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Bean public DataSource dataSource() { @@ -51,8 +54,10 @@ Consider the first use case in a practical application that requires a .build(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Bean fun dataSource(): DataSource { @@ -63,14 +68,18 @@ Consider the first use case in a practical application that requires a .build() } ---- +====== Now consider how this application can be deployed into a QA or production environment, assuming that the datasource for the application is registered with the production application server's JNDI directory. Our `dataSource` bean now looks like the following listing: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Bean(destroyMethod = "") public DataSource dataSource() throws Exception { @@ -78,8 +87,10 @@ now looks like the following listing: return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource"); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Bean(destroyMethod = "") fun dataSource(): DataSource { @@ -87,6 +98,7 @@ now looks like the following listing: return ctx.lookup("java:comp/env/jdbc/datasource") as DataSource } ---- +====== The problem is how to switch between using these two variations based on the current environment. Over time, Spring users have devised a number of ways to @@ -112,8 +124,11 @@ when one or more specified profiles are active. Using our preceding example, we can rewrite the `dataSource` configuration as follows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @Profile("development") @@ -129,8 +144,10 @@ can rewrite the `dataSource` configuration as follows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @Profile("development") @@ -146,11 +163,15 @@ can rewrite the `dataSource` configuration as follows: } } ---- +====== -- -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @Profile("production") @@ -163,6 +184,7 @@ can rewrite the `dataSource` configuration as follows: } } ---- +====== <1> `@Bean(destroyMethod = "")` disables default destroy method inference. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -206,8 +228,11 @@ of creating a custom composed annotation. The following example defines a custom `@Profile("production")`: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @@ -215,14 +240,17 @@ of creating a custom composed annotation. The following example defines a custom public @interface Production { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.CLASS) @Retention(AnnotationRetention.RUNTIME) @Profile("production") annotation class Production ---- +====== -- TIP: If a `@Configuration` class is marked with `@Profile`, all of the `@Bean` methods and @@ -239,8 +267,11 @@ of a configuration class (for example, for alternative variants of a particular the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -263,6 +294,7 @@ the following example shows: } } ---- +====== <1> The `standaloneDataSource` method is available only in the `development` profile. <2> The `jndiDataSource` method is available only in the `production` profile. @@ -416,16 +448,21 @@ Activating a profile can be done in several ways, but the most straightforward i it programmatically against the `Environment` API which is available through an `ApplicationContext`. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); ctx.getEnvironment().setActiveProfiles("development"); ctx.register(SomeConfig.class, StandaloneDataConfig.class, JndiDataConfig.class); ctx.refresh(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = AnnotationConfigApplicationContext().apply { environment.setActiveProfiles("development") @@ -433,6 +470,7 @@ it programmatically against the `Environment` API which is available through an refresh() } ---- +====== In addition, you can also declaratively activate profiles through the `spring.profiles.active` property, which may be specified through system environment @@ -447,16 +485,22 @@ profiles at once. Programmatically, you can provide multiple profile names to th `setActiveProfiles()` method, which accepts `String...` varargs. The following example activates multiple profiles: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ctx.getEnvironment().setActiveProfiles("profile1", "profile2"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- ctx.getEnvironment().setActiveProfiles("profile1", "profile2") ---- +====== Declaratively, `spring.profiles.active` may accept a comma-separated list of profile names, as the following example shows: @@ -473,8 +517,11 @@ as the following example shows: The default profile represents the profile that is enabled by default. Consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @Profile("default") @@ -489,8 +536,10 @@ following example: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @Profile("default") @@ -505,6 +554,7 @@ following example: } } ---- +====== If no profile is active, the `dataSource` is created. You can see this as a way to provide a default definition for one or more beans. If any @@ -521,22 +571,28 @@ the `Environment` or, declaratively, by using the `spring.profiles.default` prop Spring's `Environment` abstraction provides search operations over a configurable hierarchy of property sources. Consider the following listing: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext ctx = new GenericApplicationContext(); Environment env = ctx.getEnvironment(); boolean containsMyProperty = env.containsProperty("my-property"); System.out.println("Does my environment contain the 'my-property' property? " + containsMyProperty); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = GenericApplicationContext() val env = ctx.environment val containsMyProperty = env.containsProperty("my-property") println("Does my environment contain the 'my-property' property? $containsMyProperty") ---- +====== In the preceding snippet, we see a high-level way of asking Spring whether the `my-property` property is defined for the current environment. To answer this question, the `Environment` object performs @@ -580,20 +636,26 @@ of properties that you want to integrate into this search. To do so, implement and instantiate your own `PropertySource` and add it to the set of `PropertySources` for the current `Environment`. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ConfigurableApplicationContext ctx = new GenericApplicationContext(); MutablePropertySources sources = ctx.getEnvironment().getPropertySources(); sources.addFirst(new MyPropertySource()); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = GenericApplicationContext() val sources = ctx.environment.propertySources sources.addFirst(MyPropertySource()) ---- +====== In the preceding code, `MyPropertySource` has been added with highest precedence in the search. If it contains a `my-property` property, the property is detected and returned, in favor of @@ -615,8 +677,11 @@ Given a file called `app.properties` that contains the key-value pair `testbean. the following `@Configuration` class uses `@PropertySource` in such a way that a call to `testBean.getName()` returns `myTestBean`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @PropertySource("classpath:/com/myco/app.properties") @@ -633,8 +698,10 @@ a call to `testBean.getName()` returns `myTestBean`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @PropertySource("classpath:/com/myco/app.properties") @@ -649,13 +716,17 @@ a call to `testBean.getName()` returns `myTestBean`: } } ---- +====== Any `${...}` placeholders present in a `@PropertySource` resource location are resolved against the set of property sources already registered against the environment, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @PropertySource("classpath:/com/${my.placeholder:default/path}/app.properties") @@ -672,8 +743,10 @@ environment, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @PropertySource("classpath:/com/\${my.placeholder:default/path}/app.properties") @@ -688,6 +761,7 @@ environment, as the following example shows: } } ---- +====== Assuming that `my.placeholder` is present in one of the property sources already registered (for example, system properties or environment variables), the placeholder is diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc index df156b2372f8..6882cdb7add1 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc @@ -120,8 +120,11 @@ it is created by the container and prints the resulting string to the system con The following listing shows the custom `BeanPostProcessor` implementation class definition: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package scripting; @@ -140,8 +143,10 @@ The following listing shows the custom `BeanPostProcessor` implementation class } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package scripting @@ -160,6 +165,7 @@ The following listing shows the custom `BeanPostProcessor` implementation class } } ---- +====== The following `beans` element uses the `InstantiationTracingBeanPostProcessor`: @@ -196,8 +202,11 @@ xref:languages/dynamic.adoc[Dynamic Language Support].) The following Java application runs the preceding code and configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import org.springframework.context.ApplicationContext; import org.springframework.context.support.ClassPathXmlApplicationContext; @@ -213,8 +222,10 @@ The following Java application runs the preceding code and configuration: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -224,6 +235,7 @@ The following Java application runs the preceding code and configuration: println(messenger) } ---- +====== The output of the preceding application resembles the following: diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc index b13f08e79529..634ee04486f2 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc @@ -67,8 +67,11 @@ no-argument signature. With Java configuration, you can use the `initMethod` att ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ExampleBean { @@ -77,8 +80,10 @@ no-argument signature. With Java configuration, you can use the `initMethod` att } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ExampleBean { @@ -87,6 +92,7 @@ no-argument signature. With Java configuration, you can use the `initMethod` att } } ---- +====== The preceding example has almost exactly the same effect as the following example (which consists of two listings): @@ -96,8 +102,11 @@ The preceding example has almost exactly the same effect as the following exampl ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class AnotherExampleBean implements InitializingBean { @@ -107,8 +116,10 @@ The preceding example has almost exactly the same effect as the following exampl } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class AnotherExampleBean : InitializingBean { @@ -117,6 +128,7 @@ The preceding example has almost exactly the same effect as the following exampl } } ---- +====== However, the first of the two preceding examples does not couple the code to Spring. @@ -146,8 +158,11 @@ xref:core/beans/java/bean-annotation.adoc#beans-java-lifecycle-callbacks[Receivi ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ExampleBean { @@ -156,8 +171,10 @@ xref:core/beans/java/bean-annotation.adoc#beans-java-lifecycle-callbacks[Receivi } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ExampleBean { @@ -166,6 +183,7 @@ xref:core/beans/java/bean-annotation.adoc#beans-java-lifecycle-callbacks[Receivi } } ---- +====== The preceding definition has almost exactly the same effect as the following definition: @@ -174,8 +192,11 @@ The preceding definition has almost exactly the same effect as the following def ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class AnotherExampleBean implements DisposableBean { @@ -185,8 +206,10 @@ The preceding definition has almost exactly the same effect as the following def } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class AnotherExampleBean : DisposableBean { @@ -195,6 +218,7 @@ The preceding definition has almost exactly the same effect as the following def } } ---- +====== However, the first of the two preceding definitions does not couple the code to Spring. @@ -229,8 +253,11 @@ Suppose that your initialization callback methods are named `init()` and your de callback methods are named `destroy()`. Your class then resembles the class in the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class DefaultBlogService implements BlogService { @@ -248,8 +275,10 @@ following example: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class DefaultBlogService : BlogService { @@ -263,6 +292,7 @@ following example: } } ---- +====== You could then use that class in a bean resembling the following: @@ -478,8 +508,11 @@ and implement these destroy callbacks correctly. To register a shutdown hook, call the `registerShutdownHook()` method that is declared on the `ConfigurableApplicationContext` interface, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import org.springframework.context.ConfigurableApplicationContext; import org.springframework.context.support.ClassPathXmlApplicationContext; @@ -498,8 +531,10 @@ declared on the `ConfigurableApplicationContext` interface, as the following exa } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.context.support.ClassPathXmlApplicationContext @@ -514,6 +549,7 @@ declared on the `ConfigurableApplicationContext` interface, as the following exa // main method exits, hook is called prior to the app shutting down... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc index 06eb5eba3f5f..6a835bebb2fb 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc @@ -247,8 +247,11 @@ When using annotation-driven components or Java configuration, the `@RequestScop can be used to assign a component to the `request` scope. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RequestScope @Component @@ -256,8 +259,10 @@ to do so: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RequestScope @Component @@ -265,6 +270,7 @@ to do so: // ... } ---- +====== @@ -291,8 +297,11 @@ HTTP `Session` is eventually discarded, the bean that is scoped to that particul When using annotation-driven components or Java configuration, you can use the `@SessionScope` annotation to assign a component to the `session` scope. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SessionScope @Component @@ -300,8 +309,10 @@ When using annotation-driven components or Java configuration, you can use the // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SessionScope @Component @@ -309,6 +320,7 @@ When using annotation-driven components or Java configuration, you can use the // ... } ---- +====== @@ -335,8 +347,11 @@ When using annotation-driven components or Java configuration, you can use the `@ApplicationScope` annotation to assign a component to the `application` scope. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ApplicationScope @Component @@ -344,8 +359,10 @@ following example shows how to do so: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ApplicationScope @Component @@ -353,6 +370,7 @@ following example shows how to do so: // ... } ---- +====== @@ -551,62 +569,86 @@ does not exist, the method returns a new instance of the bean, after having boun the session for future reference). The following method returns the object from the underlying scope: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Object get(String name, ObjectFactory objectFactory) ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun get(name: String, objectFactory: ObjectFactory<*>): Any ---- +====== The session scope implementation, for example, removes the session-scoped bean from the underlying session. The object should be returned, but you can return `null` if the object with the specified name is not found. The following method removes the object from the underlying scope: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Object remove(String name) ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun remove(name: String): Any ---- +====== The following method registers a callback that the scope should invoke when it is destroyed or when the specified object in the scope is destroyed: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- void registerDestructionCallback(String name, Runnable destructionCallback) ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun registerDestructionCallback(name: String, destructionCallback: Runnable) ---- +====== See the {api-spring-framework}/beans/factory/config/Scope.html#registerDestructionCallback[javadoc] or a Spring scope implementation for more information on destruction callbacks. The following method obtains the conversation identifier for the underlying scope: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- String getConversationId() ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun getConversationId(): String ---- +====== This identifier is different for each scope. For a session scoped implementation, this identifier can be the session identifier. @@ -620,16 +662,22 @@ After you write and test one or more custom `Scope` implementations, you need to the Spring container aware of your new scopes. The following method is the central method to register a new `Scope` with the Spring container: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- void registerScope(String scopeName, Scope scope); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun registerScope(scopeName: String, scope: Scope) ---- +====== This method is declared on the `ConfigurableBeanFactory` interface, which is available through the `BeanFactory` property on most of the concrete `ApplicationContext` @@ -647,18 +695,24 @@ NOTE: The next example uses `SimpleThreadScope`, which is included with Spring b registered by default. The instructions would be the same for your own custom `Scope` implementations. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Scope threadScope = new SimpleThreadScope(); beanFactory.registerScope("thread", threadScope); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val threadScope = SimpleThreadScope() beanFactory.registerScope("thread", threadScope) ---- +====== You can then create bean definitions that adhere to the scoping rules of your custom `Scope`, as follows: diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/basic-concepts.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/basic-concepts.adoc index 70236637f5a4..f90a2752b7ea 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/basic-concepts.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/basic-concepts.adoc @@ -15,8 +15,11 @@ source of bean definitions. Furthermore, `@Configuration` classes let inter-bean dependencies be defined by calling other `@Bean` methods in the same class. The simplest possible `@Configuration` class reads as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -27,8 +30,10 @@ The simplest possible `@Configuration` class reads as follows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -39,6 +44,7 @@ The simplest possible `@Configuration` class reads as follows: } } ---- +====== The preceding `AppConfig` class is equivalent to the following Spring `` XML: diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc index e39ad32d4712..52089db3c58d 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc @@ -21,8 +21,11 @@ method to register a bean definition within an `ApplicationContext` of the type specified as the method's return value. By default, the bean name is the same as the method name. The following example shows a `@Bean` method declaration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -33,8 +36,10 @@ the method name. The following example shows a `@Bean` method declaration: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -43,6 +48,7 @@ the method name. The following example shows a `@Bean` method declaration: fun transferService() = TransferServiceImpl() } ---- +====== The preceding configuration is exactly equivalent to the following Spring XML: @@ -65,8 +71,11 @@ transferService -> com.acme.TransferServiceImpl You can also use default methods to define beans. This allows composition of bean configurations by implementing interfaces with bean definitions on default methods. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public interface BaseConfig { @@ -81,12 +90,16 @@ configurations by implementing interfaces with bean definitions on default metho } ---- +====== You can also declare your `@Bean` method with an interface (or base class) return type, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -97,8 +110,10 @@ return type, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -109,6 +124,7 @@ return type, as the following example shows: } } ---- +====== However, this limits the visibility for advance type prediction to the specified interface type (`TransferService`). Then, with the full type (`TransferServiceImpl`) @@ -133,8 +149,11 @@ dependencies required to build that bean. For instance, if our `TransferService` requires an `AccountRepository`, we can materialize that dependency with a method parameter, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -145,8 +164,10 @@ parameter, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -157,6 +178,7 @@ parameter, as the following example shows: } } ---- +====== The resolution mechanism is pretty much identical to constructor-based dependency @@ -184,8 +206,11 @@ The `@Bean` annotation supports specifying arbitrary initialization and destruct callback methods, much like Spring XML's `init-method` and `destroy-method` attributes on the `bean` element, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class BeanOne { @@ -215,8 +240,10 @@ on the `bean` element, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class BeanOne { @@ -242,6 +269,7 @@ class AppConfig { fun beanTwo() = BeanTwo() } ---- +====== [NOTE] ===== @@ -258,22 +286,28 @@ for a `DataSource`, as it is known to be problematic on Jakarta EE application s The following example shows how to prevent an automatic destruction callback for a `DataSource`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Bean(destroyMethod = "") public DataSource dataSource() throws NamingException { return (DataSource) jndiTemplate.lookup("MyDS"); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Bean(destroyMethod = "") fun dataSource(): DataSource { return jndiTemplate.lookup("MyDS") as DataSource } ---- +====== Also, with `@Bean` methods, you typically use programmatic JNDI lookups, either by using Spring's `JndiTemplate` or `JndiLocatorDelegate` helpers or straight JNDI @@ -286,8 +320,11 @@ intend to refer to the provided resource here). In the case of `BeanOne` from the example above the preceding note, it would be equally valid to call the `init()` method directly during construction, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -302,8 +339,10 @@ method directly during construction, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -316,6 +355,7 @@ method directly during construction, as the following example shows: // ... } ---- +====== TIP: When you work directly in Java, you can do anything you like with your objects and do not always need to rely on the container lifecycle. @@ -336,8 +376,11 @@ xref:core/beans/factory-scopes.adoc[Bean Scopes] section. The default scope is `singleton`, but you can override this with the `@Scope` annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class MyConfiguration { @@ -349,8 +392,10 @@ as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class MyConfiguration { @@ -362,6 +407,7 @@ as the following example shows: } } ---- +====== [[beans-java-scoped-proxy]] === `@Scope` and `scoped-proxy` @@ -379,8 +425,11 @@ If you port the scoped proxy example from the XML reference documentation (see xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[scoped proxies]) to our `@Bean` using Java, it resembles the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // an HTTP Session-scoped bean exposed as a proxy @Bean @@ -397,8 +446,10 @@ it resembles the following: return service; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // an HTTP Session-scoped bean exposed as a proxy @Bean @@ -413,6 +464,7 @@ it resembles the following: } } ---- +====== [[beans-java-customizing-bean-naming]] == Customizing Bean Naming @@ -421,8 +473,11 @@ By default, configuration classes use a `@Bean` method's name as the name of the resulting bean. This functionality can be overridden, however, with the `name` attribute, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -433,8 +488,10 @@ as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -443,6 +500,7 @@ as the following example shows: fun thing() = Thing() } ---- +====== [[beans-java-bean-aliasing]] @@ -453,8 +511,11 @@ multiple names, otherwise known as bean aliasing. The `name` attribute of the `@ annotation accepts a String array for this purpose. The following example shows how to set a number of aliases for a bean: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -465,8 +526,10 @@ a number of aliases for a bean: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -477,6 +540,7 @@ a number of aliases for a bean: } } ---- +====== [[beans-java-bean-description]] @@ -489,8 +553,11 @@ To add a description to a `@Bean`, you can use the {api-spring-framework}/context/annotation/Description.html[`@Description`] annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -502,8 +569,10 @@ annotation, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -513,6 +582,7 @@ annotation, as the following example shows: fun thing() = Thing() } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc index 13b342fcab39..bb919b2af7e8 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc @@ -12,8 +12,11 @@ Much as the `` element is used within Spring XML files to aid in modula configurations, the `@Import` annotation allows for loading `@Bean` definitions from another configuration class, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class ConfigA { @@ -34,8 +37,10 @@ another configuration class, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class ConfigA { @@ -52,13 +57,17 @@ another configuration class, as the following example shows: fun b() = B() } ---- +====== Now, rather than needing to specify both `ConfigA.class` and `ConfigB.class` when instantiating the context, only `ConfigB` needs to be supplied explicitly, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static void main(String[] args) { ApplicationContext ctx = new AnnotationConfigApplicationContext(ConfigB.class); @@ -68,8 +77,10 @@ following example shows: B b = ctx.getBean(B.class); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -81,6 +92,7 @@ following example shows: val b = ctx.getBean() } ---- +====== This approach simplifies container instantiation, as only one class needs to be dealt with, rather than requiring you to remember a potentially large number of @@ -106,8 +118,11 @@ a `@Bean` method can have an arbitrary number of parameters that describe the be dependencies. Consider the following more real-world scenario with several `@Configuration` classes, each depending on beans declared in the others: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class ServiceConfig { @@ -144,8 +159,10 @@ classes, each depending on beans declared in the others: transferService.transfer(100.00, "A123", "C456"); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -185,6 +202,7 @@ classes, each depending on beans declared in the others: transferService.transfer(100.00, "A123", "C456") } ---- +====== There is another way to achieve the same result. Remember that `@Configuration` classes are @@ -207,8 +225,11 @@ work on the configuration class itself, since it is possible to create it as a b The following example shows how one bean can be autowired to another bean: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class ServiceConfig { @@ -254,8 +275,10 @@ The following example shows how one bean can be autowired to another bean: transferService.transfer(100.00, "A123", "C456"); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -297,6 +320,7 @@ The following example shows how one bean can be autowired to another bean: transferService.transfer(100.00, "A123", "C456") } ---- +====== TIP: Constructor injection in `@Configuration` classes is only supported as of Spring Framework 4.3. Note also that there is no need to specify `@Autowired` if the target @@ -318,8 +342,11 @@ In cases where this ambiguity is not acceptable and you wish to have direct navi from within your IDE from one `@Configuration` class to another, consider autowiring the configuration classes themselves. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class ServiceConfig { @@ -334,8 +361,10 @@ configuration classes themselves. The following example shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class ServiceConfig { @@ -350,14 +379,18 @@ class ServiceConfig { } } ---- +====== In the preceding situation, where `AccountRepository` is defined is completely explicit. However, `ServiceConfig` is now tightly coupled to `RepositoryConfig`. That is the tradeoff. This tight coupling can be somewhat mitigated by using interface-based or abstract class-based `@Configuration` classes. Consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class ServiceConfig { @@ -404,8 +437,10 @@ abstract class-based `@Configuration` classes. Consider the following example: transferService.transfer(100.00, "A123", "C456"); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -454,6 +489,7 @@ abstract class-based `@Configuration` classes. Consider the following example: transferService.transfer(100.00, "A123", "C456") } ---- +====== Now `ServiceConfig` is loosely coupled with respect to the concrete `DefaultRepositoryConfig`, and built-in IDE tooling is still useful: You can easily @@ -487,8 +523,11 @@ Implementations of the `Condition` interface provide a `matches(...)` method that returns `true` or `false`. For example, the following listing shows the actual `Condition` implementation used for `@Profile`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Override public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) { @@ -505,8 +544,10 @@ method that returns `true` or `false`. For example, the following listing shows return true; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- override fun matches(context: ConditionContext, metadata: AnnotatedTypeMetadata): Boolean { // Read the @Profile annotation attributes @@ -522,6 +563,7 @@ method that returns `true` or `false`. For example, the following listing shows return true } ---- +====== See the {api-spring-framework}/context/annotation/Conditional.html[`@Conditional`] javadoc for more detail. @@ -558,8 +600,11 @@ properly. The following example shows an ordinary configuration class in Java: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -578,8 +623,10 @@ The following example shows an ordinary configuration class in Java: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -596,6 +643,7 @@ The following example shows an ordinary configuration class in Java: fun transferService() = TransferService(accountRepository()) } ---- +====== The following example shows part of a sample `system-test-config.xml` file: @@ -625,8 +673,11 @@ jdbc.username=sa jdbc.password= ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static void main(String[] args) { ApplicationContext ctx = new ClassPathXmlApplicationContext("classpath:/com/acme/system-test-config.xml"); @@ -634,8 +685,10 @@ jdbc.password= // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun main() { val ctx = ClassPathXmlApplicationContext("classpath:/com/acme/system-test-config.xml") @@ -643,6 +696,7 @@ jdbc.password= // ... } ---- +====== NOTE: In `system-test-config.xml` file, the `AppConfig` `` does not declare an `id` @@ -691,8 +745,11 @@ that defines a bean, a properties file, and the `main` class) shows how to use the `@ImportResource` annotation to achieve "`Java-centric`" configuration that uses XML as needed: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ImportResource("classpath:/com/acme/properties-config.xml") @@ -713,8 +770,10 @@ as needed: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @ImportResource("classpath:/com/acme/properties-config.xml") @@ -735,6 +794,7 @@ as needed: } } ---- +====== [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -752,8 +812,11 @@ jdbc.username=sa jdbc.password= ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static void main(String[] args) { ApplicationContext ctx = new AnnotationConfigApplicationContext(AppConfig.class); @@ -761,8 +824,10 @@ jdbc.password= // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -772,6 +837,7 @@ jdbc.password= // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc index ccf861e92150..d265db7e7585 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc @@ -13,8 +13,11 @@ inter-bean dependencies. See xref:core/beans/java/basic-concepts.adoc[Basic Conc When beans have dependencies on one another, expressing that dependency is as simple as having one bean method call another, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -30,8 +33,10 @@ as having one bean method call another, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -43,6 +48,7 @@ as having one bean method call another, as the following example shows: fun beanTwo() = BeanTwo() } ---- +====== In the preceding example, `beanOne` receives a reference to `beanTwo` through constructor injection. @@ -62,8 +68,11 @@ singleton-scoped bean has a dependency on a prototype-scoped bean. Using Java fo type of configuration provides a natural means for implementing this pattern. The following example shows how to use lookup method injection: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public abstract class CommandManager { public Object process(Object commandState) { @@ -78,8 +87,10 @@ following example shows how to use lookup method injection: protected abstract Command createCommand(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- abstract class CommandManager { fun process(commandState: Any): Any { @@ -94,13 +105,17 @@ following example shows how to use lookup method injection: protected abstract fun createCommand(): Command } ---- +====== By using Java configuration, you can create a subclass of `CommandManager` where the abstract `createCommand()` method is overridden in such a way that it looks up a new (prototype) command object. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Bean @Scope("prototype") @@ -121,8 +136,10 @@ the abstract `createCommand()` method is overridden in such a way that it looks } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Bean @Scope("prototype") @@ -143,6 +160,7 @@ the abstract `createCommand()` method is overridden in such a way that it looks } } ---- +====== [[beans-java-further-information-java-config]] @@ -150,8 +168,11 @@ the abstract `createCommand()` method is overridden in such a way that it looks Consider the following example, which shows a `@Bean` annotated method being called twice: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -176,8 +197,10 @@ Consider the following example, which shows a `@Bean` annotated method being cal } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -202,6 +225,7 @@ Consider the following example, which shows a `@Bean` annotated method being cal } } ---- +====== `clientDao()` has been called once in `clientService1()` and once in `clientService2()`. Since this method creates a new instance of `ClientDaoImpl` and returns it, you would diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc index 1a082498c4cf..e9c98ea126a9 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc @@ -23,8 +23,11 @@ In much the same way that Spring XML files are used as input when instantiating instantiating an `AnnotationConfigApplicationContext`. This allows for completely XML-free usage of the Spring container, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static void main(String[] args) { ApplicationContext ctx = new AnnotationConfigApplicationContext(AppConfig.class); @@ -32,8 +35,10 @@ XML-free usage of the Spring container, as the following example shows: myService.doStuff(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -43,13 +48,17 @@ XML-free usage of the Spring container, as the following example shows: myService.doStuff() } ---- +====== As mentioned earlier, `AnnotationConfigApplicationContext` is not limited to working only with `@Configuration` classes. Any `@Component` or JSR-330 annotated class may be supplied as input to the constructor, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static void main(String[] args) { ApplicationContext ctx = new AnnotationConfigApplicationContext(MyServiceImpl.class, Dependency1.class, Dependency2.class); @@ -57,8 +66,10 @@ as input to the constructor, as the following example shows: myService.doStuff(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -68,6 +79,7 @@ as input to the constructor, as the following example shows: myService.doStuff() } ---- +====== The preceding example assumes that `MyServiceImpl`, `Dependency1`, and `Dependency2` use Spring dependency injection annotations such as `@Autowired`. @@ -81,8 +93,11 @@ and then configure it by using the `register()` method. This approach is particu when programmatically building an `AnnotationConfigApplicationContext`. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static void main(String[] args) { AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); @@ -93,8 +108,10 @@ example shows how to do so: myService.doStuff(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -107,6 +124,7 @@ example shows how to do so: myService.doStuff() } ---- +====== [[beans-java-instantiating-container-scan]] @@ -114,8 +132,11 @@ example shows how to do so: To enable component scanning, you can annotate your `@Configuration` class as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ComponentScan(basePackages = "com.acme") // <1> @@ -123,6 +144,7 @@ To enable component scanning, you can annotate your `@Configuration` class as fo // ... } ---- +====== <1> This annotation enables component scanning. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -156,8 +178,11 @@ definitions within the container. `AnnotationConfigApplicationContext` exposes t `scan(String...)` method to allow for the same component-scanning functionality, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public static void main(String[] args) { AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); @@ -166,8 +191,10 @@ following example shows: MyService myService = ctx.getBean(MyService.class); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun main() { val ctx = AnnotationConfigApplicationContext() @@ -176,6 +203,7 @@ following example shows: val myService = ctx.getBean() } ---- +====== NOTE: Remember that `@Configuration` classes are xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotated] with `@Component`, so they are candidates for component-scanning. In the preceding example, diff --git a/framework-docs/modules/ROOT/pages/core/beans/standard-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/standard-annotations.adoc index 77f58b4a694e..d9929bea3d03 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/standard-annotations.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/standard-annotations.adoc @@ -29,8 +29,11 @@ You can add the following dependency to your file pom.xml: Instead of `@Autowired`, you can use `@jakarta.inject.Inject` as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import jakarta.inject.Inject; @@ -49,8 +52,10 @@ Instead of `@Autowired`, you can use `@jakarta.inject.Inject` as follows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import jakarta.inject.Inject @@ -66,6 +71,7 @@ Instead of `@Autowired`, you can use `@jakarta.inject.Inject` as follows: } } ---- +====== As with `@Autowired`, you can use `@Inject` at the field level, method level and constructor-argument level. Furthermore, you may declare your injection point as a @@ -73,8 +79,11 @@ and constructor-argument level. Furthermore, you may declare your injection poin other beans through a `Provider.get()` call. The following example offers a variant of the preceding example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import jakarta.inject.Inject; import jakarta.inject.Provider; @@ -94,8 +103,10 @@ preceding example: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import jakarta.inject.Inject @@ -111,12 +122,16 @@ preceding example: } } ---- +====== If you would like to use a qualified name for the dependency that should be injected, you should use the `@Named` annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import jakarta.inject.Inject; import jakarta.inject.Named; @@ -133,8 +148,10 @@ you should use the `@Named` annotation, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import jakarta.inject.Inject import jakarta.inject.Named @@ -151,6 +168,7 @@ you should use the `@Named` annotation, as the following example shows: // ... } ---- +====== As with `@Autowired`, `@Inject` can also be used with `java.util.Optional` or `@Nullable`. This is even more applicable here, since `@Inject` does not have @@ -168,8 +186,11 @@ a `required` attribute. The following pair of examples show how to use `@Inject` } ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleMovieLister { @@ -179,8 +200,10 @@ a `required` attribute. The following pair of examples show how to use `@Inject` } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SimpleMovieLister { @@ -188,6 +211,7 @@ a `required` attribute. The following pair of examples show how to use `@Inject` var movieFinder: MovieFinder? = null } ---- +====== @@ -197,8 +221,11 @@ a `required` attribute. The following pair of examples show how to use `@Inject` Instead of `@Component`, you can use `@jakarta.inject.Named` or `jakarta.annotation.ManagedBean`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import jakarta.inject.Inject; import jakarta.inject.Named; @@ -216,8 +243,10 @@ as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import jakarta.inject.Inject import jakarta.inject.Named @@ -231,12 +260,16 @@ as the following example shows: // ... } ---- +====== It is very common to use `@Component` without specifying a name for the component. `@Named` can be used in a similar fashion, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import jakarta.inject.Inject; import jakarta.inject.Named; @@ -254,8 +287,10 @@ It is very common to use `@Component` without specifying a name for the componen // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import jakarta.inject.Inject import jakarta.inject.Named @@ -269,12 +304,16 @@ It is very common to use `@Component` without specifying a name for the componen // ... } ---- +====== When you use `@Named` or `@ManagedBean`, you can use component scanning in the exact same way as when you use Spring annotations, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ComponentScan(basePackages = "org.example") @@ -282,8 +321,10 @@ exact same way as when you use Spring annotations, as the following example show // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @ComponentScan(basePackages = ["org.example"]) @@ -291,6 +332,7 @@ exact same way as when you use Spring annotations, as the following example show // ... } ---- +====== NOTE: In contrast to `@Component`, the JSR-330 `@Named` and the JSR-250 `@ManagedBean` annotations are not composable. You should use Spring's stereotype model for building diff --git a/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc b/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc index 6991a5f30f68..a66ade956c27 100644 --- a/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc +++ b/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc @@ -140,8 +140,11 @@ An `Encoder` allocates data buffers that others must read (and release). So an ` doesn't have much to do. However an `Encoder` must take care to release a data buffer if a serialization error occurs while populating the buffer with data. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DataBuffer buffer = factory.allocateBuffer(); boolean release = true; @@ -156,8 +159,10 @@ a serialization error occurs while populating the buffer with data. For example: } return buffer; ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val buffer = factory.allocateBuffer() var release = true @@ -171,6 +176,7 @@ a serialization error occurs while populating the buffer with data. For example: } return buffer ---- +====== The consumer of an `Encoder` is responsible for releasing the data buffers it receives. In a WebFlux application, the output of the `Encoder` is used to write to the HTTP server diff --git a/framework-docs/modules/ROOT/pages/core/expressions/beandef.adoc b/framework-docs/modules/ROOT/pages/core/expressions/beandef.adoc index be689fb15760..7617ab15ef70 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/beandef.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/beandef.adoc @@ -67,8 +67,11 @@ and method or constructor parameters. The following example sets the default value of a field: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class FieldValueTestBean { @@ -84,8 +87,10 @@ The following example sets the default value of a field: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class FieldValueTestBean { @@ -93,11 +98,15 @@ The following example sets the default value of a field: var defaultLocale: String? = null } ---- +====== The following example shows the equivalent but on a property setter method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class PropertyValueTestBean { @@ -113,8 +122,10 @@ The following example shows the equivalent but on a property setter method: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class PropertyValueTestBean { @@ -122,12 +133,16 @@ The following example shows the equivalent but on a property setter method: var defaultLocale: String? = null } ---- +====== Autowired methods and constructors can also use the `@Value` annotation, as the following examples show: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleMovieLister { @@ -144,8 +159,10 @@ examples show: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SimpleMovieLister { @@ -162,9 +179,13 @@ examples show: // ... } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MovieRecommender { @@ -181,14 +202,17 @@ examples show: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MovieRecommender(private val customerPreferenceDao: CustomerPreferenceDao, @Value("#{systemProperties['user.country']}") private val defaultLocale: String) { // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc b/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc index 096714936b9f..79b3f260b915 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc @@ -8,13 +8,17 @@ xref:core/expressions/language-ref.adoc[Language Reference]. The following code introduces the SpEL API to evaluate the literal string expression, `Hello World`. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); Expression exp = parser.parseExpression("'Hello World'"); // <1> String message = (String) exp.getValue(); ---- +====== <1> The value of the message variable is `'Hello World'`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -42,13 +46,17 @@ and calling constructors. In the following example of method invocation, we call the `concat` method on the string literal: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); Expression exp = parser.parseExpression("'Hello World'.concat('!')"); // <1> String message = (String) exp.getValue(); ---- +====== <1> The value of `message` is now 'Hello World!'. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -62,8 +70,11 @@ In the following example of method invocation, we call the `concat` method on th The following example of calling a JavaBean property calls the `String` property `Bytes`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); @@ -71,6 +82,7 @@ The following example of calling a JavaBean property calls the `String` property Expression exp = parser.parseExpression("'Hello World'.bytes"); // <1> byte[] bytes = (byte[]) exp.getValue(); ---- +====== <1> This line converts the literal to a byte array. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -90,8 +102,11 @@ Public fields may also be accessed. The following example shows how to use dot notation to get the length of a literal: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); @@ -99,6 +114,7 @@ The following example shows how to use dot notation to get the length of a liter Expression exp = parser.parseExpression("'Hello World'.bytes.length"); // <1> int length = (Integer) exp.getValue(); ---- +====== <1> `'Hello World'.bytes.length` gives the length of the literal. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -115,13 +131,17 @@ The following example shows how to use dot notation to get the length of a liter The String's constructor can be called instead of using a string literal, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); Expression exp = parser.parseExpression("new String('hello world').toUpperCase()"); // <1> String message = exp.getValue(String.class); ---- +====== <1> Construct a new `String` from the literal and make it be upper case. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -144,8 +164,11 @@ against a specific object instance (called the root object). The following examp how to retrieve the `name` property from an instance of the `Inventor` class or create a boolean condition: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Create and set a calendar GregorianCalendar c = new GregorianCalendar(); @@ -164,8 +187,10 @@ create a boolean condition: boolean result = exp.getValue(tesla, Boolean.class); // result == true ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Create and set a calendar val c = GregorianCalendar() @@ -184,6 +209,7 @@ create a boolean condition: val result = exp.getValue(tesla, Boolean::class.java) // result == true ---- +====== @@ -232,8 +258,11 @@ to set a `List` property. The type of the property is actually `List`. recognizes that the elements of the list need to be converted to `Boolean` before being placed in it. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class Simple { public List booleanList = new ArrayList<>(); @@ -251,8 +280,10 @@ being placed in it. The following example shows how to do so: // b is false Boolean b = simple.booleanList.get(0); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class Simple { var booleanList: MutableList = ArrayList() @@ -270,6 +301,7 @@ being placed in it. The following example shows how to do so: // b is false val b = simple.booleanList[0] ---- +====== [[expressions-parser-configuration]] @@ -290,8 +322,11 @@ or custom converter that knows how to set the value, `null` will remain in the a list at the specified index. The following example demonstrates how to automatically grow the list: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class Demo { public List list; @@ -313,8 +348,10 @@ the list: // demo.list will now be a real collection of 4 entries // Each entry is a new empty String ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class Demo { var list: List? = null @@ -336,6 +373,7 @@ the list: // demo.list will now be a real collection of 4 entries // Each entry is a new empty String ---- +====== @@ -404,8 +442,11 @@ since part of the expression may be running twice. After selecting a mode, use the `SpelParserConfiguration` to configure the parser. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- SpelParserConfiguration config = new SpelParserConfiguration(SpelCompilerMode.IMMEDIATE, this.getClass().getClassLoader()); @@ -418,8 +459,10 @@ following example shows how to do so: Object payload = expr.getValue(message); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val config = SpelParserConfiguration(SpelCompilerMode.IMMEDIATE, this.javaClass.classLoader) @@ -432,6 +475,7 @@ following example shows how to do so: val payload = expr.getValue(message) ---- +====== When you specify the compiler mode, you can also specify a classloader (passing null is allowed). Compiled expressions are defined in a child classloader created under any that is supplied. diff --git a/framework-docs/modules/ROOT/pages/core/expressions/example-classes.adoc b/framework-docs/modules/ROOT/pages/core/expressions/example-classes.adoc index 475029a08fc3..e94e3b8c091c 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/example-classes.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/example-classes.adoc @@ -3,8 +3,11 @@ This section lists the classes used in the examples throughout this chapter. +[tabs] +====== +Inventor.Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Inventor.Java ---- package org.spring.samples.spel.inventor; @@ -76,8 +79,10 @@ This section lists the classes used in the examples throughout this chapter. } } ---- + +Inventor.kt:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Inventor.kt ---- package org.spring.samples.spel.inventor @@ -88,9 +93,13 @@ This section lists the classes used in the examples throughout this chapter. var birthdate: Date = GregorianCalendar().time, var placeOfBirth: PlaceOfBirth? = null) ---- +====== +[tabs] +====== +PlaceOfBirth.java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.PlaceOfBirth.java ---- package org.spring.samples.spel.inventor; @@ -125,16 +134,22 @@ This section lists the classes used in the examples throughout this chapter. } } ---- + +PlaceOfBirth.kt:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.PlaceOfBirth.kt ---- package org.spring.samples.spel.inventor class PlaceOfBirth(var city: String, var country: String? = null) { ---- +====== +[tabs] +====== +Society.java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Society.java ---- package org.spring.samples.spel.inventor; @@ -176,8 +191,10 @@ This section lists the classes used in the examples throughout this chapter. } } ---- + +Society.kt:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Society.kt ---- package org.spring.samples.spel.inventor @@ -203,3 +220,4 @@ This section lists the classes used in the examples throughout this chapter. } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/array-construction.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/array-construction.adoc index aa1e52bfe17b..01e181ae3017 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/array-construction.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/array-construction.adoc @@ -4,8 +4,11 @@ You can build arrays by using the familiar Java syntax, optionally supplying an initializer to have the array populated at construction time. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- int[] numbers1 = (int[]) parser.parseExpression("new int[4]").getValue(context); @@ -15,8 +18,10 @@ to have the array populated at construction time. The following example shows ho // Multi dimensional array int[][] numbers3 = (int[][]) parser.parseExpression("new int[4][5]").getValue(context); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val numbers1 = parser.parseExpression("new int[4]").getValue(context) as IntArray @@ -26,6 +31,7 @@ to have the array populated at construction time. The following example shows ho // Multi dimensional array val numbers3 = parser.parseExpression("new int[4][5]").getValue(context) as Array ---- +====== You cannot currently supply an initializer when you construct a multi-dimensional array. diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc index 4ea79cd6319d..82e68876b1f0 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc @@ -5,8 +5,11 @@ If the evaluation context has been configured with a bean resolver, you can look up beans from an expression by using the `@` symbol. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); StandardEvaluationContext context = new StandardEvaluationContext(); @@ -15,8 +18,10 @@ to do so: // This will end up calling resolve(context,"something") on MyBeanResolver during evaluation Object bean = parser.parseExpression("@something").getValue(context); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val parser = SpelExpressionParser() val context = StandardEvaluationContext() @@ -25,12 +30,16 @@ to do so: // This will end up calling resolve(context,"something") on MyBeanResolver during evaluation val bean = parser.parseExpression("@something").getValue(context) ---- +====== To access a factory bean itself, you should instead prefix the bean name with an `&` symbol. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); StandardEvaluationContext context = new StandardEvaluationContext(); @@ -39,8 +48,10 @@ The following example shows how to do so: // This will end up calling resolve(context,"&foo") on MyBeanResolver during evaluation Object bean = parser.parseExpression("&foo").getValue(context); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val parser = SpelExpressionParser() val context = StandardEvaluationContext() @@ -49,5 +60,6 @@ The following example shows how to do so: // This will end up calling resolve(context,"&foo") on MyBeanResolver during evaluation val bean = parser.parseExpression("&foo").getValue(context) ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-projection.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-projection.adoc index bf2f229d7724..83f492766dd0 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-projection.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-projection.adoc @@ -7,18 +7,24 @@ suppose we have a list of inventors but want the list of cities where they were Effectively, we want to evaluate 'placeOfBirth.city' for every entry in the inventor list. The following example uses projection to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // returns ['Smiljan', 'Idvor' ] List placesOfBirth = (List)parser.parseExpression("members.![placeOfBirth.city]"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // returns ['Smiljan', 'Idvor' ] val placesOfBirth = parser.parseExpression("members.![placeOfBirth.city]") as List<*> ---- +====== Projection is supported for arrays and anything that implements `java.lang.Iterable` or `java.util.Map`. When using a map to drive projection, the projection expression is diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-selection.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-selection.adoc index 90ade2b7c28b..3f87541a81cb 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-selection.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/collection-selection.adoc @@ -8,18 +8,24 @@ Selection uses a syntax of `.?[selectionExpression]`. It filters the collection returns a new collection that contains a subset of the original elements. For example, selection lets us easily get a list of Serbian inventors, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- List list = (List) parser.parseExpression( "members.?[nationality == 'Serbian']").getValue(societyContext); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val list = parser.parseExpression( "members.?[nationality == 'Serbian']").getValue(societyContext) as List ---- +====== Selection is supported for arrays and anything that implements `java.lang.Iterable` or `java.util.Map`. For a list or array, the selection criteria is evaluated against each @@ -30,16 +36,22 @@ accessible as properties for use in the selection. The following expression returns a new map that consists of those elements of the original map where the entry's value is less than 27: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Map newMap = parser.parseExpression("map.?[value<27]").getValue(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val newMap = parser.parseExpression("map.?[value<27]").getValue() ---- +====== In addition to returning all the selected elements, you can retrieve only the first or the last element. To obtain the first element matching the selection, the syntax is diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/constructors.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/constructors.adoc index c99e0aada50e..a35513c9c1ec 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/constructors.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/constructors.adoc @@ -6,8 +6,11 @@ qualified class name for all types except those located in the `java.lang` packa (`Integer`, `Float`, `String`, and so on). The following example shows how to use the `new` operator to invoke constructors: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Inventor einstein = p.parseExpression( "new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German')") @@ -18,8 +21,10 @@ qualified class name for all types except those located in the `java.lang` packa "Members.add(new org.spring.samples.spel.inventor.Inventor( 'Albert Einstein', 'German'))").getValue(societyContext); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val einstein = p.parseExpression( "new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German')") @@ -30,6 +35,7 @@ qualified class name for all types except those located in the `java.lang` packa "Members.add(new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German'))") .getValue(societyContext) ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/functions.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/functions.adoc index db24cf801fa0..014d6e8b8c44 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/functions.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/functions.adoc @@ -5,27 +5,36 @@ You can extend SpEL by registering user-defined functions that can be called wit expression string. The function is registered through the `EvaluationContext`. The following example shows how to register a user-defined function: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Method method = ...; EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); context.setVariable("myFunction", method); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val method: Method = ... val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() context.setVariable("myFunction", method) ---- +====== For example, consider the following utility method that reverses a string: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public abstract class StringUtils { @@ -38,8 +47,10 @@ For example, consider the following utility method that reverses a string: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun reverseString(input: String): String { val backwards = StringBuilder(input.length) @@ -49,11 +60,15 @@ For example, consider the following utility method that reverses a string: return backwards.toString() } ---- +====== You can then register and use the preceding method, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); @@ -64,8 +79,10 @@ You can then register and use the preceding method, as the following example sho String helloWorldReversed = parser.parseExpression( "#reverseString('hello')").getValue(context, String.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val parser = SpelExpressionParser() @@ -75,6 +92,7 @@ You can then register and use the preceding method, as the following example sho val helloWorldReversed = parser.parseExpression( "#reverseString('hello')").getValue(context, String::class.java) ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-lists.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-lists.adoc index 0d23b7695c11..463d54d80955 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-lists.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-lists.adoc @@ -3,22 +3,28 @@ You can directly express lists in an expression by using `{}` notation. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // evaluates to a Java list containing the four numbers List numbers = (List) parser.parseExpression("{1,2,3,4}").getValue(context); List listOfLists = (List) parser.parseExpression("{{'a','b'},{'x','y'}}").getValue(context); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // evaluates to a Java list containing the four numbers val numbers = parser.parseExpression("{1,2,3,4}").getValue(context) as List<*> val listOfLists = parser.parseExpression("{{'a','b'},{'x','y'}}").getValue(context) as List<*> ---- +====== `{}` by itself means an empty list. For performance reasons, if the list is itself entirely composed of fixed literals, a constant list is created to represent the diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-maps.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-maps.adoc index f20b26981939..2b972329cd8b 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-maps.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/inline-maps.adoc @@ -4,22 +4,28 @@ You can also directly express maps in an expression by using `{key:value}` notation. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // evaluates to a Java map containing the two entries Map inventorInfo = (Map) parser.parseExpression("{name:'Nikola',dob:'10-July-1856'}").getValue(context); Map mapOfMaps = (Map) parser.parseExpression("{name:{first:'Nikola',last:'Tesla'},dob:{day:10,month:'July',year:1856}}").getValue(context); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- // evaluates to a Java map containing the two entries val inventorInfo = parser.parseExpression("{name:'Nikola',dob:'10-July-1856'}").getValue(context) as Map<*, *> val mapOfMaps = parser.parseExpression("{name:{first:'Nikola',last:'Tesla'},dob:{day:10,month:'July',year:1856}}").getValue(context) as Map<*, *> ---- +====== `{:}` by itself means an empty map. For performance reasons, if the map is itself composed of fixed literals or other nested constant structures (lists or maps), a diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/literal.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/literal.adoc index 077f53aa0733..c133af0f367a 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/literal.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/literal.adoc @@ -23,8 +23,11 @@ isolation like this but, rather, as part of a more complex expression -- for exa using a literal on one side of a logical comparison operator or as an argument to a method. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); @@ -43,8 +46,10 @@ method. Object nullValue = parser.parseExpression("null").getValue(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val parser = SpelExpressionParser() @@ -63,6 +68,7 @@ method. val nullValue = parser.parseExpression("null").value ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/methods.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/methods.adoc index 149d6a125770..46c91b836254 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/methods.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/methods.adoc @@ -5,8 +5,11 @@ You can invoke methods by using typical Java programming syntax. You can also in on literals. Variable arguments are also supported. The following examples show how to invoke methods: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // string literal, evaluates to "bc" String bc = parser.parseExpression("'abc'.substring(1, 3)").getValue(String.class); @@ -15,8 +18,10 @@ invoke methods: boolean isMember = parser.parseExpression("isMember('Mihajlo Pupin')").getValue( societyContext, Boolean.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // string literal, evaluates to "bc" val bc = parser.parseExpression("'abc'.substring(1, 3)").getValue(String::class.java) @@ -25,5 +30,6 @@ invoke methods: val isMember = parser.parseExpression("isMember('Mihajlo Pupin')").getValue( societyContext, Boolean::class.java) ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-elvis.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-elvis.adoc index 199f131612e9..8f7e69a0b6cb 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-elvis.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-elvis.adoc @@ -15,27 +15,36 @@ following example shows: Instead, you can use the Elvis operator (named for the resemblance to Elvis' hair style). The following example shows how to use the Elvis operator: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); String name = parser.parseExpression("name?:'Unknown'").getValue(new Inventor(), String.class); System.out.println(name); // 'Unknown' ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val parser = SpelExpressionParser() val name = parser.parseExpression("name?:'Unknown'").getValue(Inventor(), String::class.java) println(name) // 'Unknown' ---- +====== The following listing shows a more complex example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); @@ -48,8 +57,10 @@ The following listing shows a more complex example: name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String.class); System.out.println(name); // Elvis Presley ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val parser = SpelExpressionParser() val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() @@ -62,6 +73,7 @@ The following listing shows a more complex example: name = parser.parseExpression("name?:'Elvis Presley'").getValue(context, tesla, String::class.java) println(name) // Elvis Presley ---- +====== [NOTE] ===== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-safe-navigation.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-safe-navigation.adoc index 1398af00d0a0..0691cf2de87a 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-safe-navigation.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-safe-navigation.adoc @@ -8,8 +8,11 @@ it is not null before accessing methods or properties of the object. To avoid th safe navigation operator returns null instead of throwing an exception. The following example shows how to use the safe navigation operator: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); @@ -24,8 +27,10 @@ example shows how to use the safe navigation operator: city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String.class); System.out.println(city); // null - does not throw NullPointerException!!! ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val parser = SpelExpressionParser() val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() @@ -40,6 +45,7 @@ example shows how to use the safe navigation operator: city = parser.parseExpression("placeOfBirth?.city").getValue(context, tesla, String::class.java) println(city) // null - does not throw NullPointerException!!! ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-ternary.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-ternary.adoc index e843a1f582f0..0a834d195fd6 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-ternary.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-ternary.adoc @@ -4,24 +4,33 @@ You can use the ternary operator for performing if-then-else conditional logic inside the expression. The following listing shows a minimal example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- String falseString = parser.parseExpression( "false ? 'trueExp' : 'falseExp'").getValue(String.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val falseString = parser.parseExpression( "false ? 'trueExp' : 'falseExp'").getValue(String::class.java) ---- +====== In this case, the boolean `false` results in returning the string value `'falseExp'`. A more realistic example follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- parser.parseExpression("name").setValue(societyContext, "IEEE"); societyContext.setVariable("queryName", "Nikola Tesla"); @@ -33,8 +42,10 @@ realistic example follows: .getValue(societyContext, String.class); // queryResultString = "Nikola Tesla is a member of the IEEE Society" ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- parser.parseExpression("name").setValue(societyContext, "IEEE") societyContext.setVariable("queryName", "Nikola Tesla") @@ -45,6 +56,7 @@ realistic example follows: .getValue(societyContext, String::class.java) // queryResultString = "Nikola Tesla is a member of the IEEE Society" ---- +====== See the next section on the Elvis operator for an even shorter syntax for the ternary operator. diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc index 240073f7daab..7d9d6ece8e4e 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc @@ -17,8 +17,11 @@ and greater than or equal) are supported by using standard operator notation. These operators work on `Number` types as well as types implementing `Comparable`. The following listing shows a few examples of operators: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // evaluates to true boolean trueValue = parser.parseExpression("2 == 2").getValue(Boolean.class); @@ -32,8 +35,10 @@ The following listing shows a few examples of operators: // uses CustomValue:::compareTo boolean trueValue = parser.parseExpression("new CustomValue(1) < new CustomValue(2)").getValue(Boolean.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // evaluates to true val trueValue = parser.parseExpression("2 == 2").getValue(Boolean::class.java) @@ -47,6 +52,7 @@ The following listing shows a few examples of operators: // uses CustomValue:::compareTo val trueValue = parser.parseExpression("new CustomValue(1) < new CustomValue(2)").getValue(Boolean::class.java); ---- +====== [NOTE] ==== @@ -62,8 +68,11 @@ in favor of comparisons against zero (for example, `X > 0` or `X < 0`). In addition to the standard relational operators, SpEL supports the `instanceof` and regular expression-based `matches` operator. The following listing shows examples of both: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // evaluates to false boolean falseValue = parser.parseExpression( @@ -77,8 +86,10 @@ expression-based `matches` operator. The following listing shows examples of bot boolean falseValue = parser.parseExpression( "'5.0067' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // evaluates to false val falseValue = parser.parseExpression( @@ -92,6 +103,7 @@ expression-based `matches` operator. The following listing shows examples of bot val falseValue = parser.parseExpression( "'5.0067' matches '^-?\\d+(\\.\\d{2})?$'").getValue(Boolean::class.java) ---- +====== CAUTION: Be careful with primitive types, as they are immediately boxed up to their wrapper types. For example, `1 instanceof T(int)` evaluates to `false`, while @@ -125,8 +137,11 @@ SpEL supports the following logical operators: The following example shows how to use the logical operators: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // -- AND -- @@ -155,8 +170,10 @@ The following example shows how to use the logical operators: String expression = "isMember('Nikola Tesla') and !isMember('Mihajlo Pupin')"; boolean falseValue = parser.parseExpression(expression).getValue(societyContext, Boolean.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // -- AND -- @@ -185,6 +202,7 @@ The following example shows how to use the logical operators: val expression = "isMember('Nikola Tesla') and !isMember('Mihajlo Pupin')" val falseValue = parser.parseExpression(expression).getValue(societyContext, Boolean::class.java) ---- +====== [[expressions-operators-mathematical]] @@ -196,8 +214,11 @@ You can also use the modulus (`%`) and exponential power (`^`) operators on numb Standard operator precedence is enforced. The following example shows the mathematical operators in use: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Addition int two = parser.parseExpression("1 + 1").getValue(Integer.class); // 2 @@ -228,8 +249,10 @@ operators in use: // Operator precedence int minusTwentyOne = parser.parseExpression("1+2-3*8").getValue(Integer.class); // -21 ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Addition val two = parser.parseExpression("1 + 1").getValue(Int::class.java) // 2 @@ -260,6 +283,7 @@ operators in use: // Operator precedence val minusTwentyOne = parser.parseExpression("1+2-3*8").getValue(Int::class.java) // -21 ---- +====== [[expressions-assignment]] @@ -269,8 +293,11 @@ To set a property, use the assignment operator (`=`). This is typically done wit call to `setValue` but can also be done inside a call to `getValue`. The following listing shows both ways to use the assignment operator: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Inventor inventor = new Inventor(); EvaluationContext context = SimpleEvaluationContext.forReadWriteDataBinding().build(); @@ -281,8 +308,10 @@ listing shows both ways to use the assignment operator: String aleks = parser.parseExpression( "name = 'Aleksandar Seovic'").getValue(context, inventor, String.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val inventor = Inventor() val context = SimpleEvaluationContext.forReadWriteDataBinding().build() @@ -293,5 +322,6 @@ listing shows both ways to use the assignment operator: val aleks = parser.parseExpression( "name = 'Aleksandar Seovic'").getValue(context, inventor, String::class.java) ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc index bc717138aefe..3066b54dec7b 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc @@ -7,22 +7,28 @@ populated with data listed in the xref:core/expressions/example-classes.adoc[Cla section. To navigate "down" the object graph and get Tesla's year of birth and Pupin's city of birth, we use the following expressions: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // evaluates to 1856 int year = (Integer) parser.parseExpression("birthdate.year + 1900").getValue(context); String city = (String) parser.parseExpression("placeOfBirth.city").getValue(context); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // evaluates to 1856 val year = parser.parseExpression("birthdate.year + 1900").getValue(context) as Int val city = parser.parseExpression("placeOfBirth.city").getValue(context) as String ---- +====== [NOTE] ==== @@ -36,8 +42,11 @@ method invocations -- for example, `getPlaceOfBirth().getCity()` instead of The contents of arrays and lists are obtained by using square bracket notation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ExpressionParser parser = new SpelExpressionParser(); EvaluationContext context = SimpleEvaluationContext.forReadOnlyDataBinding().build(); @@ -59,8 +68,10 @@ following example shows: String invention = parser.parseExpression("members[0].inventions[6]").getValue( context, ieee, String.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val parser = SpelExpressionParser() val context = SimpleEvaluationContext.forReadOnlyDataBinding().build() @@ -82,13 +93,17 @@ following example shows: val invention = parser.parseExpression("members[0].inventions[6]").getValue( context, ieee, String::class.java) ---- +====== The contents of maps are obtained by specifying the literal key value within the brackets. In the following example, because keys for the `officers` map are strings, we can specify string literals: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Officer's Dictionary @@ -103,8 +118,10 @@ string literals: parser.parseExpression("officers['advisors'][0].placeOfBirth.country").setValue( societyContext, "Croatia"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Officer's Dictionary @@ -119,6 +136,7 @@ string literals: parser.parseExpression("officers['advisors'][0].placeOfBirth.country").setValue( societyContext, "Croatia") ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/templating.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/templating.adoc index 6c521a8f0dc1..2b4a02d24f41 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/templating.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/templating.adoc @@ -6,8 +6,11 @@ Each evaluation block is delimited with prefix and suffix characters that you ca define. A common choice is to use `#{ }` as the delimiters, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- String randomPhrase = parser.parseExpression( "random number is #{T(java.lang.Math).random()}", @@ -15,8 +18,10 @@ shows: // evaluates to "random number is 0.7038186818312008" ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val randomPhrase = parser.parseExpression( "random number is #{T(java.lang.Math).random()}", @@ -24,6 +29,7 @@ shows: // evaluates to "random number is 0.7038186818312008" ---- +====== The string is evaluated by concatenating the literal text `'random number is '` with the result of evaluating the expression inside the `#{ }` delimiter (in this case, the result @@ -32,8 +38,11 @@ is of the type `ParserContext`. The `ParserContext` interface is used to influen the expression is parsed in order to support the expression templating functionality. The definition of `TemplateParserContext` follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class TemplateParserContext implements ParserContext { @@ -50,8 +59,10 @@ The definition of `TemplateParserContext` follows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class TemplateParserContext : ParserContext { @@ -68,5 +79,6 @@ The definition of `TemplateParserContext` follows: } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/types.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/types.adoc index b74d96c606e7..df4d9cc3e0c7 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/types.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/types.adoc @@ -9,8 +9,11 @@ type). Static methods are invoked by using this operator as well. The package do not need to be fully qualified, but all other type references must be. The following example shows how to use the `T` operator: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Class dateClass = parser.parseExpression("T(java.util.Date)").getValue(Class.class); @@ -20,8 +23,10 @@ following example shows how to use the `T` operator: "T(java.math.RoundingMode).CEILING < T(java.math.RoundingMode).FLOOR") .getValue(Boolean.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val dateClass = parser.parseExpression("T(java.util.Date)").getValue(Class::class.java) @@ -31,6 +36,7 @@ following example shows how to use the `T` operator: "T(java.math.RoundingMode).CEILING < T(java.math.RoundingMode).FLOOR") .getValue(Boolean::class.java) ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/variables.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/variables.adoc index c3e88e624087..6f7ac6e971e9 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/variables.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/variables.adoc @@ -17,8 +17,11 @@ characters. The following example shows how to use variables. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Inventor tesla = new Inventor("Nikola Tesla", "Serbian"); @@ -28,8 +31,10 @@ The following example shows how to use variables. parser.parseExpression("name = #newName").getValue(context, tesla); System.out.println(tesla.getName()) // "Mike Tesla" ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val tesla = Inventor("Nikola Tesla", "Serbian") @@ -39,6 +44,7 @@ The following example shows how to use variables. parser.parseExpression("name = #newName").getValue(context, tesla) println(tesla.name) // "Mike Tesla" ---- +====== [[expressions-this-root]] @@ -50,8 +56,11 @@ defined and refers to the root context object. Although `#this` may vary as comp an expression are evaluated, `#root` always refers to the root. The following examples show how to use the `#this` and `#root` variables: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // create an array of integers List primes = new ArrayList<>(); @@ -67,8 +76,10 @@ show how to use the `#this` and `#root` variables: List primesGreaterThanTen = (List) parser.parseExpression( "#primes.?[#this>10]").getValue(context); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // create an array of integers val primes = ArrayList() @@ -84,6 +95,7 @@ show how to use the `#this` and `#root` variables: val primesGreaterThanTen = parser.parseExpression( "#primes.?[#this>10]").getValue(context) as List ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/resources.adoc b/framework-docs/modules/ROOT/pages/core/resources.adoc index d645fcca280d..3bfc74aeb33f 100644 --- a/framework-docs/modules/ROOT/pages/core/resources.adoc +++ b/framework-docs/modules/ROOT/pages/core/resources.adoc @@ -276,16 +276,22 @@ specified doesn't have a specific prefix, you get back a `Resource` type that is appropriate to that particular application context. For example, assume the following snippet of code was run against a `ClassPathXmlApplicationContext` instance: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Resource template = ctx.getResource("some/resource/path/myTemplate.txt"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val template = ctx.getResource("some/resource/path/myTemplate.txt") ---- +====== Against a `ClassPathXmlApplicationContext`, that code returns a `ClassPathResource`. If the same method were run against a `FileSystemXmlApplicationContext` instance, it would @@ -299,41 +305,59 @@ On the other hand, you may also force `ClassPathResource` to be used, regardless application context type, by specifying the special `classpath:` prefix, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Resource template = ctx.getResource("classpath:some/resource/path/myTemplate.txt"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val template = ctx.getResource("classpath:some/resource/path/myTemplate.txt") ---- +====== Similarly, you can force a `UrlResource` to be used by specifying any of the standard `java.net.URL` prefixes. The following examples use the `file` and `https` prefixes: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Resource template = ctx.getResource("file:///some/resource/path/myTemplate.txt"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val template = ctx.getResource("file:///some/resource/path/myTemplate.txt") ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Resource template = ctx.getResource("https://myhost.com/resource/path/myTemplate.txt"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val template = ctx.getResource("https://myhost.com/resource/path/myTemplate.txt") ---- +====== The following table summarizes the strategy for converting `String` objects to `Resource` objects: @@ -477,8 +501,11 @@ register and use a special JavaBeans `PropertyEditor`, which can convert `String to `Resource` objects. For example, the following `MyBean` class has a `template` property of type `Resource`. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- package example; @@ -493,11 +520,14 @@ property of type `Resource`. // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyBean(var template: Resource) ---- +====== In an XML configuration file, the `template` property can be configured with a simple string for that resource, as the following example shows: @@ -537,8 +567,11 @@ retrieve the value of the template path as a string, and a special `PropertyEdit convert the string to a `Resource` object to be injected into the `MyBean` constructor. The following example demonstrates how to achieve this. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class MyBean { @@ -552,12 +585,15 @@ The following example demonstrates how to achieve this. // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class MyBean(@Value("\${template.path}") private val template: Resource) ---- +====== If we want to support multiple templates discovered under the same path in multiple locations in the classpath -- for example, in multiple jars in the classpath -- we can @@ -566,8 +602,11 @@ use the special `classpath*:` prefix and wildcarding to define a `templates.path Spring will convert the template path pattern into an array of `Resource` objects that can be injected into the `MyBean` constructor. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class MyBean { @@ -581,12 +620,15 @@ can be injected into the `MyBean` constructor. // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class MyBean(@Value("\${templates.path}") private val templates: Resource[]) ---- +====== @@ -611,31 +653,43 @@ that path and used to load the bean definitions depends on and is appropriate to specific application context. For example, consider the following example, which creates a `ClassPathXmlApplicationContext`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext ctx = new ClassPathXmlApplicationContext("conf/appContext.xml"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = ClassPathXmlApplicationContext("conf/appContext.xml") ---- +====== The bean definitions are loaded from the classpath, because a `ClassPathResource` is used. However, consider the following example, which creates a `FileSystemXmlApplicationContext`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext ctx = new FileSystemXmlApplicationContext("conf/appContext.xml"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = FileSystemXmlApplicationContext("conf/appContext.xml") ---- +====== Now the bean definitions are loaded from a filesystem location (in this case, relative to the current working directory). @@ -644,17 +698,23 @@ Note that the use of the special `classpath` prefix or a standard URL prefix on location path overrides the default type of `Resource` created to load the bean definitions. Consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext ctx = new FileSystemXmlApplicationContext("classpath:conf/appContext.xml"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = FileSystemXmlApplicationContext("classpath:conf/appContext.xml") ---- +====== Using `FileSystemXmlApplicationContext` loads the bean definitions from the classpath. However, it is still a `FileSystemXmlApplicationContext`. If it is subsequently used as a @@ -685,17 +745,23 @@ The following example shows how a `ClassPathXmlApplicationContext` instance comp the beans defined in files named `services.xml` and `repositories.xml` (which are on the classpath) can be instantiated: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext ctx = new ClassPathXmlApplicationContext( new String[] {"services.xml", "repositories.xml"}, MessengerService.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = ClassPathXmlApplicationContext(arrayOf("services.xml", "repositories.xml"), MessengerService::class.java) ---- +====== See the {api-spring-framework}/context/support/ClassPathXmlApplicationContext.html[`ClassPathXmlApplicationContext`] javadoc for details on the various constructors. @@ -773,17 +839,23 @@ coming from jars be thoroughly tested in your specific environment before you re When constructing an XML-based application context, a location string may use the special `classpath*:` prefix, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext ctx = new ClassPathXmlApplicationContext("classpath*:conf/appContext.xml"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = ClassPathXmlApplicationContext("classpath*:conf/appContext.xml") ---- +====== This special prefix specifies that all classpath resources that match the given name must be obtained (internally, this essentially happens through a call to @@ -879,87 +951,123 @@ For backwards compatibility (historical) reasons however, this changes when the to treat all location paths as relative, whether they start with a leading slash or not. In practice, this means the following examples are equivalent: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext ctx = new FileSystemXmlApplicationContext("conf/context.xml"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = FileSystemXmlApplicationContext("conf/context.xml") ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext ctx = new FileSystemXmlApplicationContext("/conf/context.xml"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx = FileSystemXmlApplicationContext("/conf/context.xml") ---- +====== The following examples are also equivalent (even though it would make sense for them to be different, as one case is relative and the other absolute): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- FileSystemXmlApplicationContext ctx = ...; ctx.getResource("some/resource/path/myTemplate.txt"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx: FileSystemXmlApplicationContext = ... ctx.getResource("some/resource/path/myTemplate.txt") ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- FileSystemXmlApplicationContext ctx = ...; ctx.getResource("/some/resource/path/myTemplate.txt"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ctx: FileSystemXmlApplicationContext = ... ctx.getResource("/some/resource/path/myTemplate.txt") ---- +====== In practice, if you need true absolute filesystem paths, you should avoid using absolute paths with `FileSystemResource` or `FileSystemXmlApplicationContext` and force the use of a `UrlResource` by using the `file:` URL prefix. The following examples show how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // actual context type doesn't matter, the Resource will always be UrlResource ctx.getResource("file:///some/resource/path/myTemplate.txt"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // actual context type doesn't matter, the Resource will always be UrlResource ctx.getResource("file:///some/resource/path/myTemplate.txt") ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // force this FileSystemXmlApplicationContext to load its definition via a UrlResource ApplicationContext ctx = new FileSystemXmlApplicationContext("file:///conf/context.xml"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // force this FileSystemXmlApplicationContext to load its definition via a UrlResource val ctx = FileSystemXmlApplicationContext("file:///conf/context.xml") ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/spring-jcl.adoc b/framework-docs/modules/ROOT/pages/core/spring-jcl.adoc index fee802ed1834..768af0c34345 100644 --- a/framework-docs/modules/ROOT/pages/core/spring-jcl.adoc +++ b/framework-docs/modules/ROOT/pages/core/spring-jcl.adoc @@ -23,19 +23,25 @@ For logging needs within application code, prefer direct use of Log4j 2.x, SLF4J A `Log` implementation may be retrieved via `org.apache.commons.logging.LogFactory` as in the following example. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyBean { private final Log log = LogFactory.getLog(getClass()); // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyBean { private val log = LogFactory.getLog(javaClass) // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc b/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc index c22f3c6ff63f..db58aaa11e3b 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc @@ -62,8 +62,11 @@ xref:core/validation/beans-beans.adoc#beans-beans-conversion[section on `Propert The following two example classes use the `BeanWrapper` to get and set properties: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class Company { @@ -87,17 +90,23 @@ properties: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class Company { var name: String? = null var managingDirector: Employee? = null } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class Employee { @@ -122,20 +131,26 @@ properties: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class Employee { var name: String? = null var salary: Float? = null } ---- +====== The following code snippets show some examples of how to retrieve and manipulate some of the properties of instantiated ``Company``s and ``Employee``s: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- BeanWrapper company = new BeanWrapperImpl(new Company()); // setting the company name.. @@ -152,8 +167,10 @@ the properties of instantiated ``Company``s and ``Employee``s: // retrieving the salary of the managingDirector through the company Float salary = (Float) company.getPropertyValue("managingDirector.salary"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val company = BeanWrapperImpl(Company()) // setting the company name.. @@ -170,6 +187,7 @@ the properties of instantiated ``Company``s and ``Employee``s: // retrieving the salary of the managingDirector through the company val salary = company.getPropertyValue("managingDirector.salary") as Float? ---- +====== @@ -308,8 +326,11 @@ com The following Java source code for the referenced `SomethingBeanInfo` class associates a `CustomNumberEditor` with the `age` property of the `Something` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SomethingBeanInfo extends SimpleBeanInfo { @@ -330,8 +351,10 @@ associates a `CustomNumberEditor` with the `age` property of the `Something` cla } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SomethingBeanInfo : SimpleBeanInfo() { @@ -351,6 +374,7 @@ associates a `CustomNumberEditor` with the `age` property of the `Something` cla } } ---- +====== [[beans-beans-conversion-customeditor-registration]] @@ -390,8 +414,11 @@ support for additional `PropertyEditor` instances to an `ApplicationContext`. Consider the following example, which defines a user class called `ExoticType` and another class called `DependsOnExoticType`, which needs `ExoticType` set as a property: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package example; @@ -413,8 +440,10 @@ another class called `DependsOnExoticType`, which needs `ExoticType` set as a pr } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package example @@ -425,6 +454,7 @@ another class called `DependsOnExoticType`, which needs `ExoticType` set as a pr var type: ExoticType? = null } ---- +====== When things are properly set up, we want to be able to assign the type property as a string, which a `PropertyEditor` converts into an actual @@ -439,8 +469,11 @@ string, which a `PropertyEditor` converts into an actual The `PropertyEditor` implementation could look similar to the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package example; @@ -454,8 +487,10 @@ The `PropertyEditor` implementation could look similar to the following: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package example @@ -469,6 +504,7 @@ The `PropertyEditor` implementation could look similar to the following: } } ---- +====== Finally, the following example shows how to use `CustomEditorConfigurer` to register the new `PropertyEditor` with the `ApplicationContext`, which will then be able to use it as needed: @@ -504,8 +540,11 @@ instances for each bean creation attempt. The following example shows how to create your own `PropertyEditorRegistrar` implementation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package com.foo.editors.spring; @@ -520,8 +559,10 @@ The following example shows how to create your own `PropertyEditorRegistrar` imp } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package com.foo.editors.spring @@ -539,6 +580,7 @@ The following example shows how to create your own `PropertyEditorRegistrar` imp } } ---- +====== See also the `org.springframework.beans.support.ResourceEditorRegistrar` for an example `PropertyEditorRegistrar` implementation. Notice how in its implementation of the @@ -566,8 +608,11 @@ using xref:web/webmvc.adoc#mvc[Spring's MVC web framework], using a `PropertyEdi conjunction with data-binding web controllers can be very convenient. The following example uses a `PropertyEditorRegistrar` in the implementation of an `@InitBinder` method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class RegisterUserController { @@ -586,8 +631,10 @@ example uses a `PropertyEditorRegistrar` in the implementation of an `@InitBinde // other methods related to registering a User } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller class RegisterUserController( @@ -601,6 +648,7 @@ example uses a `PropertyEditorRegistrar` in the implementation of an `@InitBinde // other methods related to registering a User } ---- +====== This style of `PropertyEditor` registration can lead to concise code (the implementation of the `@InitBinder` method is only one line long) and lets common `PropertyEditor` diff --git a/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc b/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc index 46b410824ff6..3837d50a355c 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc @@ -16,27 +16,36 @@ built-in constraints, and you can also define your own custom constraints. Consider the following example, which shows a simple `PersonForm` model with two properties: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class PersonForm { private String name; private int age; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class PersonForm( private val name: String, private val age: Int ) ---- +====== Bean Validation lets you declare constraints as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class PersonForm { @@ -48,8 +57,10 @@ Bean Validation lets you declare constraints as the following example shows: private int age; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class PersonForm( @get:NotNull @get:Size(max=64) @@ -58,6 +69,7 @@ Bean Validation lets you declare constraints as the following example shows: private val age: Int ) ---- +====== A Bean Validation validator then validates instances of this class based on the declared constraints. See https://beanvalidation.org/[Bean Validation] for general information about @@ -78,8 +90,11 @@ is needed in your application. You can use the `LocalValidatorFactoryBean` to configure a default Validator as a Spring bean, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import org.springframework.validation.beanvalidation.LocalValidatorFactoryBean; @@ -92,12 +107,15 @@ bean, as the following example shows: } } ---- + +XML:: ++ [source,xml,indent=0,subs="verbatim,quotes",role="secondary"] -.XML ---- ---- +====== The basic configuration in the preceding example triggers bean validation to initialize by using its default bootstrap mechanism. A Bean Validation provider, such as the Hibernate @@ -115,8 +133,11 @@ validation logic. You can inject a reference to `jakarta.validation.Validator` if you prefer to work with the Bean Validation API directly, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import jakarta.validation.Validator; @@ -127,20 +148,26 @@ Validation API directly, as the following example shows: private Validator validator; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import jakarta.validation.Validator; @Service class MyService(@Autowired private val validator: Validator) ---- +====== You can inject a reference to `org.springframework.validation.Validator` if your bean requires the Spring Validation API, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import org.springframework.validation.Validator; @@ -151,14 +178,17 @@ requires the Spring Validation API, as the following example shows: private Validator validator; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.validation.Validator @Service class MyService(@Autowired private val validator: Validator) ---- +====== [[validation-beanvalidation-spring-constraints]] @@ -182,8 +212,11 @@ that uses Spring to create `ConstraintValidator` instances. This lets your custo The following example shows a custom `@Constraint` declaration followed by an associated `ConstraintValidator` implementation that uses Spring for dependency injection: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target({ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) @@ -191,17 +224,23 @@ The following example shows a custom `@Constraint` declaration followed by an as public @interface MyConstraint { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.FUNCTION, AnnotationTarget.FIELD) @Retention(AnnotationRetention.RUNTIME) @Constraint(validatedBy = MyConstraintValidator::class) annotation class MyConstraint ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import jakarta.validation.ConstraintValidator; @@ -213,8 +252,10 @@ The following example shows a custom `@Constraint` declaration followed by an as // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import jakarta.validation.ConstraintValidator @@ -223,6 +264,7 @@ The following example shows a custom `@Constraint` declaration followed by an as // ... } ---- +====== As the preceding example shows, a `ConstraintValidator` implementation can have its dependencies @@ -236,8 +278,11 @@ You can integrate the method validation feature supported by Bean Validation 1.1 a custom extension, also by Hibernate Validator 4.3) into a Spring context through a `MethodValidationPostProcessor` bean definition: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import org.springframework.validation.beanvalidation.MethodValidationPostProcessor; @@ -251,11 +296,14 @@ a custom extension, also by Hibernate Validator 4.3) into a Spring context throu } ---- + +XML:: ++ [source,xml,indent=0,subs="verbatim,quotes",role="secondary"] -.XML ---- ---- +====== To be eligible for Spring-driven method validation, all target classes need to be annotated with Spring's `@Validated` annotation, which can optionally also declare the validation @@ -296,8 +344,11 @@ automatically added to the binder's `BindingResult`. The following example shows how to use a `DataBinder` programmatically to invoke validation logic after binding to a target object: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Foo target = new Foo(); DataBinder binder = new DataBinder(target); @@ -312,8 +363,10 @@ logic after binding to a target object: // get BindingResult that includes any validation errors BindingResult results = binder.getBindingResult(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val target = Foo() val binder = DataBinder(target) @@ -328,6 +381,7 @@ logic after binding to a target object: // get BindingResult that includes any validation errors val results = binder.bindingResult ---- +====== You can also configure a `DataBinder` with multiple `Validator` instances through `dataBinder.addValidators` and `dataBinder.replaceValidators`. This is useful when diff --git a/framework-docs/modules/ROOT/pages/core/validation/convert.adoc b/framework-docs/modules/ROOT/pages/core/validation/convert.adoc index 3d33722dcea9..4d6c6391ab40 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/convert.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/convert.adoc @@ -259,8 +259,11 @@ xref:core/validation/format.adoc#format-FormatterRegistry-SPI[The `FormatterRegi To work with a `ConversionService` instance programmatically, you can inject a reference to it like you would for any other bean. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Service public class MyService { @@ -274,8 +277,10 @@ it like you would for any other bean. The following example shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Service class MyService(private val conversionService: ConversionService) { @@ -285,6 +290,7 @@ it like you would for any other bean. The following example shows how to do so: } } ---- +====== For most use cases, you can use the `convert` method that specifies the `targetType`, but it does not work with more complex types, such as a collection of a parameterized element. @@ -294,8 +300,11 @@ you need to provide a formal definition of the source and target types. Fortunately, `TypeDescriptor` provides various options to make doing so straightforward, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DefaultConversionService cs = new DefaultConversionService(); @@ -304,8 +313,10 @@ as the following example shows: TypeDescriptor.forObject(input), // List type descriptor TypeDescriptor.collection(List.class, TypeDescriptor.valueOf(String.class))); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val cs = DefaultConversionService() @@ -314,6 +325,7 @@ as the following example shows: TypeDescriptor.forObject(input), // List type descriptor TypeDescriptor.collection(List::class.java, TypeDescriptor.valueOf(String::class.java))) ---- +====== Note that `DefaultConversionService` automatically registers converters that are appropriate for most environments. This includes collection converters, scalar diff --git a/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc b/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc index 053d98d73c17..82fc655f1310 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc @@ -13,8 +13,11 @@ formatters manually with the help of: For example, the following Java configuration registers a global `yyyyMMdd` format: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class AppConfig { @@ -44,8 +47,10 @@ For example, the following Java configuration registers a global `yyyyMMdd` form } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class AppConfig { @@ -71,6 +76,7 @@ For example, the following Java configuration registers a global `yyyyMMdd` form } } ---- +====== If you prefer XML-based configuration, you can use a `FormattingConversionServiceFactoryBean`. The following example shows how to do so: diff --git a/framework-docs/modules/ROOT/pages/core/validation/format.adoc b/framework-docs/modules/ROOT/pages/core/validation/format.adoc index c344b2c73133..920e2a44d970 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/format.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/format.adoc @@ -78,8 +78,11 @@ a `java.text.DateFormat`. The following `DateFormatter` is an example `Formatter` implementation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package org.springframework.format.datetime; @@ -112,8 +115,10 @@ The following `DateFormatter` is an example `Formatter` implementation: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- class DateFormatter(private val pattern: String) : Formatter { @@ -131,6 +136,7 @@ The following `DateFormatter` is an example `Formatter` implementation: } } ---- +====== The Spring team welcomes community-driven `Formatter` contributions. See https://github.com/spring-projects/spring-framework/issues[GitHub Issues] to contribute. @@ -169,8 +175,11 @@ formatting logic -- for example `org.springframework.format.annotation.DateTime The following example `AnnotationFormatterFactory` implementation binds the `@NumberFormat` annotation to a formatter to let a number style or pattern be specified: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public final class NumberFormatAnnotationFormatterFactory implements AnnotationFormatterFactory { @@ -204,8 +213,10 @@ annotation to a formatter to let a number style or pattern be specified: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class NumberFormatAnnotationFormatterFactory : AnnotationFormatterFactory { @@ -235,12 +246,16 @@ annotation to a formatter to let a number style or pattern be specified: } } ---- +====== To trigger formatting, you can annotate fields with `@NumberFormat`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyModel { @@ -248,13 +263,16 @@ example shows: private BigDecimal decimal; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyModel( @field:NumberFormat(style = Style.CURRENCY) private val decimal: BigDecimal ) ---- +====== [[format-annotations-api]] @@ -268,8 +286,11 @@ package. You can use `@NumberFormat` to format `Number` fields such as `Double` The following example uses `@DateTimeFormat` to format a `java.util.Date` as an ISO Date (yyyy-MM-dd): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyModel { @@ -277,13 +298,16 @@ The following example uses `@DateTimeFormat` to format a `java.util.Date` as an private Date date; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyModel( @DateTimeFormat(iso=ISO.DATE) private val date: Date ) ---- +====== [[format-FormatterRegistry-SPI]] diff --git a/framework-docs/modules/ROOT/pages/core/validation/validator.adoc b/framework-docs/modules/ROOT/pages/core/validation/validator.adoc index aa78fd755ce7..f5140480e8e1 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/validator.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/validator.adoc @@ -7,8 +7,11 @@ validators can report validation failures to the `Errors` object. Consider the following example of a small data object: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class Person { @@ -18,11 +21,14 @@ Consider the following example of a small data object: // the usual getters and setters... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class Person(val name: String, val age: Int) ---- +====== The next example provides validation behavior for the `Person` class by implementing the following two methods of the `org.springframework.validation.Validator` interface: @@ -35,8 +41,11 @@ Implementing a `Validator` is fairly straightforward, especially when you know o `ValidationUtils` helper class that the Spring Framework also provides. The following example implements `Validator` for `Person` instances: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class PersonValidator implements Validator { @@ -58,8 +67,10 @@ example implements `Validator` for `Person` instances: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class PersonValidator : Validator { @@ -81,6 +92,7 @@ example implements `Validator` for `Person` instances: } } ---- +====== The `static` `rejectIfEmpty(..)` method on the `ValidationUtils` class is used to reject the `name` property if it is `null` or the empty string. Have a look at the @@ -98,8 +110,11 @@ within the `AddressValidator` class without resorting to copy-and-paste, you can dependency-inject or instantiate an `AddressValidator` within your `CustomerValidator`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class CustomerValidator implements Validator { @@ -137,8 +152,10 @@ as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class CustomerValidator(private val addressValidator: Validator) : Validator { @@ -171,6 +188,7 @@ as the following example shows: } } ---- +====== Validation errors are reported to the `Errors` object passed to the validator. In the case of Spring Web MVC, you can use the `` tag to inspect the error messages, but diff --git a/framework-docs/modules/ROOT/pages/data-access/dao.adoc b/framework-docs/modules/ROOT/pages/data-access/dao.adoc index 6745abbb0bf3..2af1663add74 100644 --- a/framework-docs/modules/ROOT/pages/data-access/dao.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/dao.adoc @@ -52,14 +52,18 @@ lets the component scanning support find and configure your DAOs and repositorie without having to provide XML configuration entries for them. The following example shows how to use the `@Repository` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Repository // <1> public class SomeMovieFinder implements MovieFinder { // ... } ---- +====== <1> The `@Repository` annotation. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -80,8 +84,11 @@ needs access to a JDBC `DataSource`, and a JPA-based repository needs access to injected by using one of the `@Autowired`, `@Inject`, `@Resource` or `@PersistenceContext` annotations. The following example works for a JPA repository: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Repository public class JpaMovieFinder implements MovieFinder { @@ -93,8 +100,9 @@ annotations. The following example works for a JPA repository: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Repository class JpaMovieFinder : MovieFinder { @@ -105,13 +113,17 @@ annotations. The following example works for a JPA repository: // ... } ---- +====== If you use the classic Hibernate APIs, you can inject `SessionFactory`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Repository public class HibernateMovieFinder implements MovieFinder { @@ -126,22 +138,28 @@ example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Repository class HibernateMovieFinder(private val sessionFactory: SessionFactory) : MovieFinder { // ... } ---- +====== The last example we show here is for typical JDBC support. You could have the `DataSource` injected into an initialization method or a constructor, where you would create a `JdbcTemplate` and other data access support classes (such as `SimpleJdbcCall` and others) by using this `DataSource`. The following example autowires a `DataSource`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Repository public class JdbcMovieFinder implements MovieFinder { @@ -156,8 +174,10 @@ this `DataSource`. The following example autowires a `DataSource`: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Repository class JdbcMovieFinder(dataSource: DataSource) : MovieFinder { @@ -167,6 +187,7 @@ this `DataSource`. The following example autowires a `DataSource`: // ... } ---- +====== NOTE: See the specific coverage of each persistence technology for details on how to configure the application context to take advantage of these annotations. diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc index 203952f64a86..ce43becb6123 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc @@ -17,8 +17,11 @@ the prepared statement. This method is called the number of times that you specified in the `getBatchSize` call. The following example updates the `t_actor` table based on entries in a list, and the entire list is used as the batch: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -47,8 +50,10 @@ based on entries in a list, and the entire list is used as the batch: // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -71,6 +76,7 @@ based on entries in a list, and the entire list is used as the batch: // ... additional methods } ---- +====== If you process a stream of updates or reading from a file, you might have a preferred batch size, but the last batch might not have that number of entries. In this @@ -94,8 +100,11 @@ in an array of bean-style objects (with getter methods corresponding to paramete The following example shows a batch update using named parameters: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -114,8 +123,10 @@ The following example shows a batch update using named parameters: // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -130,6 +141,7 @@ The following example shows a batch update using named parameters: // ... additional methods } ---- +====== For an SQL statement that uses the classic `?` placeholders, you pass in a list containing an object array with the update values. This object array must have one entry @@ -139,8 +151,11 @@ defined in the SQL statement. The following example is the same as the preceding example, except that it uses classic JDBC `?` placeholders: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -165,8 +180,10 @@ JDBC `?` placeholders: // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -184,6 +201,7 @@ JDBC `?` placeholders: // ... additional methods } ---- +====== All of the batch update methods that we described earlier return an `int` array containing the number of affected rows for each batch entry. This count is reported by @@ -223,8 +241,11 @@ update calls into batches of the size specified. The following example shows a batch update that uses a batch size of 100: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -250,8 +271,10 @@ The following example shows a batch update that uses a batch size of 100: // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -270,6 +293,7 @@ The following example shows a batch update that uses a batch size of 100: // ... additional methods } ---- +====== The batch update method for this call returns an array of `int` arrays that contains an array entry for each batch with an array of the number of affected rows for each update. diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc index fb787e7fa655..e8e60ac527f8 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc @@ -48,8 +48,11 @@ To configure a `DriverManagerDataSource`: The following example shows how to configure a `DriverManagerDataSource` in Java: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DriverManagerDataSource dataSource = new DriverManagerDataSource(); dataSource.setDriverClassName("org.hsqldb.jdbcDriver"); @@ -57,8 +60,10 @@ The following example shows how to configure a `DriverManagerDataSource` in Java dataSource.setUsername("sa"); dataSource.setPassword(""); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val dataSource = DriverManagerDataSource().apply { setDriverClassName("org.hsqldb.jdbcDriver") @@ -67,6 +72,7 @@ The following example shows how to configure a `DriverManagerDataSource` in Java password = "" } ---- +====== The following example shows the corresponding XML configuration: diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc index 73c5bda829ce..54a1032c22a8 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc @@ -57,54 +57,75 @@ See the attendant {api-spring-framework}/jdbc/core/JdbcTemplate.html[javadoc] fo The following query gets the number of rows in a relation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- int rowCount = this.jdbcTemplate.queryForObject("select count(*) from t_actor", Integer.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val rowCount = jdbcTemplate.queryForObject("select count(*) from t_actor")!! ---- +====== The following query uses a bind variable: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- int countOfActorsNamedJoe = this.jdbcTemplate.queryForObject( "select count(*) from t_actor where first_name = ?", Integer.class, "Joe"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val countOfActorsNamedJoe = jdbcTemplate.queryForObject( "select count(*) from t_actor where first_name = ?", arrayOf("Joe"))!! ---- +====== The following query looks for a `String`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- String lastName = this.jdbcTemplate.queryForObject( "select last_name from t_actor where id = ?", String.class, 1212L); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val lastName = this.jdbcTemplate.queryForObject( "select last_name from t_actor where id = ?", arrayOf(1212L))!! ---- +====== The following query finds and populates a single domain object: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Actor actor = jdbcTemplate.queryForObject( "select first_name, last_name from t_actor where id = ?", @@ -116,8 +137,10 @@ The following query finds and populates a single domain object: }, 1212L); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val actor = jdbcTemplate.queryForObject( "select first_name, last_name from t_actor where id = ?", @@ -125,11 +148,15 @@ The following query finds and populates a single domain object: Actor(rs.getString("first_name"), rs.getString("last_name")) } ---- +====== The following query finds and populates a list of domain objects: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- List actors = this.jdbcTemplate.query( "select first_name, last_name from t_actor", @@ -140,20 +167,26 @@ The following query finds and populates a list of domain objects: return actor; }); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val actors = jdbcTemplate.query("select first_name, last_name from t_actor") { rs, _ -> Actor(rs.getString("first_name"), rs.getString("last_name")) ---- +====== If the last two snippets of code actually existed in the same application, it would make sense to remove the duplication present in the two `RowMapper` lambda expressions and extract them out into a single field that could then be referenced by DAO methods as needed. For example, it may be better to write the preceding code snippet as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- private final RowMapper actorRowMapper = (resultSet, rowNum) -> { Actor actor = new Actor(); @@ -166,8 +199,10 @@ For example, it may be better to write the preceding code snippet as follows: return this.jdbcTemplate.query("select first_name, last_name from t_actor", actorRowMapper); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val actorMapper = RowMapper { rs: ResultSet, rowNum: Int -> Actor(rs.getString("first_name"), rs.getString("last_name")) @@ -177,6 +212,7 @@ For example, it may be better to write the preceding code snippet as follows: return jdbcTemplate.query("select first_name, last_name from t_actor", actorMapper) } ---- +====== [[jdbc-JdbcTemplate-examples-update]] === Updating (`INSERT`, `UPDATE`, and `DELETE`) with `JdbcTemplate` @@ -186,52 +222,70 @@ Parameter values are usually provided as variable arguments or, alternatively, a The following example inserts a new entry: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- this.jdbcTemplate.update( "insert into t_actor (first_name, last_name) values (?, ?)", "Leonor", "Watling"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- jdbcTemplate.update( "insert into t_actor (first_name, last_name) values (?, ?)", "Leonor", "Watling") ---- +====== The following example updates an existing entry: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- this.jdbcTemplate.update( "update t_actor set last_name = ? where id = ?", "Banjo", 5276L); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- jdbcTemplate.update( "update t_actor set last_name = ? where id = ?", "Banjo", 5276L) ---- +====== The following example deletes an entry: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- this.jdbcTemplate.update( "delete from t_actor where id = ?", Long.valueOf(actorId)); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- jdbcTemplate.update("delete from t_actor where id = ?", actorId.toLong()) ---- +====== [[jdbc-JdbcTemplate-examples-other]] === Other `JdbcTemplate` Operations @@ -241,33 +295,45 @@ method is often used for DDL statements. It is heavily overloaded with variants callback interfaces, binding variable arrays, and so on. The following example creates a table: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- this.jdbcTemplate.execute("create table mytable (id integer, name varchar(100))"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- jdbcTemplate.execute("create table mytable (id integer, name varchar(100))") ---- +====== The following example invokes a stored procedure: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- this.jdbcTemplate.update( "call SUPPORT.REFRESH_ACTORS_SUMMARY(?)", Long.valueOf(unionId)); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- jdbcTemplate.update( "call SUPPORT.REFRESH_ACTORS_SUMMARY(?)", unionId.toLong()) ---- +====== More sophisticated stored procedure support is xref:data-access/jdbc/object.adoc#jdbc-StoredProcedure[covered later]. @@ -288,8 +354,11 @@ that shared `DataSource` bean into your DAO classes. The `JdbcTemplate` is creat the setter for the `DataSource`. This leads to DAOs that resemble the following: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcCorporateEventDao implements CorporateEventDao { @@ -302,8 +371,10 @@ the setter for the `DataSource`. This leads to DAOs that resemble the following: // JDBC-backed implementations of the methods on the CorporateEventDao follow... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcCorporateEventDao(dataSource: DataSource) : CorporateEventDao { @@ -312,6 +383,7 @@ the setter for the `DataSource`. This leads to DAOs that resemble the following: // JDBC-backed implementations of the methods on the CorporateEventDao follow... } ---- +====== -- The following example shows the corresponding XML configuration: @@ -350,8 +422,11 @@ support for dependency injection. In this case, you can annotate the class with method with `@Autowired`. The following example shows how to do so: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Repository // <1> public class JdbcCorporateEventDao implements CorporateEventDao { @@ -366,6 +441,7 @@ method with `@Autowired`. The following example shows how to do so: // JDBC-backed implementations of the methods on the CorporateEventDao follow... } ---- +====== <1> Annotate the class with `@Repository`. <2> Annotate the `DataSource` setter method with `@Autowired`. <3> Create a new `JdbcTemplate` with the `DataSource`. @@ -440,8 +516,11 @@ section describes only those areas of the `NamedParameterJdbcTemplate` class tha from the `JdbcTemplate` itself -- namely, programming JDBC statements by using named parameters. The following example shows how to use `NamedParameterJdbcTemplate`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // some JDBC-backed DAO class... private NamedParameterJdbcTemplate namedParameterJdbcTemplate; @@ -460,8 +539,9 @@ parameters. The following example shows how to use `NamedParameterJdbcTemplate`: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) @@ -471,6 +551,7 @@ parameters. The following example shows how to use `NamedParameterJdbcTemplate`: return namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Int::class.java)!! } ---- +====== Notice the use of the named parameter notation in the value assigned to the `sql` variable and the corresponding value that is plugged into the `namedParameters` @@ -483,8 +564,11 @@ methods exposed by the `NamedParameterJdbcOperations` and implemented by the The following example shows the use of the `Map`-based style: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // some JDBC-backed DAO class... private NamedParameterJdbcTemplate namedParameterJdbcTemplate; @@ -502,8 +586,10 @@ The following example shows the use of the `Map`-based style: return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // some JDBC-backed DAO class... private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) @@ -514,6 +600,7 @@ The following example shows the use of the `Map`-based style: return namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Int::class.java)!! } ---- +====== One nice feature related to the `NamedParameterJdbcTemplate` (and existing in the same Java package) is the `SqlParameterSource` interface. You have already seen an example of @@ -531,8 +618,11 @@ of named parameter values. The following example shows a typical JavaBean: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class Actor { @@ -556,17 +646,23 @@ The following example shows a typical JavaBean: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- data class Actor(val id: Long, val firstName: String, val lastName: String) ---- +====== The following example uses a `NamedParameterJdbcTemplate` to return the count of the members of the class shown in the preceding example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // some JDBC-backed DAO class... private NamedParameterJdbcTemplate namedParameterJdbcTemplate; @@ -585,8 +681,10 @@ members of the class shown in the preceding example: return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // some JDBC-backed DAO class... private val namedParameterJdbcTemplate = NamedParameterJdbcTemplate(dataSource) @@ -600,6 +698,7 @@ members of the class shown in the preceding example: return namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Int::class.java)!! } ---- +====== Remember that the `NamedParameterJdbcTemplate` class wraps a classic `JdbcTemplate` template. If you need access to the wrapped `JdbcTemplate` instance to access @@ -651,8 +750,11 @@ name from the database metadata of the database in use. You can extend `SQLErrorCodeSQLExceptionTranslator`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class CustomSQLErrorCodesTranslator extends SQLErrorCodeSQLExceptionTranslator { @@ -664,8 +766,10 @@ You can extend `SQLErrorCodeSQLExceptionTranslator`, as the following example sh } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class CustomSQLErrorCodesTranslator : SQLErrorCodeSQLExceptionTranslator() { @@ -677,6 +781,7 @@ You can extend `SQLErrorCodeSQLExceptionTranslator`, as the following example sh } } ---- +====== In the preceding example, the specific error code (`-12345`) is translated, while other errors are left to be translated by the default translator implementation. To use this custom @@ -685,8 +790,11 @@ translator, you must pass it to the `JdbcTemplate` through the method processing where this translator is needed. The following example shows how you can use this custom translator: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- private JdbcTemplate jdbcTemplate; @@ -710,8 +818,10 @@ translator: " where id = ?", pct, orderId); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // create a JdbcTemplate and set data source private val jdbcTemplate = JdbcTemplate(dataSource).apply { @@ -728,6 +838,7 @@ translator: " where id = ?", pct, orderId) } ---- +====== The custom translator is passed a data source in order to look up the error codes in `sql-error-codes.xml`. @@ -741,8 +852,11 @@ Running an SQL statement requires very little code. You need a `DataSource` and `JdbcTemplate`. The following example shows what you need to include for a minimal but fully functional class that creates a new table: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import javax.sql.DataSource; import org.springframework.jdbc.core.JdbcTemplate; @@ -760,8 +874,10 @@ fully functional class that creates a new table: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import javax.sql.DataSource import org.springframework.jdbc.core.JdbcTemplate @@ -775,6 +891,7 @@ fully functional class that creates a new table: } } ---- +====== [[jdbc-statements-querying]] @@ -786,8 +903,11 @@ Java class that is passed in as an argument. If the type conversion is invalid, `InvalidDataAccessApiUsageException` is thrown. The following example contains two query methods, one for an `int` and one that queries for a `String`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import javax.sql.DataSource; import org.springframework.jdbc.core.JdbcTemplate; @@ -809,8 +929,10 @@ query methods, one for an `int` and one that queries for a `String`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import javax.sql.DataSource import org.springframework.jdbc.core.JdbcTemplate @@ -826,6 +948,7 @@ class RunAQuery(dataSource: DataSource) { get() = jdbcTemplate.queryForObject("select name from mytable") } ---- +====== In addition to the single result query methods, several methods return a list with an entry for each row that the query returned. The most generic method is `queryForList(..)`, @@ -833,8 +956,11 @@ which returns a `List` where each element is a `Map` containing one entry for ea using the column name as the key. If you add a method to the preceding example to retrieve a list of all the rows, it might be as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- private JdbcTemplate jdbcTemplate; @@ -846,8 +972,10 @@ list of all the rows, it might be as follows: return this.jdbcTemplate.queryForList("select * from mytable"); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- private val jdbcTemplate = JdbcTemplate(dataSource) @@ -855,6 +983,7 @@ list of all the rows, it might be as follows: return jdbcTemplate.queryForList("select * from mytable") } ---- +====== The returned list would resemble the following: @@ -869,8 +998,11 @@ The returned list would resemble the following: The following example updates a column for a certain primary key: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import javax.sql.DataSource; import org.springframework.jdbc.core.JdbcTemplate; @@ -888,8 +1020,10 @@ The following example updates a column for a certain primary key: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import javax.sql.DataSource import org.springframework.jdbc.core.JdbcTemplate @@ -903,6 +1037,7 @@ The following example updates a column for a certain primary key: } } ---- +====== In the preceding example, an SQL statement has placeholders for row parameters. You can pass the parameter values @@ -922,8 +1057,11 @@ update. There is no standard single way to create an appropriate `PreparedStatem (which explains why the method signature is the way it is). The following example works on Oracle but may not work on other platforms: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- final String INSERT_SQL = "insert into my_test (name) values(?)"; final String name = "Rob"; @@ -937,8 +1075,10 @@ on Oracle but may not work on other platforms: // keyHolder.getKey() now contains the generated key ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val INSERT_SQL = "insert into my_test (name) values(?)" val name = "Rob" @@ -950,6 +1090,7 @@ on Oracle but may not work on other platforms: // keyHolder.getKey() now contains the generated key ---- +====== diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc index 740d49db44d0..eaa86da5f268 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc @@ -44,8 +44,11 @@ The `EmbeddedDatabaseBuilder` class provides a fluent API for constructing an em database programmatically. You can use this when you need to create an embedded database in a stand-alone environment or in a stand-alone integration test, as in the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- EmbeddedDatabase db = new EmbeddedDatabaseBuilder() .generateUniqueName(true) @@ -60,8 +63,10 @@ stand-alone environment or in a stand-alone integration test, as in the followin db.shutdown() ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val db = EmbeddedDatabaseBuilder() .generateUniqueName(true) @@ -76,6 +81,7 @@ stand-alone environment or in a stand-alone integration test, as in the followin db.shutdown() ---- +====== See the {api-spring-framework}/jdbc/datasource/embedded/EmbeddedDatabaseBuilder.html[javadoc for `EmbeddedDatabaseBuilder`] for further details on all supported options. @@ -83,8 +89,11 @@ for further details on all supported options. You can also use the `EmbeddedDatabaseBuilder` to create an embedded database by using Java configuration, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class DataSourceConfig { @@ -102,8 +111,10 @@ configuration, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class DataSourceConfig { @@ -121,6 +132,7 @@ configuration, as the following example shows: } } ---- +====== [[jdbc-embedded-database-types]] @@ -168,8 +180,11 @@ configuring the embedded database as a bean in the Spring `ApplicationContext` a in xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-xml[Creating an Embedded Database by Using Spring XML] and xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-java[Creating an Embedded Database Programmatically]. The following listing shows the test template: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class DataAccessIntegrationTestTemplate { @@ -198,8 +213,10 @@ shows the test template: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class DataAccessIntegrationTestTemplate { @@ -227,6 +244,7 @@ shows the test template: } } ---- +====== [[jdbc-embedded-database-unique-names]] diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc index 4e0610bfd12d..65fd60c76e05 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc @@ -40,8 +40,11 @@ abstract `mapRow(..)` method to convert each row of the supplied `ResultSet` int object of the type specified. The following example shows a custom query that maps the data from the `t_actor` relation to an instance of the `Actor` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ActorMappingQuery extends MappingSqlQuery { @@ -61,8 +64,10 @@ data from the `t_actor` relation to an instance of the `Actor` class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ActorMappingQuery(ds: DataSource) : MappingSqlQuery(ds, "select id, first_name, last_name from t_actor where id = ?") { @@ -79,6 +84,7 @@ data from the `t_actor` relation to an instance of the `Actor` class: } ---- +====== The class extends `MappingSqlQuery` parameterized with the `Actor` type. The constructor for this customer query takes a `DataSource` as the only parameter. In this @@ -93,8 +99,11 @@ thread-safe after it is compiled, so, as long as these instances are created whe is initialized, they can be kept as instance variables and be reused. The following example shows how to define such a class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- private ActorMappingQuery actorMappingQuery; @@ -107,13 +116,16 @@ example shows how to define such a class: return actorMappingQuery.findObject(id); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- private val actorMappingQuery = ActorMappingQuery(dataSource) fun getCustomer(id: Long) = actorMappingQuery.findObject(id) ---- +====== The method in the preceding example retrieves the customer with the `id` that is passed in as the only parameter. Since we want only one object to be returned, we call the `findObject` convenience @@ -122,19 +134,25 @@ list of objects and took additional parameters, we would use one of the `execute methods that takes an array of parameter values passed in as varargs. The following example shows such a method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public List searchForActors(int age, String namePattern) { return actorSearchMappingQuery.execute(age, namePattern); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun searchForActors(age: Int, namePattern: String) = actorSearchMappingQuery.execute(age, namePattern) ---- +====== [[jdbc-SqlUpdate]] @@ -149,8 +167,11 @@ However, you do not have to subclass the `SqlUpdate` class, since it can easily be parameterized by setting SQL and declaring parameters. The following example creates a custom update method named `execute`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import java.sql.Types; import javax.sql.DataSource; @@ -177,8 +198,10 @@ The following example creates a custom update method named `execute`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import java.sql.Types import javax.sql.DataSource @@ -205,6 +228,7 @@ The following example creates a custom update method named `execute`: } } ---- +====== [[jdbc-StoredProcedure]] @@ -219,18 +243,24 @@ To define a parameter for the `StoredProcedure` class, you can use an `SqlParame of its subclasses. You must specify the parameter name and SQL type in the constructor, as the following code snippet shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- new SqlParameter("in_id", Types.NUMERIC), new SqlOutParameter("out_first_name", Types.VARCHAR), ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- SqlParameter("in_id", Types.NUMERIC), SqlOutParameter("out_first_name", Types.VARCHAR), ---- +====== The SQL type is specified using the `java.sql.Types` constants. @@ -259,8 +289,11 @@ returned date from the results `Map`. The results `Map` has an entry for each de output parameter (in this case, only one) by using the parameter name as the key. The following listing shows our custom StoredProcedure class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import java.sql.Types; import java.util.Date; @@ -306,8 +339,10 @@ The following listing shows our custom StoredProcedure class: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import java.sql.Types import java.util.Date @@ -343,12 +378,16 @@ The following listing shows our custom StoredProcedure class: } } ---- +====== The following example of a `StoredProcedure` has two output parameters (in this case, Oracle REF cursors): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import java.util.HashMap; import java.util.Map; @@ -374,8 +413,10 @@ Oracle REF cursors): } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import java.util.HashMap import javax.sql.DataSource @@ -401,6 +442,7 @@ Oracle REF cursors): } } ---- +====== Notice how the overloaded variants of the `declareParameter(..)` method that have been used in the `TitlesAndGenresStoredProcedure` constructor are passed `RowMapper` @@ -410,8 +452,11 @@ functionality. The next two examples provide code for the two `RowMapper` implem The `TitleMapper` class maps a `ResultSet` to a `Title` domain object for each row in the supplied `ResultSet`, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import java.sql.ResultSet; import java.sql.SQLException; @@ -428,8 +473,10 @@ the supplied `ResultSet`, as follows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import java.sql.ResultSet import com.foo.domain.Title @@ -441,12 +488,16 @@ the supplied `ResultSet`, as follows: Title(rs.getLong("id"), rs.getString("name")) } ---- +====== The `GenreMapper` class maps a `ResultSet` to a `Genre` domain object for each row in the supplied `ResultSet`, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import java.sql.ResultSet; import java.sql.SQLException; @@ -460,8 +511,10 @@ the supplied `ResultSet`, as follows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import java.sql.ResultSet import com.foo.domain.Genre @@ -474,13 +527,17 @@ the supplied `ResultSet`, as follows: } } ---- +====== To pass parameters to a stored procedure that has one or more input parameters in its definition in the RDBMS, you can code a strongly typed `execute(..)` method that would delegate to the untyped `execute(Map)` method in the superclass, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import java.sql.Types; import java.util.Date; @@ -511,8 +568,10 @@ delegate to the untyped `execute(Map)` method in the superclass, as the followin } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import java.sql.Types import java.util.Date @@ -539,6 +598,7 @@ delegate to the untyped `execute(Map)` method in the superclass, as the followin mapOf(CUTOFF_DATE_PARAM to cutoffDate)) } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/parameter-handling.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/parameter-handling.adoc index 09210858805f..7d7101d26e77 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/parameter-handling.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/parameter-handling.adoc @@ -63,8 +63,11 @@ dependency injection. The following example shows how to create and insert a BLOB: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- final File blobIn = new File("spring2004.jpg"); final InputStream blobIs = new FileInputStream(blobIn); @@ -86,6 +89,7 @@ The following example shows how to create and insert a BLOB: blobIs.close(); clobReader.close(); ---- +====== <1> Pass in the `lobHandler` that (in this example) is a plain `DefaultLobHandler`. <2> Using the method `setClobAsCharacterStream` to pass in the contents of the CLOB. <3> Using the method `setBlobAsBinaryStream` to pass in the contents of the BLOB. @@ -134,8 +138,11 @@ Now it is time to read the LOB data from the database. Again, you use a `JdbcTem with the same instance variable `lobHandler` and a reference to a `DefaultLobHandler`. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- List> l = jdbcTemplate.query("select id, a_clob, a_blob from lob_table", new RowMapper>() { @@ -149,6 +156,7 @@ The following example shows how to do so: } }); ---- +====== <1> Using the method `getClobAsString` to retrieve the contents of the CLOB. <2> Using the method `getBlobAsBytes` to retrieve the contents of the BLOB. @@ -203,8 +211,11 @@ implemented. This interface is used as part of the declaration of an `SqlOutPara The following example shows returning the value of an Oracle `STRUCT` object of the user declared type `ITEM_TYPE`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class TestItemStoredProcedure extends StoredProcedure { @@ -223,8 +234,10 @@ declared type `ITEM_TYPE`: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class TestItemStoredProcedure(dataSource: DataSource) : StoredProcedure() { @@ -239,6 +252,7 @@ declared type `ITEM_TYPE`: } } ---- +====== You can use `SqlTypeValue` to pass the value of a Java object (such as `TestItem`) to a stored procedure. The `SqlTypeValue` interface has a single method (named @@ -246,8 +260,11 @@ stored procedure. The `SqlTypeValue` interface has a single method (named can use it to create database-specific objects, such as `StructDescriptor` instances or `ArrayDescriptor` instances. The following example creates a `StructDescriptor` instance: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- final TestItem testItem = new TestItem(123L, "A test item", new SimpleDateFormat("yyyy-M-d").parse("2010-12-31")); @@ -265,8 +282,10 @@ or `ArrayDescriptor` instances. The following example creates a `StructDescripto } }; ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val (id, description, expirationDate) = TestItem(123L, "A test item", SimpleDateFormat("yyyy-M-d").parse("2010-12-31")) @@ -279,6 +298,7 @@ or `ArrayDescriptor` instances. The following example creates a `StructDescripto } } ---- +====== You can now add this `SqlTypeValue` to the `Map` that contains the input parameters for the `execute` call of the stored procedure. @@ -288,8 +308,11 @@ procedure. Oracle has its own internal `ARRAY` class that must be used in this c you can use the `SqlTypeValue` to create an instance of the Oracle `ARRAY` and populate it with values from the Java `ARRAY`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- final Long[] ids = new Long[] {1L, 2L}; @@ -301,8 +324,10 @@ it with values from the Java `ARRAY`, as the following example shows: } }; ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class TestItemStoredProcedure(dataSource: DataSource) : StoredProcedure() { @@ -317,6 +342,7 @@ it with values from the Java `ARRAY`, as the following example shows: } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc index 8b711afb5561..9e0c0200a179 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc @@ -19,8 +19,11 @@ Configuration methods for this class follow the `fluid` style that returns the i of the `SimpleJdbcInsert`, which lets you chain all configuration methods. The following example uses only one configuration method (we show examples of multiple methods later): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -41,8 +44,10 @@ example uses only one configuration method (we show examples of multiple methods // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -59,6 +64,7 @@ example uses only one configuration method (we show examples of multiple methods // ... additional methods } ---- +====== The `execute` method used here takes a plain `java.util.Map` as its only parameter. The important thing to note here is that the keys used for the `Map` must match the column @@ -75,8 +81,11 @@ the `SimpleJdbcInsert`, in addition to specifying the table name, it specifies t of the generated key column with the `usingGeneratedKeyColumns` method. The following listing shows how it works: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -99,8 +108,10 @@ listing shows how it works: // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -118,6 +129,7 @@ listing shows how it works: // ... additional methods } ---- +====== The main difference when you run the insert by using this second approach is that you do not add the `id` to the `Map`, and you call the `executeAndReturnKey` method. This returns a @@ -134,8 +146,11 @@ use a `KeyHolder` that is returned from the `executeAndReturnKeyHolder` method. You can limit the columns for an insert by specifying a list of column names with the `usingColumns` method, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -159,8 +174,10 @@ You can limit the columns for an insert by specifying a list of column names wit // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -180,6 +197,7 @@ You can limit the columns for an insert by specifying a list of column names wit // ... additional methods } ---- +====== The execution of the insert is the same as if you had relied on the metadata to determine which columns to use. @@ -195,8 +213,11 @@ which is a very convenient class if you have a JavaBean-compliant class that con your values. It uses the corresponding getter method to extract the parameter values. The following example shows how to use `BeanPropertySqlParameterSource`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -217,8 +238,10 @@ values. The following example shows how to use `BeanPropertySqlParameterSource`: // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -235,12 +258,16 @@ values. The following example shows how to use `BeanPropertySqlParameterSource`: // ... additional methods } ---- +====== Another option is the `MapSqlParameterSource` that resembles a `Map` but provides a more convenient `addValue` method that can be chained. The following example shows how to use it: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -263,8 +290,10 @@ convenient `addValue` method that can be chained. The following example shows ho // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -283,6 +312,7 @@ convenient `addValue` method that can be chained. The following example shows ho // ... additional methods } ---- +====== As you can see, the configuration is the same. Only the executing code has to change to use these alternative input classes. @@ -325,8 +355,11 @@ The following example of a `SimpleJdbcCall` configuration uses the preceding sto procedure (the only configuration option, in addition to the `DataSource`, is the name of the stored procedure): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -352,8 +385,10 @@ of the stored procedure): // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -374,6 +409,7 @@ of the stored procedure): // ... additional methods } ---- +====== The code you write for the execution of the call involves creating an `SqlParameterSource` containing the IN parameter. You must match the name provided for the input value @@ -397,8 +433,11 @@ To do the latter, you can create your own `JdbcTemplate` and set the `setResults property to `true`. Then you can pass this customized `JdbcTemplate` instance into the constructor of your `SimpleJdbcCall`. The following example shows this configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -414,8 +453,10 @@ the constructor of your `SimpleJdbcCall`. The following example shows this confi // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -426,6 +467,7 @@ the constructor of your `SimpleJdbcCall`. The following example shows this confi // ... additional methods } ---- +====== By taking this action, you avoid conflicts in the case used for the names of your returned `out` parameters. @@ -456,8 +498,11 @@ of IN parameter names to include for a given signature. The following example shows a fully declared procedure call and uses the information from the preceding example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -481,8 +526,10 @@ the preceding example: // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -501,6 +548,7 @@ the preceding example: // ... additional methods } ---- +====== The execution and end results of the two examples are the same. The second example specifies all details explicitly rather than relying on metadata. @@ -515,18 +563,24 @@ To do so, you typically specify the parameter name and SQL type in the construct is specified by using the `java.sql.Types` constants. Earlier in this chapter, we saw declarations similar to the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- new SqlParameter("in_id", Types.NUMERIC), new SqlOutParameter("out_first_name", Types.VARCHAR), ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- SqlParameter("in_id", Types.NUMERIC), SqlOutParameter("out_first_name", Types.VARCHAR), ---- +====== The first line with the `SqlParameter` declares an IN parameter. You can use IN parameters for both stored procedure calls and for queries by using the `SqlQuery` and its @@ -578,8 +632,11 @@ that returns an actor's full name: To call this function, we again create a `SimpleJdbcCall` in the initialization method, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -602,8 +659,10 @@ as the following example shows: // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -621,6 +680,7 @@ as the following example shows: // ... additional methods } ---- +====== The `executeFunction` method used returns a `String` that contains the return value from the function call. @@ -656,8 +716,11 @@ to map follows the JavaBean rules, you can use a `BeanPropertyRowMapper` that is passing in the required class to map to in the `newInstance` method. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class JdbcActorDao implements ActorDao { @@ -680,8 +743,10 @@ The following example shows how to do so: // ... additional methods } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class JdbcActorDao(dataSource: DataSource) : ActorDao { @@ -699,6 +764,7 @@ The following example shows how to do so: // ... additional methods } ---- +====== The `execute` call passes in an empty `Map`, because this call does not take any parameters. The list of actors is then retrieved from the results map and returned to the caller. diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc index bb47bbd68f68..3138409d36e3 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc @@ -61,8 +61,11 @@ do not need any special exception treatment (or both). However, Spring lets exce translation be applied transparently through the `@Repository` annotation. The following examples (one for Java configuration and one for XML configuration) show how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Repository public class ProductDaoImpl implements ProductDao { @@ -71,8 +74,10 @@ examples (one for Java configuration and one for XML configuration) show how to } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Repository class ProductDaoImpl : ProductDao { @@ -81,6 +86,7 @@ examples (one for Java configuration and one for XML configuration) show how to } ---- +====== [source,xml,indent=0,subs="verbatim,quotes"] ---- diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc index c449194c0aa7..883aafc3b0d8 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc @@ -95,8 +95,11 @@ one current `Session` per transaction. This is roughly equivalent to Spring's synchronization of one Hibernate `Session` per transaction. A corresponding DAO implementation resembles the following example, based on the plain Hibernate API: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ProductDaoImpl implements ProductDao { @@ -114,8 +117,10 @@ implementation resembles the following example, based on the plain Hibernate API } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ProductDaoImpl(private val sessionFactory: SessionFactory) : ProductDao { @@ -127,6 +132,7 @@ implementation resembles the following example, based on the plain Hibernate API } } ---- +====== This style is similar to that of the Hibernate reference documentation and examples, except for holding the `SessionFactory` in an instance variable. We strongly recommend @@ -192,8 +198,11 @@ You can annotate the service layer with `@Transactional` annotations and instruc Spring container to find these annotations and provide transactional semantics for these annotated methods. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ProductServiceImpl implements ProductService { @@ -215,8 +224,10 @@ these annotated methods. The following example shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ProductServiceImpl(private val productDao: ProductDao) : ProductService { @@ -230,6 +241,7 @@ these annotated methods. The following example shows how to do so: fun findAllProducts() = productDao.findAllProducts() } ---- +====== In the container, you need to set up the `PlatformTransactionManager` implementation (as a bean) and a `` entry, opting into `@Transactional` @@ -295,8 +307,11 @@ and an example for a business method implementation: ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ProductServiceImpl implements ProductService { @@ -321,8 +336,10 @@ and an example for a business method implementation: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ProductServiceImpl(transactionManager: PlatformTransactionManager, private val productDao: ProductDao) : ProductService { @@ -337,6 +354,7 @@ and an example for a business method implementation: } } ---- +====== Spring's `TransactionInterceptor` lets any checked application exception be thrown with the callback code, while `TransactionTemplate` is restricted to unchecked diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc index 3f0265169796..0f60323febc2 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc @@ -293,8 +293,11 @@ using an injected `EntityManagerFactory` or `EntityManager`. Spring can understa if a `PersistenceAnnotationBeanPostProcessor` is enabled. The following example shows a plain JPA DAO implementation that uses the `@PersistenceUnit` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ProductDaoImpl implements ProductDao { @@ -320,8 +323,10 @@ that uses the `@PersistenceUnit` annotation: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ProductDaoImpl : ProductDao { @@ -340,6 +345,7 @@ that uses the `@PersistenceUnit` annotation: } } ---- +====== The preceding DAO has no dependency on Spring and still fits nicely into a Spring application context. Moreover, the DAO takes advantage of annotations to require the @@ -382,8 +388,11 @@ the factory. You can avoid this by requesting a transactional `EntityManager` (a called a "`shared EntityManager`" because it is a shared, thread-safe proxy for the actual transactional EntityManager) to be injected instead of the factory. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class ProductDaoImpl implements ProductDao { @@ -397,8 +406,10 @@ transactional EntityManager) to be injected instead of the factory. The followin } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class ProductDaoImpl : ProductDao { @@ -412,6 +423,7 @@ transactional EntityManager) to be injected instead of the factory. The followin } } ---- +====== The `@PersistenceContext` annotation has an optional attribute called `type`, which defaults to `PersistenceContextType.TRANSACTION`. You can use this default to receive a shared diff --git a/framework-docs/modules/ROOT/pages/data-access/oxm.adoc b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc index a1637cbff6a3..3cbe3a502e70 100644 --- a/framework-docs/modules/ROOT/pages/data-access/oxm.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc @@ -171,8 +171,11 @@ You can use Spring's OXM for a wide variety of situations. In the following exam use it to marshal the settings of a Spring-managed application as an XML file. In the following example, we use a simple JavaBean to represent the settings: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class Settings { @@ -187,21 +190,27 @@ use a simple JavaBean to represent the settings: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class Settings { var isFooEnabled: Boolean = false } ---- +====== The application class uses this bean to store its settings. Besides a main method, the class has two methods: `saveSettings()` saves the settings bean to a file named `settings.xml`, and `loadSettings()` loads these settings again. The following `main()` method constructs a Spring application context and calls these two methods: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import java.io.FileInputStream; import java.io.FileOutputStream; @@ -249,8 +258,10 @@ constructs a Spring application context and calls these two methods: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class Application { @@ -276,6 +287,7 @@ constructs a Spring application context and calls these two methods: application.loadSettings() } ---- +====== The `Application` requires both a `marshaller` and an `unmarshaller` property to be set. We can do so by using the following `applicationContext.xml`: diff --git a/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc b/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc index 1345dd5fb0ef..57d5c9643249 100644 --- a/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc @@ -60,16 +60,22 @@ and give it to DAOs as a bean reference. The simplest way to create a `DatabaseClient` object is through a static factory method, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DatabaseClient client = DatabaseClient.create(connectionFactory); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = DatabaseClient.create(connectionFactory) ---- +====== NOTE: The `ConnectionFactory` should always be configured as a bean in the Spring IoC container. @@ -119,18 +125,24 @@ See the attendant {api-spring-framework}/r2dbc/core/DatabaseClient.html[javadoc] The following example shows what you need to include for minimal but fully functional code that creates a new table: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono completion = client.sql("CREATE TABLE person (id VARCHAR(255) PRIMARY KEY, name VARCHAR(255), age INTEGER);") .then(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client.sql("CREATE TABLE person (id VARCHAR(255) PRIMARY KEY, name VARCHAR(255), age INTEGER);") .await() ---- +====== `DatabaseClient` is designed for convenient, fluent usage. It exposes intermediate, continuation, and terminal methods at each stage of the @@ -150,35 +162,47 @@ depending on the issued query. The following query gets the `id` and `name` columns from a table: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono> first = client.sql("SELECT id, name FROM person") .fetch().first(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val first = client.sql("SELECT id, name FROM person") .fetch().awaitSingle() ---- +====== The following query uses a bind variable: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono> first = client.sql("SELECT id, name FROM person WHERE first_name = :fn") .bind("fn", "Joe") .fetch().first(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val first = client.sql("SELECT id, name FROM person WHERE first_name = :fn") .bind("fn", "Joe") .fetch().awaitSingle() ---- +====== You might have noticed the use of `fetch()` in the example above. `fetch()` is a continuation operator that lets you specify how much data you want to consume. @@ -205,20 +229,26 @@ collections and maps, and objects). The following example extracts the `name` column and emits its value: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Flux names = client.sql("SELECT name FROM person") .map(row -> row.get("name", String.class)) .all(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val names = client.sql("SELECT name FROM person") .map{ row: Row -> row.get("name", String.class) } .flow() ---- +====== [[r2dbc-DatabaseClient-mapping-null]] @@ -242,20 +272,26 @@ do not return tabular data so you use `rowsUpdated()` to consume results. The following example shows an `UPDATE` statement that returns the number of updated rows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono affectedRows = client.sql("UPDATE person SET first_name = :fn") .bind("fn", "Joe") .fetch().rowsUpdated(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val affectedRows = client.sql("UPDATE person SET first_name = :fn") .bind("fn", "Joe") .fetch().awaitRowsUpdated() ---- +====== [[r2dbc-DatabaseClient-named-parameters]] ==== Binding Values to Queries @@ -277,7 +313,6 @@ Parameter binding supports two binding strategies: The following example shows parameter binding for a query: -==== [source,java] ---- db.sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)") @@ -285,7 +320,6 @@ db.sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)") .bind("name", "Joe") .bind("age", 34); ---- -==== .R2DBC Native Bind Markers **** @@ -318,8 +352,11 @@ SELECT id, name, state FROM table WHERE (name, age) IN (('John', 35), ('Ann', 50 The preceding query can be parameterized and run as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- List tuples = new ArrayList<>(); tuples.add(new Object[] {"John", 35}); @@ -328,8 +365,10 @@ The preceding query can be parameterized and run as follows: client.sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)") .bind("tuples", tuples); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val tuples: MutableList> = ArrayList() tuples.add(arrayOf("John", 35)) @@ -338,19 +377,25 @@ The preceding query can be parameterized and run as follows: client.sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)") .bind("tuples", tuples) ---- +====== NOTE: Usage of select lists is vendor-dependent. The following example shows a simpler variant using `IN` predicates: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.sql("SELECT id, name, state FROM table WHERE age IN (:ages)") .bind("ages", Arrays.asList(35, 50)); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val tuples: MutableList> = ArrayList() tuples.add(arrayOf("John", 35)) @@ -359,6 +404,7 @@ The following example shows a simpler variant using `IN` predicates: client.sql("SELECT id, name, state FROM table WHERE age IN (:ages)") .bind("tuples", arrayOf(35, 50)) ---- +====== NOTE: R2DBC itself does not support Collection-like values. Nevertheless, expanding a given `List` in the example above works for named parameters @@ -376,27 +422,36 @@ before it gets run. Register a `Statement` filter (`StatementFilterFunction`) through `DatabaseClient` to intercept and modify statements in their execution, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") .filter((s, next) -> next.execute(s.returnGeneratedValues("id"))) .bind("name", …) .bind("state", …); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") .filter { s: Statement, next: ExecuteFunction -> next.execute(s.returnGeneratedValues("id")) } .bind("name", …) .bind("state", …) ---- +====== `DatabaseClient` exposes also simplified `filter(…)` overload accepting `Function`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") .filter(statement -> s.returnGeneratedValues("id")); @@ -404,8 +459,10 @@ modify statements in their execution, as the following example shows: client.sql("SELECT id, name, state FROM table") .filter(statement -> s.fetchSize(25)); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") .filter { statement -> s.returnGeneratedValues("id") } @@ -413,6 +470,7 @@ modify statements in their execution, as the following example shows: client.sql("SELECT id, name, state FROM table") .filter { statement -> s.fetchSize(25) } ---- +====== `StatementFilterFunction` implementations allow filtering of the `Statement` and filtering of `Result` objects. @@ -432,8 +490,11 @@ that shared `ConnectionFactory` bean into your DAO classes. The `DatabaseClient` the setter for the `ConnectionFactory`. This leads to DAOs that resemble the following: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class R2dbcCorporateEventDao implements CorporateEventDao { @@ -446,8 +507,10 @@ the setter for the `ConnectionFactory`. This leads to DAOs that resemble the fol // R2DBC-backed implementations of the methods on the CorporateEventDao follow... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class R2dbcCorporateEventDao(connectionFactory: ConnectionFactory) : CorporateEventDao { @@ -456,6 +519,7 @@ the setter for the `ConnectionFactory`. This leads to DAOs that resemble the fol // R2DBC-backed implementations of the methods on the CorporateEventDao follow... } ---- +====== -- An alternative to explicit configuration is to use component-scanning and annotation @@ -464,8 +528,11 @@ support for dependency injection. In this case, you can annotate the class with method with `@Autowired`. The following example shows how to do so: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component // <1> public class R2dbcCorporateEventDao implements CorporateEventDao { @@ -480,6 +547,7 @@ method with `@Autowired`. The following example shows how to do so: // R2DBC-backed implementations of the methods on the CorporateEventDao follow... } ---- +====== <1> Annotate the class with `@Component`. <2> Annotate the `ConnectionFactory` setter method with `@Autowired`. <3> Create a new `DatabaseClient` with the `ConnectionFactory`. @@ -516,8 +584,11 @@ that defines an auto-increment or identity column. To get full control over the column name to generate, simply register a `StatementFilterFunction` that requests the generated key for the desired column. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono generatedId = client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") .filter(statement -> s.returnGeneratedValues("id")) @@ -526,8 +597,10 @@ requests the generated key for the desired column. // generatedId emits the generated key once the INSERT statement has finished ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val generatedId = client.sql("INSERT INTO table (name, state) VALUES(:name, :state)") .filter { statement -> s.returnGeneratedValues("id") } @@ -536,6 +609,7 @@ requests the generated key for the desired column. // generatedId emits the generated key once the INSERT statement has finished ---- +====== [[r2dbc-connections]] @@ -575,16 +649,22 @@ To configure a `ConnectionFactory`: The following example shows how to configure a `ConnectionFactory`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ConnectionFactory factory = ConnectionFactories.get("r2dbc:h2:mem:///test?options=DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val factory = ConnectionFactories.get("r2dbc:h2:mem:///test?options=DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"); ---- +====== [[r2dbc-ConnectionFactoryUtils]] diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc index 83c9609e7000..a43d6e06fb4e 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc @@ -15,8 +15,11 @@ The ease-of-use afforded by the use of the `@Transactional` annotation is best illustrated with an example, which is explained in the text that follows. Consider the following class definition: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // the service class that we want to make transactional @Transactional @@ -43,8 +46,10 @@ Consider the following class definition: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // the service class that we want to make transactional @Transactional @@ -67,6 +72,7 @@ Consider the following class definition: } } ---- +====== Used at the class level as above, the annotation indicates a default for all methods of the declaring class (as well as its subclasses). Alternatively, each method can be @@ -128,8 +134,11 @@ preceding example. Reactive transactional methods use reactive return types in contrast to imperative programming arrangements as the following listing shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // the reactive service class that we want to make transactional @Transactional @@ -156,8 +165,10 @@ programming arrangements as the following listing shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // the reactive service class that we want to make transactional @Transactional @@ -180,6 +191,7 @@ programming arrangements as the following listing shows: } } ---- +====== Note that there are special considerations for the returned `Publisher` with regards to Reactive Streams cancellation signals. See the xref:data-access/transaction/programmatic.adoc#tx-prog-operator-cancel[Cancel Signals] section under @@ -322,8 +334,11 @@ annotated at the class level with the settings for a read-only transaction, but `@Transactional` annotation on the `updateFoo(Foo)` method in the same class takes precedence over the transactional settings defined at the class level. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Transactional(readOnly = true) public class DefaultFooService implements FooService { @@ -339,8 +354,10 @@ precedence over the transactional settings defined at the class level. } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Transactional(readOnly = true) class DefaultFooService : FooService { @@ -356,6 +373,7 @@ precedence over the transactional settings defined at the class level. } } ---- +====== [[transaction-declarative-attransactional-settings]] @@ -455,8 +473,11 @@ of the transaction manager bean. For example, using the qualifier notation, you combine the following Java code with the following transaction manager bean declarations in the application context: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class TransactionalService { @@ -470,8 +491,10 @@ in the application context: public Mono doSomethingReactive() { ... } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- class TransactionalService { @@ -491,6 +514,7 @@ in the application context: } } ---- +====== The following listing shows the bean declarations: @@ -527,8 +551,11 @@ methods, xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[Spring's define custom composed annotations for your specific use cases. For example, consider the following annotation definitions: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @@ -542,8 +569,10 @@ following annotation definitions: public @interface AccountTx { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.FUNCTION, AnnotationTarget.TYPE) @Retention(AnnotationRetention.RUNTIME) @@ -555,11 +584,15 @@ following annotation definitions: @Transactional(transactionManager = "account", label = ["retryable"]) annotation class AccountTx ---- +====== The preceding annotations let us write the example from the previous section as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class TransactionalService { @@ -574,8 +607,10 @@ The preceding annotations let us write the example from the previous section as } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- class TransactionalService { @@ -590,6 +625,7 @@ The preceding annotations let us write the example from the previous section as } } ---- +====== In the preceding example, we used the syntax to define the transaction manager qualifier and transactional labels, but we could also have included propagation behavior, diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc index 38d49bc4b095..bcd41b9ab7cf 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc @@ -18,8 +18,11 @@ configuration and AOP in general. The following code shows the simple profiling aspect discussed earlier: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package x.y; @@ -55,8 +58,10 @@ The following code shows the simple profiling aspect discussed earlier: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary",chomp="-packages"] -.Kotlin ---- package x.y @@ -92,6 +97,7 @@ The following code shows the simple profiling aspect discussed earlier: } } ---- +====== The ordering of advice is controlled through the `Ordered` interface. For full details on advice ordering, see diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc index 477d4b0e9e6b..58a65cafff62 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc @@ -20,8 +20,11 @@ xref:core/aop.adoc[AOP] respectively. The following example shows how to create a transaction manager and configure the `AnnotationTransactionAspect` to use it: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // construct an appropriate transaction manager DataSourceTransactionManager txManager = new DataSourceTransactionManager(getDataSource()); @@ -29,8 +32,10 @@ The following example shows how to create a transaction manager and configure th // configure the AnnotationTransactionAspect to use it; this must be done before executing any transactional methods AnnotationTransactionAspect.aspectOf().setTransactionManager(txManager); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // construct an appropriate transaction manager val txManager = DataSourceTransactionManager(getDataSource()) @@ -38,6 +43,7 @@ The following example shows how to create a transaction manager and configure th // configure the AnnotationTransactionAspect to use it; this must be done before executing any transactional methods AnnotationTransactionAspect.aspectOf().transactionManager = txManager ---- +====== NOTE: When you use this aspect, you must annotate the implementation class (or the methods within that class or both), not the interface (if any) that the class implements. AspectJ diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc index 5bbe41208f1c..c84bd17412ff 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc @@ -10,8 +10,11 @@ transactions being created and then rolled back in response to the `UnsupportedOperationException` instance. The following listing shows the `FooService` interface: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- // the service interface that we want to make transactional @@ -29,8 +32,10 @@ interface: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- // the service interface that we want to make transactional @@ -47,11 +52,15 @@ interface: fun updateFoo(foo: Foo) } ---- +====== The following example shows an implementation of the preceding interface: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package x.y.service; @@ -78,8 +87,10 @@ The following example shows an implementation of the preceding interface: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package x.y.service @@ -102,6 +113,7 @@ The following example shows an implementation of the preceding interface: } } ---- +====== Assume that the first two methods of the `FooService` interface, `getFoo(String)` and `getFoo(String, String)`, must run in the context of a transaction with read-only @@ -215,8 +227,11 @@ a transaction is started, suspended, marked as read-only, and so on, depending o transaction configuration associated with that method. Consider the following program that test drives the configuration shown earlier: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public final class Boot { @@ -227,8 +242,10 @@ that test drives the configuration shown earlier: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -238,6 +255,7 @@ that test drives the configuration shown earlier: fooService.insertFoo(Foo()) } ---- +====== The output from running the preceding program should resemble the following (the Log4J output and the stack trace from the `UnsupportedOperationException` thrown by the @@ -281,8 +299,11 @@ return type is reactive. The following listing shows a modified version of the previously used `FooService`, but this time the code uses reactive types: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- // the reactive service interface that we want to make transactional @@ -300,8 +321,10 @@ this time the code uses reactive types: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- // the reactive service interface that we want to make transactional @@ -318,11 +341,15 @@ this time the code uses reactive types: fun updateFoo(foo: Foo) : Mono } ---- +====== The following example shows an implementation of the preceding interface: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] -.Java ---- package x.y.service; @@ -349,8 +376,10 @@ The following example shows an implementation of the preceding interface: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"] -.Kotlin ---- package x.y.service @@ -373,6 +402,7 @@ The following example shows an implementation of the preceding interface: } } ---- +====== Imperative and reactive transaction management share the same semantics for transaction boundary and transaction attribute definitions. The main difference between imperative diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc index 1145aabb86d8..b002be989d24 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc @@ -26,8 +26,11 @@ automatically rolled back in case of a failure. For more information on Vavr's T refer to the [official Vavr documentation](https://www.vavr.io/vavr-docs/#_try). Here's an example of how to use Vavr's Try with a transactional method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Transactional public Try myTransactionalMethod() { @@ -37,6 +40,7 @@ Here's an example of how to use Vavr's Try with a transactional method: return Try.of(delegate::myDataAccessOperation); } ---- +====== Checked exceptions that are thrown from a transactional method do not result in a rollback in the default configuration. You can configure exactly which `Exception` types mark a @@ -138,8 +142,11 @@ is quite invasive and tightly couples your code to the Spring Framework's transa infrastructure. The following example shows how to programmatically indicate a required rollback: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public void resolvePosition() { try { @@ -150,8 +157,10 @@ rollback: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun resolvePosition() { try { @@ -162,6 +171,7 @@ rollback: } } ---- +====== You are strongly encouraged to use the declarative approach to rollback, if at all possible. Programmatic rollback is available should you absolutely need it, but its diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/event.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/event.adoc index 7bdbad98b330..b4edfd8c4e21 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/event.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/event.adoc @@ -15,8 +15,11 @@ event and that we want to define a listener that should only handle that event o transaction in which it has been published has committed successfully. The following example sets up such an event listener: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class MyComponent { @@ -27,8 +30,10 @@ example sets up such an event listener: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class MyComponent { @@ -39,6 +44,7 @@ example sets up such an event listener: } } ---- +====== The `@TransactionalEventListener` annotation exposes a `phase` attribute that lets you customize the phase of the transaction to which the listener should be bound. diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc index 4b211aff981f..6c4bbb7021fa 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc @@ -33,8 +33,11 @@ anonymous inner class) that contains the code that you need to run in the contex a transaction. You can then pass an instance of your custom `TransactionCallback` to the `execute(..)` method exposed on the `TransactionTemplate`. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleService implements Service { @@ -57,8 +60,10 @@ a transaction. You can then pass an instance of your custom `TransactionCallback } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // use constructor-injection to supply the PlatformTransactionManager class SimpleService(transactionManager: PlatformTransactionManager) : Service { @@ -72,13 +77,17 @@ a transaction. You can then pass an instance of your custom `TransactionCallback } } ---- +====== If there is no return value, you can use the convenient `TransactionCallbackWithoutResult` class with an anonymous class, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- transactionTemplate.execute(new TransactionCallbackWithoutResult() { protected void doInTransactionWithoutResult(TransactionStatus status) { @@ -87,8 +96,10 @@ with an anonymous class, as follows: } }); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- transactionTemplate.execute(object : TransactionCallbackWithoutResult() { override fun doInTransactionWithoutResult(status: TransactionStatus) { @@ -97,13 +108,17 @@ with an anonymous class, as follows: } }) ---- +====== Code within the callback can roll the transaction back by calling the `setRollbackOnly()` method on the supplied `TransactionStatus` object, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- transactionTemplate.execute(new TransactionCallbackWithoutResult() { @@ -117,8 +132,10 @@ Code within the callback can roll the transaction back by calling the } }); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- transactionTemplate.execute(object : TransactionCallbackWithoutResult() { @@ -132,6 +149,7 @@ Code within the callback can roll the transaction back by calling the } }) ---- +====== [[tx-prog-template-settings]] === Specifying Transaction Settings @@ -143,8 +161,11 @@ xref:data-access/transaction/declarative/txadvice-settings.adoc[default transact following example shows the programmatic customization of the transactional settings for a specific `TransactionTemplate:` +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleService implements Service { @@ -160,8 +181,10 @@ a specific `TransactionTemplate:` } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SimpleService(transactionManager: PlatformTransactionManager) : Service { @@ -173,6 +196,7 @@ a specific `TransactionTemplate:` } } ---- +====== The following example defines a `TransactionTemplate` with some custom transactional settings by using Spring XML configuration: @@ -212,8 +236,11 @@ to make yourself. Application code that must run in a transactional context and that explicitly uses the `TransactionalOperator` resembles the next example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleService implements Service { @@ -235,8 +262,10 @@ the `TransactionalOperator` resembles the next example: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // use constructor-injection to supply the ReactiveTransactionManager class SimpleService(transactionManager: ReactiveTransactionManager) : Service { @@ -250,6 +279,7 @@ the `TransactionalOperator` resembles the next example: } } ---- +====== `TransactionalOperator` can be used in two ways: @@ -259,8 +289,11 @@ the `TransactionalOperator` resembles the next example: Code within the callback can roll the transaction back by calling the `setRollbackOnly()` method on the supplied `ReactiveTransaction` object, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- transactionalOperator.execute(new TransactionCallback<>() { @@ -271,8 +304,10 @@ method on the supplied `ReactiveTransaction` object, as follows: } }); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- transactionalOperator.execute(object : TransactionCallback() { @@ -282,6 +317,7 @@ method on the supplied `ReactiveTransaction` object, as follows: } }) ---- +====== [[tx-prog-operator-cancel]] === Cancel Signals @@ -306,8 +342,11 @@ xref:data-access/transaction/declarative/txadvice-settings.adoc[default transact following example shows customization of the transactional settings for a specific `TransactionalOperator:` +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SimpleService implements Service { @@ -325,8 +364,10 @@ following example shows customization of the transactional settings for a specif } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SimpleService(transactionManager: ReactiveTransactionManager) : Service { @@ -339,6 +380,7 @@ following example shows customization of the transactional settings for a specif private val transactionalOperator = TransactionalOperator(transactionManager, definition) } ---- +====== [[transaction-programmatic-tm]] == Using the `TransactionManager` @@ -356,8 +398,11 @@ use to your bean through a bean reference. Then, by using the `TransactionDefini `TransactionStatus` objects, you can initiate transactions, roll back, and commit. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DefaultTransactionDefinition def = new DefaultTransactionDefinition(); // explicitly setting the transaction name is something that can be done only programmatically @@ -373,8 +418,10 @@ following example shows how to do so: } txManager.commit(status); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val def = DefaultTransactionDefinition() // explicitly setting the transaction name is something that can be done only programmatically @@ -391,6 +438,7 @@ following example shows how to do so: txManager.commit(status) ---- +====== [[transaction-programmatic-rtm]] @@ -403,8 +451,11 @@ use to your bean through a bean reference. Then, by using the `TransactionDefini `ReactiveTransaction` objects, you can initiate transactions, roll back, and commit. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DefaultTransactionDefinition def = new DefaultTransactionDefinition(); // explicitly setting the transaction name is something that can be done only programmatically @@ -421,8 +472,10 @@ following example shows how to do so: .onErrorResume(ex -> txManager.rollback(status).then(Mono.error(ex))); }); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val def = DefaultTransactionDefinition() // explicitly setting the transaction name is something that can be done only programmatically @@ -438,5 +491,6 @@ following example shows how to do so: .onErrorResume { ex -> txManager.rollback(status).then(Mono.error(ex)) } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/bean-definition-dsl.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/bean-definition-dsl.adoc index 5309da8d9213..68949a9bf0bc 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/bean-definition-dsl.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/bean-definition-dsl.adoc @@ -38,12 +38,10 @@ you can instead write the following: registerBean { Bar(it.getBean()) } } ---- -==== When the class `Bar` has a single constructor, you can even just specify the bean class, the constructor parameters will be autowired by type: -==== [source,kotlin,indent=0] ---- val context = GenericApplicationContext().apply { diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc index 721eda14c8a0..021d436a37d1 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc @@ -256,7 +256,6 @@ in order to use `val` instead of `lateinit var`. You can use {api-spring-framework}/test/context/TestConstructor.html[`@TestConstructor(autowireMode = AutowireMode.ALL)`] to enable autowiring for all parameters. -==== [source,kotlin,indent=0] ---- @SpringJUnitConfig(TestConfig::class) @@ -267,7 +266,6 @@ class OrderServiceIntegrationTests(val orderService: OrderService, // tests that use the injected OrderService and CustomerService } ---- -==== [[per_class-lifecycle]] diff --git a/framework-docs/modules/ROOT/pages/rsocket.adoc b/framework-docs/modules/ROOT/pages/rsocket.adoc index 0672161ec6ce..13777f8f9f25 100644 --- a/framework-docs/modules/ROOT/pages/rsocket.adoc +++ b/framework-docs/modules/ROOT/pages/rsocket.adoc @@ -180,8 +180,11 @@ settings for the `SETUP` frame. This is the most basic way to connect with default settings: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RSocketRequester requester = RSocketRequester.builder().tcp("localhost", 7000); @@ -189,14 +192,16 @@ This is the most basic way to connect with default settings: RSocketRequester requester = RSocketRequester.builder().webSocket(url); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val requester = RSocketRequester.builder().tcp("localhost", 7000) URI url = URI.create("https://example.org:8080/rsocket"); val requester = RSocketRequester.builder().webSocket(url) ---- +====== The above does not connect immediately. When requests are made, a shared connection is established transparently and used. @@ -233,8 +238,11 @@ metadata values. By default only the basic codecs from `spring-core` for `String `byte[]`, and `ByteBuffer` are registered. Adding `spring-web` provides access to more that can be registered as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RSocketStrategies strategies = RSocketStrategies.builder() .encoders(encoders -> encoders.add(new Jackson2CborEncoder())) @@ -246,8 +254,9 @@ can be registered as follows: .tcp("localhost", 7000); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val strategies = RSocketStrategies.builder() .encoders { it.add(Jackson2CborEncoder()) } @@ -258,6 +267,7 @@ can be registered as follows: .rsocketStrategies(strategies) .tcp("localhost", 7000) ---- +====== `RSocketStrategies` is designed for re-use. In some scenarios, e.g. client and server in the same application, it may be preferable to declare it in Spring configuration. @@ -272,8 +282,11 @@ server. You can use annotated handlers for client-side responding based on the same infrastructure that's used on a server, but registered programmatically as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RSocketStrategies strategies = RSocketStrategies.builder() .routeMatcher(new PathPatternRouteMatcher()) // <1> @@ -286,6 +299,7 @@ infrastructure that's used on a server, but registered programmatically as follo .rsocketConnector(connector -> connector.acceptor(responder)) // <3> .tcp("localhost", 7000); ---- +====== <1> Use `PathPatternRouteMatcher`, if `spring-web` is present, for efficient route matching. <2> Create a responder from a class with `@MessageMapping` and/or `@ConnectMapping` methods. @@ -314,8 +328,11 @@ Note the above is only a shortcut designed for programmatic registration of clie responders. For alternative scenarios, where client responders are in Spring configuration, you can still declare `RSocketMessageHandler` as a Spring bean and then apply as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext context = ... ; RSocketMessageHandler handler = context.getBean(RSocketMessageHandler.class); @@ -325,8 +342,9 @@ you can still declare `RSocketMessageHandler` as a Spring bean and then apply as .tcp("localhost", 7000); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -337,6 +355,7 @@ you can still declare `RSocketMessageHandler` as a Spring bean and then apply as .rsocketConnector { it.acceptor(handler.responder()) } .tcp("localhost", 7000) ---- +====== For the above you may also need to use `setHandlerPredicate` in `RSocketMessageHandler` to switch to a different strategy for detecting client responders, e.g. based on a custom @@ -355,8 +374,11 @@ See also xref:rsocket.adoc#rsocket-annot-responders[Annotated Responders], for m intervals, session resumption, interceptors, and more. You can configure options at that level as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RSocketRequester requester = RSocketRequester.builder() .rsocketConnector(connector -> { @@ -365,8 +387,9 @@ at that level as follows: .tcp("localhost", 7000); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val requester = RSocketRequester.builder() .rsocketConnector { @@ -374,6 +397,7 @@ at that level as follows: } .tcp("localhost", 7000) ---- +====== [[rsocket-requester-server]] @@ -388,8 +412,11 @@ mind that `@ConnectMapping` methods are essentially handlers of the `SETUP` fram must be handled before requests can begin. Therefore, requests at the very start must be decoupled from handling. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ConnectMapping Mono handle(RSocketRequester requester) { @@ -401,6 +428,7 @@ decoupled from handling. For example: return ... // <2> } ---- +====== <1> Start the request asynchronously, independent from handling. <2> Perform handling and return completion `Mono`. @@ -428,8 +456,11 @@ decoupled from handling. For example: Once you have a xref:rsocket.adoc#rsocket-requester-client[client] or xref:rsocket.adoc#rsocket-requester-server[server] requester, you can make requests as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ViewBox viewBox = ... ; @@ -438,6 +469,7 @@ xref:rsocket.adoc#rsocket-requester-server[server] requester, you can make reque .retrieveFlux(AirportLocation.class); // <3> ---- +====== <1> Specify a route to include in the metadata of the request message. <2> Provide data for the request message. <3> Declare the expected response. @@ -475,27 +507,36 @@ data(Object producer, ParameterizedTypeReference elementTypeRef); The `data(Object)` step is optional. Skip it for requests that don't send data: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono location = requester.route("find.radar.EWR")) .retrieveMono(AirportLocation.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.messaging.rsocket.retrieveAndAwait val location = requester.route("find.radar.EWR") .retrieveAndAwait() ---- +====== Extra metadata values can be added if using {gh-rsocket-extensions}/CompositeMetadata.md[composite metadata] (the default) and if the values are supported by a registered `Encoder`. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- String securityToken = ... ; ViewBox viewBox = ... ; @@ -506,8 +547,10 @@ values are supported by a registered `Encoder`. For example: .data(viewBox) .retrieveFlux(AirportLocation.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.messaging.rsocket.retrieveFlow @@ -522,6 +565,7 @@ values are supported by a registered `Encoder`. For example: .data(viewBox) .retrieveFlow() ---- +====== For `Fire-and-Forget` use the `send()` method that returns `Mono`. Note that the `Mono` indicates only that the message was successfully sent, and not that it was handled. @@ -547,8 +591,11 @@ To use annotated responders on the server side, add `RSocketMessageHandler` to y configuration to detect `@Controller` beans with `@MessageMapping` and `@ConnectMapping` methods: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration static class ServerConfig { @@ -561,8 +608,10 @@ methods: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class ServerConfig { @@ -573,12 +622,16 @@ methods: } } ---- +====== Then start an RSocket server through the Java RSocket API and plug the `RSocketMessageHandler` for the responder as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext context = ... ; RSocketMessageHandler handler = context.getBean(RSocketMessageHandler.class); @@ -588,8 +641,10 @@ Then start an RSocket server through the Java RSocket API and plug the .bind(TcpServerTransport.create("localhost", 7000)) .block(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.beans.factory.getBean @@ -600,6 +655,7 @@ Then start an RSocket server through the Java RSocket API and plug the .bind(TcpServerTransport.create("localhost", 7000)) .awaitSingle() ---- +====== `RSocketMessageHandler` supports {gh-rsocket-extensions}/CompositeMetadata.md[composite] and @@ -619,8 +675,11 @@ decoding as with HTTP URLs. `RSocketMessageHandler` can be configured via `RSocketStrategies` which may be useful if you need to share configuration between a client and a server in the same process: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration static class ServerConfig { @@ -642,8 +701,10 @@ you need to share configuration between a client and a server in the same proces } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class ServerConfig { @@ -661,6 +722,7 @@ you need to share configuration between a client and a server in the same proces .build() } ---- +====== @@ -680,8 +742,11 @@ Once xref:rsocket.adoc#rsocket-annot-responders-server[server] or xref:rsocket.adoc#rsocket-annot-responders-client[client] responder configuration is in place, `@MessageMapping` methods can be used as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class RadarsController { @@ -692,8 +757,10 @@ xref:rsocket.adoc#rsocket-annot-responders-client[client] responder configuratio } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller class RadarsController { @@ -704,6 +771,7 @@ class RadarsController { } } ---- +====== The above `@MessageMapping` method responds to a Request-Stream interaction having the route "locate.radars.within". It supports a flexible method signature with the option to @@ -833,28 +901,37 @@ the box it has built-in support for `String` and saves under the "route" key. For any other mime type you'll need to provide a `Decoder` and register the mime type as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DefaultMetadataExtractor extractor = new DefaultMetadataExtractor(metadataDecoders); extractor.metadataToExtract(fooMimeType, Foo.class, "foo"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.messaging.rsocket.metadataToExtract val extractor = DefaultMetadataExtractor(metadataDecoders) extractor.metadataToExtract(fooMimeType, "foo") ---- +====== Composite metadata works well to combine independent metadata values. However the requester might not support composite metadata, or may choose not to use it. For this, `DefaultMetadataExtractor` may needs custom logic to map the decoded value to the output map. Here is an example where JSON is used for metadata: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- DefaultMetadataExtractor extractor = new DefaultMetadataExtractor(metadataDecoders); extractor.metadataToExtract( @@ -864,8 +941,10 @@ map. Here is an example where JSON is used for metadata: outputMap.putAll(jsonMap); }); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.messaging.rsocket.metadataToExtract @@ -874,13 +953,17 @@ map. Here is an example where JSON is used for metadata: outputMap.putAll(jsonMap) } ---- +====== When configuring `MetadataExtractor` through `RSocketStrategies`, you can let `RSocketStrategies.Builder` create the extractor with the configured decoders, and simply use a callback to customize registrations as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RSocketStrategies strategies = RSocketStrategies.builder() .metadataExtractorRegistry(registry -> { @@ -889,8 +972,10 @@ simply use a callback to customize registrations as follows: }) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.messaging.rsocket.metadataToExtract @@ -901,6 +986,7 @@ simply use a callback to customize registrations as follows: } .build() ---- +====== diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc index aaa87fca2acc..98f394130e51 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc @@ -25,14 +25,18 @@ classes may be declared with the `value` attribute in `@SpringJUnitConfig`. The following example shows how to use the `@SpringJUnitConfig` annotation to specify a configuration class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestConfig.class) // <1> class ConfigurationClassJUnitJupiterSpringTests { // class body... } ---- +====== <1> Specify the configuration class. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -49,14 +53,18 @@ configuration class: The following example shows how to use the `@SpringJUnitConfig` annotation to specify the location of a configuration file: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(locations = "/test-config.xml") // <1> class XmlJUnitJupiterSpringTests { // class body... } ---- +====== <1> Specify the location of a configuration file. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -90,14 +98,18 @@ attribute from `@WebAppConfiguration` only by using the `resourcePath` attribute The following example shows how to use the `@SpringJUnitWebConfig` annotation to specify a configuration class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitWebConfig(TestConfig.class) // <1> class ConfigurationClassJUnitJupiterSpringWebTests { // class body... } ---- +====== <1> Specify the configuration class. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -114,14 +126,18 @@ a configuration class: The following example shows how to use the `@SpringJUnitWebConfig` annotation to specify the location of a configuration file: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitWebConfig(locations = "/test-config.xml") // <1> class XmlJUnitJupiterSpringWebTests { // class body... } ---- +====== <1> Specify the location of a configuration file. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -248,8 +264,11 @@ equivalent to `@Disabled` and `@EnabledIf("true")` is logically meaningless. You can use `@EnabledIf` as a meta-annotation to create custom composed annotations. For example, you can create a custom `@EnabledOnMac` annotation as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @@ -259,8 +278,10 @@ example, you can create a custom `@EnabledOnMac` annotation as follows: ) public @interface EnabledOnMac {} ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION) @Retention(AnnotationRetention.RUNTIME) @@ -270,6 +291,7 @@ example, you can create a custom `@EnabledOnMac` annotation as follows: ) annotation class EnabledOnMac {} ---- +====== [NOTE] ==== @@ -308,8 +330,11 @@ equivalent to `@Disabled` and `@DisabledIf("false")` is logically meaningless. You can use `@DisabledIf` as a meta-annotation to create custom composed annotations. For example, you can create a custom `@DisabledOnMac` annotation as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @@ -320,8 +345,9 @@ example, you can create a custom `@DisabledOnMac` annotation as follows: public @interface DisabledOnMac {} ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION) @Retention(AnnotationRetention.RUNTIME) @@ -331,6 +357,7 @@ example, you can create a custom `@DisabledOnMac` annotation as follows: ) annotation class DisabledOnMac {} ---- +====== [NOTE] ==== diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc index 924a17f81c73..d228a83c1857 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc @@ -27,8 +27,11 @@ means the test is implicitly enabled. This is analogous to the semantics of JUni The following example shows a test that has an `@IfProfileValue` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @IfProfileValue(name="java.vendor", value="Oracle Corporation") // <1> @Test @@ -36,6 +39,7 @@ The following example shows a test that has an `@IfProfileValue` annotation: // some logic that should run only on Java VMs from Oracle Corporation } ---- +====== <1> Run this test only when the Java vendor is "Oracle Corporation". [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -54,8 +58,11 @@ Alternatively, you can configure `@IfProfileValue` with a list of `values` (with semantics) to achieve TestNG-like support for test groups in a JUnit 4 environment. Consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @IfProfileValue(name="test-groups", values={"unit-tests", "integration-tests"}) // <1> @Test @@ -63,6 +70,7 @@ Consider the following example: // some logic that should run only for unit and integration test groups } ---- +====== <1> Run this test for unit tests and integration tests. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -86,14 +94,18 @@ of `ProfileValueSource` to use when retrieving profile values configured through test, `SystemProfileValueSource` is used by default. The following example shows how to use `@ProfileValueSourceConfiguration`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ProfileValueSourceConfiguration(CustomProfileValueSource.class) // <1> public class CustomProfileValueSourceTests { // class body... } ---- +====== <1> Use a custom profile value source. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -118,14 +130,18 @@ The time period includes running the test method itself, any repetitions of the `@Repeat`), as well as any setting up or tearing down of the test fixture. The following example shows how to use it: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Timed(millis = 1000) // <1> public void testProcessWithOneSecondTimeout() { // some logic that should not take longer than 1 second to run } ---- +====== <1> Set the time period for the test to one second. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -158,8 +174,11 @@ xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules preparation of the test instance by `TestExecutionListener` implementations. The following example shows how to use the `@Repeat` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Repeat(10) // <1> @Test @@ -167,6 +186,7 @@ following example shows how to use the `@Repeat` annotation: // ... } ---- +====== <1> Repeat this test ten times. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc index 66ee7b11232b..1e992c75e865 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc @@ -38,8 +38,11 @@ xref:testing/testcontext-framework.adoc[TestContext framework]. Consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RunWith(SpringRunner.class) @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) @@ -54,8 +57,9 @@ Consider the following example: public class UserRepositoryTests { } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RunWith(SpringRunner::class) @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") @@ -69,13 +73,17 @@ Consider the following example: @Transactional class UserRepositoryTests { } ---- +====== If we discover that we are repeating the preceding configuration across our JUnit 4-based test suite, we can reduce the duplication by introducing a custom composed annotation that centralizes the common test configuration for Spring, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @@ -85,8 +93,9 @@ that centralizes the common test configuration for Spring, as follows: public @interface TransactionalDevTestConfig { } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.TYPE) @Retention(AnnotationRetention.RUNTIME) @@ -95,12 +104,16 @@ that centralizes the common test configuration for Spring, as follows: @Transactional annotation class TransactionalDevTestConfig { } ---- +====== Then we can use our custom `@TransactionalDevTestConfig` annotation to simplify the configuration of individual JUnit 4 based test classes, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RunWith(SpringRunner.class) @TransactionalDevTestConfig @@ -111,8 +124,9 @@ configuration of individual JUnit 4 based test classes, as follows: public class UserRepositoryTests { } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RunWith(SpringRunner::class) @TransactionalDevTestConfig @@ -122,13 +136,17 @@ configuration of individual JUnit 4 based test classes, as follows: @TransactionalDevTestConfig class UserRepositoryTests ---- +====== If we write tests that use JUnit Jupiter, we can reduce code duplication even further, since annotations in JUnit 5 can also be used as meta-annotations. Consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"}) @@ -142,8 +160,10 @@ example: @Transactional class UserRepositoryTests { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) @ContextConfiguration("/app-config.xml", "/test-data-access-config.xml") @@ -157,14 +177,18 @@ example: @Transactional class UserRepositoryTests { } ---- +====== If we discover that we are repeating the preceding configuration across our JUnit Jupiter-based test suite, we can reduce the duplication by introducing a custom composed annotation that centralizes the common test configuration for Spring and JUnit Jupiter, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @@ -174,8 +198,10 @@ as follows: @Transactional public @interface TransactionalDevTestConfig { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.TYPE) @Retention(AnnotationRetention.RUNTIME) @@ -185,12 +211,16 @@ as follows: @Transactional annotation class TransactionalDevTestConfig { } ---- +====== Then we can use our custom `@TransactionalDevTestConfig` annotation to simplify the configuration of individual JUnit Jupiter based test classes, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @TransactionalDevTestConfig class OrderRepositoryTests { } @@ -198,8 +228,10 @@ configuration of individual JUnit Jupiter based test classes, as follows: @TransactionalDevTestConfig class UserRepositoryTests { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @TransactionalDevTestConfig class OrderRepositoryTests { } @@ -207,6 +239,7 @@ configuration of individual JUnit Jupiter based test classes, as follows: @TransactionalDevTestConfig class UserRepositoryTests { } ---- +====== Since JUnit Jupiter supports the use of `@Test`, `@RepeatedTest`, `ParameterizedTest`, and others as meta-annotations, you can also create custom composed annotations at the @@ -215,8 +248,11 @@ the `@Test` and `@Tag` annotations from JUnit Jupiter with the `@Transactional` annotation from Spring, we could create an `@TransactionalIntegrationTest` annotation, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @@ -225,8 +261,10 @@ follows: @Test // org.junit.jupiter.api.Test public @interface TransactionalIntegrationTest { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Target(AnnotationTarget.TYPE) @Retention(AnnotationRetention.RUNTIME) @@ -235,12 +273,16 @@ follows: @Test // org.junit.jupiter.api.Test annotation class TransactionalIntegrationTest { } ---- +====== Then we can use our custom `@TransactionalIntegrationTest` annotation to simplify the configuration of individual JUnit Jupiter based test methods, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @TransactionalIntegrationTest void saveOrder() { } @@ -249,8 +291,9 @@ configuration of individual JUnit Jupiter based test methods, as follows: void deleteOrder() { } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @TransactionalIntegrationTest fun saveOrder() { } @@ -258,6 +301,7 @@ configuration of individual JUnit Jupiter based test methods, as follows: @TransactionalIntegrationTest fun deleteOrder() { } ---- +====== For further details, see the https://github.com/spring-projects/spring-framework/wiki/Spring-Annotation-Programming-Model[Spring Annotation Programming Model] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc index 7ff17ec5425a..71217d5b79ce 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc @@ -7,8 +7,11 @@ integration test. The following example indicates that the `dev` profile should be active: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @ActiveProfiles("dev") // <1> @@ -16,6 +19,7 @@ The following example indicates that the `dev` profile should be active: // class body... } ---- +====== <1> Indicate that the `dev` profile should be active. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -33,8 +37,11 @@ The following example indicates that the `dev` profile should be active: The following example indicates that both the `dev` and the `integration` profiles should be active: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @ActiveProfiles({"dev", "integration"}) // <1> @@ -42,6 +49,7 @@ be active: // class body... } ---- +====== <1> Indicate that the `dev` and `integration` profiles should be active. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-aftertransaction.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-aftertransaction.adoc index d54a7343fe2f..680c554da08a 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-aftertransaction.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-aftertransaction.adoc @@ -7,14 +7,18 @@ transaction by using Spring's `@Transactional` annotation. `@AfterTransaction` m are not required to be `public` and may be declared on Java 8-based interface default methods. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @AfterTransaction // <1> void afterTransaction() { // logic to be run after a transaction has ended } ---- +====== <1> Run this method after a transaction. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-beforetransaction.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-beforetransaction.adoc index 943451ef2a82..3723945221e8 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-beforetransaction.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-beforetransaction.adoc @@ -9,14 +9,18 @@ methods. The following example shows how to use the `@BeforeTransaction` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @BeforeTransaction // <1> void beforeTransaction() { // logic to be run before a transaction is started } ---- +====== <1> Run this method before a transaction. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-commit.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-commit.adoc index 7702fcfa78b4..86278154703b 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-commit.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-commit.adoc @@ -9,8 +9,11 @@ annotation. The following example shows how to use the `@Commit` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Commit // <1> @Test @@ -18,6 +21,7 @@ The following example shows how to use the `@Commit` annotation: // ... } ---- +====== <1> Commit the result of the test to the database. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc index 8d783ac240ce..e5e8d853e994 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc @@ -15,14 +15,18 @@ xref:testing/testcontext-framework/ctx-management/javaconfig.adoc#testcontext-ct The following example shows a `@ContextConfiguration` annotation that refers to an XML file: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration("/test-config.xml") // <1> class XmlApplicationContextTests { // class body... } ---- +====== <1> Referring to an XML file. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -38,14 +42,18 @@ file: The following example shows a `@ContextConfiguration` annotation that refers to a class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration(classes = TestConfig.class) // <1> class ConfigClassApplicationContextTests { // class body... } ---- +====== <1> Referring to a class. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -63,14 +71,18 @@ As an alternative or in addition to declaring resource locations or component cl you can use `@ContextConfiguration` to declare `ApplicationContextInitializer` classes. The following example shows such a case: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration(initializers = CustomContextInitializer.class) // <1> class ContextInitializerTests { // class body... } ---- +====== <1> Declaring an initializer class. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -91,14 +103,18 @@ component `classes`. The following example uses both a location and a loader: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration(locations = "/test-context.xml", loader = CustomContextLoader.class) // <1> class CustomLoaderXmlApplicationContextTests { // class body... } ---- +====== <1> Configuring both a location and a custom loader. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc index 89bf31905899..f136a4da5c99 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc @@ -8,8 +8,11 @@ defines a level in the context hierarchy. The following examples demonstrate the `@ContextHierarchy` within a single test class (`@ContextHierarchy` can also be used within a test class hierarchy): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextHierarchy({ @ContextConfiguration("/parent-config.xml"), @@ -19,8 +22,10 @@ within a test class hierarchy): // class body... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ContextHierarchy( ContextConfiguration("/parent-config.xml"), @@ -29,9 +34,13 @@ within a test class hierarchy): // class body... } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @WebAppConfiguration @ContextHierarchy({ @@ -42,8 +51,10 @@ within a test class hierarchy): // class body... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @WebAppConfiguration @ContextHierarchy( @@ -53,6 +64,7 @@ within a test class hierarchy): // class body... } ---- +====== If you need to merge or override the configuration for a given level of the context hierarchy within a test class hierarchy, you must explicitly name that level by supplying diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dirtiescontext.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dirtiescontext.adoc index 9f6103a1c60a..2ccca2f0b08b 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dirtiescontext.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dirtiescontext.adoc @@ -20,14 +20,18 @@ configuration scenarios: * Before the current test class, when declared on a class with class mode set to `BEFORE_CLASS`. + +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @DirtiesContext(classMode = BEFORE_CLASS) // <1> class FreshContextTests { // some tests that require a new Spring container } ---- +====== <1> Dirty the context before the current test class. + [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -43,14 +47,18 @@ configuration scenarios: * After the current test class, when declared on a class with class mode set to `AFTER_CLASS` (i.e., the default class mode). + +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @DirtiesContext // <1> class ContextDirtyingTests { // some tests that result in the Spring container being dirtied } ---- +====== <1> Dirty the context after the current test class. + [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -67,14 +75,18 @@ configuration scenarios: * Before each test method in the current test class, when declared on a class with class mode set to `BEFORE_EACH_TEST_METHOD.` + +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @DirtiesContext(classMode = BEFORE_EACH_TEST_METHOD) // <1> class FreshContextTests { // some tests that require a new Spring container } ---- +====== <1> Dirty the context before each test method. + [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -91,14 +103,18 @@ mode set to `BEFORE_EACH_TEST_METHOD.` * After each test method in the current test class, when declared on a class with class mode set to `AFTER_EACH_TEST_METHOD.` + +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @DirtiesContext(classMode = AFTER_EACH_TEST_METHOD) // <1> class ContextDirtyingTests { // some tests that result in the Spring container being dirtied } ---- +====== <1> Dirty the context after each test method. + [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -115,8 +131,11 @@ mode set to `AFTER_EACH_TEST_METHOD.` * Before the current test, when declared on a method with the method mode set to `BEFORE_METHOD`. + +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @DirtiesContext(methodMode = BEFORE_METHOD) // <1> @Test @@ -124,6 +143,7 @@ mode set to `AFTER_EACH_TEST_METHOD.` // some logic that requires a new Spring container } ---- +====== <1> Dirty the context before the current test method. + [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -140,8 +160,11 @@ mode set to `AFTER_EACH_TEST_METHOD.` * After the current test, when declared on a method with the method mode set to `AFTER_METHOD` (i.e., the default method mode). + +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @DirtiesContext // <1> @Test @@ -149,6 +172,7 @@ mode set to `AFTER_EACH_TEST_METHOD.` // some logic that results in the Spring container being dirtied } ---- +====== <1> Dirty the context after the current test method. + [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -173,8 +197,11 @@ context are removed from the context cache and closed. If the exhaustive algorit overkill for a particular use case, you can specify the simpler current level algorithm, as the following example shows. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextHierarchy({ @ContextConfiguration("/parent-config.xml"), @@ -193,6 +220,7 @@ as the following example shows. } } ---- +====== <1> Use the current-level algorithm. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc index 21bafb5324d6..94edb68c3674 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc @@ -10,8 +10,11 @@ https://www.testcontainers.org/[Testcontainers] project. The following example demonstrates how to register a dynamic property: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration class MyIntegrationTests { @@ -26,6 +29,7 @@ The following example demonstrates how to register a dynamic property: // tests ... } ---- +====== <1> Annotate a `static` method with `@DynamicPropertySource`. <2> Accept a `DynamicPropertyRegistry` as an argument. <3> Register a dynamic `server.port` property to be retrieved lazily from the server. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc index d5eb93ed280a..1f2d84cf93eb 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc @@ -15,8 +15,11 @@ method, potentially overriding class-level `@Rollback` or `@Commit` semantics. The following example causes a test method's result to not be rolled back (that is, the result is committed to the database): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Rollback(false) // <1> @Test @@ -24,6 +27,7 @@ result is committed to the database): // ... } ---- +====== <1> Do not roll back the result. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc index 975e043e868c..982838d8b887 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc @@ -5,8 +5,11 @@ against a given database during integration tests. The following example shows how to use it: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Test @Sql({"/test-schema.sql", "/test-user-data.sql"}) // <1> @@ -14,6 +17,7 @@ it: // run code that relies on the test schema and test data } ---- +====== <1> Run two scripts for this test. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlconfig.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlconfig.adoc index 98c961544efc..128d6794f971 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlconfig.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlconfig.adoc @@ -4,8 +4,11 @@ `@SqlConfig` defines metadata that is used to determine how to parse and run SQL scripts configured with the `@Sql` annotation. The following example shows how to use it: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Test @Sql( @@ -16,6 +19,7 @@ configured with the `@Sql` annotation. The following example shows how to use it // run code that relies on the test data } ---- +====== <1> Set the comment prefix and the separator in SQL scripts. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlgroup.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlgroup.adoc index e75050853598..564645d30b3a 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlgroup.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlgroup.adoc @@ -7,8 +7,11 @@ in conjunction with Java 8's support for repeatable annotations, where `@Sql` ca declared several times on the same class or method, implicitly generating this container annotation. The following example shows how to declare an SQL group: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Test @SqlGroup({ // <1> @@ -19,6 +22,7 @@ annotation. The following example shows how to declare an SQL group: // run code that uses the test schema and test data } ---- +====== <1> Declare a group of SQL scripts. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlmergemode.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlmergemode.adoc index cd594989144c..8e101fcc0837 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlmergemode.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sqlmergemode.adoc @@ -11,8 +11,11 @@ Note that a method-level `@SqlMergeMode` declaration overrides a class-level dec The following example shows how to use `@SqlMergeMode` at the class level. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestConfig.class) @Sql("/test-schema.sql") @@ -26,6 +29,7 @@ The following example shows how to use `@SqlMergeMode` at the class level. } } ---- +====== <1> Set the `@Sql` merge mode to `MERGE` for all test methods in the class. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -47,8 +51,11 @@ The following example shows how to use `@SqlMergeMode` at the class level. The following example shows how to use `@SqlMergeMode` at the method level. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestConfig.class) @Sql("/test-schema.sql") @@ -62,6 +69,7 @@ The following example shows how to use `@SqlMergeMode` at the method level. } } ---- +====== <1> Set the `@Sql` merge mode to `MERGE` for a specific test method. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc index e79aa245eca2..998cb90a2fa1 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc @@ -8,8 +8,11 @@ xref:testing/testcontext-framework/tel-config.adoc[`TestExecutionListener` Confi The following example shows how to register two `TestExecutionListener` implementations: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @TestExecutionListeners({CustomTestExecutionListener.class, AnotherTestExecutionListener.class}) // <1> @@ -17,6 +20,7 @@ The following example shows how to register two `TestExecutionListener` implemen // class body... } ---- +====== <1> Register two `TestExecutionListener` implementations. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc index 40ba2240a392..97905b1dd4bd 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc @@ -8,8 +8,11 @@ integration test. The following example demonstrates how to declare a properties file from the classpath: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @TestPropertySource("/test.properties") // <1> @@ -17,6 +20,7 @@ The following example demonstrates how to declare a properties file from the cla // class body... } ---- +====== <1> Get properties from `test.properties` in the root of the classpath. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -33,8 +37,11 @@ The following example demonstrates how to declare a properties file from the cla The following example demonstrates how to declare inlined properties: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @TestPropertySource(properties = { "timezone = GMT", "port: 4242" }) // <1> @@ -42,6 +49,7 @@ The following example demonstrates how to declare inlined properties: // class body... } ---- +====== <1> Declare `timezone` and `port` properties. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-webappconfiguration.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-webappconfiguration.adoc index d81df81904df..568a722269db 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-webappconfiguration.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-webappconfiguration.adoc @@ -13,8 +13,11 @@ resource base path). The resource base path is used behind the scenes to create The following example shows how to use the `@WebAppConfiguration` annotation: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @WebAppConfiguration // <1> @@ -22,6 +25,7 @@ The following example shows how to use the `@WebAppConfiguration` annotation: // class body... } ---- +====== <1> The `@WebAppConfiguration` annotation. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -43,8 +47,11 @@ supported. If no resource prefix is supplied, the path is assumed to be a file s resource. The following example shows how to specify a classpath resource: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @WebAppConfiguration("classpath:test-web-resources") // <1> @@ -52,6 +59,7 @@ resource. The following example shows how to specify a classpath resource: // class body... } ---- +====== <1> Specifying a classpath resource. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-client.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-client.adoc index 1bbd496e264a..a223a9f4ca35 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-client.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-client.adoc @@ -6,8 +6,11 @@ idea is to declare expected requests and to provide "`stub`" responses so that y focus on testing the code in isolation (that is, without running a server). The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RestTemplate restTemplate = new RestTemplate(); @@ -18,8 +21,10 @@ example shows how to do so: mockServer.verify(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val restTemplate = RestTemplate() @@ -30,6 +35,7 @@ example shows how to do so: mockServer.verify() ---- +====== In the preceding example, `MockRestServiceServer` (the central class for client-side REST tests) configures the `RestTemplate` with a custom `ClientHttpRequestFactory` that @@ -45,24 +51,33 @@ can set the `ignoreExpectOrder` option when building the server, in which case a expectations are checked (in order) to find a match for a given request. That means requests are allowed to come in any order. The following example uses `ignoreExpectOrder`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- server = MockRestServiceServer.bindTo(restTemplate).ignoreExpectOrder(true).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- server = MockRestServiceServer.bindTo(restTemplate).ignoreExpectOrder(true).build() ---- +====== Even with unordered requests by default, each request is allowed to run once only. The `expect` method provides an overloaded variant that accepts an `ExpectedCount` argument that specifies a count range (for example, `once`, `manyTimes`, `max`, `min`, `between`, and so on). The following example uses `times`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RestTemplate restTemplate = new RestTemplate(); @@ -74,8 +89,10 @@ argument that specifies a count range (for example, `once`, `manyTimes`, `max`, mockServer.verify(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val restTemplate = RestTemplate() @@ -87,6 +104,7 @@ argument that specifies a count range (for example, `once`, `manyTimes`, `max`, mockServer.verify() ---- +====== Note that, when `ignoreExpectOrder` is not set (the default), and, therefore, requests are expected in order of declaration, then that order applies only to the first of any @@ -100,29 +118,38 @@ As an alternative to all of the above, the client-side test support also provide bind it to a `MockMvc` instance. That allows processing requests using actual server-side logic but without running a server. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build(); this.restTemplate = new RestTemplate(new MockMvcClientHttpRequestFactory(mockMvc)); // Test code that uses the above RestTemplate ... ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build() restTemplate = RestTemplate(MockMvcClientHttpRequestFactory(mockMvc)) // Test code that uses the above RestTemplate ... ---- +====== In some cases it may be necessary to perform an actual call to a remote service instead of mocking the response. The following example shows how to do that through `ExecutingResponseCreator`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RestTemplate restTemplate = new RestTemplate(); @@ -137,8 +164,10 @@ of mocking the response. The following example shows how to do that through mockServer.verify(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val restTemplate = RestTemplate() @@ -153,6 +182,7 @@ of mocking the response. The following example shows how to do that through mockServer.verify() ---- +====== In the preceding example, we create the `ExecutingResponseCreator` using the `ClientHttpRequestFactory` from the `RestTemplate` _before_ `MockRestServiceServer` replaces diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc index f8e8cda9090c..d8c17db3e94c 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc @@ -16,8 +16,11 @@ first, then manually performing the async dispatch, and finally verifying the re Below is an example test for controller methods that return `DeferredResult`, `Callable`, or reactive type such as Reactor `Mono`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // static import of MockMvcRequestBuilders.* and MockMvcResultMatchers.* @@ -34,6 +37,7 @@ or reactive type such as Reactor `Mono`: .andExpect(content().string("body")); } ---- +====== <1> Check response status is still unchanged <2> Async processing must have started <3> Wait and assert the async result diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-defining-expectations.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-defining-expectations.adoc index a558611599d9..e581e32b1905 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-defining-expectations.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-defining-expectations.adoc @@ -5,16 +5,20 @@ You can define expectations by appending one or more `andExpect(..)` calls after performing a request, as the following example shows. As soon as one expectation fails, no other expectations will be asserted. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // static import of MockMvcRequestBuilders.* and MockMvcResultMatchers.* mockMvc.perform(get("/accounts/1")).andExpect(status().isOk()); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.servlet.get @@ -22,14 +26,18 @@ no other expectations will be asserted. status { isOk() } } ---- +====== You can define multiple expectations by appending `andExpectAll(..)` after performing a request, as the following example shows. In contrast to `andExpect(..)`, `andExpectAll(..)` guarantees that all supplied expectations will be asserted and that all failures will be tracked and reported. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // static import of MockMvcRequestBuilders.* and MockMvcResultMatchers.* @@ -38,8 +46,9 @@ all failures will be tracked and reported. content().contentType("application/json;charset=UTF-8")); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.servlet.get @@ -48,6 +57,7 @@ all failures will be tracked and reported. content { contentType(APPLICATION_JSON) } } ---- +====== `MockMvcResultMatchers.*` provides a number of expectations, some of which are further nested with more detailed expectations. @@ -64,16 +74,20 @@ inspect Servlet specific aspects, such as request and session attributes. The following test asserts that binding or validation failed: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- mockMvc.perform(post("/persons")) .andExpect(status().isOk()) .andExpect(model().attributeHasErrors("person")); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.servlet.post @@ -84,13 +98,17 @@ The following test asserts that binding or validation failed: } } ---- +====== Many times, when writing tests, it is useful to dump the results of the performed request. You can do so as follows, where `print()` is a static import from `MockMvcResultHandlers`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- mockMvc.perform(post("/persons")) .andDo(print()) @@ -98,8 +116,9 @@ request. You can do so as follows, where `print()` is a static import from .andExpect(model().attributeHasErrors("person")); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.servlet.post @@ -112,6 +131,7 @@ request. You can do so as follows, where `print()` is a static import from } } ---- +====== As long as request processing does not cause an unhandled exception, the `print()` method prints all the available result data to `System.out`. There is also a `log()` method and @@ -126,36 +146,47 @@ In some cases, you may want to get direct access to the result and verify someth cannot be verified otherwise. This can be achieved by appending `.andReturn()` after all other expectations, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- MvcResult mvcResult = mockMvc.perform(post("/persons")).andExpect(status().isOk()).andReturn(); // ... ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- var mvcResult = mockMvc.post("/persons").andExpect { status { isOk() } }.andReturn() // ... ---- +====== If all tests repeat the same expectations, you can set up common expectations once when building the `MockMvc` instance, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- standaloneSetup(new SimpleController()) .alwaysExpect(status().isOk()) .alwaysExpect(content().contentType("application/json;charset=UTF-8")) .build() ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ---- +====== Note that common expectations are always applied and cannot be overridden without creating a separate `MockMvc` instance. @@ -164,15 +195,19 @@ When a JSON response content contains hypermedia links created with https://github.com/spring-projects/spring-hateoas[Spring HATEOAS], you can verify the resulting links by using JsonPath expressions, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- mockMvc.perform(get("/people").accept(MediaType.APPLICATION_JSON)) .andExpect(jsonPath("$.links[?(@.rel == 'self')].href").value("http://localhost:8080/people")); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- mockMvc.get("/people") { accept(MediaType.APPLICATION_JSON) @@ -182,21 +217,26 @@ resulting links by using JsonPath expressions, as the following example shows: } } ---- +====== When XML response content contains hypermedia links created with https://github.com/spring-projects/spring-hateoas[Spring HATEOAS], you can verify the resulting links by using XPath expressions: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Map ns = Collections.singletonMap("ns", "http://www.w3.org/2005/Atom"); mockMvc.perform(get("/handle").accept(MediaType.APPLICATION_XML)) .andExpect(xpath("/person/ns:link[@rel='self']/@href", ns).string("http://localhost:8080/people")); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val ns = mapOf("ns" to "http://www.w3.org/2005/Atom") mockMvc.get("/handle") { @@ -207,4 +247,5 @@ resulting links by using XPath expressions: } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc index ad3c33b5192f..7b379b88cde5 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-filters.adoc @@ -5,16 +5,22 @@ When setting up a `MockMvc` instance, you can register one or more Servlet `Filter` instances, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- mockMvc = standaloneSetup(new PersonController()).addFilters(new CharacterEncodingFilter()).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ---- +====== Registered filters are invoked through the `MockFilterChain` from `spring-test`, and the last filter delegates to the `DispatcherServlet`. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc index 3809ffd3b555..145fbb6b809d 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc @@ -14,8 +14,11 @@ First, make sure that you have included a test dependency on We can easily create an HtmlUnit `WebClient` that integrates with MockMvc by using the `MockMvcWebClientBuilder`, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient webClient; @@ -27,8 +30,9 @@ We can easily create an HtmlUnit `WebClient` that integrates with MockMvc by usi } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- lateinit var webClient: WebClient @@ -39,6 +43,7 @@ We can easily create an HtmlUnit `WebClient` that integrates with MockMvc by usi .build() } ---- +====== NOTE: This is a simple example of using `MockMvcWebClientBuilder`. For advanced usage, see xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-advanced-builder[Advanced `MockMvcWebClientBuilder`]. @@ -55,17 +60,22 @@ Now we can use HtmlUnit as we normally would but without the need to deploy our application to a Servlet container. For example, we can request the view to create a message with the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HtmlPage createMsgFormPage = webClient.getPage("http://localhost/messages/form"); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val createMsgFormPage = webClient.getPage("http://localhost/messages/form") ---- +====== NOTE: The default context path is `""`. Alternatively, we can specify the context path, as described in xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-advanced-builder[Advanced `MockMvcWebClientBuilder`]. @@ -73,8 +83,11 @@ as described in xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc# Once we have a reference to the `HtmlPage`, we can then fill out the form and submit it to create a message, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HtmlForm form = createMsgFormPage.getHtmlElementById("messageForm"); HtmlTextInput summaryInput = createMsgFormPage.getHtmlElementById("summary"); @@ -84,8 +97,10 @@ to create a message, as the following example shows: HtmlSubmitInput submit = form.getOneHtmlElementByAttribute("input", "type", "submit"); HtmlPage newMessagePage = submit.click(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val form = createMsgFormPage.getHtmlElementById("messageForm") val summaryInput = createMsgFormPage.getHtmlElementById("summary") @@ -95,12 +110,16 @@ to create a message, as the following example shows: val submit = form.getOneHtmlElementByAttribute("input", "type", "submit") val newMessagePage = submit.click() ---- +====== Finally, we can verify that a new message was created successfully. The following assertions use the https://assertj.github.io/doc/[AssertJ] library: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- assertThat(newMessagePage.getUrl().toString()).endsWith("/messages/123"); String id = newMessagePage.getHtmlElementById("id").getTextContent(); @@ -110,8 +129,10 @@ assertions use the https://assertj.github.io/doc/[AssertJ] library: String text = newMessagePage.getHtmlElementById("text").getTextContent(); assertThat(text).isEqualTo("In case you didn't know, Spring Rocks!"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- assertThat(newMessagePage.getUrl().toString()).endsWith("/messages/123") val id = newMessagePage.getHtmlElementById("id").getTextContent() @@ -121,6 +142,7 @@ assertions use the https://assertj.github.io/doc/[AssertJ] library: val text = newMessagePage.getHtmlElementById("text").getTextContent() assertThat(text).isEqualTo("In case you didn't know, Spring Rocks!") ---- +====== The preceding code improves on our xref:testing/spring-mvc-test-framework/server-htmlunit/why.adoc#spring-mvc-test-server-htmlunit-mock-mvc-test[MockMvc test] in a number of ways. @@ -142,8 +164,11 @@ In the examples so far, we have used `MockMvcWebClientBuilder` in the simplest w possible, by building a `WebClient` based on the `WebApplicationContext` loaded for us by the Spring TestContext Framework. This approach is repeated in the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient webClient; @@ -155,8 +180,9 @@ the Spring TestContext Framework. This approach is repeated in the following exa } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- lateinit var webClient: WebClient @@ -167,11 +193,15 @@ the Spring TestContext Framework. This approach is repeated in the following exa .build() } ---- +====== We can also specify additional configuration options, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient webClient; @@ -188,8 +218,10 @@ We can also specify additional configuration options, as the following example s .build(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- lateinit var webClient: WebClient @@ -206,12 +238,16 @@ We can also specify additional configuration options, as the following example s .build() } ---- +====== As an alternative, we can perform the exact same setup by configuring the `MockMvc` instance separately and supplying it to the `MockMvcWebClientBuilder`, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- MockMvc mockMvc = MockMvcBuilders .webAppContextSetup(context) @@ -228,11 +264,13 @@ instance separately and supplying it to the `MockMvcWebClientBuilder`, as follow .build(); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ---- +====== This is more verbose, but, by building the `WebClient` with a `MockMvc` instance, we have the full power of MockMvc at our fingertips. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc index fbc2d34485fa..79bb9e9fb823 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc @@ -26,25 +26,34 @@ afterwards. If one of the fields were named "`summary`", we might have something that resembles the following repeated in multiple places within our tests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HtmlTextInput summaryInput = currentPage.getHtmlElementById("summary"); summaryInput.setValueAttribute(summary); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val summaryInput = currentPage.getHtmlElementById("summary") summaryInput.setValueAttribute(summary) ---- +====== So what happens if we change the `id` to `smmry`? Doing so would force us to update all of our tests to incorporate this change. This violates the DRY principle, so we should ideally extract this code into its own method, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public HtmlPage createMessage(HtmlPage currentPage, String summary, String text) { setSummary(currentPage, summary); @@ -57,8 +66,9 @@ ideally extract this code into its own method, as follows: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun createMessage(currentPage: HtmlPage, summary:String, text:String) :HtmlPage{ setSummary(currentPage, summary); @@ -70,14 +80,18 @@ ideally extract this code into its own method, as follows: summaryInput.setValueAttribute(summary) } ---- +====== Doing so ensures that we do not have to update all of our tests if we change the UI. We might even take this a step further and place this logic within an `Object` that represents the `HtmlPage` we are currently on, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class CreateMessagePage { @@ -111,8 +125,10 @@ represents the `HtmlPage` we are currently on, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class CreateMessagePage(private val currentPage: HtmlPage) { @@ -139,6 +155,7 @@ represents the `HtmlPage` we are currently on, as the following example shows: } } ---- +====== Formerly, this pattern was known as the https://github.com/SeleniumHQ/selenium/wiki/PageObjects[Page Object Pattern]. While we @@ -154,8 +171,11 @@ includes a test dependency on `org.seleniumhq.selenium:selenium-htmlunit-driver` We can easily create a Selenium WebDriver that integrates with MockMvc by using the `MockMvcHtmlUnitDriverBuilder` as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebDriver driver; @@ -166,8 +186,10 @@ We can easily create a Selenium WebDriver that integrates with MockMvc by using .build(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- lateinit var driver: WebDriver @@ -178,6 +200,7 @@ We can easily create a Selenium WebDriver that integrates with MockMvc by using .build() } ---- +====== NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced usage, see xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc#spring-mvc-test-server-htmlunit-webdriver-advanced-builder[Advanced `MockMvcHtmlUnitDriverBuilder`]. @@ -195,35 +218,45 @@ application to a Servlet container. For example, we can request the view to crea message with the following: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- CreateMessagePage page = CreateMessagePage.to(driver); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val page = CreateMessagePage.to(driver) ---- +====== -- We can then fill out the form and submit it to create a message, as follows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ViewMessagePage viewMessagePage = page.createMessage(ViewMessagePage.class, expectedSummary, expectedText); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val viewMessagePage = page.createMessage(ViewMessagePage::class, expectedSummary, expectedText) ---- +====== -- This improves on the design of our xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-usage[HtmlUnit test] @@ -233,8 +266,11 @@ with HtmlUnit, but it is much easier with WebDriver. Consider the following `CreateMessagePage` implementation: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class CreateMessagePage extends AbstractPage { // <1> @@ -262,6 +298,7 @@ with HtmlUnit, but it is much easier with WebDriver. Consider the following } } ---- +====== <1> `CreateMessagePage` extends the `AbstractPage`. We do not go over the details of `AbstractPage`, but, in summary, it contains common functionality for all of our pages. For example, if our application has a navigational bar, global error messages, and other @@ -327,26 +364,35 @@ Finally, we can verify that a new message was created successfully. The followin assertions use the https://assertj.github.io/doc/[AssertJ] assertion library: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- assertThat(viewMessagePage.getMessage()).isEqualTo(expectedMessage); assertThat(viewMessagePage.getSuccess()).isEqualTo("Successfully created a new message"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- assertThat(viewMessagePage.message).isEqualTo(expectedMessage) assertThat(viewMessagePage.success).isEqualTo("Successfully created a new message") ---- +====== -- We can see that our `ViewMessagePage` lets us interact with our custom domain model. For example, it exposes a method that returns a `Message` object: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public Message getMessage() throws ParseException { Message message = new Message(); @@ -357,11 +403,14 @@ example, it exposes a method that returns a `Message` object: return message; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun getMessage() = Message(getId(), getCreated(), getSummary(), getText()) ---- +====== -- We can then use the rich domain objects in our assertions. @@ -370,8 +419,11 @@ Lastly, we must not forget to close the `WebDriver` instance when the test is co as follows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @AfterEach void destroy() { @@ -381,8 +433,9 @@ as follows: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @AfterEach fun destroy() { @@ -391,6 +444,7 @@ as follows: } } ---- +====== -- For additional information on using WebDriver, see the Selenium @@ -403,8 +457,11 @@ In the examples so far, we have used `MockMvcHtmlUnitDriverBuilder` in the simpl possible, by building a `WebDriver` based on the `WebApplicationContext` loaded for us by the Spring TestContext Framework. This approach is repeated here, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebDriver driver; @@ -416,8 +473,9 @@ the Spring TestContext Framework. This approach is repeated here, as follows: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- lateinit var driver: WebDriver @@ -428,11 +486,15 @@ the Spring TestContext Framework. This approach is repeated here, as follows: .build() } ---- +====== We can also specify additional configuration options, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebDriver driver; @@ -449,8 +511,10 @@ We can also specify additional configuration options, as follows: .build(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- lateinit var driver: WebDriver @@ -467,12 +531,16 @@ We can also specify additional configuration options, as follows: .build() } ---- +====== As an alternative, we can perform the exact same setup by configuring the `MockMvc` instance separately and supplying it to the `MockMvcHtmlUnitDriverBuilder`, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- MockMvc mockMvc = MockMvcBuilders .webAppContextSetup(context) @@ -489,11 +557,13 @@ instance separately and supplying it to the `MockMvcHtmlUnitDriverBuilder`, as f .build(); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ---- +====== This is more verbose, but, by building the `WebDriver` with a `MockMvc` instance, we have the full power of MockMvc at our fingertips. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc index 174f9108fa1d..04493364f859 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc @@ -8,8 +8,11 @@ supports paging through all messages. How would you go about testing it? With Spring MVC Test, we can easily test if we are able to create a `Message`, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- MockHttpServletRequestBuilder createMessage = post("/messages/") .param("summary", "Spring Rocks") @@ -19,8 +22,10 @@ With Spring MVC Test, we can easily test if we are able to create a `Message`, a .andExpect(status().is3xxRedirection()) .andExpect(redirectedUrl("/messages/123")); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Test fun test() { @@ -33,6 +38,7 @@ With Spring MVC Test, we can easily test if we are able to create a `Message`, a } } ---- +====== What if we want to test the form view that lets us create the message? For example, assume our form looks like the following snippet: @@ -57,31 +63,39 @@ assume our form looks like the following snippet: How do we ensure that our form produce the correct request to create a new message? A naive attempt might resemble the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- mockMvc.perform(get("/messages/form")) .andExpect(xpath("//input[@name='summary']").exists()) .andExpect(xpath("//textarea[@name='text']").exists()); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- mockMvc.get("/messages/form").andExpect { xpath("//input[@name='summary']") { exists() } xpath("//textarea[@name='text']") { exists() } } ---- +====== This test has some obvious drawbacks. If we update our controller to use the parameter `message` instead of `text`, our form test continues to pass, even though the HTML form is out of synch with the controller. To resolve this we can combine our two tests, as follows: +[tabs] +====== +Java:: ++ [[spring-mvc-test-server-htmlunit-mock-mvc-test]] [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- String summaryParamName = "summary"; String textParamName = "text"; @@ -98,8 +112,9 @@ follows: .andExpect(redirectedUrl("/messages/123")); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val summaryParamName = "summary"; val textParamName = "text"; @@ -115,6 +130,7 @@ follows: redirectedUrl("/messages/123") } ---- +====== This would reduce the risk of our test incorrectly passing, but there are still some problems: diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc index 4bb64992e32d..ba8ac3772dc3 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc @@ -7,16 +7,20 @@ xref:testing/webtestclient.adoc#webtestclient-tests[Writing Tests] instead. To perform requests that use any HTTP method, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // static import of MockMvcRequestBuilders.* mockMvc.perform(post("/hotels/{id}", 42).accept(MediaType.APPLICATION_JSON)); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.servlet.post @@ -24,19 +28,24 @@ To perform requests that use any HTTP method, as the following example shows: accept = MediaType.APPLICATION_JSON } ---- +====== You can also perform file upload requests that internally use `MockMultipartHttpServletRequest` so that there is no actual parsing of a multipart request. Rather, you have to set it up to be similar to the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- mockMvc.perform(multipart("/doc").file("a1", "ABC".getBytes("UTF-8"))); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.servlet.multipart @@ -44,30 +53,42 @@ request. Rather, you have to set it up to be similar to the following example: file("a1", "ABC".toByteArray(charset("UTF8"))) } ---- +====== You can specify query parameters in URI template style, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- mockMvc.perform(get("/hotels?thing={thing}", "somewhere")); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- mockMvc.get("/hotels?thing={thing}", "somewhere") ---- +====== You can also add Servlet request parameters that represent either query or form parameters, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- mockMvc.perform(get("/hotels").param("thing", "somewhere")); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.servlet.get @@ -75,6 +96,7 @@ parameters, as the following example shows: param("thing", "somewhere") } ---- +====== If application code relies on Servlet request parameters and does not check the query string explicitly (as is most often the case), it does not matter which option you use. @@ -87,13 +109,18 @@ request URI. If you must test with the full request URI, be sure to set the `con and `servletPath` accordingly so that request mappings work, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- mockMvc.perform(get("/app/main/hotels/{id}").contextPath("/app").servletPath("/main")) ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.servlet.get @@ -102,13 +129,17 @@ shows: servletPath = "/main" } ---- +====== In the preceding example, it would be cumbersome to set the `contextPath` and `servletPath` with every performed request. Instead, you can set up default request properties, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class MyWebTests { @@ -123,11 +154,14 @@ properties, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ---- +====== The preceding properties affect every request performed through the `MockMvc` instance. If the same property is also specified on a given request, it overrides the default diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc index d6a6cf9f4844..b38d69ed683e 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc @@ -7,8 +7,11 @@ point to Spring configuration with Spring MVC and controller infrastructure in i To set up MockMvc for testing a specific controller, use the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class MyWebTests { @@ -24,8 +27,9 @@ To set up MockMvc for testing a specific controller, use the following: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyWebTests { @@ -40,6 +44,7 @@ To set up MockMvc for testing a specific controller, use the following: } ---- +====== Or you can also use this setup when testing through the xref:testing/webtestclient.adoc#webtestclient-controller-config[WebTestClient] which delegates to the same builder @@ -47,8 +52,11 @@ as shown above. To set up MockMvc through Spring configuration, use the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitWebConfig(locations = "my-servlet-context.xml") class MyWebTests { @@ -65,8 +73,9 @@ To set up MockMvc through Spring configuration, use the following: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitWebConfig(locations = ["my-servlet-context.xml"]) class MyWebTests { @@ -82,6 +91,7 @@ To set up MockMvc through Spring configuration, use the following: } ---- +====== Or you can also use this setup when testing through the xref:testing/webtestclient.adoc#webtestclient-context-config[WebTestClient] which delegates to the same builder @@ -108,8 +118,11 @@ a mock service with Mockito: You can then inject the mock service into the test to set up and verify your expectations, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitWebConfig(locations = "test-servlet-context.xml") class AccountTests { @@ -128,8 +141,10 @@ expectations, as the following example shows: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitWebConfig(locations = ["test-servlet-context.xml"]) class AccountTests { @@ -148,6 +163,7 @@ expectations, as the following example shows: } ---- +====== The `standaloneSetup`, on the other hand, is a little closer to a unit test. It tests one controller at a time. You can manually inject the controller with mock dependencies, and diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-steps.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-steps.adoc index 3ebd6a8a00c7..2ec41f725a57 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-steps.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-steps.adoc @@ -6,8 +6,11 @@ some common and very useful features. For example, you can declare an `Accept` h all requests and expect a status of 200 as well as a `Content-Type` header in all responses, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // static import of MockMvcBuilders.standaloneSetup @@ -18,19 +21,24 @@ responses, as follows: .build(); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ---- +====== In addition, third-party frameworks (and applications) can pre-package setup instructions, such as those in a `MockMvcConfigurer`. The Spring Framework has one such built-in implementation that helps to save and re-use the HTTP session across requests. You can use it as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // static import of SharedHttpSessionConfigurer.sharedHttpSession @@ -41,11 +49,13 @@ You can use it as follows: // Use mockMvc to perform requests... ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed ---- +====== See the javadoc for {api-spring-framework}/test/web/servlet/setup/ConfigurableMockMvcBuilder.html[`ConfigurableMockMvcBuilder`] diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-streaming-response.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-streaming-response.adoc index f1004ec9c16f..c5c3e7dc5a2c 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-streaming-response.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/vs-streaming-response.adoc @@ -5,8 +5,11 @@ The best way to test streaming responses such as Server-Sent Events is through t <> which can be used as a test client to connect to a `MockMvc` instance to perform tests on Spring MVC controllers without a running server. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebTestClient client = MockMvcWebTestClient.bindToController(new SseController()).build(); @@ -26,6 +29,7 @@ to perform tests on Spring MVC controllers without a running server. For example .thenCancel() .verify(); ---- +====== `WebTestClient` can also connect to a live server and perform full end-to-end integration tests. This is also supported in Spring Boot where you can diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc index b9779c015226..eba93a4326ab 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc @@ -28,8 +28,11 @@ https://assertj.github.io/doc/[AssertJ] to assert the types of application event published while invoking a method in a Spring-managed component: // Don't use "quotes" in the "subs" section because of the asterisks in /* ... */ +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @SpringJUnitConfig(/* ... */) @RecordApplicationEvents // <1> @@ -51,6 +54,7 @@ published while invoking a method in a Spring-managed component: } } ---- +====== <1> Annotate the test class with `@RecordApplicationEvents`. <2> Inject the `ApplicationEvents` instance for the current test. <3> Use the `ApplicationEvents` API to count how many `OrderSubmitted` events were published. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc index 3807f827d0d1..c922c4271814 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc @@ -16,8 +16,11 @@ As an alternative to implementing the `ApplicationContextAware` interface, you c the application context for your test class through the `@Autowired` annotation on either a field or setter method, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig class MyTest { @@ -28,6 +31,7 @@ a field or setter method, as the following example shows: // class body... } ---- +====== <1> Injecting the `ApplicationContext`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -48,8 +52,11 @@ a field or setter method, as the following example shows: Similarly, if your test is configured to load a `WebApplicationContext`, you can inject the web application context into your test, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitWebConfig // <1> class MyWebAppTest { @@ -60,6 +67,7 @@ the web application context into your test, as follows: // class body... } ---- +====== <1> Configuring the `WebApplicationContext`. <2> Injecting the `WebApplicationContext`. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc index 30de9635eb9e..ad418ef4cdfc 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc @@ -38,8 +38,11 @@ ensure that each subclass gets its own `ApplicationContext` with the correct dyn properties. ==== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(/* ... */) @Testcontainers @@ -59,8 +62,10 @@ properties. } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig(/* ... */) @Testcontainers @@ -85,6 +90,7 @@ properties. } ---- +====== [[precedence]] == Precedence diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc index 1f41ef8a09c2..bb868bf5fae4 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc @@ -59,8 +59,11 @@ Consider two examples with XML configuration and `@Configuration` classes: ---- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be loaded from "classpath:/app-config.xml" @@ -77,8 +80,10 @@ Consider two examples with XML configuration and `@Configuration` classes: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) // ApplicationContext will be loaded from "classpath:/app-config.xml" @@ -95,6 +100,7 @@ Consider two examples with XML configuration and `@Configuration` classes: } } ---- +====== When `TransferServiceTest` is run, its `ApplicationContext` is loaded from the `app-config.xml` configuration file in the root of the classpath. If you inspect @@ -118,8 +124,11 @@ but define an in-memory data source as a default when neither of these is active The following code listings demonstrate how to implement the same configuration and integration test with `@Configuration` classes instead of XML: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @Profile("dev") @@ -135,8 +144,10 @@ integration test with `@Configuration` classes instead of XML: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @Profile("dev") @@ -152,9 +163,13 @@ integration test with `@Configuration` classes instead of XML: } } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @Profile("production") @@ -167,8 +182,10 @@ integration test with `@Configuration` classes instead of XML: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @Profile("production") @@ -181,9 +198,13 @@ integration test with `@Configuration` classes instead of XML: } } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @Profile("default") @@ -198,8 +219,10 @@ integration test with `@Configuration` classes instead of XML: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @Profile("default") @@ -214,9 +237,13 @@ integration test with `@Configuration` classes instead of XML: } } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class TransferServiceConfig { @@ -239,8 +266,10 @@ integration test with `@Configuration` classes instead of XML: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class TransferServiceConfig { @@ -264,9 +293,13 @@ integration test with `@Configuration` classes instead of XML: } } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig({ TransferServiceConfig.class, @@ -285,8 +318,10 @@ integration test with `@Configuration` classes instead of XML: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig( TransferServiceConfig::class, @@ -305,6 +340,7 @@ integration test with `@Configuration` classes instead of XML: } } ---- +====== In this variation, we have split the XML configuration into four independent `@Configuration` classes: @@ -333,8 +369,11 @@ has been moved to an abstract superclass, `AbstractIntegrationTest`: NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] for details. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig({ TransferServiceConfig.class, @@ -346,8 +385,9 @@ classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig( TransferServiceConfig::class, @@ -358,9 +398,13 @@ classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext abstract class AbstractIntegrationTest { } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // "dev" profile inherited from superclass class TransferServiceTest extends AbstractIntegrationTest { @@ -374,8 +418,10 @@ classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // "dev" profile inherited from superclass class TransferServiceTest : AbstractIntegrationTest() { @@ -389,12 +435,16 @@ classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext } } ---- +====== `@ActiveProfiles` also supports an `inheritProfiles` attribute that can be used to disable the inheritance of active profiles, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // "dev" profile overridden with "production" @ActiveProfiles(profiles = "production", inheritProfiles = false) @@ -403,8 +453,9 @@ disable the inheritance of active profiles, as the following example shows: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // "dev" profile overridden with "production" @ActiveProfiles("production", inheritProfiles = false) @@ -412,6 +463,7 @@ disable the inheritance of active profiles, as the following example shows: // test body } ---- +====== [[testcontext-ctx-management-env-profiles-ActiveProfilesResolver]] Furthermore, it is sometimes necessary to resolve active profiles for tests @@ -430,8 +482,11 @@ attribute of `@ActiveProfiles`. For further information, see the corresponding The following example demonstrates how to implement and register a custom `OperatingSystemActiveProfilesResolver`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // "dev" profile overridden programmatically via a custom resolver @ActiveProfiles( @@ -442,8 +497,9 @@ The following example demonstrates how to implement and register a custom } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // "dev" profile overridden programmatically via a custom resolver @ActiveProfiles( @@ -453,9 +509,13 @@ The following example demonstrates how to implement and register a custom // test body } ---- +====== +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class OperatingSystemActiveProfilesResolver implements ActiveProfilesResolver { @@ -467,8 +527,10 @@ The following example demonstrates how to implement and register a custom } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class OperatingSystemActiveProfilesResolver : ActiveProfilesResolver { @@ -479,4 +541,5 @@ The following example demonstrates how to implement and register a custom } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc index e34e5b3becc9..f44fdfd39652 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc @@ -14,8 +14,11 @@ TestContext Framework is enabled automatically if Groovy is on the classpath. The following example shows how to specify Groovy configuration files: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be loaded from "/AppConfig.groovy" and @@ -25,6 +28,7 @@ The following example shows how to specify Groovy configuration files: // class body... } ---- +====== <1> Specifying the location of Groovy configuration files. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -49,8 +53,11 @@ detect a default location based on the name of the test class. If your class is `"classpath:com/example/MyTestContext.groovy"`. The following example shows how to use the default: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be loaded from @@ -60,6 +67,7 @@ the default: // class body... } ---- +====== <1> Loading configuration from the default location. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -87,8 +95,11 @@ configured resource location ends with `.xml`, it is loaded by using an The following listing shows how to combine both in an integration test: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be loaded from @@ -98,8 +109,10 @@ The following listing shows how to combine both in an integration test: // class body... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) // ApplicationContext will be loaded from @@ -109,5 +122,6 @@ The following listing shows how to combine both in an integration test: // class body... } ---- +====== ===== diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc index 1411e7c1b187..c92ebb9064b2 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc @@ -35,8 +35,11 @@ one for the root `WebApplicationContext` (loaded by using the `TestAppConfig` that is autowired into the test instance is the one for the child context (that is, the lowest context in the hierarchy). The following listing shows this configuration scenario: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @WebAppConfiguration @@ -53,8 +56,9 @@ lowest context in the hierarchy). The following listing shows this configuration } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) @WebAppConfiguration @@ -69,6 +73,7 @@ lowest context in the hierarchy). The following listing shows this configuration // ... } ---- +====== -- **Class hierarchy with implicit parent context** @@ -86,8 +91,11 @@ based on the configuration in `AbstractWebTests` is set as the parent context fo the contexts loaded for the concrete subclasses. The following listing shows this configuration scenario: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @WebAppConfiguration @@ -100,8 +108,10 @@ configuration scenario: @ContextHierarchy(@ContextConfiguration("/spring/rest-ws-config.xml")) public class RestWebServiceTests extends AbstractWebTests {} ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) @WebAppConfiguration @@ -115,6 +125,7 @@ configuration scenario: class RestWebServiceTests : AbstractWebTests() ---- +====== -- **Class hierarchy with merged context hierarchy configuration** @@ -131,8 +142,11 @@ application context loaded from `/app-config.xml` is set as the parent context f contexts loaded from `/user-config.xml` and `{"/user-config.xml", "/order-config.xml"}`. The following listing shows this configuration scenario: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @ContextHierarchy({ @@ -147,8 +161,9 @@ The following listing shows this configuration scenario: class ExtendedTests extends BaseTests {} ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) @ContextHierarchy( @@ -161,6 +176,7 @@ The following listing shows this configuration scenario: ) class ExtendedTests : BaseTests() {} ---- +====== -- **Class hierarchy with overridden context hierarchy configuration** @@ -172,8 +188,11 @@ application context for `ExtendedTests` is loaded only from `/test-user-config.x has its parent set to the context loaded from `/app-config.xml`. The following listing shows this configuration scenario: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @ContextHierarchy({ @@ -190,8 +209,10 @@ shows this configuration scenario: )) class ExtendedTests extends BaseTests {} ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) @ContextHierarchy( @@ -207,6 +228,7 @@ shows this configuration scenario: )) class ExtendedTests : BaseTests() {} ---- +====== .Dirtying a context within a context hierarchy NOTE: If you use `@DirtiesContext` in a test whose context is configured as part of a diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc index 6c7b7650f266..b4b8fed16fb4 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc @@ -26,8 +26,11 @@ Beans defined in `extended-config.xml` can, therefore, override (that is, replac defined in `base-config.xml`. The following example shows how one class can extend another and use both its own configuration file and the superclass's configuration file: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be loaded from "/base-config.xml" @@ -44,6 +47,7 @@ another and use both its own configuration file and the superclass's configurati // class body... } ---- +====== <1> Configuration file defined in the superclass. <2> Configuration file defined in the subclass. @@ -75,8 +79,11 @@ order. Beans defined in `ExtendedConfig` can, therefore, override (that is, repl those defined in `BaseConfig`. The following example shows how one class can extend another and use both its own configuration class and the superclass's configuration class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // ApplicationContext will be loaded from BaseConfig @SpringJUnitConfig(BaseConfig.class) // <1> @@ -90,6 +97,7 @@ another and use both its own configuration class and the superclass's configurat // class body... } ---- +====== <1> Configuration class defined in the superclass. <2> Configuration class defined in the subclass. @@ -119,8 +127,11 @@ implement Spring's `Ordered` interface or are annotated with Spring's `@Order` a or the standard `@Priority` annotation. The following example shows how one class can extend another and use both its own initializer and the superclass's initializer: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // ApplicationContext will be initialized by BaseInitializer @SpringJUnitConfig(initializers = BaseInitializer.class) // <1> @@ -135,6 +146,7 @@ extend another and use both its own initializer and the superclass's initializer // class body... } ---- +====== <1> Initializer defined in the superclass. <2> Initializer defined in the subclass. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/initializers.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/initializers.adoc index 4263559232fc..caba982d2882 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/initializers.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/initializers.adoc @@ -13,8 +13,11 @@ order in which the initializers are invoked depends on whether they implement Sp `Ordered` interface or are annotated with Spring's `@Order` annotation or the standard `@Priority` annotation. The following example shows how to use initializers: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be loaded from TestConfig @@ -26,6 +29,7 @@ order in which the initializers are invoked depends on whether they implement Sp // class body... } ---- +====== <1> Specifying configuration by using a configuration class and an initializer. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -50,8 +54,11 @@ component classes in `@ContextConfiguration` entirely and instead declare only in the context -- for example, by programmatically loading bean definitions from XML files or configuration classes. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be initialized by EntireAppInitializer @@ -61,6 +68,7 @@ files or configuration classes. The following example shows how to do so: // class body... } ---- +====== <1> Specifying configuration by using only an initializer. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc index bd7af6c1487c..97cb4df38015 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc @@ -6,8 +6,11 @@ xref:core/beans/java.adoc[Java-based container configuration]), you can annotate class with `@ContextConfiguration` and configure the `classes` attribute with an array that contains references to component classes. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be loaded from AppConfig and TestConfig @@ -16,6 +19,7 @@ that contains references to component classes. The following example shows how t // class body... } ---- +====== <1> Specifying component classes. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -64,8 +68,11 @@ example, the `OrderServiceTest` class declares a `static` nested configuration c named `Config` that is automatically used to load the `ApplicationContext` for the test class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig <1> // ApplicationContext will be loaded from the static nested Config class @@ -93,6 +100,7 @@ class: } ---- +====== <1> Loading configuration information from the nested `Config` class. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc index 263e21446d41..4d8812325423 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc @@ -40,8 +40,11 @@ loaded by using the specified resource protocol. Resource location wildcards (su The following example uses a test properties file: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @TestPropertySource("/test.properties") // <1> @@ -49,6 +52,7 @@ The following example uses a test properties file: // class body... } ---- +====== <1> Specifying a properties file with an absolute path. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -77,8 +81,11 @@ a Java properties file: The following example sets two inlined properties: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @TestPropertySource(properties = {"timezone = GMT", "port: 4242"}) // <1> @@ -86,6 +93,7 @@ The following example sets two inlined properties: // class body... } ---- +====== <1> Setting two properties by using two variations of the key-value syntax. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -147,8 +155,11 @@ entries for the `timezone` and `port` properties those are overridden by the inl properties declared by using the `properties` attribute. The following example shows how to specify properties both in a file and inline: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @TestPropertySource( @@ -160,8 +171,9 @@ to specify properties both in a file and inline: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ContextConfiguration @TestPropertySource("/test.properties", @@ -171,6 +183,7 @@ to specify properties both in a file and inline: // class body... } ---- +====== [[inheriting-and-overriding-test-property-sources]] == Inheriting and Overriding Test Property Sources @@ -199,8 +212,11 @@ for `ExtendedTest` is loaded by using the `base.properties` and `extended.proper files as test property source locations. The following example shows how to define properties in both a subclass and its superclass by using `properties` files: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @TestPropertySource("base.properties") @ContextConfiguration @@ -214,8 +230,10 @@ properties in both a subclass and its superclass by using `properties` files: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @TestPropertySource("base.properties") @ContextConfiguration @@ -229,14 +247,18 @@ properties in both a subclass and its superclass by using `properties` files: // ... } ---- +====== In the next example, the `ApplicationContext` for `BaseTest` is loaded by using only the inlined `key1` property. In contrast, the `ApplicationContext` for `ExtendedTest` is loaded by using the inlined `key1` and `key2` properties. The following example shows how to define properties in both a subclass and its superclass by using inline properties: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @TestPropertySource(properties = "key1 = value1") @ContextConfiguration @@ -250,8 +272,10 @@ to define properties in both a subclass and its superclass by using inline prope // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @TestPropertySource(properties = ["key1 = value1"]) @ContextConfiguration @@ -265,4 +289,5 @@ to define properties in both a subclass and its superclass by using inline prope // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc index 990888625389..267baf8e0e0b 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc @@ -18,9 +18,11 @@ mocks can be autowired into your test instance. Note that the `WebApplicationCon `MockServletContext` are both cached across the test suite, whereas the other mocks are managed per test method by the `ServletTestExecutionListener`. -.Injecting mocks +[tabs] +====== +Injecting mocks:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitWebConfig class WacTests { @@ -47,8 +49,9 @@ managed per test method by the `ServletTestExecutionListener`. } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitWebConfig class WacTests { @@ -74,4 +77,5 @@ managed per test method by the `ServletTestExecutionListener`. //... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web.adoc index 163720fc87cb..cfc6778bbb95 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web.adoc @@ -29,9 +29,11 @@ The remaining examples in this section show some of the various configuration op loading a `WebApplicationContext`. The following example shows the TestContext framework's support for convention over configuration: -.Conventions +[tabs] +====== +Conventions:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @@ -45,8 +47,10 @@ framework's support for convention over configuration: //... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) @@ -60,6 +64,7 @@ framework's support for convention over configuration: //... } ---- +====== If you annotate a test class with `@WebAppConfiguration` without specifying a resource base path, the resource path effectively defaults to `file:src/main/webapp`. Similarly, @@ -71,9 +76,11 @@ as the `WacTests` class or static nested `@Configuration` classes). The following example shows how to explicitly declare a resource base path with `@WebAppConfiguration` and an XML resource location with `@ContextConfiguration`: -.Default resource semantics +[tabs] +====== +Default resource semantics:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @@ -86,8 +93,10 @@ The following example shows how to explicitly declare a resource base path with //... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) @@ -100,6 +109,7 @@ The following example shows how to explicitly declare a resource base path with //... } ---- +====== The important thing to note here is the different semantics for paths with these two annotations. By default, `@WebAppConfiguration` resource paths are file system based, @@ -108,9 +118,11 @@ whereas `@ContextConfiguration` resource locations are classpath based. The following example shows that we can override the default resource semantics for both annotations by specifying a Spring resource prefix: -.Explicit resource semantics +[tabs] +====== +Explicit resource semantics:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @@ -123,8 +135,10 @@ annotations by specifying a Spring resource prefix: //... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) @@ -137,6 +151,7 @@ annotations by specifying a Spring resource prefix: //... } ---- +====== Contrast the comments in this example with the previous example. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/xml.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/xml.adoc index b11a6c4be70b..2ee0dc5bddf5 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/xml.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/xml.adoc @@ -10,8 +10,11 @@ is treated as an absolute classpath location (for example, `/org/example/config. path that represents a resource URL (i.e., a path prefixed with `classpath:`, `file:`, `http:`, etc.) is used _as is_. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be loaded from "/app-config.xml" and @@ -21,6 +24,7 @@ path that represents a resource URL (i.e., a path prefixed with `classpath:`, `f // class body... } ---- +====== <1> Setting the locations attribute to a list of XML files. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -43,8 +47,11 @@ attributes in `@ContextConfiguration`, you can omit the declaration of the `loca attribute name and declare the resource locations by using the shorthand format demonstrated in the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @ContextConfiguration({"/app-config.xml", "/test-config.xml"}) <1> @@ -52,6 +59,7 @@ demonstrated in the following example: // class body... } ---- +====== <1> Specifying XML files without using the `locations` attribute. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -74,8 +82,11 @@ class. If your class is named `com.example.MyTest`, `GenericXmlContextLoader` lo application context from `"classpath:com/example/MyTest-context.xml"`. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // ApplicationContext will be loaded from @@ -85,6 +96,7 @@ example shows how to do so: // class body... } ---- +====== <1> Loading configuration from the default location. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc index bfb51004538e..dc51cfa9d0dc 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc @@ -46,8 +46,11 @@ to run the populator against a `javax.sql.DataSource`. The following example specifies SQL scripts for a test schema and test data, sets the statement separator to `@@`, and run the scripts against a `DataSource`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Test void databaseTest() { @@ -60,8 +63,10 @@ specifies SQL scripts for a test schema and test data, sets the statement separa // run code that uses the test schema and data } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Test fun databaseTest() { @@ -74,6 +79,7 @@ specifies SQL scripts for a test schema and test data, sets the statement separa // run code that uses the test schema and data } ---- +====== Note that `ResourceDatabasePopulator` internally delegates to `ScriptUtils` for parsing and running SQL scripts. Similarly, the `executeSqlScript(..)` methods in @@ -110,8 +116,11 @@ the specified resource protocol. The following example shows how to use `@Sql` at the class level and at the method level within a JUnit Jupiter based integration test class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig @Sql("/test-schema.sql") @@ -130,8 +139,9 @@ within a JUnit Jupiter based integration test class: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig @Sql("/test-schema.sql") @@ -149,6 +159,7 @@ within a JUnit Jupiter based integration test class: } } ---- +====== [[testcontext-executing-sql-declaratively-script-detection]] === Default Script Detection @@ -175,8 +186,11 @@ Java 8, you can use `@Sql` as a repeatable annotation. Otherwise, you can use th The following example shows how to use `@Sql` as a repeatable annotation with Java 8: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Test @Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")) @@ -185,11 +199,14 @@ The following example shows how to use `@Sql` as a repeatable annotation with Ja // run code that uses the test schema and test data } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Repeatable annotations with non-SOURCE retention are not yet supported by Kotlin ---- +====== In the scenario presented in the preceding example, the `test-schema.sql` script uses a different syntax for single-line comments. @@ -199,8 +216,11 @@ declarations are grouped together within `@SqlGroup`. With Java 8 and above, the `@SqlGroup` is optional, but you may need to use `@SqlGroup` for compatibility with other JVM languages such as Kotlin. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Test @SqlGroup({ @@ -211,8 +231,10 @@ other JVM languages such as Kotlin. // run code that uses the test schema and test data } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Test @SqlGroup( @@ -222,6 +244,7 @@ other JVM languages such as Kotlin. // Run code that uses the test schema and test data } ---- +====== [[testcontext-executing-sql-declaratively-script-execution-phases]] === Script Execution Phases @@ -231,8 +254,11 @@ you need to run a particular set of scripts after the test method (for example, up database state), you can use the `executionPhase` attribute in `@Sql`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Test @Sql( @@ -249,8 +275,10 @@ following example shows: // to the database outside of the test's transaction } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Test @SqlGroup( @@ -264,6 +292,7 @@ following example shows: // to the database outside of the test's transaction } ---- +====== Note that `ISOLATED` and `AFTER_TEST_METHOD` are statically imported from `Sql.TransactionMode` and `Sql.ExecutionPhase`, respectively. @@ -319,8 +348,11 @@ reference manual, the javadoc for provide detailed information, and the following example shows a typical testing scenario that uses JUnit Jupiter and transactional tests with `@Sql`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestDatabaseConfig.class) @Transactional @@ -351,8 +383,10 @@ that uses JUnit Jupiter and transactional tests with `@Sql`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig(TestDatabaseConfig::class) @Transactional @@ -378,6 +412,7 @@ that uses JUnit Jupiter and transactional tests with `@Sql`: } } ---- +====== Note that there is no need to clean up the database after the `usersTest()` method is run, since any changes made to the database (either within the test method or within the diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc index 2951d0430d28..54ce51bffef2 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc @@ -54,8 +54,11 @@ example. The first code listing shows a JUnit Jupiter based implementation of the test class that uses `@Autowired` for field injection: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // specifies the Spring configuration to load for this test fixture @@ -74,8 +77,9 @@ uses `@Autowired` for field injection: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) // specifies the Spring configuration to load for this test fixture @@ -93,12 +97,16 @@ uses `@Autowired` for field injection: } } ---- +====== Alternatively, you can configure the class to use `@Autowired` for setter injection, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) // specifies the Spring configuration to load for this test fixture @@ -121,8 +129,9 @@ follows: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExtendWith(SpringExtension::class) // specifies the Spring configuration to load for this test fixture @@ -144,6 +153,7 @@ follows: } } ---- +====== The preceding code listings use the same XML context file referenced by the `@ContextConfiguration` annotation (that is, `repository-config.xml`). The following @@ -178,8 +188,11 @@ such a case, you can override the setter method and use the `@Qualifier` annotat indicate a specific target bean, as follows (but make sure to delegate to the overridden method in the superclass as well): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // ... @@ -192,8 +205,9 @@ method in the superclass as well): // ... ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // ... @@ -204,6 +218,7 @@ method in the superclass as well): // ... ---- +====== The specified qualifier value indicates the specific `DataSource` bean to inject, narrowing the set of type matches to a specific bean. Its value is matched against diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc index ae9aa71b1bca..7f0a8c19aa23 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc @@ -20,8 +20,11 @@ xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules The following code listing shows the minimal requirements for configuring a test class to run with the custom Spring `Runner`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RunWith(SpringRunner.class) @TestExecutionListeners({}) @@ -34,8 +37,9 @@ run with the custom Spring `Runner`: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RunWith(SpringRunner::class) @TestExecutionListeners @@ -47,6 +51,7 @@ run with the custom Spring `Runner`: } } ---- +====== In the preceding example, `@TestExecutionListeners` is configured with an empty list, to disable the default listeners, which otherwise would require an `ApplicationContext` to @@ -74,8 +79,11 @@ To support the full functionality of the TestContext framework, you must combine `SpringClassRule` with a `SpringMethodRule`. The following example shows the proper way to declare these rules in an integration test: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Optionally specify a non-Spring Runner via @RunWith(...) @ContextConfiguration @@ -94,8 +102,9 @@ to declare these rules in an integration test: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Optionally specify a non-Spring Runner via @RunWith(...) @ContextConfiguration @@ -115,6 +124,7 @@ to declare these rules in an integration test: } } ---- +====== [[testcontext-support-classes-junit4]] == JUnit 4 Support Classes @@ -179,8 +189,11 @@ TestNG: The following code listing shows how to configure a test class to use the `SpringExtension` in conjunction with `@ContextConfiguration`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Instructs JUnit Jupiter to extend the test with Spring support. @ExtendWith(SpringExtension.class) @@ -195,8 +208,9 @@ The following code listing shows how to configure a test class to use the } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Instructs JUnit Jupiter to extend the test with Spring support. @ExtendWith(SpringExtension::class) @@ -210,6 +224,7 @@ The following code listing shows how to configure a test class to use the } } ---- +====== Since you can also use annotations in JUnit 5 as meta-annotations, Spring provides the `@SpringJUnitConfig` and `@SpringJUnitWebConfig` composed annotations to simplify the @@ -218,8 +233,11 @@ configuration of the test `ApplicationContext` and JUnit Jupiter. The following example uses `@SpringJUnitConfig` to reduce the amount of configuration used in the previous example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Instructs Spring to register the SpringExtension with JUnit // Jupiter and load an ApplicationContext from TestConfig.class @@ -233,8 +251,9 @@ used in the previous example: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Instructs Spring to register the SpringExtension with JUnit // Jupiter and load an ApplicationContext from TestConfig.class @@ -247,12 +266,16 @@ used in the previous example: } } ---- +====== Similarly, the following example uses `@SpringJUnitWebConfig` to create a `WebApplicationContext` for use with JUnit Jupiter: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Instructs Spring to register the SpringExtension with JUnit // Jupiter and load a WebApplicationContext from TestWebConfig.class @@ -266,8 +289,9 @@ Similarly, the following example uses `@SpringJUnitWebConfig` to create a } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Instructs Spring to register the SpringExtension with JUnit // Jupiter and load a WebApplicationContext from TestWebConfig::class @@ -280,6 +304,7 @@ Similarly, the following example uses `@SpringJUnitWebConfig` to create a } } ---- +====== See the documentation for `@SpringJUnitConfig` and `@SpringJUnitWebConfig` in xref:testing/annotations/integration-junit-jupiter.adoc[Spring JUnit Jupiter Testing Annotations] for further details. @@ -345,8 +370,11 @@ In the following example, Spring injects the `OrderService` bean from the `ApplicationContext` loaded from `TestConfig.class` into the `OrderServiceIntegrationTests` constructor. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestConfig.class) class OrderServiceIntegrationTests { @@ -362,8 +390,9 @@ In the following example, Spring injects the `OrderService` bean from the } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig(TestConfig::class) class OrderServiceIntegrationTests @Autowired constructor(private val orderService: OrderService){ @@ -371,6 +400,7 @@ In the following example, Spring injects the `OrderService` bean from the } ---- +====== Note that this feature lets test dependencies be `final` and therefore immutable. @@ -378,8 +408,11 @@ If the `spring.test.constructor.autowire.mode` property is to `all` (see xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`]), we can omit the declaration of `@Autowired` on the constructor in the previous example, resulting in the following. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestConfig.class) class OrderServiceIntegrationTests { @@ -394,14 +427,16 @@ xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-anno } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig(TestConfig::class) class OrderServiceIntegrationTests(val orderService:OrderService) { // tests that use the injected OrderService } ---- +====== [[testcontext-junit-jupiter-di-method]] ==== Method Injection @@ -414,8 +449,11 @@ parameter with the corresponding bean from the test's `ApplicationContext`. In the following example, Spring injects the `OrderService` from the `ApplicationContext` loaded from `TestConfig.class` into the `deleteOrder()` test method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestConfig.class) class OrderServiceIntegrationTests { @@ -427,8 +465,9 @@ loaded from `TestConfig.class` into the `deleteOrder()` test method: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig(TestConfig::class) class OrderServiceIntegrationTests { @@ -439,6 +478,7 @@ loaded from `TestConfig.class` into the `deleteOrder()` test method: } } ---- +====== Due to the robustness of the `ParameterResolver` support in JUnit Jupiter, you can also have multiple dependencies injected into a single method, not only from Spring but also @@ -447,8 +487,11 @@ from JUnit Jupiter itself or other third-party extensions. The following example shows how to have both Spring and JUnit Jupiter inject dependencies into the `placeOrderRepeatedly()` test method simultaneously. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestConfig.class) class OrderServiceIntegrationTests { @@ -463,8 +506,9 @@ into the `placeOrderRepeatedly()` test method simultaneously. } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig(TestConfig::class) class OrderServiceIntegrationTests { @@ -477,6 +521,7 @@ into the `placeOrderRepeatedly()` test method simultaneously. } } ---- +====== Note that the use of `@RepeatedTest` from JUnit Jupiter lets the test method gain access to the `RepetitionInfo`. @@ -514,8 +559,11 @@ xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching] xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration[supported annotations] to see which annotations can be inherited in `@Nested` test classes. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestConfig.class) class GreetingServiceTests { @@ -542,8 +590,9 @@ which annotations can be inherited in `@Nested` test classes. } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig(TestConfig::class) class GreetingServiceTests { @@ -569,6 +618,7 @@ which annotations can be inherited in `@Nested` test classes. } } ---- +====== [[testcontext-support-classes-testng]] == TestNG Support Classes diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc index 6b255cb59b21..3bb86387d393 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc @@ -37,8 +37,11 @@ If you extend a class that is annotated with `@TestExecutionListeners` and you n switch to using the default set of listeners, you can annotate your class with the following. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Switch to default listeners @TestExecutionListeners( @@ -50,8 +53,9 @@ following. } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Switch to default listeners @TestExecutionListeners( @@ -62,6 +66,7 @@ following. // class body... } ---- +====== ==== [[testcontext-tel-config-automatic-discovery]] @@ -103,8 +108,11 @@ default listeners are not registered. In most common testing scenarios, this eff forces the developer to manually declare all default listeners in addition to any custom listeners. The following listing demonstrates this style of configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @TestExecutionListeners({ @@ -121,8 +129,9 @@ listeners. The following listing demonstrates this style of configuration: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ContextConfiguration @TestExecutionListeners( @@ -138,6 +147,7 @@ listeners. The following listing demonstrates this style of configuration: // class body... } ---- +====== The challenge with this approach is that it requires that the developer know exactly which listeners are registered by default. Moreover, the set of default listeners can @@ -165,8 +175,11 @@ configures its `order` value (for example, `500`) to be less than the order of t defaults in front of the `ServletTestExecutionListener`, and the previous example could be replaced with the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration @TestExecutionListeners( @@ -177,8 +190,10 @@ be replaced with the following: // class body... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ContextConfiguration @TestExecutionListeners( @@ -189,4 +204,5 @@ be replaced with the following: // class body... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc index babf258e0ffc..3d609bf25e9c 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc @@ -102,8 +102,11 @@ are preconfigured for transactional support at the class level. The following example demonstrates a common scenario for writing an integration test for a Hibernate-based `UserRepository`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(TestConfig.class) @Transactional @@ -145,8 +148,9 @@ a Hibernate-based `UserRepository`: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig(TestConfig::class) @Transactional @@ -187,6 +191,7 @@ a Hibernate-based `UserRepository`: } } ---- +====== As explained in xref:testing/testcontext-framework/tx.adoc#testcontext-tx-rollback-and-commit-behavior[Transaction Rollback and Commit Behavior], there is no need to clean up the database after the `createUser()` method runs, since any changes made to the @@ -214,8 +219,11 @@ The following example demonstrates some of the features of `TestTransaction`. Se javadoc for {api-spring-framework}/test/context/transaction/TestTransaction.html[`TestTransaction`] for further details. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ContextConfiguration(classes = TestConfig.class) public class ProgrammaticTransactionManagementTests extends @@ -244,8 +252,10 @@ for further details. } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ContextConfiguration(classes = [TestConfig::class]) class ProgrammaticTransactionManagementTests : AbstractTransactionalJUnit4SpringContextTests() { @@ -273,6 +283,7 @@ for further details. } } ---- +====== [[testcontext-tx-before-and-after-tx]] == Running Code Outside of a Transaction @@ -318,8 +329,11 @@ information and configuration examples. xref:testing/testcontext-framework/execu declarative SQL script execution with default transaction rollback semantics. The following example shows the relevant annotations: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig @Transactional(transactionManager = "txMgr") @@ -356,8 +370,9 @@ following example shows the relevant annotations: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitConfig @Transactional(transactionManager = "txMgr") @@ -393,6 +408,7 @@ following example shows the relevant annotations: } ---- +====== [[testcontext-tx-false-positives]] .Avoid false positives when testing ORM code @@ -407,8 +423,11 @@ of work. In the following Hibernate-based example test case, one method demonstr false positive, and the other method correctly exposes the results of flushing the session: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // ... @@ -434,8 +453,9 @@ session: // ... ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // ... @@ -460,11 +480,15 @@ session: // ... ---- +====== The following example shows matching methods for JPA: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // ... @@ -489,8 +513,10 @@ The following example shows matching methods for JPA: // ... ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // ... @@ -515,6 +541,7 @@ The following example shows matching methods for JPA: // ... ---- +====== ===== [[testcontext-tx-orm-lifecycle-callbacks]] @@ -539,8 +566,11 @@ The following example shows how to flush the `EntityManager` to ensure that a `@PostPersist` callback method has been registered for the `Person` entity used in the example. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // ... @@ -565,8 +595,10 @@ example. // ... ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // ... @@ -591,6 +623,7 @@ example. // ... ---- +====== See https://github.com/spring-projects/spring-framework/blob/main/spring-test/src/test/java/org/springframework/test/context/junit/jupiter/orm/JpaEntityListenerTests.java[JpaEntityListenerTests] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc index 5c87d206a113..20e7926a7f59 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc @@ -47,9 +47,11 @@ the provided `MockHttpServletRequest`. When the `loginUser()` method is invoked set parameters). We can then perform assertions against the results based on the known inputs for the username and password. The following listing shows how to do so: -.Request-scoped bean test +[tabs] +====== +Request-scoped bean test:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitWebConfig class RequestScopedBeanTests { @@ -67,8 +69,10 @@ inputs for the username and password. The following listing shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitWebConfig class RequestScopedBeanTests { @@ -86,6 +90,7 @@ inputs for the username and password. The following listing shows how to do so: } } ---- +====== The following code snippet is similar to the one we saw earlier for a request-scoped bean. However, this time, the `userService` bean has a dependency on a session-scoped @@ -119,9 +124,11 @@ the user service has access to the session-scoped `userPreferences` for the curr `MockHttpSession`, and we can perform assertions against the results based on the configured theme. The following example shows how to do so: -.Session-scoped bean test +[tabs] +====== +Session-scoped bean test:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitWebConfig class SessionScopedBeanTests { @@ -139,8 +146,9 @@ configured theme. The following example shows how to do so: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @SpringJUnitWebConfig class SessionScopedBeanTests { @@ -157,4 +165,5 @@ configured theme. The following example shows how to do so: } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc b/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc index f5f1cab0a7bb..900596e07ea7 100644 --- a/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc +++ b/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc @@ -32,17 +32,23 @@ xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Java c controller(s), and creates a xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[WebHandler chain] to handle requests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebTestClient client = WebTestClient.bindToController(new TestController()).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = WebTestClient.bindToController(TestController()).build() ---- +====== For Spring MVC, use the following which delegates to the {api-spring-framework}/test/web/servlet/setup/StandaloneMockMvcBuilder.html[StandaloneMockMvcBuilder] @@ -50,17 +56,23 @@ to load infrastructure equivalent to the xref:web/webmvc/mvc-config.adoc[WebMvc registers the given controller(s), and creates an instance of xref:testing/spring-mvc-test-framework.adoc[MockMvc] to handle requests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebTestClient client = MockMvcWebTestClient.bindToController(new TestController()).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = MockMvcWebTestClient.bindToController(TestController()).build() ---- +====== @@ -76,8 +88,11 @@ For WebFlux, use the following where the Spring `ApplicationContext` is passed t to create the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[WebHandler chain] to handle requests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @SpringJUnitConfig(WebConfig.class) // <1> class MyTests { @@ -90,6 +105,7 @@ requests: } } ---- +====== <1> Specify the configuration to load <2> Inject the configuration <3> Create the `WebTestClient` @@ -117,8 +133,11 @@ For Spring MVC, use the following where the Spring `ApplicationContext` is passe to create a xref:testing/spring-mvc-test-framework.adoc[MockMvc] instance to handle requests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExtendWith(SpringExtension.class) @WebAppConfiguration("classpath:META-INF/web-resources") // <1> @@ -139,6 +158,7 @@ requests: } } ---- +====== <1> Specify the configuration to load <2> Inject the configuration <3> Create the `WebTestClient` @@ -180,18 +200,24 @@ mock request and response objects, without a running server. For WebFlux, use the following which delegates to `RouterFunctions.toWebHandler` to create a server setup to handle requests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RouterFunction route = ... client = WebTestClient.bindToRouterFunction(route).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val route: RouterFunction<*> = ... val client = WebTestClient.bindToRouterFunction(route).build() ---- +====== For Spring MVC there are currently no options to test xref:web/webmvc-functional.adoc[WebMvc functional endpoints]. @@ -203,16 +229,22 @@ xref:web/webmvc-functional.adoc[WebMvc functional endpoints]. This setup connects to a running server to perform full, end-to-end HTTP tests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client = WebTestClient.bindToServer().baseUrl("http://localhost:8080").build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client = WebTestClient.bindToServer().baseUrl("http://localhost:8080").build() ---- +====== @@ -225,22 +257,28 @@ are readily available following `bindToServer()`. For all other configuration op you need to use `configureClient()` to transition from server to client configuration, as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client = WebTestClient.bindToController(new TestController()) .configureClient() .baseUrl("/test") .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client = WebTestClient.bindToController(TestController()) .configureClient() .baseUrl("/test") .build() ---- +====== @@ -258,8 +296,11 @@ instead continues with a workflow to verify responses. To assert the response status and headers, use the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.get().uri("/persons/1") .accept(MediaType.APPLICATION_JSON) @@ -267,8 +308,10 @@ To assert the response status and headers, use the following: .expectStatus().isOk() .expectHeader().contentType(MediaType.APPLICATION_JSON); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client.get().uri("/persons/1") .accept(MediaType.APPLICATION_JSON) @@ -276,14 +319,18 @@ To assert the response status and headers, use the following: .expectStatus().isOk() .expectHeader().contentType(MediaType.APPLICATION_JSON) ---- +====== If you would like for all expectations to be asserted even if one of them fails, you can use `expectAll(..)` instead of multiple chained `expect*(..)` calls. This feature is similar to the _soft assertions_ support in AssertJ and the `assertAll()` support in JUnit Jupiter. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.get().uri("/persons/1") .accept(MediaType.APPLICATION_JSON) @@ -293,6 +340,7 @@ JUnit Jupiter. spec -> spec.expectHeader().contentType(MediaType.APPLICATION_JSON) ); ---- +====== You can then choose to decode the response body through one of the following: @@ -302,16 +350,21 @@ You can then choose to decode the response body through one of the following: And perform assertions on the resulting higher level Object(s): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.get().uri("/persons") .exchange() .expectStatus().isOk() .expectBodyList(Person.class).hasSize(3).contains(person); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.reactive.server.expectBodyList @@ -320,12 +373,16 @@ And perform assertions on the resulting higher level Object(s): .expectStatus().isOk() .expectBodyList().hasSize(3).contains(person) ---- +====== If the built-in assertions are insufficient, you can consume the object instead and perform any other assertions: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import org.springframework.test.web.reactive.server.expectBody @@ -337,8 +394,10 @@ perform any other assertions: // custom assertions (e.g. AssertJ)... }); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client.get().uri("/persons/1") .exchange() @@ -348,11 +407,15 @@ perform any other assertions: // custom assertions (e.g. AssertJ)... } ---- +====== Or you can exit the workflow and obtain an `EntityExchangeResult`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- EntityExchangeResult result = client.get().uri("/persons/1") .exchange() @@ -360,8 +423,10 @@ Or you can exit the workflow and obtain an `EntityExchangeResult`: .expectBody(Person.class) .returnResult(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.reactive.server.expectBody @@ -371,6 +436,7 @@ Or you can exit the workflow and obtain an `EntityExchangeResult`: .expectBody() .returnResult() ---- +====== TIP: When you need to decode to a target type with generics, look for the overloaded methods that accept @@ -384,8 +450,11 @@ instead of `Class`. If the response is not expected to have content, you can assert that as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.post().uri("/persons") .body(personMono, Person.class) @@ -393,8 +462,10 @@ If the response is not expected to have content, you can assert that as follows: .expectStatus().isCreated() .expectBody().isEmpty(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client.post().uri("/persons") .bodyValue(person) @@ -402,26 +473,33 @@ If the response is not expected to have content, you can assert that as follows: .expectStatus().isCreated() .expectBody().isEmpty() ---- +====== If you want to ignore the response content, the following releases the content without any assertions: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.get().uri("/persons/123") .exchange() .expectStatus().isNotFound() .expectBody(Void.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client.get().uri("/persons/123") .exchange() .expectStatus().isNotFound .expectBody() ---- +====== @@ -433,8 +511,11 @@ content rather than through higher level Object(s). To verify the full JSON content with https://jsonassert.skyscreamer.org[JSONAssert]: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.get().uri("/persons/1") .exchange() @@ -442,8 +523,10 @@ To verify the full JSON content with https://jsonassert.skyscreamer.org[JSONAsse .expectBody() .json("{\"name\":\"Jane\"}") ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client.get().uri("/persons/1") .exchange() @@ -451,11 +534,15 @@ To verify the full JSON content with https://jsonassert.skyscreamer.org[JSONAsse .expectBody() .json("{\"name\":\"Jane\"}") ---- +====== To verify JSON content with https://github.com/jayway/JsonPath[JSONPath]: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- client.get().uri("/persons") .exchange() @@ -464,8 +551,10 @@ To verify JSON content with https://github.com/jayway/JsonPath[JSONPath]: .jsonPath("$[0].name").isEqualTo("Jane") .jsonPath("$[1].name").isEqualTo("Jason"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- client.get().uri("/persons") .exchange() @@ -474,6 +563,7 @@ To verify JSON content with https://github.com/jayway/JsonPath[JSONPath]: .jsonPath("$[0].name").isEqualTo("Jane") .jsonPath("$[1].name").isEqualTo("Jason") ---- +====== @@ -484,8 +574,11 @@ To test potentially infinite streams such as `"text/event-stream"` or `"application/x-ndjson"`, start by verifying the response status and headers, and then obtain a `FluxExchangeResult`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- FluxExchangeResult result = client.get().uri("/events") .accept(TEXT_EVENT_STREAM) @@ -494,8 +587,10 @@ obtain a `FluxExchangeResult`: .returnResult(MyEvent.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.test.web.reactive.server.returnResult @@ -505,11 +600,15 @@ obtain a `FluxExchangeResult`: .expectStatus().isOk() .returnResult() ---- +====== Now you're ready to consume the response stream with `StepVerifier` from `reactor-test`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Flux eventFlux = result.getResponseBody(); @@ -520,8 +619,10 @@ Now you're ready to consume the response stream with `StepVerifier` from `reacto .thenCancel() .verify(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val eventFlux = result.getResponseBody() @@ -532,6 +633,7 @@ Now you're ready to consume the response stream with `StepVerifier` from `reacto .thenCancel() .verify() ---- +====== [[webtestclient-mockmvc]] @@ -544,8 +646,11 @@ When testing a Spring MVC application with a MockMvc server setup, you have the choice to perform further assertions on the server response. To do that start by obtaining an `ExchangeResult` after asserting the body: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // For a response with a body EntityExchangeResult result = client.get().uri("/persons/1") @@ -559,8 +664,10 @@ obtaining an `ExchangeResult` after asserting the body: .exchange() .expectBody().isEmpty(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // For a response with a body val result = client.get().uri("/persons/1") @@ -574,21 +681,28 @@ obtaining an `ExchangeResult` after asserting the body: .exchange() .expectBody().isEmpty(); ---- +====== Then switch to MockMvc server response assertions: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- MockMvcWebTestClient.resultActionsFor(result) .andExpect(model().attribute("integer", 3)) .andExpect(model().attribute("string", "a string value")); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- MockMvcWebTestClient.resultActionsFor(result) .andExpect(model().attribute("integer", 3)) .andExpect(model().attribute("string", "a string value")); ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc b/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc index 8ee097700de1..9c63eed3a298 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc @@ -84,8 +84,11 @@ annotation enables cross-origin requests on annotated controller methods, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RestController @RequestMapping("/account") @@ -103,8 +106,10 @@ following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RestController @RequestMapping("/account") @@ -122,6 +127,7 @@ following example shows: } } ---- +====== -- By default, `@CrossOrigin` allows: @@ -142,8 +148,11 @@ the `allowOriginPatterns` property may be used to match to a dynamic set of orig The following example specifies a certain domain and sets `maxAge` to an hour: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @CrossOrigin(origins = "https://domain2.com", maxAge = 3600) @RestController @@ -161,8 +170,10 @@ The following example specifies a certain domain and sets `maxAge` to an hour: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @CrossOrigin("https://domain2.com", maxAge = 3600) @RestController @@ -180,14 +191,18 @@ The following example specifies a certain domain and sets `maxAge` to an hour: } } ---- +====== -- You can use `@CrossOrigin` at both the class and the method level, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @CrossOrigin(maxAge = 3600) // <1> @RestController @@ -206,6 +221,7 @@ as the following example shows: } } ---- +====== <1> Using `@CrossOrigin` at the class level. <2> Using `@CrossOrigin` at the method level. @@ -261,8 +277,11 @@ the `allowOriginPatterns` property may be used to match to a dynamic set of orig To enable CORS in the WebFlux Java configuration, you can use the `CorsRegistry` callback, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -282,8 +301,10 @@ as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -302,6 +323,7 @@ as the following example shows: } } ---- +====== @@ -321,8 +343,11 @@ CORS. To configure the filter, you can declare a `CorsWebFilter` bean and pass a `CorsConfigurationSource` to its constructor, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Bean CorsWebFilter corsFilter() { @@ -343,8 +368,10 @@ To configure the filter, you can declare a `CorsWebFilter` bean and pass a return new CorsWebFilter(source); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Bean fun corsFilter(): CorsWebFilter { @@ -365,3 +392,4 @@ To configure the filter, you can declare a `CorsWebFilter` bean and pass a return CorsWebFilter(source) } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc b/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc index daba67c29027..d0ed6a69d07d 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc @@ -30,8 +30,11 @@ difference that router functions provide not just data, but also behavior. `RouterFunctions.route()` provides a router builder that facilitates the creation of routers, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.http.MediaType.APPLICATION_JSON; import static org.springframework.web.reactive.function.server.RequestPredicates.*; @@ -64,6 +67,7 @@ as the following example shows: } } ---- +====== <1> Create router using `route()`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -133,80 +137,113 @@ while access to the body is provided through the `body` methods. The following example extracts the request body to a `Mono`: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- Mono string = request.bodyToMono(String.class); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val string = request.awaitBody() ---- +====== The following example extracts the body to a `Flux` (or a `Flow` in Kotlin), where `Person` objects are decoded from some serialized form, such as JSON or XML: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- Flux people = request.bodyToFlux(Person.class); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val people = request.bodyToFlow() ---- +====== The preceding examples are shortcuts that use the more general `ServerRequest.body(BodyExtractor)`, which accepts the `BodyExtractor` functional strategy interface. The utility class `BodyExtractors` provides access to a number of instances. For example, the preceding examples can also be written as follows: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- Mono string = request.body(BodyExtractors.toMono(String.class)); Flux people = request.body(BodyExtractors.toFlux(Person.class)); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val string = request.body(BodyExtractors.toMono(String::class.java)).awaitSingle() val people = request.body(BodyExtractors.toFlux(Person::class.java)).asFlow() ---- +====== The following example shows how to access form data: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- Mono> map = request.formData(); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val map = request.awaitFormData() ---- +====== The following example shows how to access multipart data as a map: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- Mono> map = request.multipartData(); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val map = request.awaitMultipartData() ---- +====== The following example shows how to access multipart data, one at a time, in streaming fashion: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Flux allPartEvents = request.bodyToFlux(PartEvent.class); allPartsEvents.windowUntil(PartEvent::isLast) @@ -232,8 +269,9 @@ allPartsEvents.windowUntil(PartEvent::isLast) })); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val parts = request.bodyToFlux() allPartsEvents.windowUntil(PartEvent::isLast) @@ -258,6 +296,7 @@ allPartsEvents.windowUntil(PartEvent::isLast) } } ---- +====== Note that the body contents of the `PartEvent` objects must be completely consumed, relayed, or released to avoid memory leaks. @@ -269,47 +308,65 @@ a `build` method to create it. You can use the builder to set the response statu headers, or to provide a body. The following example creates a 200 (OK) response with JSON content: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- Mono person = ... ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person, Person.class); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val person: Person = ... ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).bodyValue(person) ---- +====== The following example shows how to build a 201 (CREATED) response with a `Location` header and no body: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- URI location = ... ServerResponse.created(location).build(); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val location: URI = ... ServerResponse.created(location).build() ---- +====== Depending on the codec used, it is possible to pass hint parameters to customize how the body is serialized or deserialized. For example, to specify a https://www.baeldung.com/jackson-json-view-annotation[Jackson JSON view]: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- ServerResponse.ok().hint(Jackson2CodecSupport.JSON_VIEW_HINT, MyJacksonView.class).body(...); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- ServerResponse.ok().hint(Jackson2CodecSupport.JSON_VIEW_HINT, MyJacksonView::class.java).body(...) ---- +====== [[webflux-fn-handler-classes]] @@ -318,17 +375,23 @@ ServerResponse.ok().hint(Jackson2CodecSupport.JSON_VIEW_HINT, MyJacksonView::cla We can write a handler function as a lambda, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HandlerFunction helloWorld = request -> ServerResponse.ok().bodyValue("Hello World"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val helloWorld = HandlerFunction { ServerResponse.ok().bodyValue("Hello World") } ---- +====== -- That is convenient, but in an application we need multiple functions, and multiple inline @@ -338,8 +401,11 @@ has a similar role as `@Controller` in an annotation-based application. For example, the following class exposes a reactive `Person` repository: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.http.MediaType.APPLICATION_JSON; import static org.springframework.web.reactive.function.server.ServerResponse.ok; @@ -370,6 +436,7 @@ public class PersonHandler { } } ---- +====== <1> `listPeople` is a handler function that returns all `Person` objects found in the repository as JSON. <2> `createPerson` is a handler function that stores a new `Person` contained in the request body. @@ -422,8 +489,11 @@ A functional endpoint can use Spring's xref:web/webmvc/mvc-config/validation.ado apply validation to the request body. For example, given a custom Spring xref:web/webmvc/mvc-config/validation.adoc[Validator] implementation for a `Person`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class PersonHandler { @@ -445,6 +515,7 @@ xref:web/webmvc/mvc-config/validation.adoc[Validator] implementation for a `Pers } } ---- +====== <1> Create `Validator` instance. <2> Apply validation. <3> Raise exception for a 400 response. @@ -515,15 +586,20 @@ and so on. The following example uses a request predicate to create a constraint based on the `Accept` header: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RouterFunction route = RouterFunctions.route() .GET("/hello-world", accept(MediaType.TEXT_PLAIN), request -> ServerResponse.ok().bodyValue("Hello World")).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val route = coRouter { GET("/hello-world", accept(TEXT_PLAIN)) { @@ -531,6 +607,7 @@ header: } } ---- +====== You can compose multiple request predicates together by using: @@ -568,8 +645,11 @@ There are also other ways to compose multiple router functions together: The following example shows the composition of four routes: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.http.MediaType.APPLICATION_JSON; import static org.springframework.web.reactive.function.server.RequestPredicates.*; @@ -586,6 +666,7 @@ RouterFunction route = route() .add(otherRoute) // <4> .build(); ---- +====== <1> pass:q[`GET /person/{id}`] with an `Accept` header that matches JSON is routed to `PersonHandler.getPerson` <2> `GET /person` with an `Accept` header that matches JSON is routed to @@ -630,8 +711,11 @@ this duplication by using a type-level `@RequestMapping` annotation that maps to router function builder. For instance, the last few lines of the example above can be improved in the following way by using nested routes: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RouterFunction route = route() .path("/person", builder -> builder // <1> @@ -640,6 +724,7 @@ RouterFunction route = route() .POST(handler::createPerson)) .build(); ---- +====== <1> Note that second parameter of `path` is a consumer that takes the router builder. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -660,8 +745,11 @@ the `nest` method on the builder. The above still contains some duplication in the form of the shared `Accept`-header predicate. We can further improve by using the `nest` method together with `accept`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RouterFunction route = route() .path("/person", b1 -> b1 @@ -671,8 +759,10 @@ We can further improve by using the `nest` method together with `accept`: .POST(handler::createPerson)) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val route = coRouter { "/person".nest { @@ -684,6 +774,7 @@ We can further improve by using the `nest` method together with `accept`: } } ---- +====== [[webflux-fn-running]] @@ -721,8 +812,11 @@ starter. The following example shows a WebFlux Java configuration (see xref:web/webflux/dispatcher-handler.adoc[DispatcherHandler] for how to run it): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -756,8 +850,10 @@ xref:web/webflux/dispatcher-handler.adoc[DispatcherHandler] for how to run it): } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -788,6 +884,7 @@ xref:web/webflux/dispatcher-handler.adoc[DispatcherHandler] for how to run it): } } ---- +====== @@ -803,8 +900,11 @@ The filter will apply to all routes that are built by the builder. This means that filters defined in nested routes do not apply to "top-level" routes. For instance, consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RouterFunction route = route() .path("/person", b1 -> b1 @@ -818,6 +918,7 @@ For instance, consider the following example: .after((request, response) -> logResponse(response)) // <2> .build(); ---- +====== <1> The `before` filter that adds a custom request header is only applied to the two GET routes. <2> The `after` filter that logs the response is applied to all routes, including the nested ones. @@ -853,8 +954,11 @@ Now we can add a simple security filter to our route, assuming that we have a `S can determine whether a particular path is allowed. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- SecurityManager securityManager = ... @@ -874,8 +978,10 @@ The following example shows how to do so: }) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val securityManager: SecurityManager = ... @@ -895,6 +1001,7 @@ The following example shows how to do so: } } ---- +====== The preceding example demonstrates that invoking the `next.handle(ServerRequest)` is optional. We only let the handler function be run when access is allowed. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-view.adoc b/framework-docs/modules/ROOT/pages/web/webflux-view.adoc index 6122ef22bd11..491a064f3ffd 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-view.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-view.adoc @@ -47,8 +47,11 @@ integration for using Spring WebFlux with FreeMarker templates. The following example shows how to configure FreeMarker as a view technology: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -69,8 +72,10 @@ The following example shows how to configure FreeMarker as a view technology: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -88,6 +93,7 @@ The following example shows how to configure FreeMarker as a view technology: } } ---- +====== Your templates need to be stored in the directory specified by the `FreeMarkerConfigurer`, shown in the preceding example. Given the preceding configuration, if your controller @@ -106,8 +112,11 @@ properties on the `FreeMarkerConfigurer` bean. The `freemarkerSettings` property a `java.util.Properties` object, and the `freemarkerVariables` property requires a `java.util.Map`. The following example shows how to use a `FreeMarkerConfigurer`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -127,8 +136,10 @@ a `java.util.Properties` object, and the `freemarkerVariables` property requires } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -143,6 +154,7 @@ a `java.util.Properties` object, and the `freemarkerVariables` property requires } } ---- +====== See the FreeMarker documentation for details of settings and variables as they apply to the `Configuration` object. @@ -245,8 +257,11 @@ You can declare a `ScriptTemplateConfigurer` bean to specify the script engine t the script files to load, what function to call to render templates, and so on. The following example uses Mustache templates and the Nashorn JavaScript engine: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -268,8 +283,10 @@ The following example uses Mustache templates and the Nashorn JavaScript engine: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -288,6 +305,7 @@ The following example uses Mustache templates and the Nashorn JavaScript engine: } } ---- +====== The `render` function is called with the following parameters: @@ -307,8 +325,11 @@ https://en.wikipedia.org/wiki/Polyfill[polyfill] in order to emulate some browser facilities not available in the server-side script engine. The following example shows how to set a custom render function: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -330,8 +351,10 @@ The following example shows how to set a custom render function: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -350,6 +373,7 @@ The following example shows how to set a custom render function: } } ---- +====== NOTE: Setting the `sharedEngine` property to `false` is required when using non-thread-safe script engines with templating libraries not designed for concurrency, such as Handlebars or diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-attributes.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-attributes.adoc index 78fc4db2a525..1683021b269b 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-attributes.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-attributes.adoc @@ -5,8 +5,11 @@ You can add attributes to a request. This is convenient if you want to pass info through the filter chain and influence the behavior of filters for a given request. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient client = WebClient.builder() .filter((request, next) -> { @@ -22,8 +25,10 @@ For example: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = WebClient.builder() .filter { request, _ -> @@ -37,6 +42,7 @@ For example: .retrieve() .awaitBody() ---- +====== Note that you can configure a `defaultRequest` callback globally at the `WebClient.Builder` level which lets you insert attributes into all requests, diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-body.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-body.adoc index 900041278a73..4419eaa296fe 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-body.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-body.adoc @@ -4,8 +4,11 @@ The request body can be encoded from any asynchronous type handled by `ReactiveAdapterRegistry`, like `Mono` or Kotlin Coroutines `Deferred` as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono personMono = ... ; @@ -16,8 +19,10 @@ like `Mono` or Kotlin Coroutines `Deferred` as the following example shows: .retrieve() .bodyToMono(Void.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val personDeferred: Deferred = ... @@ -28,11 +33,15 @@ like `Mono` or Kotlin Coroutines `Deferred` as the following example shows: .retrieve() .awaitBody() ---- +====== You can also have a stream of objects be encoded, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Flux personFlux = ... ; @@ -43,8 +52,10 @@ You can also have a stream of objects be encoded, as the following example shows .retrieve() .bodyToMono(Void.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val people: Flow = ... @@ -55,12 +66,16 @@ You can also have a stream of objects be encoded, as the following example shows .retrieve() .awaitBody() ---- +====== Alternatively, if you have the actual value, you can use the `bodyValue` shortcut method, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Person person = ... ; @@ -71,8 +86,10 @@ as the following example shows: .retrieve() .bodyToMono(Void.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val person: Person = ... @@ -83,6 +100,7 @@ as the following example shows: .retrieve() .awaitBody() ---- +====== @@ -93,8 +111,11 @@ To send form data, you can provide a `MultiValueMap` as the body content is automatically set to `application/x-www-form-urlencoded` by the `FormHttpMessageWriter`. The following example shows how to use `MultiValueMap`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- MultiValueMap formData = ... ; @@ -104,8 +125,10 @@ content is automatically set to `application/x-www-form-urlencoded` by the .retrieve() .bodyToMono(Void.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val formData: MultiValueMap = ... @@ -115,11 +138,15 @@ content is automatically set to `application/x-www-form-urlencoded` by the .retrieve() .awaitBody() ---- +====== You can also supply form data in-line by using `BodyInserters`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.web.reactive.function.BodyInserters.*; @@ -129,8 +156,10 @@ You can also supply form data in-line by using `BodyInserters`, as the following .retrieve() .bodyToMono(Void.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.web.reactive.function.BodyInserters.* @@ -140,6 +169,7 @@ You can also supply form data in-line by using `BodyInserters`, as the following .retrieve() .awaitBody() ---- +====== @@ -151,8 +181,11 @@ either `Object` instances that represent part content or `HttpEntity` instances headers for a part. `MultipartBodyBuilder` provides a convenient API to prepare a multipart request. The following example shows how to create a `MultiValueMap`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- MultipartBodyBuilder builder = new MultipartBodyBuilder(); builder.part("fieldPart", "fieldValue"); @@ -162,8 +195,10 @@ multipart request. The following example shows how to create a `MultiValueMap> parts = builder.build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val builder = MultipartBodyBuilder().apply { part("fieldPart", "fieldValue") @@ -174,6 +209,7 @@ multipart request. The following example shows how to create a `MultiValueMap() ---- +====== If the `MultiValueMap` contains at least one non-`String` value, which could also represent regular form data (that is, `application/x-www-form-urlencoded`), you need not @@ -215,8 +257,11 @@ set the `Content-Type` to `multipart/form-data`. This is always the case when us As an alternative to `MultipartBodyBuilder`, you can also provide multipart content, inline-style, through the built-in `BodyInserters`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.web.reactive.function.BodyInserters.*; @@ -226,8 +271,10 @@ inline-style, through the built-in `BodyInserters`, as the following example sho .retrieve() .bodyToMono(Void.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.web.reactive.function.BodyInserters.* @@ -237,6 +284,7 @@ inline-style, through the built-in `BodyInserters`, as the following example sho .retrieve() .awaitBody() ---- +====== [[partevent]] === `PartEvent` @@ -252,8 +300,11 @@ the `WebClient`. For instance, this sample will POST a multipart form containing a form field and a file. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Resource resource = ... Mono result = webClient @@ -266,8 +317,10 @@ Mono result = webClient .retrieve() .bodyToMono(String.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- var resource: Resource = ... var result: Mono = webClient @@ -282,6 +335,7 @@ var result: Mono = webClient .retrieve() .bodyToMono() ---- +====== On the server side, `PartEvent` objects that are received via `@RequestBody` or `ServerRequest::bodyToFlux(PartEvent.class)` can be relayed to another service diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc index 3b4b44e64d63..08d788f0e04d 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc @@ -21,26 +21,35 @@ You can also use `WebClient.builder()` with further options: For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient client = WebClient.builder() .codecs(configurer -> ... ) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val webClient = WebClient.builder() .codecs { configurer -> ... } .build() ---- +====== Once built, a `WebClient` is immutable. However, you can clone it and build a modified copy as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient client1 = WebClient.builder() .filter(filterA).filter(filterB).build(); @@ -52,8 +61,10 @@ modified copy as follows: // client2 has filterA, filterB, filterC, filterD ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client1 = WebClient.builder() .filter(filterA).filter(filterB).build() @@ -65,6 +76,7 @@ modified copy as follows: // client2 has filterA, filterB, filterC, filterD ---- +====== [[webflux-client-builder-maxinmemorysize]] == MaxInMemorySize @@ -79,20 +91,26 @@ org.springframework.core.io.buffer.DataBufferLimitException: Exceeded limit on m To change the limit for default codecs, use the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient webClient = WebClient.builder() .codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024)) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val webClient = WebClient.builder() .codecs { configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024) } .build() ---- +====== @@ -101,8 +119,11 @@ To change the limit for default codecs, use the following: To customize Reactor Netty settings, provide a pre-configured `HttpClient`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpClient httpClient = HttpClient.create().secure(sslSpec -> ...); @@ -110,8 +131,10 @@ To customize Reactor Netty settings, provide a pre-configured `HttpClient`: .clientConnector(new ReactorClientHttpConnector(httpClient)) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val httpClient = HttpClient.create().secure { ... } @@ -119,6 +142,7 @@ To customize Reactor Netty settings, provide a pre-configured `HttpClient`: .clientConnector(ReactorClientHttpConnector(httpClient)) .build() ---- +====== [[webflux-client-builder-reactor-resources]] @@ -137,20 +161,26 @@ Netty global resources are shut down when the Spring `ApplicationContext` is clo as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Bean public ReactorResourceFactory reactorResourceFactory() { return new ReactorResourceFactory(); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Bean fun reactorResourceFactory() = ReactorResourceFactory() ---- +====== -- You can also choose not to participate in the global Reactor Netty resources. However, @@ -158,8 +188,11 @@ in this mode, the burden is on you to ensure that all Reactor Netty client and s instances use shared resources, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Bean public ReactorResourceFactory resourceFactory() { @@ -181,6 +214,7 @@ instances use shared resources, as the following example shows: return WebClient.builder().clientConnector(connector).build(); // <3> } ---- +====== <1> Create resources independent of global ones. <2> Use the `ReactorClientHttpConnector` constructor with resource factory. <3> Plug the connector into the `WebClient.Builder`. @@ -216,8 +250,11 @@ instances use shared resources, as the following example shows: To configure a connection timeout: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import io.netty.channel.ChannelOption; @@ -228,8 +265,10 @@ To configure a connection timeout: .clientConnector(new ReactorClientHttpConnector(httpClient)) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import io.netty.channel.ChannelOption @@ -240,11 +279,15 @@ To configure a connection timeout: .clientConnector(ReactorClientHttpConnector(httpClient)) .build(); ---- +====== To configure a read or write timeout: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import io.netty.handler.timeout.ReadTimeoutHandler; import io.netty.handler.timeout.WriteTimeoutHandler; @@ -257,8 +300,10 @@ To configure a read or write timeout: // Create WebClient... ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import io.netty.handler.timeout.ReadTimeoutHandler import io.netty.handler.timeout.WriteTimeoutHandler @@ -271,30 +316,40 @@ To configure a read or write timeout: // Create WebClient... ---- +====== To configure a response timeout for all requests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpClient httpClient = HttpClient.create() .responseTimeout(Duration.ofSeconds(2)); // Create WebClient... ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val httpClient = HttpClient.create() .responseTimeout(Duration.ofSeconds(2)); // Create WebClient... ---- +====== To configure a response timeout for a specific request: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient.create().get() .uri("https://example.org/path") @@ -305,8 +360,10 @@ To configure a response timeout for a specific request: .retrieve() .bodyToMono(String.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- WebClient.create().get() .uri("https://example.org/path") @@ -317,6 +374,7 @@ To configure a response timeout for a specific request: .retrieve() .bodyToMono(String::class.java) ---- +====== @@ -325,8 +383,11 @@ To configure a response timeout for a specific request: The following example shows how to customize the JDK `HttpClient`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpClient httpClient = HttpClient.newBuilder() .followRedirects(Redirect.NORMAL) @@ -339,8 +400,9 @@ The following example shows how to customize the JDK `HttpClient`: WebClient webClient = WebClient.builder().clientConnector(connector).build(); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val httpClient = HttpClient.newBuilder() .followRedirects(Redirect.NORMAL) @@ -351,6 +413,7 @@ The following example shows how to customize the JDK `HttpClient`: val webClient = WebClient.builder().clientConnector(connector).build() ---- +====== @@ -360,8 +423,11 @@ The following example shows how to customize the JDK `HttpClient`: The following example shows how to customize Jetty `HttpClient` settings: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpClient httpClient = new HttpClient(); httpClient.setCookieStore(...); @@ -370,8 +436,10 @@ The following example shows how to customize Jetty `HttpClient` settings: .clientConnector(new JettyClientHttpConnector(httpClient)) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val httpClient = HttpClient() httpClient.cookieStore = ... @@ -380,6 +448,7 @@ The following example shows how to customize Jetty `HttpClient` settings: .clientConnector(JettyClientHttpConnector(httpClient)) .build(); ---- +====== -- By default, `HttpClient` creates its own resources (`Executor`, `ByteBufferPool`, `Scheduler`), @@ -391,8 +460,11 @@ declaring a Spring-managed bean of type `JettyResourceFactory`, as the following shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Bean public JettyResourceFactory resourceFactory() { @@ -411,6 +483,7 @@ shows: return WebClient.builder().clientConnector(connector).build(); <2> } ---- +====== <1> Use the `JettyClientHttpConnector` constructor with resource factory. <2> Plug the connector into the `WebClient.Builder`. @@ -442,8 +515,11 @@ shows: The following example shows how to customize Apache HttpComponents `HttpClient` settings: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpAsyncClientBuilder clientBuilder = HttpAsyncClients.custom(); clientBuilder.setDefaultRequestConfig(...); @@ -453,8 +529,10 @@ The following example shows how to customize Apache HttpComponents `HttpClient` WebClient webClient = WebClient.builder().clientConnector(connector).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = HttpAsyncClients.custom().apply { setDefaultRequestConfig(...) @@ -462,5 +540,6 @@ The following example shows how to customize Apache HttpComponents `HttpClient` val connector = HttpComponentsClientHttpConnector(client) val webClient = WebClient.builder().clientConnector(connector).build() ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc index 0cb4e619b3c1..749517ae205a 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc @@ -9,8 +9,11 @@ e.g. via `concatMap`, then you'll need to use the Reactor `Context`. The Reactor `Context` needs to be populated at the end of a reactive chain in order to apply to all operations. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient client = WebClient.builder() .filter((request, next) -> @@ -28,6 +31,7 @@ apply to all operations. For example: }) .contextWrite(context -> context.put("foo", ...)); ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-exchange.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-exchange.adoc index e1f1f3976501..83ddb7f3a88d 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-exchange.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-exchange.adoc @@ -5,8 +5,11 @@ The `exchangeToMono()` and `exchangeToFlux()` methods (or `awaitExchange { }` an are useful for more advanced cases that require more control, such as to decode the response differently depending on the response status: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono entityMono = client.get() .uri("/persons/1") @@ -21,8 +24,10 @@ depending on the response status: } }); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val entity = client.get() .uri("/persons/1") @@ -36,6 +41,7 @@ val entity = client.get() } } ---- +====== When using the above, after the returned `Mono` or `Flux` completes, the response body is checked and if not consumed it is released to prevent memory and connection leaks. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-filter.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-filter.adoc index c571ed258cf9..4fd49bf8045a 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-filter.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-filter.adoc @@ -4,8 +4,11 @@ You can register a client filter (`ExchangeFilterFunction`) through the `WebClient.Builder` in order to intercept and modify requests, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient client = WebClient.builder() .filter((request, next) -> { @@ -18,8 +21,10 @@ in order to intercept and modify requests, as the following example shows: }) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = WebClient.builder() .filter { request, next -> @@ -32,12 +37,16 @@ in order to intercept and modify requests, as the following example shows: } .build() ---- +====== This can be used for cross-cutting concerns, such as authentication. The following example uses a filter for basic authentication through a static factory method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication; @@ -45,8 +54,10 @@ a filter for basic authentication through a static factory method: .filter(basicAuthentication("user", "password")) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication @@ -54,12 +65,16 @@ a filter for basic authentication through a static factory method: .filter(basicAuthentication("user", "password")) .build() ---- +====== Filters can be added or removed by mutating an existing `WebClient` instance, resulting in a new `WebClient` instance that does not affect the original one. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication; @@ -69,13 +84,16 @@ in a new `WebClient` instance that does not affect the original one. For example }) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = webClient.mutate() .filters { it.add(0, basicAuthentication("user", "password")) } .build() ---- +====== `WebClient` is a thin facade around the chain of filters followed by an `ExchangeFunction`. It provides a workflow to make requests, to encode to and from higher @@ -85,8 +103,11 @@ its content or to otherwise propagate it downstream to the `WebClient` which wil the same. Below is a filter that handles the `UNAUTHORIZED` status code but ensures that any response content, whether expected or not, is released: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public ExchangeFilterFunction renewTokenFilter() { return (request, next) -> next.exchange(request).flatMap(response -> { @@ -103,8 +124,10 @@ any response content, whether expected or not, is released: }); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun renewTokenFilter(): ExchangeFilterFunction? { return ExchangeFilterFunction { request: ClientRequest?, next: ExchangeFunction -> @@ -123,6 +146,7 @@ any response content, whether expected or not, is released: } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-retrieve.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-retrieve.adoc index 500ae9d3a8b3..28cb417588a7 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-retrieve.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-retrieve.adoc @@ -3,8 +3,11 @@ The `retrieve()` method can be used to declare how to extract the response. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient client = WebClient.create("https://example.org"); @@ -13,8 +16,10 @@ The `retrieve()` method can be used to declare how to extract the response. For .retrieve() .toEntity(Person.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = WebClient.create("https://example.org") @@ -23,11 +28,15 @@ The `retrieve()` method can be used to declare how to extract the response. For .retrieve() .toEntity().awaitSingle() ---- +====== Or to get only the body: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient client = WebClient.create("https://example.org"); @@ -36,8 +45,10 @@ Or to get only the body: .retrieve() .bodyToMono(Person.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = WebClient.create("https://example.org") @@ -46,32 +57,42 @@ Or to get only the body: .retrieve() .awaitBody() ---- +====== To get a stream of decoded objects: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Flux result = client.get() .uri("/quotes").accept(MediaType.TEXT_EVENT_STREAM) .retrieve() .bodyToFlux(Quote.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val result = client.get() .uri("/quotes").accept(MediaType.TEXT_EVENT_STREAM) .retrieve() .bodyToFlow() ---- +====== By default, 4xx or 5xx responses result in an `WebClientResponseException`, including sub-classes for specific HTTP status codes. To customize the handling of error responses, use `onStatus` handlers as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono result = client.get() .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) @@ -80,8 +101,10 @@ responses, use `onStatus` handlers as follows: .onStatus(HttpStatus::is5xxServerError, response -> ...) .bodyToMono(Person.class); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val result = client.get() .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON) @@ -90,6 +113,7 @@ responses, use `onStatus` handlers as follows: .onStatus(HttpStatus::is5xxServerError) { ... } .awaitBody() ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-synchronous.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-synchronous.adoc index 07cb96ad72c9..7f9c4a0e4ffc 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-synchronous.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-synchronous.adoc @@ -3,8 +3,11 @@ `WebClient` can be used in synchronous style by blocking at the end for the result: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Person person = client.get().uri("/person/{id}", i).retrieve() .bodyToMono(Person.class) @@ -15,8 +18,10 @@ .collectList() .block(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val person = runBlocking { client.get().uri("/person/{id}", i).retrieve() @@ -29,12 +34,16 @@ .toList() } ---- +====== However if multiple calls need to be made, it's more efficient to avoid blocking on each response individually, and instead wait for the combined result: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono personMono = client.get().uri("/person/{id}", personId) .retrieve().bodyToMono(Person.class); @@ -50,8 +59,10 @@ response individually, and instead wait for the combined result: }) .block(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val data = runBlocking { val personDeferred = async { @@ -67,6 +78,7 @@ response individually, and instead wait for the combined result: mapOf("person" to personDeferred.await(), "hobbies" to hobbiesDeferred.await()) } ---- +====== The above is merely one example. There are lots of other patterns and operators for putting together a reactive pipeline that makes many remote calls, potentially some nested, diff --git a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc index 01f1134dd852..a2f3060cd1e7 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc @@ -23,8 +23,11 @@ server-side applications that handle WebSocket messages. To create a WebSocket server, you can first create a `WebSocketHandler`. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import org.springframework.web.reactive.socket.WebSocketHandler; import org.springframework.web.reactive.socket.WebSocketSession; @@ -37,8 +40,10 @@ The following example shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.web.reactive.socket.WebSocketHandler import org.springframework.web.reactive.socket.WebSocketSession @@ -50,11 +55,15 @@ The following example shows how to do so: } } ---- +====== Then you can map it to a URL: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration class WebConfig { @@ -69,8 +78,10 @@ Then you can map it to a URL: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class WebConfig { @@ -84,13 +95,17 @@ Then you can map it to a URL: } } ---- +====== If using the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] there is nothing further to do, or otherwise if not using the WebFlux config you'll need to declare a `WebSocketHandlerAdapter` as shown below: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration class WebConfig { @@ -103,8 +118,10 @@ further to do, or otherwise if not using the WebFlux config you'll need to decla } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class WebConfig { @@ -115,6 +132,7 @@ further to do, or otherwise if not using the WebFlux config you'll need to decla fun handlerAdapter() = WebSocketHandlerAdapter() } ---- +====== @@ -155,8 +173,11 @@ receives a cancellation signal. The most basic implementation of a handler is one that handles the inbound stream. The following example shows such an implementation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class ExampleHandler implements WebSocketHandler { @@ -173,6 +194,7 @@ following example shows such an implementation: } } ---- +====== <1> Access the stream of inbound messages. <2> Do something with each message. <3> Perform nested asynchronous operations that use the message content. @@ -208,8 +230,11 @@ xref:core/databuffer-codec.adoc[Data Buffers and Codecs]. The following implementation combines the inbound and outbound streams: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class ExampleHandler implements WebSocketHandler { @@ -229,6 +254,7 @@ The following implementation combines the inbound and outbound streams: } } ---- +====== <1> Handle the inbound message stream. <2> Create the outbound message, producing a combined flow. <3> Return a `Mono` that does not complete while we continue to receive. @@ -261,8 +287,11 @@ The following implementation combines the inbound and outbound streams: Inbound and outbound streams can be independent and be joined only for completion, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class ExampleHandler implements WebSocketHandler { @@ -285,6 +314,7 @@ as the following example shows: } } ---- +====== <1> Handle inbound message stream. <2> Send outgoing messages. <3> Join the streams and return a `Mono` that completes when either stream ends. @@ -359,8 +389,11 @@ such properties as shown in the corresponding section of the xref:web/webflux/config.adoc#webflux-config-websocket-service[WebFlux Config], or otherwise if not using the WebFlux config, use the below: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration class WebConfig { @@ -378,8 +411,10 @@ not using the WebFlux config, use the below: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class WebConfig { @@ -397,6 +432,7 @@ not using the WebFlux config, use the below: } } ---- +====== Check the upgrade strategy for your server to see what options are available. Currently, only Tomcat and Jetty expose such options. @@ -429,8 +465,11 @@ API to suspend receiving messages for back pressure. To start a WebSocket session, you can create an instance of the client and use its `execute` methods: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebSocketClient client = new ReactorNettyWebSocketClient(); @@ -440,8 +479,10 @@ methods: .doOnNext(System.out::println) .then()); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val client = ReactorNettyWebSocketClient() @@ -452,6 +493,7 @@ methods: .then() } ---- +====== Some clients, such as Jetty, implement `Lifecycle` and need to be stopped and started before you can use them. All clients have constructor options related to configuration diff --git a/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc index 0c5c120714b1..8ebcf5cf59d8 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc @@ -30,8 +30,11 @@ While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all directives for the `Cache-Control` response header, the `CacheControl` type takes a use case-oriented approach that focuses on the common scenarios, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Cache for an hour - "Cache-Control: max-age=3600" CacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS); @@ -45,8 +48,9 @@ use case-oriented approach that focuses on the common scenarios, as the followin CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic(); ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Cache for an hour - "Cache-Control: max-age=3600" val ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS) @@ -60,6 +64,7 @@ use case-oriented approach that focuses on the common scenarios, as the followin val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic() ---- +====== @@ -73,8 +78,11 @@ against conditional request headers. A controller can add an `ETag` and `Cache-C settings to a `ResponseEntity`, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/book/{id}") public ResponseEntity showBook(@PathVariable Long id) { @@ -90,8 +98,9 @@ settings to a `ResponseEntity`, as the following example shows: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/book/{id}") fun showBook(@PathVariable id: Long): ResponseEntity { @@ -106,6 +115,7 @@ settings to a `ResponseEntity`, as the following example shows: .body(book) } ---- +====== -- The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison @@ -116,8 +126,11 @@ You can also make the check against conditional request headers in the controlle as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RequestMapping public String myHandleMethod(ServerWebExchange exchange, Model model) { @@ -132,6 +145,7 @@ as the following example shows: return "myViewName"; } ---- +====== <1> Application-specific calculation. <2> Response has been set to 304 (NOT_MODIFIED). No further processing. <3> Continue with request processing. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc index 4ee87320682f..10e87907b6dc 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc @@ -22,8 +22,11 @@ xref:web/webflux/config.adoc#webflux-config-advanced-java[Advanced Configuration You can use the `@EnableWebFlux` annotation in your Java config, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -31,13 +34,15 @@ You can use the `@EnableWebFlux` annotation in your Java config, as the followin } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux class WebConfig ---- +====== The preceding example registers a number of Spring WebFlux xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[infrastructure beans] and adapts to dependencies @@ -52,8 +57,11 @@ available on the classpath -- for JSON, XML, and others. In your Java configuration, you can implement the `WebFluxConfigurer` interface, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -63,8 +71,9 @@ as the following example shows: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -73,6 +82,7 @@ class WebConfig : WebFluxConfigurer { // Implement configuration methods... } ---- +====== @@ -85,8 +95,11 @@ for customization via `@NumberFormat` and `@DateTimeFormat` on fields. To register custom formatters and converters in Java config, use the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -99,8 +112,10 @@ To register custom formatters and converters in Java config, use the following: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -111,14 +126,18 @@ To register custom formatters and converters in Java config, use the following: } } ---- +====== By default Spring WebFlux considers the request Locale when parsing and formatting date values. This works for forms where dates are represented as Strings with "input" form fields. For "date" and "time" form fields, however, browsers use a fixed format defined in the HTML spec. For such cases date and time formatting can be customized as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -132,8 +151,10 @@ in the HTML spec. For such cases date and time formatting can be customized as f } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -146,6 +167,7 @@ in the HTML spec. For such cases date and time formatting can be customized as f } } ---- +====== NOTE: See xref:core/validation/format.adoc#format-FormatterRegistrar-SPI[`FormatterRegistrar` SPI] and the `FormattingConversionServiceFactoryBean` for more information on when to @@ -165,8 +187,11 @@ is registered as a global xref:core/validation/validator.adoc[validator] for use In your Java configuration, you can customize the global `Validator` instance, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -179,8 +204,10 @@ as the following example shows: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -192,12 +219,16 @@ as the following example shows: } ---- +====== Note that you can also register `Validator` implementations locally, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class MyController { @@ -209,8 +240,10 @@ as the following example shows: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller class MyController { @@ -221,6 +254,7 @@ as the following example shows: } } ---- +====== TIP: If you need to have a `LocalValidatorFactoryBean` injected somewhere, create a bean and @@ -238,8 +272,11 @@ but you can also enable a query parameter-based strategy. The following example shows how to customize the requested content type resolution: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -251,8 +288,10 @@ The following example shows how to customize the requested content type resoluti } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -263,6 +302,7 @@ The following example shows how to customize the requested content type resoluti } } ---- +====== @@ -272,8 +312,11 @@ The following example shows how to customize the requested content type resoluti The following example shows how to customize how the request and response body are read and written: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -285,8 +328,10 @@ The following example shows how to customize how the request and response body a } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -297,6 +342,7 @@ The following example shows how to customize how the request and response body a } } ---- +====== `ServerCodecConfigurer` provides a set of default readers and writers. You can use it to add more readers and writers, customize the default ones, or replace the default ones completely. @@ -323,8 +369,11 @@ It also automatically registers the following well-known modules if they are det The following example shows how to configure view resolution: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -336,8 +385,10 @@ The following example shows how to configure view resolution: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -348,13 +399,17 @@ The following example shows how to configure view resolution: } } ---- +====== The `ViewResolverRegistry` has shortcuts for view technologies with which the Spring Framework integrates. The following example uses FreeMarker (which also requires configuring the underlying FreeMarker view technology): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -376,8 +431,10 @@ underlying FreeMarker view technology): } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -395,11 +452,15 @@ underlying FreeMarker view technology): } } ---- +====== You can also plug in any `ViewResolver` implementation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -413,8 +474,10 @@ You can also plug in any `ViewResolver` implementation, as the following example } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -426,14 +489,18 @@ You can also plug in any `ViewResolver` implementation, as the following example } } ---- +====== To support xref:web/webflux/dispatcher-handler.adoc#webflux-multiple-representations[Content Negotiation] and rendering other formats through view resolution (besides HTML), you can configure one or more default views based on the `HttpMessageWriterView` implementation, which accepts any of the available xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] from `spring-web`. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -451,8 +518,10 @@ xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] from `spring-web`. // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -469,6 +538,7 @@ xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] from `spring-web`. // ... } ---- +====== See xref:web/webflux-view.adoc[View Technologies] for more on the view technologies that are integrated with Spring WebFlux. @@ -488,8 +558,11 @@ and a reduction in HTTP requests made by the browser. The `Last-Modified` header evaluated and, if present, a `304` status code is returned. The following listing shows the example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -504,8 +577,10 @@ the example: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -518,6 +593,7 @@ the example: } } ---- +====== See also xref:web/webflux/caching.adoc#webflux-caching-static-resources[HTTP caching support for static resources]. @@ -533,8 +609,11 @@ JavaScript resources used with a module loader). The following example shows how to use `VersionResourceResolver` in your Java configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -550,8 +629,10 @@ The following example shows how to use `VersionResourceResolver` in your Java co } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -566,6 +647,7 @@ The following example shows how to use `VersionResourceResolver` in your Java co } ---- +====== You can use `ResourceUrlProvider` to rewrite URLs and apply the full chain of resolvers and transformers (for example, to insert versions). The WebFlux configuration provides a `ResourceUrlProvider` @@ -606,8 +688,11 @@ You can customize options related to path matching. For details on the individua {api-spring-framework}/web/reactive/config/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc. The following example shows how to use `PathMatchConfigurer`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -621,8 +706,10 @@ The following example shows how to use `PathMatchConfigurer`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -636,6 +723,7 @@ The following example shows how to use `PathMatchConfigurer`: } } ---- +====== [TIP] ==== @@ -664,8 +752,11 @@ In some cases it may be necessary to create the `WebSocketHandlerAdapter` bean w provided `WebSocketService` service which allows configuring WebSocket server properties. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -679,8 +770,10 @@ For example: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -695,6 +788,7 @@ For example: } } ---- +====== @@ -713,8 +807,11 @@ For advanced mode, you can remove `@EnableWebFlux` and extend directly from `DelegatingWebFluxConfiguration` instead of implementing `WebFluxConfigurer`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class WebConfig extends DelegatingWebFluxConfiguration { @@ -722,8 +819,10 @@ as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class WebConfig : DelegatingWebFluxConfiguration { @@ -731,6 +830,7 @@ as the following example shows: // ... } ---- +====== You can keep existing methods in `WebConfig`, but you can now also override bean declarations from the base class and still have any number of other `WebMvcConfigurer` implementations on diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc index 32d1a1fb60f6..5db87830f5a5 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc @@ -10,8 +10,11 @@ do not have to extend base classes nor implement specific interfaces. The following listing shows a basic example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RestController public class HelloController { @@ -22,8 +25,10 @@ The following listing shows a basic example: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RestController class HelloController { @@ -32,6 +37,7 @@ The following listing shows a basic example: fun handle() = "Hello WebFlux" } ---- +====== In the preceding example, the method returns a `String` to be written to the response body. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc index 1ad6529c0683..362425369283 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc @@ -25,8 +25,11 @@ By default, `@ControllerAdvice` methods apply to every request (that is, all con but you can narrow that down to a subset of controllers by using attributes on the annotation, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Target all Controllers annotated with @RestController @ControllerAdvice(annotations = RestController.class) @@ -41,8 +44,9 @@ annotation, as the following example shows: public class ExampleAdvice3 {} ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Target all Controllers annotated with @RestController @ControllerAdvice(annotations = [RestController::class]) @@ -56,6 +60,7 @@ annotation, as the following example shows: @ControllerAdvice(assignableTypes = [ControllerInterface::class, AbstractController::class]) public class ExampleAdvice3 {} ---- +====== The selectors in the preceding example are evaluated at runtime and may negatively impact performance if used extensively. See the diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc index ab7c3ea2e364..078942e9c9ca 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc @@ -7,8 +7,11 @@ `@ExceptionHandler` methods to handle exceptions from controller methods. The following example includes such a handler method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class SimpleController { @@ -21,6 +24,7 @@ example includes such a handler method: } } ---- +====== <1> Declaring an `@ExceptionHandler`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc index 2c523e925fd8..c0a369778adc 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc @@ -22,8 +22,11 @@ with a `WebDataBinder` argument, for registrations, and a `void` return value. The following example uses the `@InitBinder` annotation: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class FormController { @@ -38,6 +41,7 @@ The following example uses the `@InitBinder` annotation: // ... } ---- +====== <1> Using the `@InitBinder` annotation. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -64,8 +68,11 @@ Alternatively, when using a `Formatter`-based setup through a shared controller-specific `Formatter` instances, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class FormController { @@ -78,6 +85,7 @@ controller-specific `Formatter` instances, as the following example shows: // ... } ---- +====== <1> Adding a custom formatter (a `DateFormatter`, in this case). [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc index a90cf11ad71a..639273e645ab 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc @@ -15,14 +15,18 @@ JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84 The following code sample demonstrates how to get the cookie value: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/demo") public void handle(@CookieValue("JSESSIONID") String cookie) { // <1> //... } ---- +====== <1> Get the cookie value. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc index 1b326645c8b0..1c9d77d8494e 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc @@ -7,21 +7,27 @@ container object that exposes request headers and the body. The following example uses an `HttpEntity`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/accounts") public void handle(HttpEntity entity) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/accounts") fun handle(entity: HttpEntity) { // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc index ee443c1d7b0e..fe3db7c7d560 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc @@ -13,8 +13,11 @@ which allows rendering only a subset of all fields in an `Object`. To use it wit `@ResponseBody` or `ResponseEntity` controller methods, you can use Jackson's `@JsonView` annotation to activate a serialization view class, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RestController public class UserController { @@ -54,8 +57,9 @@ which allows rendering only a subset of all fields in an `Object`. To use it wit } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RestController class UserController { @@ -75,6 +79,7 @@ which allows rendering only a subset of all fields in an `Object`. To use it wit interface WithPasswordView : WithoutPasswordView } ---- +====== NOTE: `@JsonView` allows an array of view classes but you can only specify only one per controller method. Use a composite interface if you need to activate multiple views. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc index f37d3830f560..b5a5bd9753c5 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc @@ -19,8 +19,11 @@ to mask variable content. That said, if you want to access matrix variables from controller method, you need to add a URI variable to the path segment where matrix variables are expected. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // GET /pets/42;q=11;r=22 @@ -31,8 +34,10 @@ variables are expected. The following example shows how to do so: // q == 11 } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // GET /pets/42;q=11;r=22 @@ -43,14 +48,18 @@ variables are expected. The following example shows how to do so: // q == 11 } ---- +====== Given that all path segments can contain matrix variables, you may sometimes need to disambiguate which path variable the matrix variable is expected to be in, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // GET /owners/42;q=11/pets/21;q=22 @@ -63,8 +72,10 @@ as the following example shows: // q2 == 22 } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/owners/{ownerId}/pets/{petId}") fun findPet( @@ -75,12 +86,16 @@ as the following example shows: // q2 == 22 } ---- +====== You can define a matrix variable may be defined as optional and specify a default value as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // GET /pets/42 @@ -90,8 +105,10 @@ as the following example shows: // q == 1 } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // GET /pets/42 @@ -101,11 +118,15 @@ as the following example shows: // q == 1 } ---- +====== To get all matrix variables, use a `MultiValueMap`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 @@ -118,8 +139,10 @@ To get all matrix variables, use a `MultiValueMap`, as the following example sho // petMatrixVars: ["q" : 22, "s" : 23] } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 @@ -132,5 +155,6 @@ To get all matrix variables, use a `MultiValueMap`, as the following example sho // petMatrixVars: ["q" : 22, "s" : 23] } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc index f2d234a0b1dc..cf92220ce282 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc @@ -9,12 +9,16 @@ the values of query parameters and form fields whose names match to field names. referred to as data binding, and it saves you from having to deal with parsing and converting individual query parameters and form fields. The following example binds an instance of `Pet`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/owners/{ownerId}/pets/{petId}/edit") public String processSubmit(@ModelAttribute Pet pet) { } // <1> ---- +====== <1> Bind an instance of `Pet`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -45,8 +49,11 @@ Data binding can result in errors. By default, a `WebExchangeBindException` is r to check for such errors in the controller method, you can add a `BindingResult` argument immediately next to the `@ModelAttribute`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/owners/{ownerId}/pets/{petId}/edit") public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { <1> @@ -56,6 +63,7 @@ immediately next to the `@ModelAttribute`, as the following example shows: // ... } ---- +====== <1> Adding a `BindingResult`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -76,8 +84,11 @@ You can automatically apply validation after data binding by adding the xref:core/validation/beanvalidation.adoc[Bean Validation] and xref:web/webmvc/mvc-config/validation.adoc[Spring validation]). The following example uses the `@Valid` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/owners/{ownerId}/pets/{petId}/edit") public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { // <1> @@ -87,6 +98,7 @@ xref:web/webmvc/mvc-config/validation.adoc[Spring validation]). The following ex // ... } ---- +====== <1> Using `@Valid` on a model attribute argument. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -110,8 +122,11 @@ argument, you must declare the `@ModelAttribute` argument before it without a re type wrapper, as shown earlier. Alternatively, you can handle any errors through the reactive type, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/owners/{ownerId}/pets/{petId}/edit") public Mono processSubmit(@Valid @ModelAttribute("pet") Mono petMono) { @@ -124,8 +139,10 @@ reactive type, as the following example shows: }); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/owners/{ownerId}/pets/{petId}/edit") fun processSubmit(@Valid @ModelAttribute("pet") petMono: Mono): Mono { @@ -138,6 +155,7 @@ reactive type, as the following example shows: } } ---- +====== Note that use of `@ModelAttribute` is optional -- for example, to set its attributes. By default, any argument that is not a simple value type (as determined by diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc index 489c6ec2d8f7..18eb97cf45d8 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc @@ -9,8 +9,11 @@ is through data binding to a xref:web/webflux/controller/ann-methods/modelattrib as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class MyForm { @@ -32,8 +35,10 @@ as the following example shows: } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyForm( val name: String, @@ -49,6 +54,7 @@ as the following example shows: } ---- +====== -- You can also submit multipart requests from non-browser clients in a RESTful service @@ -77,8 +83,11 @@ Content-Transfer-Encoding: 8bit You can access individual parts with `@RequestPart`, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/") public String handle(@RequestPart("meta-data") Part metadata, // <1> @@ -86,6 +95,7 @@ You can access individual parts with `@RequestPart`, as the following example sh // ... } ---- +====== <1> Using `@RequestPart` to get the metadata. <2> Using `@RequestPart` to get the file. @@ -107,14 +117,18 @@ To deserialize the raw part content (for example, to JSON -- similar to `@Reques you can declare a concrete target `Object`, instead of `Part`, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/") public String handle(@RequestPart("meta-data") MetaData metadata) { // <1> // ... } ---- +====== <1> Using `@RequestPart` to get the metadata. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -136,8 +150,11 @@ in the controller method by declaring the argument with an async wrapper and the error related operators: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/") public String handle(@Valid @RequestPart("meta-data") Mono metadata) { @@ -145,28 +162,34 @@ error related operators: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/") fun handle(@Valid @RequestPart("meta-data") metadata: MetaData): String { // ... } ---- +====== -- To access all multipart data as a `MultiValueMap`, you can use `@RequestBody`, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/") public String handle(@RequestBody Mono> parts) { // <1> // ... } ---- +====== <1> Using `@RequestBody`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -196,8 +219,11 @@ when uploading. If the file is large enough to be split across multiple buffers, For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/") public void handle(@RequestBody Flux allPartsEvents) { <1> @@ -224,6 +250,7 @@ For example: })); } ---- +====== <1> Using `@RequestBody`. <2> The final `PartEvent` for a particular part will have `isLast()` set to `true`, and can be followed by additional events belonging to subsequent parts. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc index b91d1d18bcc3..7eec57f6970b 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc @@ -7,14 +7,18 @@ Similarly to `@SessionAttribute`, you can use the `@RequestAttribute` annotation access pre-existing request attributes created earlier (for example, by a `WebFilter`), as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/") public String handle(@RequestAttribute Client client) { <1> // ... } ---- +====== <1> Using `@RequestAttribute`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc index 40e79bf6ba22..8190c2811251 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc @@ -7,8 +7,11 @@ You can use the `@RequestBody` annotation to have the request body read and dese `Object` through an xref:web/webflux/reactive-spring.adoc#webflux-codecs[HttpMessageReader]. The following example uses a `@RequestBody` argument: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/accounts") public void handle(@RequestBody Account account) { @@ -16,34 +19,42 @@ The following example uses a `@RequestBody` argument: } ---- +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/accounts") fun handle(@RequestBody account: Account) { // ... } ---- +====== Unlike Spring MVC, in WebFlux, the `@RequestBody` method argument supports reactive types and fully non-blocking reading and (client-to-server) streaming. +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/accounts") public void handle(@RequestBody Mono account) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/accounts") fun handle(@RequestBody accounts: Flow) { // ... } ---- +====== You can use the xref:web/webflux/config.adoc#webflux-config-message-codecs[HTTP message codecs] option of the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] to configure or customize message readers. @@ -55,21 +66,27 @@ The exception contains a `BindingResult` with error details and can be handled i controller method by declaring the argument with an async wrapper and then using error related operators: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/accounts") public void handle(@Valid @RequestBody Mono account) { // use one of the onError* operators... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/accounts") fun handle(@Valid @RequestBody account: Mono) { // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc index cf08bc245316..e625a46c0f7c 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc @@ -21,8 +21,11 @@ Keep-Alive 300 The following example gets the value of the `Accept-Encoding` and `Keep-Alive` headers: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/demo") public void handle( @@ -31,6 +34,7 @@ The following example gets the value of the `Accept-Encoding` and `Keep-Alive` h //... } ---- +====== <1> Get the value of the `Accept-Encoding` header. <2> Get the value of the `Keep-Alive` header. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc index 64bad1fd03a7..b1da2d825ed3 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc @@ -6,8 +6,11 @@ You can use the `@RequestParam` annotation to bind query parameters to a method argument in a controller. The following code snippet shows the usage: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller @RequestMapping("/pets") @@ -25,6 +28,7 @@ controller. The following code snippet shows the usage: // ... } ---- +====== <1> Using `@RequestParam`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc index ce69b696b018..d6befe47fdc7 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc @@ -7,8 +7,11 @@ You can use the `@ResponseBody` annotation on a method to have the return serial to the response body through an xref:web/webflux/reactive-spring.adoc#webflux-codecs[HttpMessageWriter]. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/accounts/{id}") @ResponseBody @@ -16,8 +19,10 @@ example shows how to do so: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/accounts/{id}") @ResponseBody @@ -25,6 +30,7 @@ example shows how to do so: // ... } ---- +====== `@ResponseBody` is also supported at the class level, in which case it is inherited by all controller methods. This is the effect of `@RestController`, which is nothing more diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc index 06c68e11125d..00de86dad575 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc @@ -5,8 +5,11 @@ `ResponseEntity` is like xref:web/webflux/controller/ann-methods/responsebody.adoc[`@ResponseBody`] but with status and headers. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/something") public ResponseEntity handle() { @@ -15,8 +18,10 @@ return ResponseEntity.ok().eTag(etag).body(body); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/something") fun handle(): ResponseEntity { @@ -25,6 +30,7 @@ return ResponseEntity.ok().eTag(etag).build(body) } ---- +====== WebFlux supports using a single value xref:web-reactive.adoc#webflux-reactive-libraries[reactive type] to produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive types diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc index a205bd26c44b..f34751f91b4d 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc @@ -7,14 +7,18 @@ If you need access to pre-existing session attributes that are managed globally (that is, outside the controller -- for example, by a filter) and may or may not be present, you can use the `@SessionAttribute` annotation on a method parameter, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/") public String handle(@SessionAttribute User user) { // <1> // ... } ---- +====== <1> Using `@SessionAttribute`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc index 72fd242c82d3..05426026206e 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc @@ -11,8 +11,11 @@ requests to access. Consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller @SessionAttributes("pet") <1> @@ -20,6 +23,7 @@ Consider the following example: // ... } ---- +====== <1> Using the `@SessionAttributes` annotation. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -38,8 +42,11 @@ it is automatically promoted to and saved in the `WebSession`. It remains there another controller method uses a `SessionStatus` method argument to clear the storage, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller @SessionAttributes("pet") // <1> @@ -58,6 +65,7 @@ as the following example shows: } } ---- +====== <1> Using the `@SessionAttributes` annotation. <2> Using a `SessionStatus` variable. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc index 654d0fc9a940..bf8d7afa04e9 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc @@ -24,8 +24,11 @@ related to the request body). The following example uses a `@ModelAttribute` method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ModelAttribute public void populateModel(@RequestParam String number, Model model) { @@ -33,8 +36,10 @@ The following example uses a `@ModelAttribute` method: // add more ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ModelAttribute fun populateModel(@RequestParam number: String, model: Model) { @@ -42,25 +47,32 @@ The following example uses a `@ModelAttribute` method: // add more ... } ---- +====== The following example adds one attribute only: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ModelAttribute public Account addAccount(@RequestParam String number) { return accountRepository.findAccount(number); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ModelAttribute fun addAccount(@RequestParam number: String): Account { return accountRepository.findAccount(number); } ---- +====== NOTE: When a name is not explicitly specified, a default name is chosen based on the type, as explained in the javadoc for {api-spring-framework}/core/Conventions.html[`Conventions`]. @@ -73,8 +85,11 @@ attributes can be transparently resolved (and the model updated) to their actual at the time of `@RequestMapping` invocation, provided a `@ModelAttribute` argument is declared without a wrapper, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ModelAttribute public void addAccount(@RequestParam String number) { @@ -87,8 +102,10 @@ declared without a wrapper, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.ui.set @@ -103,6 +120,7 @@ declared without a wrapper, as the following example shows: // ... } ---- +====== In addition, any model attributes that have a reactive type wrapper are resolved to their @@ -115,8 +133,11 @@ controllers, unless the return value is a `String` that would otherwise be inter as a view name. `@ModelAttribute` can also help to customize the model attribute name, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/accounts/{id}") @ModelAttribute("myAccount") @@ -125,8 +146,10 @@ as the following example shows: return account; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/accounts/{id}") @ModelAttribute("myAccount") @@ -135,6 +158,7 @@ as the following example shows: return account } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc index 053b79565919..80db7ea50479 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc @@ -23,8 +23,11 @@ using `@RequestMapping`, which, by default, matches to all HTTP methods. At the The following example uses type and method level mappings: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RestController @RequestMapping("/persons") @@ -42,8 +45,10 @@ The following example uses type and method level mappings: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RestController @RequestMapping("/persons") @@ -61,6 +66,7 @@ The following example uses type and method level mappings: } } ---- +====== [[webflux-ann-requestmapping-uri-templates]] @@ -106,29 +112,38 @@ You can map requests by using glob patterns and wildcards: Captured URI variables can be accessed with `@PathVariable`, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/owners/{ownerId}/pets/{petId}") public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/owners/{ownerId}/pets/{petId}") fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { // ... } ---- +====== -- You can declare URI variables at the class and method levels, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller @RequestMapping("/owners/{ownerId}") // <1> @@ -140,6 +155,7 @@ You can declare URI variables at the class and method levels, as the following e } } ---- +====== <1> Class-level URI mapping. <2> Method-level URI mapping. @@ -179,22 +195,28 @@ syntax: `{varName:regex}`. For example, given a URL of `/spring-web-3.0.5.jar`, extracts the name, version, and file extension: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") public void handle(@PathVariable String version, @PathVariable String ext) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") fun handle(@PathVariable version: String, @PathVariable ext: String) { // ... } ---- +====== -- URI path patterns can also have embedded `${...}` placeholders that are resolved on startup @@ -234,22 +256,28 @@ sorted last instead. If two patterns are both catch-all, the longer is chosen. You can narrow the request mapping based on the `Content-Type` of the request, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping(path = "/pets", consumes = "application/json") public void addPet(@RequestBody Pet pet) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/pets", consumes = ["application/json"]) fun addPet(@RequestBody pet: Pet) { // ... } ---- +====== The consumes attribute also supports negation expressions -- for example, `!text/plain` means any content type other than `text/plain`. @@ -269,8 +297,11 @@ TIP: `MediaType` provides constants for commonly used media types -- for example You can narrow the request mapping based on the `Accept` request header and the list of content types that a controller method produces, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping(path = "/pets/{petId}", produces = "application/json") @ResponseBody @@ -278,8 +309,10 @@ content types that a controller method produces, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/pets/{petId}", produces = ["application/json"]) @ResponseBody @@ -287,6 +320,7 @@ content types that a controller method produces, as the following example shows: // ... } ---- +====== The media type can specify a character set. Negated expressions are supported -- for example, `!text/plain` means any content type other than `text/plain`. @@ -307,14 +341,18 @@ You can narrow request mappings based on query parameter conditions. You can tes presence of a query parameter (`myParam`), for its absence (`!myParam`), or for a specific value (`myParam=myValue`). The following examples tests for a parameter with a value: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping(path = "/pets/{petId}", params = "myParam=myValue") // <1> public void findPet(@PathVariable String petId) { // ... } ---- +====== <1> Check that `myParam` equals `myValue`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -329,14 +367,18 @@ specific value (`myParam=myValue`). The following examples tests for a parameter You can also use the same with request header conditions, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") // <1> public void findPet(@PathVariable String petId) { // ... } ---- +====== <1> Check that `myHeader` equals `myValue`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -401,8 +443,11 @@ You can programmatically register Handler methods, which can be used for dynamic registrations or for advanced cases, such as different instances of the same handler under different URLs. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class MyConfig { @@ -421,6 +466,7 @@ under different URLs. The following example shows how to do so: } ---- +====== <1> Inject target handlers and the handler mapping for controllers. <2> Prepare the request mapping metadata. <3> Get the handler method. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc index c44f42c332dd..8ace15c65775 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc @@ -12,8 +12,11 @@ a web component. To enable auto-detection of such `@Controller` beans, you can add component scanning to your Java configuration, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ComponentScan("org.example.web") // <1> @@ -22,6 +25,7 @@ your Java configuration, as the following example shows: // ... } ---- +====== <1> Scan the `org.example.web` package. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc b/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc index 46250c6f6895..b0919fd8fdab 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc @@ -25,18 +25,24 @@ Spring configuration in a WebFlux application typically contains: The configuration is given to `WebHttpHandlerBuilder` to build the processing chain, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- ApplicationContext context = ... HttpHandler handler = WebHttpHandlerBuilder.applicationContext(context).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val context: ApplicationContext = ... val handler = WebHttpHandlerBuilder.applicationContext(context).build() ---- +====== The resulting `HttpHandler` is ready for use with a xref:web/webflux/reactive-spring.adoc#webflux-httphandler[server adapter]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc index 052378f29a99..495dc89ab868 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc @@ -84,42 +84,57 @@ https://github.com/spring-projects/spring-framework/wiki/What%27s-New-in-the-Spr The code snippets below show using the `HttpHandler` adapters with each server API: *Reactor Netty* +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpHandler handler = ... ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(handler); HttpServer.create().host(host).port(port).handle(adapter).bindNow(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val handler: HttpHandler = ... val adapter = ReactorHttpHandlerAdapter(handler) HttpServer.create().host(host).port(port).handle(adapter).bindNow() ---- +====== *Undertow* +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpHandler handler = ... UndertowHttpHandlerAdapter adapter = new UndertowHttpHandlerAdapter(handler); Undertow server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build(); server.start(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val handler: HttpHandler = ... val adapter = UndertowHttpHandlerAdapter(handler) val server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build() server.start() ---- +====== *Tomcat* +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpHandler handler = ... Servlet servlet = new TomcatHttpHandlerAdapter(handler); @@ -133,8 +148,10 @@ The code snippets below show using the `HttpHandler` adapters with each server A server.setPort(port); server.start(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val handler: HttpHandler = ... val servlet = TomcatHttpHandlerAdapter(handler) @@ -148,11 +165,15 @@ The code snippets below show using the `HttpHandler` adapters with each server A server.setPort(port) server.start() ---- +====== *Jetty* +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpHandler handler = ... Servlet servlet = new JettyHttpHandlerAdapter(handler); @@ -168,8 +189,10 @@ The code snippets below show using the `HttpHandler` adapters with each server A server.addConnector(connector); server.start(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val handler: HttpHandler = ... val servlet = JettyHttpHandlerAdapter(handler) @@ -185,6 +208,7 @@ The code snippets below show using the `HttpHandler` adapters with each server A server.addConnector(connector) server.start() ---- +====== *Servlet Container* @@ -277,16 +301,22 @@ Spring ApplicationContext, or that can be registered directly with it: `ServerWebExchange` exposes the following method for accessing form data: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono> getFormData(); ---- + +Kotlin:: ++ [source,Kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- suspend fun getFormData(): MultiValueMap ---- +====== The `DefaultServerWebExchange` uses the configured `HttpMessageReader` to parse form data (`application/x-www-form-urlencoded`) into a `MultiValueMap`. By default, @@ -300,16 +330,22 @@ The `DefaultServerWebExchange` uses the configured `HttpMessageReader` to parse `ServerWebExchange` exposes the following method for accessing multipart data: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Mono> getMultipartData(); ---- + +Kotlin:: ++ [source,Kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- suspend fun getMultipartData(): MultiValueMap ---- +====== The `DefaultServerWebExchange` uses the configured `HttpMessageReader>` to parse `multipart/form-data`, @@ -621,8 +657,11 @@ headers are masked by default and you must explicitly enable their logging in fu The following example shows how to do so for server-side requests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebFlux @@ -634,8 +673,10 @@ The following example shows how to do so for server-side requests: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebFlux @@ -646,11 +687,15 @@ The following example shows how to do so for server-side requests: } } ---- +====== The following example shows how to do so for client-side requests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- Consumer consumer = configurer -> configurer.defaultCodecs().enableLoggingRequestDetails(true); @@ -659,8 +704,10 @@ The following example shows how to do so for client-side requests: .exchangeStrategies(strategies -> strategies.codecs(consumer)) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val consumer: (ClientCodecConfigurer) -> Unit = { configurer -> configurer.defaultCodecs().enableLoggingRequestDetails(true) } @@ -668,6 +715,7 @@ The following example shows how to do so for client-side requests: .exchangeStrategies({ strategies -> strategies.codecs(consumer) }) .build() ---- +====== [[webflux-logging-appenders]] @@ -693,8 +741,11 @@ or xref:web/webflux/reactive-spring.adoc#webflux-logging-sensitive-data[logging The following example shows how to do so for client-side requests: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- WebClient webClient = WebClient.builder() .codecs(configurer -> { @@ -703,8 +754,10 @@ The following example shows how to do so for client-side requests: }) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val webClient = WebClient.builder() .codecs({ configurer -> @@ -713,4 +766,5 @@ The following example shows how to do so for client-side requests: }) .build() ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc index c41e79bfcb7a..e959c141a1f6 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc @@ -83,8 +83,11 @@ The {api-spring-framework}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`] annotation enables cross-origin requests on annotated controller methods, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RestController @RequestMapping("/account") @@ -102,8 +105,10 @@ as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RestController @RequestMapping("/account") @@ -121,6 +126,7 @@ as the following example shows: } } ---- +====== By default, `@CrossOrigin` allows: @@ -139,8 +145,11 @@ the `allowOriginPatterns` property may be used to match to a dynamic set of orig `@CrossOrigin` is supported at the class level, too, and is inherited by all methods, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @CrossOrigin(origins = "https://domain2.com", maxAge = 3600) @RestController @@ -158,8 +167,10 @@ public class AccountController { } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @CrossOrigin(origins = ["https://domain2.com"], maxAge = 3600) @RestController @@ -176,12 +187,16 @@ public class AccountController { // ... } ---- +====== You can use `@CrossOrigin` at both the class level and the method level, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @CrossOrigin(maxAge = 3600) @RestController @@ -200,8 +215,10 @@ as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @CrossOrigin(maxAge = 3600) @RestController @@ -220,6 +237,7 @@ as the following example shows: } } ---- +====== @@ -257,8 +275,11 @@ the `allowOriginPatterns` property may be used to match to a dynamic set of orig To enable CORS in the MVC Java config, you can use the `CorsRegistry` callback, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -278,8 +299,10 @@ as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -298,6 +321,7 @@ as the following example shows: } } ---- +====== @@ -341,8 +365,11 @@ CORS. To configure the filter, pass a `CorsConfigurationSource` to its constructor, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- CorsConfiguration config = new CorsConfiguration(); @@ -359,8 +386,10 @@ following example shows: CorsFilter filter = new CorsFilter(source); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- val config = CorsConfiguration() @@ -377,3 +406,4 @@ following example shows: val filter = CorsFilter(source) ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc index 988a1d795f7a..6f93344081f1 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc @@ -30,8 +30,11 @@ difference that router functions provide not just data, but also behavior. `RouterFunctions.route()` provides a router builder that facilitates the creation of routers, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.http.MediaType.APPLICATION_JSON; import static org.springframework.web.servlet.function.RequestPredicates.*; @@ -64,6 +67,7 @@ as the following example shows: } } ---- +====== <1> Create router using `route()`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -125,44 +129,62 @@ while access to the body is provided through the `body` methods. The following example extracts the request body to a `String`: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- String string = request.body(String.class); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val string = request.body() ---- +====== The following example extracts the body to a `List`, where `Person` objects are decoded from a serialized form, such as JSON or XML: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- List people = request.body(new ParameterizedTypeReference>() {}); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val people = request.body() ---- +====== The following example shows how to access parameters: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- MultiValueMap params = request.params(); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val map = request.params() ---- +====== [[webmvc-fn-response]] @@ -173,69 +195,94 @@ a `build` method to create it. You can use the builder to set the response statu headers, or to provide a body. The following example creates a 200 (OK) response with JSON content: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- Person person = ... ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val person: Person = ... ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person) ---- +====== The following example shows how to build a 201 (CREATED) response with a `Location` header and no body: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- URI location = ... ServerResponse.created(location).build(); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val location: URI = ... ServerResponse.created(location).build() ---- +====== You can also use an asynchronous result as the body, in the form of a `CompletableFuture`, `Publisher`, or any other type supported by the `ReactiveAdapterRegistry`. For instance: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- Mono person = webClient.get().retrieve().bodyToMono(Person.class); ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person); ---- + +Kotlin:: ++ [source,kotlin,role="secondary"] -.Kotlin ---- val person = webClient.get().retrieve().awaitBody() ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person) ---- +====== If not just the body, but also the status or headers are based on an asynchronous type, you can use the static `async` method on `ServerResponse`, which accepts `CompletableFuture`, `Publisher`, or any other asynchronous type supported by the `ReactiveAdapterRegistry`. For instance: +[tabs] +====== +Java:: ++ [source,java,role="primary"] -.Java ---- Mono asyncResponse = webClient.get().retrieve().bodyToMono(Person.class) .map(p -> ServerResponse.ok().header("Name", p.name()).body(p)); ServerResponse.async(asyncResponse); ---- +====== https://www.w3.org/TR/eventsource/[Server-Sent Events] can be provided via the static `sse` method on `ServerResponse`. The builder provided by that method allows you to send Strings, or other objects as JSON. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public RouterFunction sse() { return route(GET("/sse"), request -> ServerResponse.sse(sseBuilder -> { @@ -258,8 +305,10 @@ allows you to send Strings, or other objects as JSON. For example: // and done at some point sseBuilder.complete(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- fun sse(): RouterFunction = router { GET("/sse") { request -> ServerResponse.sse { sseBuilder -> @@ -282,6 +331,7 @@ allows you to send Strings, or other objects as JSON. For example: // and done at some point sseBuilder.complete() ---- +====== @@ -291,18 +341,24 @@ allows you to send Strings, or other objects as JSON. For example: We can write a handler function as a lambda, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HandlerFunction helloWorld = request -> ServerResponse.ok().body("Hello World"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val helloWorld: (ServerRequest) -> ServerResponse = { ServerResponse.ok().body("Hello World") } ---- +====== -- That is convenient, but in an application we need multiple functions, and multiple inline @@ -312,8 +368,11 @@ has a similar role as `@Controller` in an annotation-based application. For example, the following class exposes a reactive `Person` repository: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.http.MediaType.APPLICATION_JSON; import static org.springframework.web.reactive.function.server.ServerResponse.ok; @@ -350,6 +409,7 @@ public class PersonHandler { } ---- +====== <1> `listPeople` is a handler function that returns all `Person` objects found in the repository as JSON. <2> `createPerson` is a handler function that stores a new `Person` contained in the request body. @@ -397,8 +457,11 @@ A functional endpoint can use Spring's xref:web/webmvc/mvc-config/validation.ado apply validation to the request body. For example, given a custom Spring xref:web/webmvc/mvc-config/validation.adoc[Validator] implementation for a `Person`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class PersonHandler { @@ -422,6 +485,7 @@ xref:web/webmvc/mvc-config/validation.adoc[Validator] implementation for a `Pers } } ---- +====== <1> Create `Validator` instance. <2> Apply validation. <3> Raise exception for a 400 response. @@ -492,15 +556,20 @@ and so on. The following example uses a request predicate to create a constraint based on the `Accept` header: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RouterFunction route = RouterFunctions.route() .GET("/hello-world", accept(MediaType.TEXT_PLAIN), request -> ServerResponse.ok().body("Hello World")).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.web.servlet.function.router @@ -510,6 +579,7 @@ header: } } ---- +====== You can compose multiple request predicates together by using: @@ -547,8 +617,11 @@ There are also other ways to compose multiple router functions together: The following example shows the composition of four routes: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import static org.springframework.http.MediaType.APPLICATION_JSON; import static org.springframework.web.servlet.function.RequestPredicates.*; @@ -565,6 +638,7 @@ The following example shows the composition of four routes: .add(otherRoute) // <4> .build(); ---- +====== <1> pass:q[`GET /person/{id}`] with an `Accept` header that matches JSON is routed to `PersonHandler.getPerson` <2> `GET /person` with an `Accept` header that matches JSON is routed to @@ -611,8 +685,11 @@ When using annotations, you would remove this duplication by using a type-level In WebMvc.fn, path predicates can be shared through the `path` method on the router function builder. For instance, the last few lines of the example above can be improved in the following way by using nested routes: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RouterFunction route = route() .path("/person", builder -> builder // <1> @@ -621,6 +698,7 @@ RouterFunction route = route() .POST(handler::createPerson)) .build(); ---- +====== <1> Note that second parameter of `path` is a consumer that takes the router builder. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -643,8 +721,11 @@ the `nest` method on the builder. The above still contains some duplication in the form of the shared `Accept`-header predicate. We can further improve by using the `nest` method together with `accept`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RouterFunction route = route() .path("/person", b1 -> b1 @@ -654,8 +735,10 @@ We can further improve by using the `nest` method together with `accept`: .POST(handler::createPerson)) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.web.servlet.function.router @@ -669,6 +752,7 @@ We can further improve by using the `nest` method together with `accept`: } } ---- +====== [[webmvc-fn-running]] @@ -693,8 +777,11 @@ starter. The following example shows a WebFlux Java configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableMvc @@ -728,8 +815,10 @@ The following example shows a WebFlux Java configuration: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableMvc @@ -760,6 +849,7 @@ The following example shows a WebFlux Java configuration: } } ---- +====== @@ -775,8 +865,11 @@ The filter will apply to all routes that are built by the builder. This means that filters defined in nested routes do not apply to "top-level" routes. For instance, consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- RouterFunction route = route() .path("/person", b1 -> b1 @@ -790,6 +883,7 @@ For instance, consider the following example: .after((request, response) -> logResponse(response)) // <2> .build(); ---- +====== <1> The `before` filter that adds a custom request header is only applied to the two GET routes. <2> The `after` filter that logs the response is applied to all routes, including the nested ones. @@ -827,8 +921,11 @@ Now we can add a simple security filter to our route, assuming that we have a `S can determine whether a particular path is allowed. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- SecurityManager securityManager = ... @@ -848,8 +945,10 @@ The following example shows how to do so: }) .build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.web.servlet.function.router @@ -871,6 +970,7 @@ The following example shows how to do so: } } ---- +====== The preceding example demonstrates that invoking the `next.handle(ServerRequest)` is optional. We only let the handler function be run when access is allowed. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-document.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-document.adoc index 627885398d3b..64a49310d125 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-document.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-document.adoc @@ -32,8 +32,11 @@ A simple PDF view for a word list could extend `org.springframework.web.servlet.view.document.AbstractPdfView` and implement the `buildPdfDocument()` method, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class PdfWordList extends AbstractPdfView { @@ -47,8 +50,10 @@ A simple PDF view for a word list could extend } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class PdfWordList : AbstractPdfView() { @@ -62,6 +67,7 @@ A simple PDF view for a word list could extend } } ---- +====== A controller can return such a view either from an external view definition (referencing it by name) or as a `View` instance from the handler method. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-feeds.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-feeds.adoc index e9cdbfbe3b67..68714b3dfe5c 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-feeds.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-feeds.adoc @@ -10,8 +10,11 @@ package `org.springframework.web.servlet.view.feed`. optionally override the `buildFeedMetadata()` method (the default implementation is empty). The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SampleContentAtomView extends AbstractAtomFeedView { @@ -28,8 +31,10 @@ empty). The following example shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SampleContentAtomView : AbstractAtomFeedView() { @@ -44,11 +49,15 @@ empty). The following example shows how to do so: } } ---- +====== Similar requirements apply for implementing `AbstractRssFeedView`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class SampleContentRssView extends AbstractRssFeedView { @@ -65,8 +74,10 @@ Similar requirements apply for implementing `AbstractRssFeedView`, as the follow } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class SampleContentRssView : AbstractRssFeedView() { @@ -81,6 +92,7 @@ Similar requirements apply for implementing `AbstractRssFeedView`, as the follow } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc index dbd748170658..e0e95083b980 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc @@ -15,8 +15,11 @@ integration for using Spring MVC with FreeMarker templates. The following example shows how to configure FreeMarker as a view technology: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -37,8 +40,10 @@ The following example shows how to configure FreeMarker as a view technology: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -56,6 +61,7 @@ The following example shows how to configure FreeMarker as a view technology: } } ---- +====== The following example shows how to configure the same in XML: @@ -364,8 +370,11 @@ and a default value in the form backing object, the HTML resembles the following If your application expects to handle cities by internal codes (for example), you can create the map of codes with suitable keys, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- protected Map referenceData(HttpServletRequest request) throws Exception { Map cityMap = new LinkedHashMap<>(); @@ -378,8 +387,10 @@ codes with suitable keys, as the following example shows: return model; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- protected fun referenceData(request: HttpServletRequest): Map { val cityMap = linkedMapOf( @@ -390,6 +401,7 @@ codes with suitable keys, as the following example shows: return hashMapOf("cityMap" to cityMap) } ---- +====== The code now produces output where the radio values are the relevant codes, but the user still sees the more user-friendly city names, as follows: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-groovymarkup.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-groovymarkup.adoc index 60292b26f090..7793e08c1048 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-groovymarkup.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-groovymarkup.adoc @@ -15,8 +15,11 @@ NOTE: The Groovy Markup Template engine requires Groovy 2.3.1+. The following example shows how to configure the Groovy Markup Template Engine: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -37,8 +40,10 @@ The following example shows how to configure the Groovy Markup Template Engine: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -56,6 +61,7 @@ The following example shows how to configure the Groovy Markup Template Engine: } } ---- +====== The following example shows how to configure the same in XML: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc index 5284dc012600..1e37619d3932 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc @@ -185,8 +185,11 @@ This tag renders an HTML `input` tag with the `type` set to `checkbox`. Assume that our `User` has preferences such as newsletter subscription and a list of hobbies. The following example shows the `Preferences` class: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class Preferences { @@ -219,8 +222,10 @@ hobbies. The following example shows the `Preferences` class: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class Preferences( var receiveNewsletter: Boolean, @@ -228,6 +233,7 @@ hobbies. The following example shows the `Preferences` class: var favouriteWord: String ) ---- +====== The corresponding `form.jsp` could then resemble the following: @@ -582,8 +588,11 @@ Assume that we want to display all error messages for the `firstName` and `lastN fields once we submit the form. We have a validator for instances of the `User` class called `UserValidator`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class UserValidator implements Validator { @@ -597,8 +606,10 @@ called `UserValidator`, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class UserValidator : Validator { @@ -612,6 +623,7 @@ called `UserValidator`, as the following example shows: } } ---- +====== The `form.jsp` could be as follows: @@ -785,8 +797,11 @@ web.xml, as the following example shows: The following example shows the corresponding `@Controller` method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RequestMapping(method = RequestMethod.DELETE) public String deletePet(@PathVariable int ownerId, @PathVariable int petId) { @@ -794,8 +809,10 @@ The following example shows the corresponding `@Controller` method: return "redirect:/owners/" + ownerId; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RequestMapping(method = [RequestMethod.DELETE]) fun deletePet(@PathVariable ownerId: Int, @PathVariable petId: Int): String { @@ -803,6 +820,7 @@ The following example shows the corresponding `@Controller` method: return "redirect:/owners/$ownerId" } ---- +====== [[mvc-view-jsp-formtaglib-html5]] === HTML5 Tags diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc index 8cb6e1b12490..27fac970a199 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc @@ -53,8 +53,11 @@ You can declare a `ScriptTemplateConfigurer` bean to specify the script engine t the script files to load, what function to call to render templates, and so on. The following example uses Mustache templates and the Nashorn JavaScript engine: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -76,8 +79,10 @@ The following example uses Mustache templates and the Nashorn JavaScript engine: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -96,6 +101,7 @@ The following example uses Mustache templates and the Nashorn JavaScript engine: } } ---- +====== The following example shows the same arrangement in XML: @@ -114,8 +120,11 @@ The following example shows the same arrangement in XML: The controller would look no different for the Java and XML configurations, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class SampleController { @@ -128,8 +137,10 @@ The controller would look no different for the Java and XML configurations, as t } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller class SampleController { @@ -142,6 +153,7 @@ The controller would look no different for the Java and XML configurations, as t } } ---- +====== The following example shows the Mustache template: @@ -176,8 +188,11 @@ browser facilities that are not available in the server-side script engine. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -199,8 +214,10 @@ The following example shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -219,6 +236,7 @@ The following example shows how to do so: } } ---- +====== NOTE: Setting the `sharedEngine` property to `false` is required when using non-thread-safe script engines with templating libraries not designed for concurrency, such as Handlebars or diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc index b139bad0deee..255c899eb6e2 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc @@ -22,8 +22,11 @@ Configuration is standard for a simple Spring web application: The MVC configura has to define an `XsltViewResolver` bean and regular MVC annotation configuration. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @EnableWebMvc @ComponentScan @@ -39,8 +42,10 @@ The following example shows how to do so: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @EnableWebMvc @ComponentScan @@ -54,6 +59,7 @@ The following example shows how to do so: } } ---- +====== [[mvc-view-xslt-controllercode]] @@ -64,8 +70,11 @@ We also need a Controller that encapsulates our word-generation logic. The controller logic is encapsulated in a `@Controller` class, with the handler method being defined as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class XsltController { @@ -88,8 +97,10 @@ handler method being defined as follows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.ui.set @@ -114,6 +125,7 @@ handler method being defined as follows: } } ---- +====== So far, we have only created a DOM document and added it to the Model map. Note that you can also load an XML file as a `Resource` and use it instead of a custom DOM document. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc index 8cad1a50b913..83276621eba3 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc @@ -21,8 +21,11 @@ Once the asynchronous request processing feature is xref:web/webmvc/mvc-ann-asyn in the Servlet container, controller methods can wrap any supported controller method return value with `DeferredResult`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/quotes") @ResponseBody @@ -35,8 +38,10 @@ return value with `DeferredResult`, as the following example shows: // From some other thread... deferredResult.setResult(result); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/quotes") @ResponseBody @@ -49,6 +54,7 @@ return value with `DeferredResult`, as the following example shows: // From some other thread... deferredResult.setResult(result) ---- +====== The controller can produce the return value asynchronously, from a different thread -- for example, in response to an external event (JMS message), a scheduled task, or other event. @@ -61,16 +67,21 @@ example, in response to an external event (JMS message), a scheduled task, or ot A controller can wrap any supported return value with `java.util.concurrent.Callable`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping public Callable processUpload(final MultipartFile file) { return () -> "someView"; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping fun processUpload(file: MultipartFile) = Callable { @@ -78,6 +89,7 @@ as the following example shows: "someView" } ---- +====== The return value can then be obtained by running the given task through the xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration-spring-mvc[configured] `TaskExecutor`. @@ -211,8 +223,11 @@ each object is serialized with an xref:integration/rest-clients.adoc#rest-message-conversion[`HttpMessageConverter`] and written to the response, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/events") public ResponseBodyEmitter handle() { @@ -230,8 +245,10 @@ response, as the following example shows: // and done at some point emitter.complete(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/events") fun handle() = ResponseBodyEmitter().apply { @@ -247,6 +264,7 @@ response, as the following example shows: // and done at some point emitter.complete() ---- +====== You can also use `ResponseBodyEmitter` as the body in a `ResponseEntity`, letting you customize the status and headers of the response. @@ -267,8 +285,11 @@ https://www.w3.org/TR/eventsource/[Server-Sent Events], where events sent from t are formatted according to the W3C SSE specification. To produce an SSE stream from a controller, return `SseEmitter`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping(path="/events", produces=MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter handle() { @@ -286,8 +307,10 @@ stream from a controller, return `SseEmitter`, as the following example shows: // and done at some point emitter.complete(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/events", produces = [MediaType.TEXT_EVENT_STREAM_VALUE]) fun handle() = SseEmitter().apply { @@ -303,6 +326,7 @@ stream from a controller, return `SseEmitter`, as the following example shows: // and done at some point emitter.complete() ---- +====== While SSE is the main option for streaming into browsers, note that Internet Explorer does not support Server-Sent Events. Consider using Spring's @@ -320,8 +344,11 @@ Sometimes, it is useful to bypass message conversion and stream directly to the `OutputStream` (for example, for a file download). You can use the `StreamingResponseBody` return value type to do so, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/download") public StreamingResponseBody handle() { @@ -333,14 +360,17 @@ return value type to do so, as the following example shows: }; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/download") fun handle() = StreamingResponseBody { // write... } ---- +====== You can use `StreamingResponseBody` as the body in a `ResponseEntity` to customize the status and headers of the response. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc index da2ed1757f1f..758f82cfd761 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc @@ -32,8 +32,11 @@ While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all directives for the `Cache-Control` response header, the `CacheControl` type takes a use case-oriented approach that focuses on the common scenarios: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Cache for an hour - "Cache-Control: max-age=3600" CacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS); @@ -46,8 +49,10 @@ use case-oriented approach that focuses on the common scenarios: // "Cache-Control: max-age=864000, public, no-transform" CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Cache for an hour - "Cache-Control: max-age=3600" val ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS) @@ -60,6 +65,7 @@ use case-oriented approach that focuses on the common scenarios: // "Cache-Control: max-age=864000, public, no-transform" val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic() ---- +====== `WebContentGenerator` also accepts a simpler `cachePeriod` property (defined in seconds) that works as follows: @@ -81,8 +87,11 @@ against conditional request headers. A controller can add an `ETag` header and ` settings to a `ResponseEntity`, as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/book/{id}") public ResponseEntity showBook(@PathVariable Long id) { @@ -97,8 +106,10 @@ settings to a `ResponseEntity`, as the following example shows: .body(book); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/book/{id}") fun showBook(@PathVariable id: Long): ResponseEntity { @@ -113,6 +124,7 @@ settings to a `ResponseEntity`, as the following example shows: .body(book) } ---- +====== -- The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison @@ -123,8 +135,11 @@ You can also make the check against conditional request headers in the controlle as the following example shows: -- +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RequestMapping public String myHandleMethod(WebRequest request, Model model) { @@ -139,6 +154,7 @@ as the following example shows: return "myViewName"; } ---- +====== <1> Application-specific calculation. <2> The response has been set to 304 (NOT_MODIFIED) -- no further processing. <3> Continue with the request processing. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc index edf120d60135..dbcdcaccb015 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc @@ -12,8 +12,11 @@ For advanced mode, you can remove `@EnableWebMvc` and extend directly from `DelegatingWebMvcConfiguration` instead of implementing `WebMvcConfigurer`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class WebConfig extends DelegatingWebMvcConfiguration { @@ -21,8 +24,10 @@ as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration class WebConfig : DelegatingWebMvcConfiguration() { @@ -30,6 +35,7 @@ as the following example shows: // ... } ---- +====== You can keep existing methods in `WebConfig`, but you can now also override bean declarations from the base class, and you can still have any number of other `WebMvcConfigurer` implementations on diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-xml.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-xml.adoc index c203f2ee64dd..bb7203372647 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-xml.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-xml.adoc @@ -5,8 +5,11 @@ The MVC namespace does not have an advanced mode. If you need to customize a pro a bean that you cannot change otherwise, you can use the `BeanPostProcessor` lifecycle hook of the Spring `ApplicationContext`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Component public class MyPostProcessor implements BeanPostProcessor { @@ -16,8 +19,10 @@ hook of the Spring `ApplicationContext`, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Component class MyPostProcessor : BeanPostProcessor { @@ -27,6 +32,7 @@ hook of the Spring `ApplicationContext`, as the following example shows: } } ---- +====== Note that you need to declare `MyPostProcessor` as a bean, either explicitly in XML or diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc index 2848ad42b110..c209826dcbf8 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc @@ -16,8 +16,11 @@ more details. In Java configuration, you can customize requested content type resolution, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -30,8 +33,10 @@ following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -43,6 +48,7 @@ following example shows: } } ---- +====== The following example shows how to achieve the same configuration in XML: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc index 2de0ddc856e7..35d0998934de 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc @@ -8,8 +8,11 @@ for customization via `@NumberFormat` and `@DateTimeFormat` on fields. To register custom formatters and converters in Java config, use the following: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -21,8 +24,10 @@ To register custom formatters and converters in Java config, use the following: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -33,6 +38,7 @@ To register custom formatters and converters in Java config, use the following: } } ---- +====== To do the same in XML config, use the following: @@ -78,8 +84,11 @@ values. This works for forms where dates are represented as Strings with "input" fields. For "date" and "time" form fields, however, browsers use a fixed format defined in the HTML spec. For such cases date and time formatting can be customized as follows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -93,8 +102,10 @@ in the HTML spec. For such cases date and time formatting can be customized as f } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -107,6 +118,7 @@ in the HTML spec. For such cases date and time formatting can be customized as f } } ---- +====== NOTE: See xref:core/validation/format.adoc#format-FormatterRegistrar-SPI[the `FormatterRegistrar` SPI] and the `FormattingConversionServiceFactoryBean` for more information on when to use diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc index f9126edd1f21..dd7cf7e635e1 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc @@ -6,8 +6,11 @@ In Java configuration, you can implement the `WebMvcConfigurer` interface, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -16,8 +19,10 @@ following example shows: // Implement configuration methods... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -26,6 +31,7 @@ following example shows: // Implement configuration methods... } ---- +====== In XML, you can check attributes and sub-elements of ``. You can diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/default-servlet-handler.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/default-servlet-handler.adoc index 1fea95fc8079..8251cd53528b 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/default-servlet-handler.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/default-servlet-handler.adoc @@ -15,8 +15,11 @@ lower than that of the `DefaultServletHttpRequestHandler`, which is `Integer.MAX The following example shows how to enable the feature by using the default setup: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -28,8 +31,10 @@ The following example shows how to enable the feature by using the default setup } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -40,6 +45,7 @@ The following example shows how to enable the feature by using the default setup } } ---- +====== The following example shows how to achieve the same configuration in XML: @@ -57,8 +63,11 @@ If the default Servlet has been custom-configured with a different name, or if a different Servlet container is being used where the default Servlet name is unknown, then you must explicitly provide the default Servlet's name, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -70,8 +79,10 @@ then you must explicitly provide the default Servlet's name, as the following ex } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -82,6 +93,7 @@ then you must explicitly provide the default Servlet's name, as the following ex } } ---- +====== The following example shows how to achieve the same configuration in XML: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc index e7300178a1e9..bec619f91f3d 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc @@ -6,21 +6,27 @@ In Java configuration, you can use the `@EnableWebMvc` annotation to enable MVC configuration, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc public class WebConfig { } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc class WebConfig ---- +====== In XML configuration, you can use the `` element to enable MVC configuration, as the following example shows: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc index 2bdaf5effb6f..ccbf3433b2e5 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc @@ -4,8 +4,11 @@ In Java configuration, you can register interceptors to apply to incoming requests, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -18,8 +21,10 @@ the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -31,6 +36,7 @@ the following example shows: } } ---- +====== The following example shows how to achieve the same configuration in XML: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc index c8c861157931..0f3d79bc71c6 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc @@ -12,8 +12,11 @@ You can customize `HttpMessageConverter` in Java configuration by overriding The following example adds XML and Jackson JSON converters with a customized `ObjectMapper` instead of the default ones: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -30,8 +33,10 @@ The following example adds XML and Jackson JSON converters with a customized } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -45,6 +50,7 @@ The following example adds XML and Jackson JSON converters with a customized converters.add(MappingJackson2HttpMessageConverter(builder.build())) converters.add(MappingJackson2XmlHttpMessageConverter(builder.createXmlMapper(true).build())) ---- +====== In the preceding example, {api-spring-framework}/http/converter/json/Jackson2ObjectMapperBuilder.html[`Jackson2ObjectMapperBuilder`] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc index a3318bc15b94..eff9db98d660 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc @@ -9,8 +9,11 @@ For details on the individual options, see the The following example shows how to customize path matching in Java configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -26,8 +29,10 @@ The following example shows how to customize path matching in Java configuration } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -42,6 +47,7 @@ The following example shows how to customize path matching in Java configuration } } ---- +====== The following example shows how to customize path matching in XML configuration: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc index 7620f00ec714..adb887831e97 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc @@ -15,8 +15,11 @@ so that HTTP conditional requests are supported with `"Last-Modified"` headers. The following listing shows how to do so with Java configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -30,8 +33,10 @@ The following listing shows how to do so with Java configuration: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -44,6 +49,7 @@ The following listing shows how to do so with Java configuration: } } ---- +====== The following example shows how to achieve the same configuration in XML: @@ -69,8 +75,11 @@ JavaScript resources used with a module loader. The following example shows how to use `VersionResourceResolver` in Java configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -85,8 +94,10 @@ The following example shows how to use `VersionResourceResolver` in Java configu } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -100,6 +111,7 @@ The following example shows how to use `VersionResourceResolver` in Java configu } } ---- +====== The following example shows how to achieve the same configuration in XML: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc index 82a89a8e1303..833914f4ab3e 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc @@ -11,8 +11,11 @@ registered as a global xref:core/validation/validator.adoc[Validator] for use wi In Java configuration, you can customize the global `Validator` instance, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -24,8 +27,10 @@ following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -36,6 +41,7 @@ following example shows: } } ---- +====== The following example shows how to achieve the same configuration in XML: @@ -59,8 +65,11 @@ The following example shows how to achieve the same configuration in XML: Note that you can also register `Validator` implementations locally, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class MyController { @@ -71,8 +80,10 @@ example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller class MyController { @@ -83,6 +94,7 @@ example shows: } } ---- +====== TIP: If you need to have a `LocalValidatorFactoryBean` injected somewhere, create a bean and mark it with `@Primary` in order to avoid conflict with the one declared in the MVC configuration. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-controller.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-controller.adoc index 0df943d14e05..91811b7f415c 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-controller.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-controller.adoc @@ -7,8 +7,11 @@ logic to run before the view generates the response. The following example of Java configuration forwards a request for `/` to a view called `home`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -20,8 +23,10 @@ The following example of Java configuration forwards a request for `/` to a view } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -32,6 +37,7 @@ The following example of Java configuration forwards a request for `/` to a view } } ---- +====== The following example achieves the same thing as the preceding example, but with XML, by using the `` element: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc index da2227b20ec4..cea23436efd8 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc @@ -8,8 +8,11 @@ The MVC configuration simplifies the registration of view resolvers. The following Java configuration example configures content negotiation view resolution by using JSP and Jackson as a default `View` for JSON rendering: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -22,8 +25,10 @@ resolution by using JSP and Jackson as a default `View` for JSON rendering: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -35,6 +40,7 @@ resolution by using JSP and Jackson as a default `View` for JSON rendering: } } ---- +====== The following example shows how to achieve the same configuration in XML: @@ -75,8 +81,11 @@ The MVC namespace provides dedicated elements. The following example works with In Java configuration, you can add the respective `Configurer` bean, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @EnableWebMvc @@ -96,8 +105,10 @@ as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @EnableWebMvc @@ -114,6 +125,7 @@ as the following example shows: } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc index 7af5f14a5586..112361f7dba1 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc @@ -9,8 +9,11 @@ exception handling, and more. Annotated controllers have flexible method signatu do not have to extend base classes nor implement specific interfaces. The following example shows a controller defined by annotations: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class HelloController { @@ -22,8 +25,10 @@ The following example shows a controller defined by annotations: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.ui.set @@ -37,6 +42,7 @@ The following example shows a controller defined by annotations: } } ---- +====== In the preceding example, the method accepts a `Model` and returns a view name as a `String`, but many other options exist and are explained later in this chapter. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc index 7cda8894f6ae..46726f71ad24 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc @@ -23,8 +23,11 @@ By contrast, global `@ModelAttribute` and `@InitBinder` methods are applied _bef The `@ControllerAdvice` annotation has attributes that let you narrow the set of controllers and handlers that they apply to. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // Target all Controllers annotated with @RestController @ControllerAdvice(annotations = RestController.class) @@ -38,8 +41,10 @@ and handlers that they apply to. For example: @ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class}) public class ExampleAdvice3 {} ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // Target all Controllers annotated with @RestController @ControllerAdvice(annotations = [RestController::class]) @@ -53,6 +58,7 @@ and handlers that they apply to. For example: @ControllerAdvice(assignableTypes = [ControllerInterface::class, AbstractController::class]) class ExampleAdvice3 ---- +====== The selectors in the preceding example are evaluated at runtime and may negatively impact performance if used extensively. See the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc index 89f7aeff9a02..73af9fa6ce46 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc @@ -6,8 +6,11 @@ `@Controller` and xref:web/webmvc/mvc-controller/ann-advice.adoc[@ControllerAdvice] classes can have `@ExceptionHandler` methods to handle exceptions from controller methods, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class SimpleController { @@ -20,8 +23,10 @@ } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller class SimpleController { @@ -34,6 +39,7 @@ } } ---- +====== The exception may match against a top-level exception being propagated (e.g. a direct `IOException` being thrown) or against a nested cause within a wrapper exception (e.g. @@ -48,42 +54,54 @@ is used to sort exceptions based on their depth from the thrown exception type. Alternatively, the annotation declaration may narrow the exception types to match, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExceptionHandler({FileSystemException.class, RemoteException.class}) public ResponseEntity handle(IOException ex) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExceptionHandler(FileSystemException::class, RemoteException::class) fun handle(ex: IOException): ResponseEntity { // ... } ---- +====== You can even use a list of specific exception types with a very generic argument signature, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ExceptionHandler({FileSystemException.class, RemoteException.class}) public ResponseEntity handle(Exception ex) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ExceptionHandler(FileSystemException::class, RemoteException::class) fun handle(ex: Exception): ResponseEntity { // ... } ---- +====== [NOTE] ==== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc index 2c2a5ecce647..d4149a76a912 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc @@ -21,8 +21,11 @@ do, except for `@ModelAttribute` (command object) arguments. Typically, they are with a `WebDataBinder` argument (for registrations) and a `void` return value. The following listing shows an example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class FormController { @@ -37,6 +40,7 @@ The following listing shows an example: // ... } ---- +====== <1> Defining an `@InitBinder` method. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -61,8 +65,11 @@ Alternatively, when you use a `Formatter`-based setup through a shared `FormattingConversionService`, you can re-use the same approach and register controller-specific `Formatter` implementations, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class FormController { @@ -75,6 +82,7 @@ controller-specific `Formatter` implementations, as the following example shows: // ... } ---- +====== <1> Defining an `@InitBinder` method on a custom formatter. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc index 953953f51eec..0d680ce43e87 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc @@ -15,14 +15,18 @@ JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84 The following example shows how to get the cookie value: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/demo") public void handle(@CookieValue("JSESSIONID") String cookie) { <1> //... } ---- +====== <1> Get the value of the `JSESSIONID` cookie. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc index 9ed54e0d6f29..024f99b14919 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc @@ -6,22 +6,28 @@ `HttpEntity` is more or less identical to using xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[`@RequestBody`] but is based on a container object that exposes request headers and body. The following listing shows an example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/accounts") public void handle(HttpEntity entity) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/accounts") fun handle(entity: HttpEntity) { // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc index c8a44324c281..3ea43c3e9713 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc @@ -13,8 +13,11 @@ which allow rendering only a subset of all fields in an `Object`. To use it with `@ResponseBody` or `ResponseEntity` controller methods, you can use Jackson's `@JsonView` annotation to activate a serialization view class, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RestController public class UserController { @@ -53,8 +56,10 @@ which allow rendering only a subset of all fields in an `Object`. To use it with } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RestController class UserController { @@ -72,6 +77,7 @@ which allow rendering only a subset of all fields in an `Object`. To use it with interface WithPasswordView : WithoutPasswordView } ---- +====== NOTE: `@JsonView` allows an array of view classes, but you can specify only one per controller method. If you need to activate multiple views, you can use a composite interface. @@ -79,8 +85,11 @@ controller method. If you need to activate multiple views, you can use a composi If you want to do the above programmatically, instead of declaring an `@JsonView` annotation, wrap the return value with `MappingJacksonValue` and use it to supply the serialization view: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RestController public class UserController { @@ -94,8 +103,10 @@ wrap the return value with `MappingJacksonValue` and use it to supply the serial } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RestController class UserController { @@ -108,12 +119,16 @@ wrap the return value with `MappingJacksonValue` and use it to supply the serial } } ---- +====== For controllers that rely on view resolution, you can add the serialization view class to the model, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class UserController extends AbstractController { @@ -126,8 +141,10 @@ to the model, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller class UserController : AbstractController() { @@ -140,6 +157,7 @@ to the model, as the following example shows: } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc index 927cf90a718f..83171fc4f036 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc @@ -18,8 +18,11 @@ method must use a URI variable to mask that variable content and ensure the requ be matched successfully independent of matrix variable order and presence. The following example uses a matrix variable: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // GET /pets/42;q=11;r=22 @@ -30,8 +33,10 @@ The following example uses a matrix variable: // q == 11 } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // GET /pets/42;q=11;r=22 @@ -42,13 +47,17 @@ The following example uses a matrix variable: // q == 11 } ---- +====== Given that all path segments may contain matrix variables, you may sometimes need to disambiguate which path variable the matrix variable is expected to be in. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // GET /owners/42;q=11/pets/21;q=22 @@ -61,8 +70,10 @@ The following example shows how to do so: // q2 == 22 } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // GET /owners/42;q=11/pets/21;q=22 @@ -75,12 +86,16 @@ The following example shows how to do so: // q2 == 22 } ---- +====== A matrix variable may be defined as optional and a default value specified, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // GET /pets/42 @@ -90,8 +105,10 @@ following example shows: // q == 1 } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // GET /pets/42 @@ -101,11 +118,15 @@ following example shows: // q == 1 } ---- +====== To get all matrix variables, you can use a `MultiValueMap`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 @@ -118,8 +139,10 @@ To get all matrix variables, you can use a `MultiValueMap`, as the following exa // petMatrixVars: ["q" : 22, "s" : 23] } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 @@ -132,6 +155,7 @@ To get all matrix variables, you can use a `MultiValueMap`, as the following exa // petMatrixVars: ["q" : 22, "s" : 23] } ---- +====== Note that you need to enable the use of matrix variables. In the MVC Java configuration, you need to set a `UrlPathHelper` with `removeSemicolonContent=false` through diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc index 8140ea15dc2d..06a8de2dfd4d 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc @@ -9,14 +9,18 @@ values from HTTP Servlet request parameters whose names match to field names. Th to as data binding, and it saves you from having to deal with parsing and converting individual query parameters and form fields. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/owners/{ownerId}/pets/{petId}/edit") public String processSubmit(@ModelAttribute Pet pet) { // <1> // method logic... } ---- +====== <1> Bind an instance of `Pet`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -51,14 +55,18 @@ In the following example, the model attribute name is `account` which matches th path variable `account`, and there is a registered `Converter` which could load the `Account` from a data store: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PutMapping("/accounts/{account}") public String save(@ModelAttribute("account") Account account) { // <1> // ... } ---- +====== <1> Bind an instance of `Account` using an explicit attribute name. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -82,8 +90,11 @@ Data binding can result in errors. By default, a `BindException` is raised. Howe for such errors in the controller method, you can add a `BindingResult` argument immediately next to the `@ModelAttribute`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/owners/{ownerId}/pets/{petId}/edit") public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { // <1> @@ -93,6 +104,7 @@ to the `@ModelAttribute`, as the following example shows: // ... } ---- +====== <1> Adding a `BindingResult` next to the `@ModelAttribute`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -112,8 +124,11 @@ In some cases, you may want access to a model attribute without data binding. Fo cases, you can inject the `Model` into the controller and access it directly or, alternatively, set `@ModelAttribute(binding=false)`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ModelAttribute public AccountForm setUpForm() { @@ -131,6 +146,7 @@ alternatively, set `@ModelAttribute(binding=false)`, as the following example sh // ... } ---- +====== <1> Setting `@ModelAttribute(binding=false)`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -159,8 +175,11 @@ You can automatically apply validation after data binding by adding the (xref:core/validation/beanvalidation.adoc[Bean Validation] and xref:web/webmvc/mvc-config/validation.adoc[Spring validation]). The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/owners/{ownerId}/pets/{petId}/edit") public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { // <1> @@ -170,6 +189,7 @@ xref:web/webmvc/mvc-config/validation.adoc[Spring validation]). The following ex // ... } ---- +====== <1> Validate the `Pet` instance. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc index 5348bc47508a..de91ecad48de 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc @@ -8,8 +8,11 @@ requests with `multipart/form-data` is parsed and accessible as regular request parameters. The following example accesses one regular form field and one uploaded file: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller public class FileUploadController { @@ -27,8 +30,10 @@ file: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller class FileUploadController { @@ -46,6 +51,7 @@ file: } } ---- +====== Declaring the argument type as a `List` allows for resolving multiple files for the same parameter name. @@ -62,8 +68,11 @@ xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[command and file from the preceding example could be fields on a form object, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- class MyForm { @@ -88,8 +97,10 @@ as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyForm(val name: String, val file: MultipartFile, ...) @@ -107,6 +118,7 @@ as the following example shows: } } ---- +====== Multipart requests can also be submitted from non-browser clients in a RESTful service @@ -137,8 +149,11 @@ probably want it deserialized from JSON (similar to `@RequestBody`). Use the `@RequestPart` annotation to access a multipart after converting it with an xref:integration/rest-clients.adoc#rest-message-conversion[HttpMessageConverter]: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/") public String handle(@RequestPart("meta-data") MetaData metadata, @@ -146,8 +161,10 @@ xref:integration/rest-clients.adoc#rest-message-conversion[HttpMessageConverter] // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/") fun handle(@RequestPart("meta-data") metadata: MetaData, @@ -155,6 +172,7 @@ xref:integration/rest-clients.adoc#rest-message-conversion[HttpMessageConverter] // ... } ---- +====== You can use `@RequestPart` in combination with `jakarta.validation.Valid` or use Spring's `@Validated` annotation, both of which cause Standard Bean Validation to be applied. @@ -163,8 +181,11 @@ into a 400 (BAD_REQUEST) response. Alternatively, you can handle validation erro within the controller through an `Errors` or `BindingResult` argument, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/") public String handle(@Valid @RequestPart("meta-data") MetaData metadata, @@ -172,8 +193,10 @@ as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/") fun handle(@Valid @RequestPart("meta-data") metadata: MetaData, @@ -181,6 +204,7 @@ as the following example shows: // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc index d32331c410f2..5ed5b89b4d15 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc @@ -26,8 +26,11 @@ Note that URI template variables from the present request are automatically made available when expanding a redirect URL, and you don't need to explicitly add them through `Model` or `RedirectAttributes`. The following example shows how to define a redirect: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/files/{path}") public String upload(...) { @@ -35,8 +38,10 @@ through `Model` or `RedirectAttributes`. The following example shows how to defi return "redirect:files/{path}"; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/files/{path}") fun upload(...): String { @@ -44,6 +49,7 @@ through `Model` or `RedirectAttributes`. The following example shows how to defi return "redirect:files/{path}" } ---- +====== Another way of passing data to the redirect target is by using flash attributes. Unlike other redirect attributes, flash attributes are saved in the HTTP session (and, hence, do diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc index 30858af1c966..40986e90c979 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc @@ -7,14 +7,18 @@ Similar to `@SessionAttribute`, you can use the `@RequestAttribute` annotations access pre-existing request attributes created earlier (for example, by a Servlet `Filter` or `HandlerInterceptor`): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/") public String handle(@RequestAttribute Client client) { // <1> // ... } ---- +====== <1> Using the `@RequestAttribute` annotation. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc index b5cc27f47ec0..2c4f316feb9a 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc @@ -7,22 +7,28 @@ You can use the `@RequestBody` annotation to have the request body read and dese `Object` through an xref:integration/rest-clients.adoc#rest-message-conversion[`HttpMessageConverter`]. The following example uses a `@RequestBody` argument: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/accounts") public void handle(@RequestBody Account account) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/accounts") fun handle(@RequestBody account: Account) { // ... } ---- +====== You can use the xref:web/webmvc/mvc-config/message-converters.adoc[Message Converters] option of the xref:web/webmvc/mvc-config.adoc[MVC Config] to @@ -35,21 +41,27 @@ into a 400 (BAD_REQUEST) response. Alternatively, you can handle validation erro within the controller through an `Errors` or `BindingResult` argument, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping("/accounts") public void handle(@Valid @RequestBody Account account, BindingResult result) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @PostMapping("/accounts") fun handle(@Valid @RequestBody account: Account, result: BindingResult) { // ... } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc index d4ce20b0f8b3..0e2f952569c7 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc @@ -21,8 +21,11 @@ Keep-Alive 300 The following example gets the value of the `Accept-Encoding` and `Keep-Alive` headers: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/demo") public void handle( @@ -31,6 +34,7 @@ The following example gets the value of the `Accept-Encoding` and `Keep-Alive` h //... } ---- +====== <1> Get the value of the `Accept-Encoding` header. <2> Get the value of the `Keep-Alive` header. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc index 41b66fe9fa13..9017bd2284be 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc @@ -8,8 +8,11 @@ query parameters or form data) to a method argument in a controller. The following example shows how to do so: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller @RequestMapping("/pets") @@ -28,6 +31,7 @@ The following example shows how to do so: } ---- +====== <1> Using `@RequestParam` to bind `petId`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc index 7462334c47cc..1cd1816e5d3c 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc @@ -8,8 +8,11 @@ to the response body through an xref:integration/rest-clients.adoc#rest-message-conversion[HttpMessageConverter]. The following listing shows an example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/accounts/{id}") @ResponseBody @@ -17,8 +20,10 @@ The following listing shows an example: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/accounts/{id}") @ResponseBody @@ -26,6 +31,7 @@ The following listing shows an example: // ... } ---- +====== `@ResponseBody` is also supported at the class level, in which case it is inherited by all controller methods. This is the effect of `@RestController`, which is nothing more diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc index 9fb12986a292..f311386cabb4 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc @@ -5,8 +5,11 @@ `ResponseEntity` is like xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[`@ResponseBody`] but with status and headers. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/something") public ResponseEntity handle() { @@ -15,8 +18,10 @@ return ResponseEntity.ok().eTag(etag).body(body); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/something") fun handle(): ResponseEntity { @@ -25,6 +30,7 @@ return ResponseEntity.ok().eTag(etag).build(body) } ---- +====== Spring MVC supports using a single value xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[reactive type] to produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc index 3e5fcad06f6f..2ecb0bb8deb3 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc @@ -8,14 +8,18 @@ If you need access to pre-existing session attributes that are managed globally you can use the `@SessionAttribute` annotation on a method parameter, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RequestMapping("/") public String handle(@SessionAttribute User user) { <1> // ... } ---- +====== <1> Using a `@SessionAttribute` annotation. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc index 3dcbf3a6d831..30a606d4ccac 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc @@ -11,8 +11,11 @@ requests to access. The following example uses the `@SessionAttributes` annotation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller @SessionAttributes("pet") // <1> @@ -20,6 +23,7 @@ The following example uses the `@SessionAttributes` annotation: // ... } ---- +====== <1> Using the `@SessionAttributes` annotation. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -38,8 +42,11 @@ it is automatically promoted to and saved in the HTTP Servlet session. It remain until another controller method uses a `SessionStatus` method argument to clear the storage, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller @SessionAttributes("pet") // <1> @@ -57,6 +64,7 @@ storage, as the following example shows: } } ---- +====== <1> Storing the `Pet` value in the Servlet session. <2> Clearing the `Pet` value from the Servlet session. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc index fec596077f66..0f58a97dd8d6 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc @@ -24,8 +24,11 @@ related to the request body. The following example shows a `@ModelAttribute` method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ModelAttribute public void populateModel(@RequestParam String number, Model model) { @@ -33,8 +36,10 @@ The following example shows a `@ModelAttribute` method: // add more ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ModelAttribute fun populateModel(@RequestParam number: String, model: Model) { @@ -42,25 +47,32 @@ The following example shows a `@ModelAttribute` method: // add more ... } ---- +====== The following example adds only one attribute: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @ModelAttribute public Account addAccount(@RequestParam String number) { return accountRepository.findAccount(number); } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @ModelAttribute fun addAccount(@RequestParam number: String): Account { return accountRepository.findAccount(number) } ---- +====== NOTE: When a name is not explicitly specified, a default name is chosen based on the `Object` @@ -74,8 +86,11 @@ attribute. This is typically not required, as it is the default behavior in HTML unless the return value is a `String` that would otherwise be interpreted as a view name. `@ModelAttribute` can also customize the model attribute name, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/accounts/{id}") @ModelAttribute("myAccount") @@ -84,8 +99,10 @@ unless the return value is a `String` that would otherwise be interpreted as a v return account; } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/accounts/{id}") @ModelAttribute("myAccount") @@ -94,6 +111,7 @@ unless the return value is a `String` that would otherwise be interpreted as a v return account } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc index 36b81824db3d..afa7de56fb0d 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc @@ -23,8 +23,11 @@ A `@RequestMapping` is still needed at the class level to express shared mapping The following example has type and method level mappings: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RestController @RequestMapping("/persons") @@ -42,8 +45,10 @@ The following example has type and method level mappings: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RestController @RequestMapping("/persons") @@ -61,6 +66,7 @@ The following example has type and method level mappings: } } ---- +====== @@ -102,28 +108,37 @@ Some example patterns: Captured URI variables can be accessed with `@PathVariable`. For example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/owners/{ownerId}/pets/{petId}") public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/owners/{ownerId}/pets/{petId}") fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet { // ... } ---- +====== You can declare URI variables at the class and method levels, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller @RequestMapping("/owners/{ownerId}") @@ -135,8 +150,10 @@ You can declare URI variables at the class and method levels, as the following e } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller @RequestMapping("/owners/{ownerId}") @@ -148,6 +165,7 @@ You can declare URI variables at the class and method levels, as the following e } } ---- +====== URI variables are automatically converted to the appropriate type, or `TypeMismatchException` is raised. Simple types (`int`, `long`, `Date`, and so on) are supported by default and you can @@ -162,22 +180,28 @@ The syntax `{varName:regex}` declares a URI variable with a regular expression t syntax of `{varName:regex}`. For example, given URL `"/spring-web-3.0.5.jar"`, the following method extracts the name, version, and file extension: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") public void handle(@PathVariable String name, @PathVariable String version, @PathVariable String ext) { // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}") fun handle(@PathVariable name: String, @PathVariable version: String, @PathVariable ext: String) { // ... } ---- +====== URI path patterns can also have embedded `${...}` placeholders that are resolved on startup by using `PropertySourcesPlaceholderConfigurer` against local, system, environment, and @@ -274,14 +298,18 @@ recommendations related to RFD. You can narrow the request mapping based on the `Content-Type` of the request, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @PostMapping(path = "/pets", consumes = "application/json") // <1> public void addPet(@RequestBody Pet pet) { // ... } ---- +====== <1> Using a `consumes` attribute to narrow the mapping by the content type. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -312,8 +340,11 @@ TIP: `MediaType` provides constants for commonly used media types, such as You can narrow the request mapping based on the `Accept` request header and the list of content types that a controller method produces, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping(path = "/pets/{petId}", produces = "application/json") // <1> @ResponseBody @@ -321,6 +352,7 @@ content types that a controller method produces, as the following example shows: // ... } ---- +====== <1> Using a `produces` attribute to narrow the mapping by the content type. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -353,14 +385,18 @@ You can narrow request mappings based on request parameter conditions. You can t presence of a request parameter (`myParam`), for the absence of one (`!myParam`), or for a specific value (`myParam=myValue`). The following example shows how to test for a specific value: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping(path = "/pets/{petId}", params = "myParam=myValue") // <1> public void findPet(@PathVariable String petId) { // ... } ---- +====== <1> Testing whether `myParam` equals `myValue`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -375,14 +411,18 @@ specific value (`myParam=myValue`). The following example shows how to test for You can also use the same with request header conditions, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @GetMapping(path = "/pets/{petId}", headers = "myHeader=myValue") // <1> public void findPet(@PathVariable String petId) { // ... } ---- +====== <1> Testing whether `myHeader` equals `myValue`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -455,8 +495,11 @@ You can programmatically register handler methods, which you can use for dynamic registrations or for advanced cases, such as different instances of the same handler under different URLs. The following example registers a handler method: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration public class MyConfig { @@ -474,6 +517,7 @@ under different URLs. The following example registers a handler method: } } ---- +====== <1> Inject the target handler and the handler mapping for controllers. <2> Prepare the request mapping meta data. <3> Get the handler method. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc index 502a3587ad41..b6495f54dd44 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc @@ -12,8 +12,11 @@ annotated class, indicating its role as a web component. To enable auto-detection of such `@Controller` beans, you can add component scanning to your Java configuration, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Configuration @ComponentScan("org.example.web") @@ -22,8 +25,10 @@ your Java configuration, as the following example shows: // ... } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Configuration @ComponentScan("org.example.web") @@ -32,6 +37,7 @@ your Java configuration, as the following example shows: // ... } ---- +====== The following example shows the XML configuration equivalent of the preceding example: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc index 388084fda2f8..173ee07e6797 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc @@ -18,8 +18,11 @@ The following example of the Java configuration registers and initializes the `DispatcherServlet`, which is auto-detected by the Servlet container (see xref:web/webmvc/mvc-servlet/container-config.adoc[Servlet Config]): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyWebApplicationInitializer implements WebApplicationInitializer { @@ -38,8 +41,10 @@ the `DispatcherServlet`, which is auto-detected by the Servlet container } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyWebApplicationInitializer : WebApplicationInitializer { @@ -57,6 +62,7 @@ the `DispatcherServlet`, which is auto-detected by the Servlet container } } ---- +====== NOTE: In addition to using the ServletContext API directly, you can also extend `AbstractAnnotationConfigDispatcherServletInitializer` and override specific methods diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/container-config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/container-config.adoc index d5624854e6f0..a6a4755c0230 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/container-config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/container-config.adoc @@ -5,8 +5,11 @@ In a Servlet environment, you have the option of configuring the Servlet contain programmatically as an alternative or in combination with a `web.xml` file. The following example registers a `DispatcherServlet`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- import org.springframework.web.WebApplicationInitializer; @@ -23,8 +26,10 @@ The following example registers a `DispatcherServlet`: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- import org.springframework.web.WebApplicationInitializer @@ -40,6 +45,7 @@ The following example registers a `DispatcherServlet`: } } ---- +====== `WebApplicationInitializer` is an interface provided by Spring MVC that ensures your @@ -52,8 +58,11 @@ location of the `DispatcherServlet` configuration. This is recommended for applications that use Java-based Spring configuration, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { @@ -73,8 +82,10 @@ following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { @@ -91,12 +102,16 @@ following example shows: } } ---- +====== If you use XML-based Spring configuration, you should extend directly from `AbstractDispatcherServletInitializer`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyWebAppInitializer extends AbstractDispatcherServletInitializer { @@ -118,8 +133,10 @@ If you use XML-based Spring configuration, you should extend directly from } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyWebAppInitializer : AbstractDispatcherServletInitializer() { @@ -138,13 +155,17 @@ If you use XML-based Spring configuration, you should extend directly from } } ---- +====== `AbstractDispatcherServletInitializer` also provides a convenient way to add `Filter` instances and have them be automatically mapped to the `DispatcherServlet`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyWebAppInitializer extends AbstractDispatcherServletInitializer { @@ -157,8 +178,10 @@ following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyWebAppInitializer : AbstractDispatcherServletInitializer() { @@ -169,6 +192,7 @@ following example shows: } } ---- +====== Each filter is added with a default name based on its concrete type and automatically mapped to the `DispatcherServlet`. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc index 8884cfacc891..5e18f2e21eac 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc @@ -24,8 +24,11 @@ image::mvc-context-hierarchy.png[] The following example configures a `WebApplicationContext` hierarchy: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { @@ -45,8 +48,10 @@ The following example configures a `WebApplicationContext` hierarchy: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { @@ -63,6 +68,7 @@ The following example configures a `WebApplicationContext` hierarchy: } } ---- +====== TIP: If an application context hierarchy is not required, applications can return all configuration through `getRootConfigClasses()` and `null` from `getServletConfigClasses()`. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc index c839fb111529..23e8587b3bde 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc @@ -74,8 +74,11 @@ Servlet container makes an ERROR dispatch within the container to the configured to a `@Controller`, which could be implemented to return an error view name with a model or to render a JSON response, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RestController public class ErrorController { @@ -89,8 +92,10 @@ or to render a JSON response, as the following example shows: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RestController class ErrorController { @@ -104,6 +109,7 @@ or to render a JSON response, as the following example shows: } } ---- +====== TIP: The Servlet API does not provide a way to create error page mappings in Java. You can, however, use both a `WebApplicationInitializer` and a minimal `web.xml`. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc index d3ab01eb37eb..26e4193d81d0 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc @@ -25,8 +25,11 @@ through the `enableLoggingRequestDetails` property on `DispatcherServlet`. The following example shows how to do so by using Java configuration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class MyInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { @@ -53,8 +56,10 @@ public class MyInitializer } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class MyInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { @@ -75,6 +80,7 @@ public class MyInitializer } } ---- +====== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc index a0dfe886c6dd..44844ba9a06b 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc @@ -28,8 +28,11 @@ To do so: The following example shows how to set a `MultipartConfigElement` on the Servlet registration: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- public class AppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer { @@ -44,8 +47,10 @@ The following example shows how to set a `MultipartConfigElement` on the Servlet } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- class AppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() { @@ -59,6 +64,7 @@ The following example shows how to set a `MultipartConfigElement` on the Servlet } ---- +====== Once the Servlet multipart configuration is in place, you can add a bean of type `StandardServletMultipartResolver` with a name of `multipartResolver`. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc index ea5a7699957a..3e18dae861ad 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc @@ -15,8 +15,11 @@ include::partial$web/web-uris.adoc[leveloffset=+1] You can use `ServletUriComponentsBuilder` to create URIs relative to the current request, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpServletRequest request = ... @@ -26,8 +29,10 @@ as the following example shows: .replaceQueryParam("accountId", "{id}") .build("123"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val request: HttpServletRequest = ... @@ -37,11 +42,15 @@ as the following example shows: .replaceQueryParam("accountId", "{id}") .build("123") ---- +====== You can create URIs relative to the context path, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpServletRequest request = ... @@ -52,8 +61,10 @@ You can create URIs relative to the context path, as the following example shows .build() .toUri(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val request: HttpServletRequest = ... @@ -64,12 +75,16 @@ You can create URIs relative to the context path, as the following example shows .build() .toUri() ---- +====== You can create URIs relative to a Servlet (for example, `/main/{asterisk}`), as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- HttpServletRequest request = ... @@ -80,8 +95,10 @@ as the following example shows: .build() .toUri(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val request: HttpServletRequest = ... @@ -92,6 +109,7 @@ as the following example shows: .build() .toUri() ---- +====== NOTE: As of 5.1, `ServletUriComponentsBuilder` ignores information from the `Forwarded` and `X-Forwarded-*` headers, which specify the client-originated address. Consider using the @@ -106,8 +124,11 @@ such headers. Spring MVC provides a mechanism to prepare links to controller methods. For example, the following MVC controller allows for link creation: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @Controller @RequestMapping("/hotels/{hotel}") @@ -119,8 +140,10 @@ the following MVC controller allows for link creation: } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @Controller @RequestMapping("/hotels/{hotel}") @@ -132,25 +155,32 @@ the following MVC controller allows for link creation: } } ---- +====== You can prepare a link by referring to the method by name, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- UriComponents uriComponents = MvcUriComponentsBuilder .fromMethodName(BookingController.class, "getBooking", 21).buildAndExpand(42); URI uri = uriComponents.encode().toUri(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val uriComponents = MvcUriComponentsBuilder .fromMethodName(BookingController::class.java, "getBooking", 21).buildAndExpand(42) val uri = uriComponents.encode().toUri() ---- +====== In the preceding example, we provide actual method argument values (in this case, the long value: `21`) to be used as a path variable and inserted into the URL. Furthermore, we provide the @@ -163,22 +193,28 @@ There are additional ways to use `MvcUriComponentsBuilder`. For example, you can akin to mock testing through proxies to avoid referring to the controller method by name, as the following example shows (the example assumes static import of `MvcUriComponentsBuilder.on`): +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- UriComponents uriComponents = MvcUriComponentsBuilder .fromMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42); URI uri = uriComponents.encode().toUri(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val uriComponents = MvcUriComponentsBuilder .fromMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42) val uri = uriComponents.encode().toUri() ---- +====== NOTE: Controller method signatures are limited in their design when they are supposed to be usable for link creation with `fromMethodCall`. Aside from needing a proper parameter signature, @@ -200,8 +236,11 @@ For such cases, you can use the static `fromXxx` overloaded methods that accept with a base URL and then use the instance-based `withXxx` methods. For example, the following listing uses `withMethodCall`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- UriComponentsBuilder base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en"); MvcUriComponentsBuilder builder = MvcUriComponentsBuilder.relativeTo(base); @@ -209,8 +248,10 @@ following listing uses `withMethodCall`: URI uri = uriComponents.encode().toUri(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en") val builder = MvcUriComponentsBuilder.relativeTo(base) @@ -218,6 +259,7 @@ following listing uses `withMethodCall`: val uri = uriComponents.encode().toUri() ---- +====== NOTE: As of 5.1, `MvcUriComponentsBuilder` ignores information from the `Forwarded` and `X-Forwarded-*` headers, which specify the client-originated address. Consider using the @@ -234,8 +276,11 @@ by referring to the implicitly or explicitly assigned name for each request mapp Consider the following example: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- @RequestMapping("/people/{id}/addresses") public class PersonAddressController { @@ -244,8 +289,10 @@ Consider the following example: public HttpEntity getAddress(@PathVariable String country) { ... } } ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- @RequestMapping("/people/{id}/addresses") class PersonAddressController { @@ -254,6 +301,7 @@ Consider the following example: fun getAddress(@PathVariable country: String): HttpEntity { ... } } ---- +====== Given the preceding controller, you can prepare a link from a JSP, as follows: diff --git a/framework-docs/modules/ROOT/partials/web/web-uris.adoc b/framework-docs/modules/ROOT/partials/web/web-uris.adoc index b644cd2e1709..a0e8218b4a46 100644 --- a/framework-docs/modules/ROOT/partials/web/web-uris.adoc +++ b/framework-docs/modules/ROOT/partials/web/web-uris.adoc @@ -4,8 +4,11 @@ `UriComponentsBuilder` helps to build URI's from URI templates with variables, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- UriComponents uriComponents = UriComponentsBuilder .fromUriString("https://example.com/hotels/{hotel}") // <1> @@ -15,6 +18,7 @@ URI uri = uriComponents.expand("Westin", "123").toUri(); // <5> ---- +====== <1> Static factory method with a URI template. <2> Add or replace URI components. <3> Request to have the URI template and URI variables encoded. @@ -41,8 +45,11 @@ The preceding example can be consolidated into one chain and shortened with `buildAndExpand`, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- URI uri = UriComponentsBuilder .fromUriString("https://example.com/hotels/{hotel}") @@ -51,8 +58,10 @@ as the following example shows: .buildAndExpand("Westin", "123") .toUri(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val uri = UriComponentsBuilder .fromUriString("https://example.com/hotels/{hotel}") @@ -61,43 +70,56 @@ as the following example shows: .buildAndExpand("Westin", "123") .toUri() ---- +====== You can shorten it further by going directly to a URI (which implies encoding), as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- URI uri = UriComponentsBuilder .fromUriString("https://example.com/hotels/{hotel}") .queryParam("q", "{q}") .build("Westin", "123"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val uri = UriComponentsBuilder .fromUriString("https://example.com/hotels/{hotel}") .queryParam("q", "{q}") .build("Westin", "123") ---- +====== You can shorten it further still with a full URI template, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- URI uri = UriComponentsBuilder .fromUriString("https://example.com/hotels/{hotel}?q={q}") .build("Westin", "123"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val uri = UriComponentsBuilder .fromUriString("https://example.com/hotels/{hotel}?q={q}") .build("Westin", "123") ---- +====== @@ -117,8 +139,11 @@ exposes shared configuration options. The following example shows how to configure a `RestTemplate`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode; @@ -129,8 +154,10 @@ The following example shows how to configure a `RestTemplate`: RestTemplate restTemplate = new RestTemplate(); restTemplate.setUriTemplateHandler(factory); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode @@ -141,11 +168,15 @@ The following example shows how to configure a `RestTemplate`: val restTemplate = RestTemplate() restTemplate.uriTemplateHandler = factory ---- +====== The following example configures a `WebClient`: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- // import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode; @@ -155,8 +186,10 @@ The following example configures a `WebClient`: WebClient client = WebClient.builder().uriBuilderFactory(factory).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- // import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode @@ -166,13 +199,17 @@ The following example configures a `WebClient`: val client = WebClient.builder().uriBuilderFactory(factory).build() ---- +====== In addition, you can also use `DefaultUriBuilderFactory` directly. It is similar to using `UriComponentsBuilder` but, instead of static factory methods, it is an actual instance that holds configuration and preferences, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- String baseUrl = "https://example.com"; DefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl); @@ -181,8 +218,10 @@ that holds configuration and preferences, as the following example shows: .queryParam("q", "{q}") .build("Westin", "123"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val baseUrl = "https://example.com" val uriBuilderFactory = DefaultUriBuilderFactory(baseUrl) @@ -191,6 +230,7 @@ that holds configuration and preferences, as the following example shows: .queryParam("q", "{q}") .build("Westin", "123") ---- +====== [[uri-encoding]] @@ -219,8 +259,11 @@ incidentally looks like a URI variable. The following example uses the first option: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}") .queryParam("q", "{q}") @@ -230,8 +273,10 @@ The following example uses the first option: // Result is "/hotel%20list/New%20York?q=foo%2Bbar" ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val uri = UriComponentsBuilder.fromPath("/hotel list/{city}") .queryParam("q", "{q}") @@ -241,46 +286,62 @@ The following example uses the first option: // Result is "/hotel%20list/New%20York?q=foo%2Bbar" ---- +====== You can shorten the preceding example by going directly to the URI (which implies encoding), as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}") .queryParam("q", "{q}") .build("New York", "foo+bar"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val uri = UriComponentsBuilder.fromPath("/hotel list/{city}") .queryParam("q", "{q}") .build("New York", "foo+bar") ---- +====== You can shorten it further still with a full URI template, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- URI uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}") .build("New York", "foo+bar"); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}") .build("New York", "foo+bar") ---- +====== The `WebClient` and the `RestTemplate` expand and encode URI templates internally through the `UriBuilderFactory` strategy. Both can be configured with a custom strategy, as the following example shows: +[tabs] +====== +Java:: ++ [source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ---- String baseUrl = "https://example.com"; DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl) @@ -293,8 +354,10 @@ as the following example shows: // Customize the WebClient.. WebClient client = WebClient.builder().uriBuilderFactory(factory).build(); ---- + +Kotlin:: ++ [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ---- val baseUrl = "https://example.com" val factory = DefaultUriBuilderFactory(baseUrl).apply { @@ -309,6 +372,7 @@ as the following example shows: // Customize the WebClient.. val client = WebClient.builder().uriBuilderFactory(factory).build() ---- +====== The `DefaultUriBuilderFactory` implementation uses `UriComponentsBuilder` internally to expand and encode URI templates. As a factory, it provides a single place to configure From 5abc829ed696c5643a754e57bf9eb74718425730 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 3 May 2023 00:37:41 -0500 Subject: [PATCH 29/31] Use the shared antora playbook --- .github/workflows/deploy-docs.yml | 2 +- .gitignore | 2 ++ framework-docs/antora-playbook.yml | 35 ---------------------------- framework-docs/framework-docs.gradle | 16 ++++++------- 4 files changed, 11 insertions(+), 44 deletions(-) delete mode 100644 framework-docs/antora-playbook.yml diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 4b03c87d01af..f3e899c4fe0e 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -13,7 +13,7 @@ permissions: jobs: build: runs-on: ubuntu-latest - # if: github.repository_owner == 'spring-projects' + if: github.repository_owner == 'spring-projects' steps: - name: Checkout uses: actions/checkout@v3 diff --git a/.gitignore b/.gitignore index 696c333f41d5..211080d88ab0 100644 --- a/.gitignore +++ b/.gitignore @@ -50,3 +50,5 @@ atlassian-ide-plugin.xml # VS Code .vscode/ + +cached-antora-playbook.yml diff --git a/framework-docs/antora-playbook.yml b/framework-docs/antora-playbook.yml deleted file mode 100644 index 6e9e4308e612..000000000000 --- a/framework-docs/antora-playbook.yml +++ /dev/null @@ -1,35 +0,0 @@ -# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2 -# -# The purpose of this Antora playbook is to build the docs in the current branch. -antora: - extensions: - - '@antora/collector-extension' -site: - title: Spring Framework Reference - url: https://https://rwinch.github.io/spring-framework/ -content: - sources: - - url: ../. - branches: HEAD - start_path: framework-docs - worktrees: true -asciidoc: - attributes: - page-pagination: '' - hide-uri-scheme: '@' - tabs-sync-option: '@' - chomp: 'all' - extensions: - - '@asciidoctor/tabs' - - '@springio/asciidoctor-extensions' - - '@springio/asciidoctor-extensions/include-code-extension' - sourcemap: true -urls: - latest_version_segment: '' -runtime: - log: - failure_level: warn -ui: - bundle: - url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip - snapshot: true \ No newline at end of file diff --git a/framework-docs/framework-docs.gradle b/framework-docs/framework-docs.gradle index 59c29569a4ef..dcf2f7c22c4a 100644 --- a/framework-docs/framework-docs.gradle +++ b/framework-docs/framework-docs.gradle @@ -11,13 +11,13 @@ apply from: "${rootDir}/gradle/publications.gradle" antora { version = '3.2.0-alpha.2' - playbook = 'antora-playbook.yml' -// playbookProvider { -// repository = 'rwinch/spring-framework' -// branch = 'docs-build' -// path = 'lib/antora/templates/per-branch-antora-playbook.yml' -// checkLocalBranch = true -// } + playbook = 'cached-antora-playbook.yml' + playbookProvider { + repository = 'rwinch/spring-framework' + branch = 'docs-build' + path = 'lib/antora/templates/per-branch-antora-playbook.yml' + checkLocalBranch = true + } options = ['--clean', '--stacktrace'] environment = [ 'ALGOLIA_API_KEY': '82c7ead946afbac3cf98c32446154691', @@ -29,7 +29,7 @@ antora { '@antora/collector-extension': '1.0.0-alpha.3', '@asciidoctor/tabs': '1.0.0-beta.3', '@opendevise/antora-release-line-extension': '1.0.0-alpha.2', - '@springio/antora-extensions': '1.1.0', + '@springio/antora-extensions': '1.3.0', '@springio/asciidoctor-extensions': '1.0.0-alpha.9' ] } From de738e89476cd645ca1eb6889edf9215021b33a6 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 3 May 2023 01:11:28 -0500 Subject: [PATCH 30/31] Remove invalid deploy-docs.yml --- .../.github/workflows/deploy-docs.yml | 33 ------------------- 1 file changed, 33 deletions(-) delete mode 100644 framework-docs/.github/workflows/deploy-docs.yml diff --git a/framework-docs/.github/workflows/deploy-docs.yml b/framework-docs/.github/workflows/deploy-docs.yml deleted file mode 100644 index 1435fc2171d1..000000000000 --- a/framework-docs/.github/workflows/deploy-docs.yml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy Docs -on: - push: - branches-ignore: [ gh-pages ] - tags: '**' - repository_dispatch: - types: request-build-reference # legacy - #schedule: - #- cron: '0 10 * * *' # Once per day at 10am UTC - workflow_dispatch: -permissions: - actions: write -jobs: - build: - runs-on: ubuntu-latest - # FIXME enable when pushed to spring-projects - # if: github.repository_owner == 'spring-projects' - steps: - - name: Checkout - uses: actions/checkout@v3 - with: - ref: docs-build - fetch-depth: 1 - - name: Dispatch (partial build) - if: github.ref_type == 'branch' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} - - name: Dispatch (full build) - if: github.ref_type == 'tag' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) From 5e43a7a7ca36ff63d744a35b156e816370d12284 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Thu, 4 May 2023 09:13:22 -0500 Subject: [PATCH 31/31] Fix Web Reactive link on the landing page --- framework-docs/modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework-docs/modules/ROOT/pages/index.adoc b/framework-docs/modules/ROOT/pages/index.adoc index 67998e243bbf..fbaa99ff04f3 100644 --- a/framework-docs/modules/ROOT/pages/index.adoc +++ b/framework-docs/modules/ROOT/pages/index.adoc @@ -13,7 +13,7 @@ xref:data-access.adoc[Data Access] :: Transactions, DAO Support, JDBC, R2DBC, O/R Mapping, XML Marshalling. xref:web.adoc[Web Servlet] :: Spring MVC, WebSocket, SockJS, STOMP Messaging. -xref:testing/unit.adoc#mock-objects-web-reactive[Web Reactive] :: Spring WebFlux, WebClient, +xref:web-reactive.adoc[Web Reactive] :: Spring WebFlux, WebClient, WebSocket, RSocket. xref:integration.adoc[Integration] :: REST Clients, JMS, JCA, JMX, Email, Tasks, Scheduling, Caching, Observability.

    Defaults to {@link ScopedProxyMode#TARGET_CLASS}. - */ - @AliasFor(annotation = Scope.class) - ScopedProxyMode proxyMode() default ScopedProxyMode.TARGET_CLASS; - - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION) - @Retention(AnnotationRetention.RUNTIME) - @MustBeDocumented - @Scope(WebApplicationContext.SCOPE_SESSION) - annotation class SessionScope( - @get:AliasFor(annotation = Scope::class) - val proxyMode: ScopedProxyMode = ScopedProxyMode.TARGET_CLASS - ) ----- - -You can then use `@SessionScope` without declaring the `proxyMode` as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Service - @SessionScope - public class SessionScopedService { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Service - @SessionScope - class SessionScopedService { - // ... - } ----- - -You can also override the value for the `proxyMode`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Service - @SessionScope(proxyMode = ScopedProxyMode.INTERFACES) - public class SessionScopedUserService implements UserService { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Service - @SessionScope(proxyMode = ScopedProxyMode.INTERFACES) - class SessionScopedUserService : UserService { - // ... - } ----- - -For further details, see the -https://github.com/spring-projects/spring-framework/wiki/Spring-Annotation-Programming-Model[Spring Annotation Programming Model] -wiki page. - - - -[[beans-scanning-autodetection]] -=== Automatically Detecting Classes and Registering Bean Definitions - -Spring can automatically detect stereotyped classes and register corresponding -`BeanDefinition` instances with the `ApplicationContext`. For example, the following two classes -are eligible for such autodetection: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Service - public class SimpleMovieLister { - - private MovieFinder movieFinder; - - public SimpleMovieLister(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Service - class SimpleMovieLister(private val movieFinder: MovieFinder) ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Repository - public class JpaMovieFinder implements MovieFinder { - // implementation elided for clarity - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Repository - class JpaMovieFinder : MovieFinder { - // implementation elided for clarity - } ----- - - -To autodetect these classes and register the corresponding beans, you need to add -`@ComponentScan` to your `@Configuration` class, where the `basePackages` attribute -is a common parent package for the two classes. (Alternatively, you can specify a -comma- or semicolon- or space-separated list that includes the parent package of each class.) - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ComponentScan(basePackages = "org.example") - public class AppConfig { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ComponentScan(basePackages = ["org.example"]) - class AppConfig { - // ... - } ----- - -NOTE: For brevity, the preceding example could have used the `value` attribute of the -annotation (that is, `@ComponentScan("org.example")`). - -The following alternative uses XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -TIP: The use of `` implicitly enables the functionality of -``. There is usually no need to include the -`` element when using ``. - -[NOTE] -==== -The scanning of classpath packages requires the presence of corresponding directory -entries in the classpath. When you build JARs with Ant, make sure that you do not -activate the files-only switch of the JAR task. Also, classpath directories may not be -exposed based on security policies in some environments -- for example, standalone apps on -JDK 1.7.0_45 and higher (which requires 'Trusted-Library' setup in your manifests -- see -https://stackoverflow.com/questions/19394570/java-jre-7u45-breaks-classloader-getresources). - -On JDK 9's module path (Jigsaw), Spring's classpath scanning generally works as expected. -However, make sure that your component classes are exported in your `module-info` -descriptors. If you expect Spring to invoke non-public members of your classes, make -sure that they are 'opened' (that is, that they use an `opens` declaration instead of an -`exports` declaration in your `module-info` descriptor). -==== - -Furthermore, the `AutowiredAnnotationBeanPostProcessor` and -`CommonAnnotationBeanPostProcessor` are both implicitly included when you use the -component-scan element. That means that the two components are autodetected and -wired together -- all without any bean configuration metadata provided in XML. - -NOTE: You can disable the registration of `AutowiredAnnotationBeanPostProcessor` and -`CommonAnnotationBeanPostProcessor` by including the `annotation-config` attribute -with a value of `false`. - - - -[[beans-scanning-filters]] -=== Using Filters to Customize Scanning - -By default, classes annotated with `@Component`, `@Repository`, `@Service`, `@Controller`, -`@Configuration`, or a custom annotation that itself is annotated with `@Component` are -the only detected candidate components. However, you can modify and extend this behavior -by applying custom filters. Add them as `includeFilters` or `excludeFilters` attributes of -the `@ComponentScan` annotation (or as `` or -`` child elements of the `` element in -XML configuration). Each filter element requires the `type` and `expression` attributes. -The following table describes the filtering options: - -[[beans-scanning-filters-tbl]] -.Filter Types -|=== -| Filter Type| Example Expression| Description - -| annotation (default) -| `org.example.SomeAnnotation` -| An annotation to be _present_ or _meta-present_ at the type level in target components. - -| assignable -| `org.example.SomeClass` -| A class (or interface) that the target components are assignable to (extend or implement). - -| aspectj -| `org.example..*Service+` -| An AspectJ type expression to be matched by the target components. - -| regex -| `org\.example\.Default.*` -| A regex expression to be matched by the target components' class names. - -| custom -| `org.example.MyTypeFilter` -| A custom implementation of the `org.springframework.core.type.TypeFilter` interface. -|=== - -The following example shows the configuration ignoring all `@Repository` annotations -and using "`stub`" repositories instead: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ComponentScan(basePackages = "org.example", - includeFilters = @Filter(type = FilterType.REGEX, pattern = ".*Stub.*Repository"), - excludeFilters = @Filter(Repository.class)) - public class AppConfig { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ComponentScan(basePackages = ["org.example"], - includeFilters = [Filter(type = FilterType.REGEX, pattern = [".*Stub.*Repository"])], - excludeFilters = [Filter(Repository::class)]) - class AppConfig { - // ... - } ----- - -The following listing shows the equivalent XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - ----- - -NOTE: You can also disable the default filters by setting `useDefaultFilters=false` on the -annotation or by providing `use-default-filters="false"` as an attribute of the -`` element. This effectively disables automatic detection of classes -annotated or meta-annotated with `@Component`, `@Repository`, `@Service`, `@Controller`, -`@RestController`, or `@Configuration`. - - - -[[beans-factorybeans-annotations]] -=== Defining Bean Metadata within Components - -Spring components can also contribute bean definition metadata to the container. You can do -this with the same `@Bean` annotation used to define bean metadata within `@Configuration` -annotated classes. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - public class FactoryMethodComponent { - - @Bean - @Qualifier("public") - public TestBean publicInstance() { - return new TestBean("publicInstance"); - } - - public void doWork() { - // Component method implementation omitted - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - class FactoryMethodComponent { - - @Bean - @Qualifier("public") - fun publicInstance() = TestBean("publicInstance") - - fun doWork() { - // Component method implementation omitted - } - } ----- - -The preceding class is a Spring component that has application-specific code in its -`doWork()` method. However, it also contributes a bean definition that has a factory -method referring to the method `publicInstance()`. The `@Bean` annotation identifies the -factory method and other bean definition properties, such as a qualifier value through -the `@Qualifier` annotation. Other method-level annotations that can be specified are -`@Scope`, `@Lazy`, and custom qualifier annotations. - -TIP: In addition to its role for component initialization, you can also place the `@Lazy` -annotation on injection points marked with `@Autowired` or `@Inject`. In this context, -it leads to the injection of a lazy-resolution proxy. However, such a proxy approach -is rather limited. For sophisticated lazy interactions, in particular in combination -with optional dependencies, we recommend `ObjectProvider` instead. - -Autowired fields and methods are supported, as previously discussed, with additional -support for autowiring of `@Bean` methods. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - public class FactoryMethodComponent { - - private static int i; - - @Bean - @Qualifier("public") - public TestBean publicInstance() { - return new TestBean("publicInstance"); - } - - // use of a custom qualifier and autowiring of method parameters - @Bean - protected TestBean protectedInstance( - @Qualifier("public") TestBean spouse, - @Value("#{privateInstance.age}") String country) { - TestBean tb = new TestBean("protectedInstance", 1); - tb.setSpouse(spouse); - tb.setCountry(country); - return tb; - } - - @Bean - private TestBean privateInstance() { - return new TestBean("privateInstance", i++); - } - - @Bean - @RequestScope - public TestBean requestScopedInstance() { - return new TestBean("requestScopedInstance", 3); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - class FactoryMethodComponent { - - companion object { - private var i: Int = 0 - } - - @Bean - @Qualifier("public") - fun publicInstance() = TestBean("publicInstance") - - // use of a custom qualifier and autowiring of method parameters - @Bean - protected fun protectedInstance( - @Qualifier("public") spouse: TestBean, - @Value("#{privateInstance.age}") country: String) = TestBean("protectedInstance", 1).apply { - this.spouse = spouse - this.country = country - } - - @Bean - private fun privateInstance() = TestBean("privateInstance", i++) - - @Bean - @RequestScope - fun requestScopedInstance() = TestBean("requestScopedInstance", 3) - } ----- - -The example autowires the `String` method parameter `country` to the value of the `age` -property on another bean named `privateInstance`. A Spring Expression Language element -defines the value of the property through the notation `#{ }`. For `@Value` -annotations, an expression resolver is preconfigured to look for bean names when -resolving expression text. - -As of Spring Framework 4.3, you may also declare a factory method parameter of type -`InjectionPoint` (or its more specific subclass: `DependencyDescriptor`) to -access the requesting injection point that triggers the creation of the current bean. -Note that this applies only to the actual creation of bean instances, not to the -injection of existing instances. As a consequence, this feature makes most sense for -beans of prototype scope. For other scopes, the factory method only ever sees the -injection point that triggered the creation of a new bean instance in the given scope -(for example, the dependency that triggered the creation of a lazy singleton bean). -You can use the provided injection point metadata with semantic care in such scenarios. -The following example shows how to use `InjectionPoint`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - public class FactoryMethodComponent { - - @Bean @Scope("prototype") - public TestBean prototypeInstance(InjectionPoint injectionPoint) { - return new TestBean("prototypeInstance for " + injectionPoint.getMember()); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - class FactoryMethodComponent { - - @Bean - @Scope("prototype") - fun prototypeInstance(injectionPoint: InjectionPoint) = - TestBean("prototypeInstance for ${injectionPoint.member}") - } ----- - -The `@Bean` methods in a regular Spring component are processed differently than their -counterparts inside a Spring `@Configuration` class. The difference is that `@Component` -classes are not enhanced with CGLIB to intercept the invocation of methods and fields. -CGLIB proxying is the means by which invoking methods or fields within `@Bean` methods -in `@Configuration` classes creates bean metadata references to collaborating objects. -Such methods are not invoked with normal Java semantics but rather go through the -container in order to provide the usual lifecycle management and proxying of Spring -beans, even when referring to other beans through programmatic calls to `@Bean` methods. -In contrast, invoking a method or field in a `@Bean` method within a plain `@Component` -class has standard Java semantics, with no special CGLIB processing or other -constraints applying. - -[NOTE] -==== -You may declare `@Bean` methods as `static`, allowing for them to be called without -creating their containing configuration class as an instance. This makes particular -sense when defining post-processor beans (for example, of type `BeanFactoryPostProcessor` -or `BeanPostProcessor`), since such beans get initialized early in the container -lifecycle and should avoid triggering other parts of the configuration at that point. - -Calls to static `@Bean` methods never get intercepted by the container, not even within -`@Configuration` classes (as described earlier in this section), due to technical -limitations: CGLIB subclassing can override only non-static methods. As a consequence, -a direct call to another `@Bean` method has standard Java semantics, resulting -in an independent instance being returned straight from the factory method itself. - -The Java language visibility of `@Bean` methods does not have an immediate impact on -the resulting bean definition in Spring's container. You can freely declare your -factory methods as you see fit in non-`@Configuration` classes and also for static -methods anywhere. However, regular `@Bean` methods in `@Configuration` classes need -to be overridable -- that is, they must not be declared as `private` or `final`. - -`@Bean` methods are also discovered on base classes of a given component or -configuration class, as well as on Java 8 default methods declared in interfaces -implemented by the component or configuration class. This allows for a lot of -flexibility in composing complex configuration arrangements, with even multiple -inheritance being possible through Java 8 default methods as of Spring 4.2. - -Finally, a single class may hold multiple `@Bean` methods for the same -bean, as an arrangement of multiple factory methods to use depending on available -dependencies at runtime. This is the same algorithm as for choosing the "`greediest`" -constructor or factory method in other configuration scenarios: The variant with -the largest number of satisfiable dependencies is picked at construction time, -analogous to how the container selects between multiple `@Autowired` constructors. -==== - - - -[[beans-scanning-name-generator]] -=== Naming Autodetected Components - -When a component is autodetected as part of the scanning process, its bean name is -generated by the `BeanNameGenerator` strategy known to that scanner. By default, any -Spring stereotype annotation (`@Component`, `@Repository`, `@Service`, and -`@Controller`) that contains a name `value` thereby provides that name to the -corresponding bean definition. - -If such an annotation contains no name `value` or for any other detected component -(such as those discovered by custom filters), the default bean name generator returns -the uncapitalized non-qualified class name. For example, if the following component -classes were detected, the names would be `myMovieLister` and `movieFinderImpl`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Service("myMovieLister") - public class SimpleMovieLister { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Service("myMovieLister") - class SimpleMovieLister { - // ... - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Repository - public class MovieFinderImpl implements MovieFinder { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Repository - class MovieFinderImpl : MovieFinder { - // ... - } ----- - -If you do not want to rely on the default bean-naming strategy, you can provide a custom -bean-naming strategy. First, implement the -{api-spring-framework}/beans/factory/support/BeanNameGenerator.html[`BeanNameGenerator`] -interface, and be sure to include a default no-arg constructor. Then, provide the fully -qualified class name when configuring the scanner, as the following example annotation -and bean definition show. - -TIP: If you run into naming conflicts due to multiple autodetected components having the -same non-qualified class name (i.e., classes with identical names but residing in -different packages), you may need to configure a `BeanNameGenerator` that defaults to the -fully qualified class name for the generated bean name. As of Spring Framework 5.2.3, the -`FullyQualifiedAnnotationBeanNameGenerator` located in package -`org.springframework.context.annotation` can be used for such purposes. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ComponentScan(basePackages = "org.example", nameGenerator = MyNameGenerator.class) - public class AppConfig { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ComponentScan(basePackages = ["org.example"], nameGenerator = MyNameGenerator::class) - class AppConfig { - // ... - } ----- - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -As a general rule, consider specifying the name with the annotation whenever other -components may be making explicit references to it. On the other hand, the -auto-generated names are adequate whenever the container is responsible for wiring. - - - -[[beans-scanning-scope-resolver]] -=== Providing a Scope for Autodetected Components - -As with Spring-managed components in general, the default and most common scope for -autodetected components is `singleton`. However, sometimes you need a different scope -that can be specified by the `@Scope` annotation. You can provide the name of the -scope within the annotation, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Scope("prototype") - @Repository - public class MovieFinderImpl implements MovieFinder { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Scope("prototype") - @Repository - class MovieFinderImpl : MovieFinder { - // ... - } ----- - -NOTE: `@Scope` annotations are only introspected on the concrete bean class (for annotated -components) or the factory method (for `@Bean` methods). In contrast to XML bean -definitions, there is no notion of bean definition inheritance, and inheritance -hierarchies at the class level are irrelevant for metadata purposes. - -For details on web-specific scopes such as "`request`" or "`session`" in a Spring context, -see <>. As with the pre-built annotations for those scopes, -you may also compose your own scoping annotations by using Spring's meta-annotation -approach: for example, a custom annotation meta-annotated with `@Scope("prototype")`, -possibly also declaring a custom scoped-proxy mode. - -NOTE: To provide a custom strategy for scope resolution rather than relying on the -annotation-based approach, you can implement the -{api-spring-framework}/context/annotation/ScopeMetadataResolver.html[`ScopeMetadataResolver`] -interface. Be sure to include a default no-arg constructor. Then you can provide the -fully qualified class name when configuring the scanner, as the following example of both -an annotation and a bean definition shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ComponentScan(basePackages = "org.example", scopeResolver = MyScopeResolver.class) - public class AppConfig { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ComponentScan(basePackages = ["org.example"], scopeResolver = MyScopeResolver::class) - class AppConfig { - // ... - } ----- - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -When using certain non-singleton scopes, it may be necessary to generate proxies for the -scoped objects. The reasoning is described in <>. -For this purpose, a scoped-proxy attribute is available on the component-scan -element. The three possible values are: `no`, `interfaces`, and `targetClass`. For example, -the following configuration results in standard JDK dynamic proxies: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ComponentScan(basePackages = "org.example", scopedProxy = ScopedProxyMode.INTERFACES) - public class AppConfig { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ComponentScan(basePackages = ["org.example"], scopedProxy = ScopedProxyMode.INTERFACES) - class AppConfig { - // ... - } ----- - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - - - -[[beans-scanning-qualifiers]] -=== Providing Qualifier Metadata with Annotations - -The `@Qualifier` annotation is discussed in <>. -The examples in that section demonstrate the use of the `@Qualifier` annotation and -custom qualifier annotations to provide fine-grained control when you resolve autowire -candidates. Because those examples were based on XML bean definitions, the qualifier -metadata was provided on the candidate bean definitions by using the `qualifier` or `meta` -child elements of the `bean` element in the XML. When relying upon classpath scanning for -auto-detection of components, you can provide the qualifier metadata with type-level -annotations on the candidate class. The following three examples demonstrate this -technique: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - @Qualifier("Action") - public class ActionMovieCatalog implements MovieCatalog { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - @Qualifier("Action") - class ActionMovieCatalog : MovieCatalog ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - @Genre("Action") - public class ActionMovieCatalog implements MovieCatalog { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Component - @Genre("Action") - class ActionMovieCatalog : MovieCatalog { - // ... - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Component - @Offline - public class CachingMovieCatalog implements MovieCatalog { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -@Component -@Offline -class CachingMovieCatalog : MovieCatalog { - // ... -} ----- - -NOTE: As with most annotation-based alternatives, keep in mind that the annotation metadata is -bound to the class definition itself, while the use of XML allows for multiple beans -of the same type to provide variations in their qualifier metadata, because that -metadata is provided per-instance rather than per-class. - - - -[[beans-scanning-index]] -=== Generating an Index of Candidate Components - -While classpath scanning is very fast, it is possible to improve the startup performance -of large applications by creating a static list of candidates at compilation time. In this -mode, all modules that are targets of component scanning must use this mechanism. - -NOTE: Your existing `@ComponentScan` or `` directives must remain -unchanged to request the context to scan candidates in certain packages. When the -`ApplicationContext` detects such an index, it automatically uses it rather than scanning -the classpath. - -To generate the index, add an additional dependency to each module that contains -components that are targets for component scan directives. The following example shows -how to do so with Maven: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - org.springframework - spring-context-indexer - {spring-version} - true - - ----- - -With Gradle 4.5 and earlier, the dependency should be declared in the `compileOnly` -configuration, as shown in the following example: - -[source,groovy,indent=0,subs="verbatim,quotes,attributes"] ----- - dependencies { - compileOnly "org.springframework:spring-context-indexer:{spring-version}" - } ----- - -With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` -configuration, as shown in the following example: - -[source,groovy,indent=0,subs="verbatim,quotes,attributes"] ----- - dependencies { - annotationProcessor "org.springframework:spring-context-indexer:{spring-version}" - } ----- - -The `spring-context-indexer` artifact generates a `META-INF/spring.components` file that -is included in the jar file. - -NOTE: When working with this mode in your IDE, the `spring-context-indexer` must be -registered as an annotation processor to make sure the index is up-to-date when -candidate components are updated. - -TIP: The index is enabled automatically when a `META-INF/spring.components` file is found -on the classpath. If an index is partially available for some libraries (or use cases) -but could not be built for the whole application, you can fall back to a regular classpath -arrangement (as though no index were present at all) by setting `spring.index.ignore` to -`true`, either as a JVM system property or via the -<> mechanism. - - - - -[[beans-standard-annotations]] -== Using JSR 330 Standard Annotations - -Spring offers support for JSR-330 standard annotations (Dependency Injection). Those -annotations are scanned in the same way as the Spring annotations. To use them, you need -to have the relevant jars in your classpath. - -[NOTE] -===== -If you use Maven, the `jakarta.inject` artifact is available in the standard Maven -repository ( -https://repo.maven.apache.org/maven2/jakarta/inject/jakarta.inject-api/2.0.0/[https://repo.maven.apache.org/maven2/jakarta/inject/jakarta.inject-api/2.0.0/]). -You can add the following dependency to your file pom.xml: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - jakarta.inject - jakarta.inject-api - 2.0.0 - ----- -===== - - - -[[beans-inject-named]] -=== Dependency Injection with `@Inject` and `@Named` - -Instead of `@Autowired`, you can use `@jakarta.inject.Inject` as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import jakarta.inject.Inject; - - public class SimpleMovieLister { - - private MovieFinder movieFinder; - - @Inject - public void setMovieFinder(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - - public void listMovies() { - this.movieFinder.findMovies(...); - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import jakarta.inject.Inject - - class SimpleMovieLister { - - @Inject - lateinit var movieFinder: MovieFinder - - - fun listMovies() { - movieFinder.findMovies(...) - // ... - } - } ----- - -As with `@Autowired`, you can use `@Inject` at the field level, method level -and constructor-argument level. Furthermore, you may declare your injection point as a -`Provider`, allowing for on-demand access to beans of shorter scopes or lazy access to -other beans through a `Provider.get()` call. The following example offers a variant of the -preceding example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import jakarta.inject.Inject; - import jakarta.inject.Provider; - - public class SimpleMovieLister { - - private Provider movieFinder; - - @Inject - public void setMovieFinder(Provider movieFinder) { - this.movieFinder = movieFinder; - } - - public void listMovies() { - this.movieFinder.get().findMovies(...); - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import jakarta.inject.Inject - - class SimpleMovieLister { - - @Inject - lateinit var movieFinder: Provider - - - fun listMovies() { - movieFinder.get().findMovies(...) - // ... - } - } ----- - -If you would like to use a qualified name for the dependency that should be injected, -you should use the `@Named` annotation, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import jakarta.inject.Inject; - import jakarta.inject.Named; - - public class SimpleMovieLister { - - private MovieFinder movieFinder; - - @Inject - public void setMovieFinder(@Named("main") MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import jakarta.inject.Inject - import jakarta.inject.Named - - class SimpleMovieLister { - - private lateinit var movieFinder: MovieFinder - - @Inject - fun setMovieFinder(@Named("main") movieFinder: MovieFinder) { - this.movieFinder = movieFinder - } - - // ... - } ----- - -As with `@Autowired`, `@Inject` can also be used with `java.util.Optional` or -`@Nullable`. This is even more applicable here, since `@Inject` does not have -a `required` attribute. The following pair of examples show how to use `@Inject` and -`@Nullable`: - -[source,java,indent=0,subs="verbatim,quotes"] ----- - public class SimpleMovieLister { - - @Inject - public void setMovieFinder(Optional movieFinder) { - // ... - } - } ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class SimpleMovieLister { - - @Inject - public void setMovieFinder(@Nullable MovieFinder movieFinder) { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class SimpleMovieLister { - - @Inject - var movieFinder: MovieFinder? = null - } ----- - - - -[[beans-named]] -=== `@Named` and `@ManagedBean`: Standard Equivalents to the `@Component` Annotation - -Instead of `@Component`, you can use `@jakarta.inject.Named` or `jakarta.annotation.ManagedBean`, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import jakarta.inject.Inject; - import jakarta.inject.Named; - - @Named("movieListener") // @ManagedBean("movieListener") could be used as well - public class SimpleMovieLister { - - private MovieFinder movieFinder; - - @Inject - public void setMovieFinder(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import jakarta.inject.Inject - import jakarta.inject.Named - - @Named("movieListener") // @ManagedBean("movieListener") could be used as well - class SimpleMovieLister { - - @Inject - lateinit var movieFinder: MovieFinder - - // ... - } ----- - -It is very common to use `@Component` without specifying a name for the component. -`@Named` can be used in a similar fashion, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - import jakarta.inject.Inject; - import jakarta.inject.Named; - - @Named - public class SimpleMovieLister { - - private MovieFinder movieFinder; - - @Inject - public void setMovieFinder(MovieFinder movieFinder) { - this.movieFinder = movieFinder; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import jakarta.inject.Inject - import jakarta.inject.Named - - @Named - class SimpleMovieLister { - - @Inject - lateinit var movieFinder: MovieFinder - - // ... - } ----- - -When you use `@Named` or `@ManagedBean`, you can use component scanning in the -exact same way as when you use Spring annotations, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ComponentScan(basePackages = "org.example") - public class AppConfig { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ComponentScan(basePackages = ["org.example"]) - class AppConfig { - // ... - } ----- - -NOTE: In contrast to `@Component`, the JSR-330 `@Named` and the JSR-250 `@ManagedBean` -annotations are not composable. You should use Spring's stereotype model for building -custom component annotations. - - - -[[beans-standard-annotations-limitations]] -=== Limitations of JSR-330 Standard Annotations - -When you work with standard annotations, you should know that some significant -features are not available, as the following table shows: - -[[annotations-comparison]] -.Spring component model elements versus JSR-330 variants -|=== -| Spring| jakarta.inject.*| jakarta.inject restrictions / comments - -| @Autowired -| @Inject -| `@Inject` has no 'required' attribute. Can be used with Java 8's `Optional` instead. - -| @Component -| @Named / @ManagedBean -| JSR-330 does not provide a composable model, only a way to identify named components. - -| @Scope("singleton") -| @Singleton -| The JSR-330 default scope is like Spring's `prototype`. However, in order to keep it - consistent with Spring's general defaults, a JSR-330 bean declared in the Spring - container is a `singleton` by default. In order to use a scope other than `singleton`, - you should use Spring's `@Scope` annotation. `jakarta.inject` also provides a - `jakarta.inject.Scope` annotation: however, this one is only intended to be used - for creating custom annotations. - -| @Qualifier -| @Qualifier / @Named -| `jakarta.inject.Qualifier` is just a meta-annotation for building custom qualifiers. - Concrete `String` qualifiers (like Spring's `@Qualifier` with a value) can be associated - through `jakarta.inject.Named`. - -| @Value -| - -| no equivalent - -| @Lazy -| - -| no equivalent - -| ObjectFactory -| Provider -| `jakarta.inject.Provider` is a direct alternative to Spring's `ObjectFactory`, - only with a shorter `get()` method name. It can also be used in combination with - Spring's `@Autowired` or with non-annotated constructors and setter methods. -|=== - - - -[[beans-java]] -== Java-based Container Configuration - -This section covers how to use annotations in your Java code to configure the Spring -container. It includes the following topics: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - - - -[[beans-java-basic-concepts]] -=== Basic Concepts: `@Bean` and `@Configuration` - -The central artifacts in Spring's Java configuration support are -`@Configuration`-annotated classes and `@Bean`-annotated methods. - -The `@Bean` annotation is used to indicate that a method instantiates, configures, and -initializes a new object to be managed by the Spring IoC container. For those familiar -with Spring's `` XML configuration, the `@Bean` annotation plays the same role as -the `` element. You can use `@Bean`-annotated methods with any Spring -`@Component`. However, they are most often used with `@Configuration` beans. - -Annotating a class with `@Configuration` indicates that its primary purpose is as a -source of bean definitions. Furthermore, `@Configuration` classes let inter-bean -dependencies be defined by calling other `@Bean` methods in the same class. -The simplest possible `@Configuration` class reads as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public MyServiceImpl myService() { - return new MyServiceImpl(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun myService(): MyServiceImpl { - return MyServiceImpl() - } - } ----- - -The preceding `AppConfig` class is equivalent to the following Spring `` XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -.Full @Configuration vs "`lite`" @Bean mode? -**** -When `@Bean` methods are declared within classes that are not annotated with -`@Configuration`, they are referred to as being processed in a "`lite`" mode. Bean methods -declared in a `@Component` or even in a plain old class are considered to be "`lite`", -with a different primary purpose of the containing class and a `@Bean` method -being a sort of bonus there. For example, service components may expose management views -to the container through an additional `@Bean` method on each applicable component class. -In such scenarios, `@Bean` methods are a general-purpose factory method mechanism. - -Unlike full `@Configuration`, lite `@Bean` methods cannot declare inter-bean dependencies. -Instead, they operate on their containing component's internal state and, optionally, on -arguments that they may declare. Such a `@Bean` method should therefore not invoke other -`@Bean` methods. Each such method is literally only a factory method for a particular -bean reference, without any special runtime semantics. The positive side-effect here is -that no CGLIB subclassing has to be applied at runtime, so there are no limitations in -terms of class design (that is, the containing class may be `final` and so forth). - -In common scenarios, `@Bean` methods are to be declared within `@Configuration` classes, -ensuring that "`full`" mode is always used and that cross-method references therefore -get redirected to the container's lifecycle management. This prevents the same -`@Bean` method from accidentally being invoked through a regular Java call, which helps -to reduce subtle bugs that can be hard to track down when operating in "`lite`" mode. -**** - -The `@Bean` and `@Configuration` annotations are discussed in depth in the following sections. -First, however, we cover the various ways of creating a spring container by using -Java-based configuration. - - - -[[beans-java-instantiating-container]] -=== Instantiating the Spring Container by Using `AnnotationConfigApplicationContext` - -The following sections document Spring's `AnnotationConfigApplicationContext`, introduced in Spring -3.0. This versatile `ApplicationContext` implementation is capable of accepting not only -`@Configuration` classes as input but also plain `@Component` classes and classes -annotated with JSR-330 metadata. - -When `@Configuration` classes are provided as input, the `@Configuration` class itself -is registered as a bean definition and all declared `@Bean` methods within the class -are also registered as bean definitions. - -When `@Component` and JSR-330 classes are provided, they are registered as bean -definitions, and it is assumed that DI metadata such as `@Autowired` or `@Inject` are -used within those classes where necessary. - - -[[beans-java-instantiating-container-constructor]] -==== Simple Construction - -In much the same way that Spring XML files are used as input when instantiating a -`ClassPathXmlApplicationContext`, you can use `@Configuration` classes as input when -instantiating an `AnnotationConfigApplicationContext`. This allows for completely -XML-free usage of the Spring container, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static void main(String[] args) { - ApplicationContext ctx = new AnnotationConfigApplicationContext(AppConfig.class); - MyService myService = ctx.getBean(MyService.class); - myService.doStuff(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - fun main() { - val ctx = AnnotationConfigApplicationContext(AppConfig::class.java) - val myService = ctx.getBean() - myService.doStuff() - } ----- - -As mentioned earlier, `AnnotationConfigApplicationContext` is not limited to working only -with `@Configuration` classes. Any `@Component` or JSR-330 annotated class may be supplied -as input to the constructor, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static void main(String[] args) { - ApplicationContext ctx = new AnnotationConfigApplicationContext(MyServiceImpl.class, Dependency1.class, Dependency2.class); - MyService myService = ctx.getBean(MyService.class); - myService.doStuff(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - fun main() { - val ctx = AnnotationConfigApplicationContext(MyServiceImpl::class.java, Dependency1::class.java, Dependency2::class.java) - val myService = ctx.getBean() - myService.doStuff() - } ----- - -The preceding example assumes that `MyServiceImpl`, `Dependency1`, and `Dependency2` use Spring -dependency injection annotations such as `@Autowired`. - - -[[beans-java-instantiating-container-register]] -==== Building the Container Programmatically by Using `register(Class...)` - -You can instantiate an `AnnotationConfigApplicationContext` by using a no-arg constructor -and then configure it by using the `register()` method. This approach is particularly useful -when programmatically building an `AnnotationConfigApplicationContext`. The following -example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static void main(String[] args) { - AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); - ctx.register(AppConfig.class, OtherConfig.class); - ctx.register(AdditionalConfig.class); - ctx.refresh(); - MyService myService = ctx.getBean(MyService.class); - myService.doStuff(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - fun main() { - val ctx = AnnotationConfigApplicationContext() - ctx.register(AppConfig::class.java, OtherConfig::class.java) - ctx.register(AdditionalConfig::class.java) - ctx.refresh() - val myService = ctx.getBean() - myService.doStuff() - } ----- - - -[[beans-java-instantiating-container-scan]] -==== Enabling Component Scanning with `scan(String...)` - -To enable component scanning, you can annotate your `@Configuration` class as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ComponentScan(basePackages = "com.acme") // <1> - public class AppConfig { - // ... - } ----- -<1> This annotation enables component scanning. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ComponentScan(basePackages = ["com.acme"]) // <1> - class AppConfig { - // ... - } ----- -<1> This annotation enables component scanning. - - -[TIP] -===== -Experienced Spring users may be familiar with the XML declaration equivalent from -Spring's `context:` namespace, shown in the following example: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- -===== - -In the preceding example, the `com.acme` package is scanned to look for any -`@Component`-annotated classes, and those classes are registered as Spring bean -definitions within the container. `AnnotationConfigApplicationContext` exposes the -`scan(String...)` method to allow for the same component-scanning functionality, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static void main(String[] args) { - AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); - ctx.scan("com.acme"); - ctx.refresh(); - MyService myService = ctx.getBean(MyService.class); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun main() { - val ctx = AnnotationConfigApplicationContext() - ctx.scan("com.acme") - ctx.refresh() - val myService = ctx.getBean() - } ----- - -NOTE: Remember that `@Configuration` classes are <> -with `@Component`, so they are candidates for component-scanning. In the preceding example, -assuming that `AppConfig` is declared within the `com.acme` package (or any package -underneath), it is picked up during the call to `scan()`. Upon `refresh()`, all its `@Bean` -methods are processed and registered as bean definitions within the container. - - -[[beans-java-instantiating-container-web]] -==== Support for Web Applications with `AnnotationConfigWebApplicationContext` - -A `WebApplicationContext` variant of `AnnotationConfigApplicationContext` is available -with `AnnotationConfigWebApplicationContext`. You can use this implementation when -configuring the Spring `ContextLoaderListener` servlet listener, Spring MVC -`DispatcherServlet`, and so forth. The following `web.xml` snippet configures a typical -Spring MVC web application (note the use of the `contextClass` context-param and -init-param): - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - contextClass - - org.springframework.web.context.support.AnnotationConfigWebApplicationContext - - - - - - contextConfigLocation - com.acme.AppConfig - - - - - org.springframework.web.context.ContextLoaderListener - - - - - dispatcher - org.springframework.web.servlet.DispatcherServlet - - - contextClass - - org.springframework.web.context.support.AnnotationConfigWebApplicationContext - - - - - contextConfigLocation - com.acme.web.MvcConfig - - - - - - dispatcher - /app/* - - ----- - -NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an -alternative to `AnnotationConfigWebApplicationContext`. See the -{api-spring-framework}/web/context/support/GenericWebApplicationContext.html[`GenericWebApplicationContext`] -javadoc for details. - - -[[beans-java-bean-annotation]] -=== Using the `@Bean` Annotation - -`@Bean` is a method-level annotation and a direct analog of the XML `` element. -The annotation supports some of the attributes offered by ``, such as: - -* <> -* <> -* <> -* `name`. - -You can use the `@Bean` annotation in a `@Configuration`-annotated or in a -`@Component`-annotated class. - - -[[beans-java-declaring-a-bean]] -==== Declaring a Bean - -To declare a bean, you can annotate a method with the `@Bean` annotation. You use this -method to register a bean definition within an `ApplicationContext` of the type -specified as the method's return value. By default, the bean name is the same as -the method name. The following example shows a `@Bean` method declaration: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public TransferServiceImpl transferService() { - return new TransferServiceImpl(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun transferService() = TransferServiceImpl() - } ----- - -The preceding configuration is exactly equivalent to the following Spring XML: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -Both declarations make a bean named `transferService` available in the -`ApplicationContext`, bound to an object instance of type `TransferServiceImpl`, as the -following text image shows: - -[literal,subs="verbatim,quotes"] ----- -transferService -> com.acme.TransferServiceImpl ----- - -You can also use default methods to define beans. This allows composition of bean -configurations by implementing interfaces with bean definitions on default methods. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public interface BaseConfig { - - @Bean - default TransferServiceImpl transferService() { - return new TransferServiceImpl(); - } - } - - @Configuration - public class AppConfig implements BaseConfig { - - } ----- - -You can also declare your `@Bean` method with an interface (or base class) -return type, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public TransferService transferService() { - return new TransferServiceImpl(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun transferService(): TransferService { - return TransferServiceImpl() - } - } ----- - -However, this limits the visibility for advance type prediction to the specified -interface type (`TransferService`). Then, with the full type (`TransferServiceImpl`) -known to the container only once the affected singleton bean has been instantiated. -Non-lazy singleton beans get instantiated according to their declaration order, -so you may see different type matching results depending on when another component -tries to match by a non-declared type (such as `@Autowired TransferServiceImpl`, -which resolves only once the `transferService` bean has been instantiated). - -TIP: If you consistently refer to your types by a declared service interface, your -`@Bean` return types may safely join that design decision. However, for components -that implement several interfaces or for components potentially referred to by their -implementation type, it is safer to declare the most specific return type possible -(at least as specific as required by the injection points that refer to your bean). - - -[[beans-java-dependencies]] -==== Bean Dependencies - -A `@Bean`-annotated method can have an arbitrary number of parameters that describe the -dependencies required to build that bean. For instance, if our `TransferService` -requires an `AccountRepository`, we can materialize that dependency with a method -parameter, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public TransferService transferService(AccountRepository accountRepository) { - return new TransferServiceImpl(accountRepository); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun transferService(accountRepository: AccountRepository): TransferService { - return TransferServiceImpl(accountRepository) - } - } ----- - - -The resolution mechanism is pretty much identical to constructor-based dependency -injection. See <> for more details. - - -[[beans-java-lifecycle-callbacks]] -==== Receiving Lifecycle Callbacks - -Any classes defined with the `@Bean` annotation support the regular lifecycle callbacks -and can use the `@PostConstruct` and `@PreDestroy` annotations from JSR-250. See -<> for further -details. - -The regular Spring <> callbacks are fully supported as -well. If a bean implements `InitializingBean`, `DisposableBean`, or `Lifecycle`, their -respective methods are called by the container. - -The standard set of `*Aware` interfaces (such as <>, -<>, -<>, -<>, and so on) are also fully supported. - -The `@Bean` annotation supports specifying arbitrary initialization and destruction -callback methods, much like Spring XML's `init-method` and `destroy-method` attributes -on the `bean` element, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class BeanOne { - - public void init() { - // initialization logic - } - } - - public class BeanTwo { - - public void cleanup() { - // destruction logic - } - } - - @Configuration - public class AppConfig { - - @Bean(initMethod = "init") - public BeanOne beanOne() { - return new BeanOne(); - } - - @Bean(destroyMethod = "cleanup") - public BeanTwo beanTwo() { - return new BeanTwo(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -class BeanOne { - - fun init() { - // initialization logic - } -} - -class BeanTwo { - - fun cleanup() { - // destruction logic - } -} - -@Configuration -class AppConfig { - - @Bean(initMethod = "init") - fun beanOne() = BeanOne() - - @Bean(destroyMethod = "cleanup") - fun beanTwo() = BeanTwo() -} ----- - -[NOTE] -===== -By default, beans defined with Java configuration that have a public `close` or `shutdown` -method are automatically enlisted with a destruction callback. If you have a public -`close` or `shutdown` method and you do not wish for it to be called when the container -shuts down, you can add `@Bean(destroyMethod = "")` to your bean definition to disable the -default `(inferred)` mode. - -You may want to do that by default for a resource that you acquire with JNDI, as its -lifecycle is managed outside the application. In particular, make sure to always do it -for a `DataSource`, as it is known to be problematic on Jakarta EE application servers. - -The following example shows how to prevent an automatic destruction callback for a -`DataSource`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Bean(destroyMethod = "") - public DataSource dataSource() throws NamingException { - return (DataSource) jndiTemplate.lookup("MyDS"); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Bean(destroyMethod = "") - fun dataSource(): DataSource { - return jndiTemplate.lookup("MyDS") as DataSource - } ----- - -Also, with `@Bean` methods, you typically use programmatic JNDI lookups, either by -using Spring's `JndiTemplate` or `JndiLocatorDelegate` helpers or straight JNDI -`InitialContext` usage but not the `JndiObjectFactoryBean` variant (which would force -you to declare the return type as the `FactoryBean` type instead of the actual target -type, making it harder to use for cross-reference calls in other `@Bean` methods that -intend to refer to the provided resource here). -===== - -In the case of `BeanOne` from the example above the preceding note, it would be equally valid to call the `init()` -method directly during construction, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public BeanOne beanOne() { - BeanOne beanOne = new BeanOne(); - beanOne.init(); - return beanOne; - } - - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun beanOne() = BeanOne().apply { - init() - } - - // ... - } ----- - -TIP: When you work directly in Java, you can do anything you like with your objects and do -not always need to rely on the container lifecycle. - - -[[beans-java-specifying-bean-scope]] -==== Specifying Bean Scope - -Spring includes the `@Scope` annotation so that you can specify the scope of a bean. - -[[beans-java-available-scopes]] -===== Using the `@Scope` Annotation - -You can specify that your beans defined with the `@Bean` annotation should have a -specific scope. You can use any of the standard scopes specified in the -<> section. - -The default scope is `singleton`, but you can override this with the `@Scope` annotation, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class MyConfiguration { - - @Bean - @Scope("prototype") - public Encryptor encryptor() { - // ... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class MyConfiguration { - - @Bean - @Scope("prototype") - fun encryptor(): Encryptor { - // ... - } - } ----- - -[[beans-java-scoped-proxy]] -===== `@Scope` and `scoped-proxy` - -Spring offers a convenient way of working with scoped dependencies through -<>. The easiest way to create -such a proxy when using the XML configuration is the `` element. -Configuring your beans in Java with a `@Scope` annotation offers equivalent support -with the `proxyMode` attribute. The default is `ScopedProxyMode.DEFAULT`, which -typically indicates that no scoped proxy should be created unless a different default -has been configured at the component-scan instruction level. You can specify -`ScopedProxyMode.TARGET_CLASS`, `ScopedProxyMode.INTERFACES` or `ScopedProxyMode.NO`. - -If you port the scoped proxy example from the XML reference documentation (see -<>) to our `@Bean` using Java, -it resembles the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // an HTTP Session-scoped bean exposed as a proxy - @Bean - @SessionScope - public UserPreferences userPreferences() { - return new UserPreferences(); - } - - @Bean - public Service userService() { - UserService service = new SimpleUserService(); - // a reference to the proxied userPreferences bean - service.setUserPreferences(userPreferences()); - return service; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // an HTTP Session-scoped bean exposed as a proxy - @Bean - @SessionScope - fun userPreferences() = UserPreferences() - - @Bean - fun userService(): Service { - return SimpleUserService().apply { - // a reference to the proxied userPreferences bean - setUserPreferences(userPreferences()) - } - } ----- - -[[beans-java-customizing-bean-naming]] -==== Customizing Bean Naming - -By default, configuration classes use a `@Bean` method's name as the name of the -resulting bean. This functionality can be overridden, however, with the `name` attribute, -as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean("myThing") - public Thing thing() { - return new Thing(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean("myThing") - fun thing() = Thing() - } ----- - - -[[beans-java-bean-aliasing]] -==== Bean Aliasing - -As discussed in <>, it is sometimes desirable to give a single bean -multiple names, otherwise known as bean aliasing. The `name` attribute of the `@Bean` -annotation accepts a String array for this purpose. The following example shows how to set -a number of aliases for a bean: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean({"dataSource", "subsystemA-dataSource", "subsystemB-dataSource"}) - public DataSource dataSource() { - // instantiate, configure and return DataSource bean... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean("dataSource", "subsystemA-dataSource", "subsystemB-dataSource") - fun dataSource(): DataSource { - // instantiate, configure and return DataSource bean... - } - } ----- - - -[[beans-java-bean-description]] -==== Bean Description - -Sometimes, it is helpful to provide a more detailed textual description of a bean. This can -be particularly useful when beans are exposed (perhaps through JMX) for monitoring purposes. - -To add a description to a `@Bean`, you can use the -{api-spring-framework}/context/annotation/Description.html[`@Description`] -annotation, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - @Description("Provides a basic example of a bean") - public Thing thing() { - return new Thing(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - @Description("Provides a basic example of a bean") - fun thing() = Thing() - } ----- - - - -[[beans-java-configuration-annotation]] -=== Using the `@Configuration` annotation - -`@Configuration` is a class-level annotation indicating that an object is a source of -bean definitions. `@Configuration` classes declare beans through `@Bean`-annotated -methods. Calls to `@Bean` methods on `@Configuration` classes can also be used to define -inter-bean dependencies. See <> for a general introduction. - - -[[beans-java-injecting-dependencies]] -==== Injecting Inter-bean Dependencies - -When beans have dependencies on one another, expressing that dependency is as simple -as having one bean method call another, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public BeanOne beanOne() { - return new BeanOne(beanTwo()); - } - - @Bean - public BeanTwo beanTwo() { - return new BeanTwo(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun beanOne() = BeanOne(beanTwo()) - - @Bean - fun beanTwo() = BeanTwo() - } ----- - -In the preceding example, `beanOne` receives a reference to `beanTwo` through constructor -injection. - -NOTE: This method of declaring inter-bean dependencies works only when the `@Bean` method -is declared within a `@Configuration` class. You cannot declare inter-bean dependencies -by using plain `@Component` classes. - - - -[[beans-java-method-injection]] -==== Lookup Method Injection - -As noted earlier, <> is an -advanced feature that you should use rarely. It is useful in cases where a -singleton-scoped bean has a dependency on a prototype-scoped bean. Using Java for this -type of configuration provides a natural means for implementing this pattern. The -following example shows how to use lookup method injection: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public abstract class CommandManager { - public Object process(Object commandState) { - // grab a new instance of the appropriate Command interface - Command command = createCommand(); - // set the state on the (hopefully brand new) Command instance - command.setState(commandState); - return command.execute(); - } - - // okay... but where is the implementation of this method? - protected abstract Command createCommand(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - abstract class CommandManager { - fun process(commandState: Any): Any { - // grab a new instance of the appropriate Command interface - val command = createCommand() - // set the state on the (hopefully brand new) Command instance - command.setState(commandState) - return command.execute() - } - - // okay... but where is the implementation of this method? - protected abstract fun createCommand(): Command - } ----- - -By using Java configuration, you can create a subclass of `CommandManager` where -the abstract `createCommand()` method is overridden in such a way that it looks up a new -(prototype) command object. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Bean - @Scope("prototype") - public AsyncCommand asyncCommand() { - AsyncCommand command = new AsyncCommand(); - // inject dependencies here as required - return command; - } - - @Bean - public CommandManager commandManager() { - // return new anonymous implementation of CommandManager with createCommand() - // overridden to return a new prototype Command object - return new CommandManager() { - protected Command createCommand() { - return asyncCommand(); - } - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Bean - @Scope("prototype") - fun asyncCommand(): AsyncCommand { - val command = AsyncCommand() - // inject dependencies here as required - return command - } - - @Bean - fun commandManager(): CommandManager { - // return new anonymous implementation of CommandManager with createCommand() - // overridden to return a new prototype Command object - return object : CommandManager() { - override fun createCommand(): Command { - return asyncCommand() - } - } - } ----- - - -[[beans-java-further-information-java-config]] -==== Further Information About How Java-based Configuration Works Internally - -Consider the following example, which shows a `@Bean` annotated method being called twice: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean - public ClientService clientService1() { - ClientServiceImpl clientService = new ClientServiceImpl(); - clientService.setClientDao(clientDao()); - return clientService; - } - - @Bean - public ClientService clientService2() { - ClientServiceImpl clientService = new ClientServiceImpl(); - clientService.setClientDao(clientDao()); - return clientService; - } - - @Bean - public ClientDao clientDao() { - return new ClientDaoImpl(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean - fun clientService1(): ClientService { - return ClientServiceImpl().apply { - clientDao = clientDao() - } - } - - @Bean - fun clientService2(): ClientService { - return ClientServiceImpl().apply { - clientDao = clientDao() - } - } - - @Bean - fun clientDao(): ClientDao { - return ClientDaoImpl() - } - } ----- - -`clientDao()` has been called once in `clientService1()` and once in `clientService2()`. -Since this method creates a new instance of `ClientDaoImpl` and returns it, you would -normally expect to have two instances (one for each service). That definitely would be -problematic: In Spring, instantiated beans have a `singleton` scope by default. This is -where the magic comes in: All `@Configuration` classes are subclassed at startup-time -with `CGLIB`. In the subclass, the child method checks the container first for any -cached (scoped) beans before it calls the parent method and creates a new instance. - -NOTE: The behavior could be different according to the scope of your bean. We are talking -about singletons here. - -[NOTE] -==== -It is not necessary to add CGLIB to your classpath because CGLIB classes are repackaged -under the `org.springframework.cglib` package and included directly within the -`spring-core` JAR. -==== - -[TIP] -==== -There are a few restrictions due to the fact that CGLIB dynamically adds features at -startup-time. In particular, configuration classes must not be final. However, any -constructors are allowed on configuration classes, including the use of `@Autowired` or a -single non-default constructor declaration for default injection. - -If you prefer to avoid any CGLIB-imposed limitations, consider declaring your `@Bean` -methods on non-`@Configuration` classes (for example, on plain `@Component` classes -instead) or by annotating your configuration class with -`@Configuration(proxyBeanMethods = false)`. Cross-method calls between `@Bean` methods -are then not intercepted, so you have to exclusively rely on dependency injection at the -constructor or method level there. -==== - - - -[[beans-java-composing-configuration-classes]] -=== Composing Java-based Configurations - -Spring's Java-based configuration feature lets you compose annotations, which can reduce -the complexity of your configuration. - - -[[beans-java-using-import]] -==== Using the `@Import` Annotation - -Much as the `` element is used within Spring XML files to aid in modularizing -configurations, the `@Import` annotation allows for loading `@Bean` definitions from -another configuration class, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class ConfigA { - - @Bean - public A a() { - return new A(); - } - } - - @Configuration - @Import(ConfigA.class) - public class ConfigB { - - @Bean - public B b() { - return new B(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class ConfigA { - - @Bean - fun a() = A() - } - - @Configuration - @Import(ConfigA::class) - class ConfigB { - - @Bean - fun b() = B() - } ----- - -Now, rather than needing to specify both `ConfigA.class` and `ConfigB.class` when -instantiating the context, only `ConfigB` needs to be supplied explicitly, as the -following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static void main(String[] args) { - ApplicationContext ctx = new AnnotationConfigApplicationContext(ConfigB.class); - - // now both beans A and B will be available... - A a = ctx.getBean(A.class); - B b = ctx.getBean(B.class); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - fun main() { - val ctx = AnnotationConfigApplicationContext(ConfigB::class.java) - - // now both beans A and B will be available... - val a = ctx.getBean() - val b = ctx.getBean() - } ----- - -This approach simplifies container instantiation, as only one class needs to be dealt -with, rather than requiring you to remember a potentially large number of -`@Configuration` classes during construction. - -TIP: As of Spring Framework 4.2, `@Import` also supports references to regular component -classes, analogous to the `AnnotationConfigApplicationContext.register` method. -This is particularly useful if you want to avoid component scanning, by using a few -configuration classes as entry points to explicitly define all your components. - -[[beans-java-injecting-imported-beans]] -===== Injecting Dependencies on Imported `@Bean` Definitions - -The preceding example works but is simplistic. In most practical scenarios, beans have -dependencies on one another across configuration classes. When using XML, this is not an -issue, because no compiler is involved, and you can declare -`ref="someBean"` and trust Spring to work it out during container initialization. -When using `@Configuration` classes, the Java compiler places constraints on -the configuration model, in that references to other beans must be valid Java syntax. - -Fortunately, solving this problem is simple. As <>, -a `@Bean` method can have an arbitrary number of parameters that describe the bean -dependencies. Consider the following more real-world scenario with several `@Configuration` -classes, each depending on beans declared in the others: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class ServiceConfig { - - @Bean - public TransferService transferService(AccountRepository accountRepository) { - return new TransferServiceImpl(accountRepository); - } - } - - @Configuration - public class RepositoryConfig { - - @Bean - public AccountRepository accountRepository(DataSource dataSource) { - return new JdbcAccountRepository(dataSource); - } - } - - @Configuration - @Import({ServiceConfig.class, RepositoryConfig.class}) - public class SystemTestConfig { - - @Bean - public DataSource dataSource() { - // return new DataSource - } - } - - public static void main(String[] args) { - ApplicationContext ctx = new AnnotationConfigApplicationContext(SystemTestConfig.class); - // everything wires up across configuration classes... - TransferService transferService = ctx.getBean(TransferService.class); - transferService.transfer(100.00, "A123", "C456"); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - @Configuration - class ServiceConfig { - - @Bean - fun transferService(accountRepository: AccountRepository): TransferService { - return TransferServiceImpl(accountRepository) - } - } - - @Configuration - class RepositoryConfig { - - @Bean - fun accountRepository(dataSource: DataSource): AccountRepository { - return JdbcAccountRepository(dataSource) - } - } - - @Configuration - @Import(ServiceConfig::class, RepositoryConfig::class) - class SystemTestConfig { - - @Bean - fun dataSource(): DataSource { - // return new DataSource - } - } - - - fun main() { - val ctx = AnnotationConfigApplicationContext(SystemTestConfig::class.java) - // everything wires up across configuration classes... - val transferService = ctx.getBean() - transferService.transfer(100.00, "A123", "C456") - } ----- - - -There is another way to achieve the same result. Remember that `@Configuration` classes are -ultimately only another bean in the container: This means that they can take advantage of -`@Autowired` and `@Value` injection and other features the same as any other bean. - -[WARNING] -==== -Make sure that the dependencies you inject that way are of the simplest kind only. `@Configuration` -classes are processed quite early during the initialization of the context, and forcing a dependency -to be injected this way may lead to unexpected early initialization. Whenever possible, resort to -parameter-based injection, as in the preceding example. - -Also, be particularly careful with `BeanPostProcessor` and `BeanFactoryPostProcessor` definitions -through `@Bean`. Those should usually be declared as `static @Bean` methods, not triggering the -instantiation of their containing configuration class. Otherwise, `@Autowired` and `@Value` may not -work on the configuration class itself, since it is possible to create it as a bean instance earlier than -{api-spring-framework}/beans/factory/annotation/AutowiredAnnotationBeanPostProcessor.html[`AutowiredAnnotationBeanPostProcessor`]. -==== - -The following example shows how one bean can be autowired to another bean: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class ServiceConfig { - - @Autowired - private AccountRepository accountRepository; - - @Bean - public TransferService transferService() { - return new TransferServiceImpl(accountRepository); - } - } - - @Configuration - public class RepositoryConfig { - - private final DataSource dataSource; - - public RepositoryConfig(DataSource dataSource) { - this.dataSource = dataSource; - } - - @Bean - public AccountRepository accountRepository() { - return new JdbcAccountRepository(dataSource); - } - } - - @Configuration - @Import({ServiceConfig.class, RepositoryConfig.class}) - public class SystemTestConfig { - - @Bean - public DataSource dataSource() { - // return new DataSource - } - } - - public static void main(String[] args) { - ApplicationContext ctx = new AnnotationConfigApplicationContext(SystemTestConfig.class); - // everything wires up across configuration classes... - TransferService transferService = ctx.getBean(TransferService.class); - transferService.transfer(100.00, "A123", "C456"); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - @Configuration - class ServiceConfig { - - @Autowired - lateinit var accountRepository: AccountRepository - - @Bean - fun transferService(): TransferService { - return TransferServiceImpl(accountRepository) - } - } - - @Configuration - class RepositoryConfig(private val dataSource: DataSource) { - - @Bean - fun accountRepository(): AccountRepository { - return JdbcAccountRepository(dataSource) - } - } - - @Configuration - @Import(ServiceConfig::class, RepositoryConfig::class) - class SystemTestConfig { - - @Bean - fun dataSource(): DataSource { - // return new DataSource - } - } - - fun main() { - val ctx = AnnotationConfigApplicationContext(SystemTestConfig::class.java) - // everything wires up across configuration classes... - val transferService = ctx.getBean() - transferService.transfer(100.00, "A123", "C456") - } ----- - -TIP: Constructor injection in `@Configuration` classes is only supported as of Spring -Framework 4.3. Note also that there is no need to specify `@Autowired` if the target -bean defines only one constructor. - -.[[beans-java-injecting-imported-beans-fq]]Fully-qualifying imported beans for ease of navigation --- -In the preceding scenario, using `@Autowired` works well and provides the desired -modularity, but determining exactly where the autowired bean definitions are declared is -still somewhat ambiguous. For example, as a developer looking at `ServiceConfig`, how do -you know exactly where the `@Autowired AccountRepository` bean is declared? It is not -explicit in the code, and this may be just fine. Remember that the -https://spring.io/tools[Spring Tools for Eclipse] provides tooling that -can render graphs showing how everything is wired, which may be all you need. Also, -your Java IDE can easily find all declarations and uses of the `AccountRepository` type -and quickly show you the location of `@Bean` methods that return that type. - -In cases where this ambiguity is not acceptable and you wish to have direct navigation -from within your IDE from one `@Configuration` class to another, consider autowiring the -configuration classes themselves. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class ServiceConfig { - - @Autowired - private RepositoryConfig repositoryConfig; - - @Bean - public TransferService transferService() { - // navigate 'through' the config class to the @Bean method! - return new TransferServiceImpl(repositoryConfig.accountRepository()); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- -@Configuration -class ServiceConfig { - - @Autowired - private lateinit var repositoryConfig: RepositoryConfig - - @Bean - fun transferService(): TransferService { - // navigate 'through' the config class to the @Bean method! - return TransferServiceImpl(repositoryConfig.accountRepository()) - } -} ----- - -In the preceding situation, where `AccountRepository` is defined is completely explicit. -However, `ServiceConfig` is now tightly coupled to `RepositoryConfig`. That is the -tradeoff. This tight coupling can be somewhat mitigated by using interface-based or -abstract class-based `@Configuration` classes. Consider the following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class ServiceConfig { - - @Autowired - private RepositoryConfig repositoryConfig; - - @Bean - public TransferService transferService() { - return new TransferServiceImpl(repositoryConfig.accountRepository()); - } - } - - @Configuration - public interface RepositoryConfig { - - @Bean - AccountRepository accountRepository(); - } - - @Configuration - public class DefaultRepositoryConfig implements RepositoryConfig { - - @Bean - public AccountRepository accountRepository() { - return new JdbcAccountRepository(...); - } - } - - @Configuration - @Import({ServiceConfig.class, DefaultRepositoryConfig.class}) // import the concrete config! - public class SystemTestConfig { - - @Bean - public DataSource dataSource() { - // return DataSource - } - - } - - public static void main(String[] args) { - ApplicationContext ctx = new AnnotationConfigApplicationContext(SystemTestConfig.class); - TransferService transferService = ctx.getBean(TransferService.class); - transferService.transfer(100.00, "A123", "C456"); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - @Configuration - class ServiceConfig { - - @Autowired - private lateinit var repositoryConfig: RepositoryConfig - - @Bean - fun transferService(): TransferService { - return TransferServiceImpl(repositoryConfig.accountRepository()) - } - } - - @Configuration - interface RepositoryConfig { - - @Bean - fun accountRepository(): AccountRepository - } - - @Configuration - class DefaultRepositoryConfig : RepositoryConfig { - - @Bean - fun accountRepository(): AccountRepository { - return JdbcAccountRepository(...) - } - } - - @Configuration - @Import(ServiceConfig::class, DefaultRepositoryConfig::class) // import the concrete config! - class SystemTestConfig { - - @Bean - fun dataSource(): DataSource { - // return DataSource - } - - } - - fun main() { - val ctx = AnnotationConfigApplicationContext(SystemTestConfig::class.java) - val transferService = ctx.getBean() - transferService.transfer(100.00, "A123", "C456") - } ----- - -Now `ServiceConfig` is loosely coupled with respect to the concrete -`DefaultRepositoryConfig`, and built-in IDE tooling is still useful: You can easily -get a type hierarchy of `RepositoryConfig` implementations. In this -way, navigating `@Configuration` classes and their dependencies becomes no different -than the usual process of navigating interface-based code. --- - -TIP: If you want to influence the startup creation order of certain beans, consider -declaring some of them as `@Lazy` (for creation on first access instead of on startup) -or as `@DependsOn` certain other beans (making sure that specific other beans are -created before the current bean, beyond what the latter's direct dependencies imply). - - -[[beans-java-conditional]] -==== Conditionally Include `@Configuration` Classes or `@Bean` Methods - -It is often useful to conditionally enable or disable a complete `@Configuration` class -or even individual `@Bean` methods, based on some arbitrary system state. One common -example of this is to use the `@Profile` annotation to activate beans only when a specific -profile has been enabled in the Spring `Environment` (see <> -for details). - -The `@Profile` annotation is actually implemented by using a much more flexible annotation -called {api-spring-framework}/context/annotation/Conditional.html[`@Conditional`]. -The `@Conditional` annotation indicates specific -`org.springframework.context.annotation.Condition` implementations that should be -consulted before a `@Bean` is registered. - -Implementations of the `Condition` interface provide a `matches(...)` -method that returns `true` or `false`. For example, the following listing shows the actual -`Condition` implementation used for `@Profile`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Override - public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) { - // Read the @Profile annotation attributes - MultiValueMap attrs = metadata.getAllAnnotationAttributes(Profile.class.getName()); - if (attrs != null) { - for (Object value : attrs.get("value")) { - if (context.getEnvironment().acceptsProfiles(((String[]) value))) { - return true; - } - } - return false; - } - return true; - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - override fun matches(context: ConditionContext, metadata: AnnotatedTypeMetadata): Boolean { - // Read the @Profile annotation attributes - val attrs = metadata.getAllAnnotationAttributes(Profile::class.java.name) - if (attrs != null) { - for (value in attrs["value"]!!) { - if (context.environment.acceptsProfiles(Profiles.of(*value as Array))) { - return true - } - } - return false - } - return true - } ----- - -See the {api-spring-framework}/context/annotation/Conditional.html[`@Conditional`] -javadoc for more detail. - - -[[beans-java-combining]] -==== Combining Java and XML Configuration - -Spring's `@Configuration` class support does not aim to be a 100% complete replacement -for Spring XML. Some facilities, such as Spring XML namespaces, remain an ideal way to -configure the container. In cases where XML is convenient or necessary, you have a -choice: either instantiate the container in an "`XML-centric`" way by using, for example, -`ClassPathXmlApplicationContext`, or instantiate it in a "`Java-centric`" way by using -`AnnotationConfigApplicationContext` and the `@ImportResource` annotation to import XML -as needed. - -[[beans-java-combining-xml-centric]] -===== XML-centric Use of `@Configuration` Classes - -It may be preferable to bootstrap the Spring container from XML and include -`@Configuration` classes in an ad-hoc fashion. For example, in a large existing codebase -that uses Spring XML, it is easier to create `@Configuration` classes on an -as-needed basis and include them from the existing XML files. Later in this section, we cover the -options for using `@Configuration` classes in this kind of "`XML-centric`" situation. - -.[[beans-java-combining-xml-centric-declare-as-bean]]Declaring `@Configuration` classes as plain Spring `` elements --- -Remember that `@Configuration` classes are ultimately bean definitions in the -container. In this series examples, we create a `@Configuration` class named `AppConfig` and -include it within `system-test-config.xml` as a `` definition. Because -`` is switched on, the container recognizes the -`@Configuration` annotation and processes the `@Bean` methods declared in `AppConfig` -properly. - -The following example shows an ordinary configuration class in Java: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Autowired - private DataSource dataSource; - - @Bean - public AccountRepository accountRepository() { - return new JdbcAccountRepository(dataSource); - } - - @Bean - public TransferService transferService() { - return new TransferService(accountRepository()); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Autowired - private lateinit var dataSource: DataSource - - @Bean - fun accountRepository(): AccountRepository { - return JdbcAccountRepository(dataSource) - } - - @Bean - fun transferService() = TransferService(accountRepository()) - } ----- - -The following example shows part of a sample `system-test-config.xml` file: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - ----- - -The following example shows a possible `jdbc.properties` file: - -[literal,subs="verbatim,quotes"] ----- -jdbc.url=jdbc:hsqldb:hsql://localhost/xdb -jdbc.username=sa -jdbc.password= ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static void main(String[] args) { - ApplicationContext ctx = new ClassPathXmlApplicationContext("classpath:/com/acme/system-test-config.xml"); - TransferService transferService = ctx.getBean(TransferService.class); - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun main() { - val ctx = ClassPathXmlApplicationContext("classpath:/com/acme/system-test-config.xml") - val transferService = ctx.getBean() - // ... - } ----- - - -NOTE: In `system-test-config.xml` file, the `AppConfig` `` does not declare an `id` -element. While it would be acceptable to do so, it is unnecessary, given that no other bean -ever refers to it, and it is unlikely to be explicitly fetched from the container by name. -Similarly, the `DataSource` bean is only ever autowired by type, so an explicit bean `id` -is not strictly required. --- - -.[[beans-java-combining-xml-centric-component-scan]] Using to pick up `@Configuration` classes --- -Because `@Configuration` is meta-annotated with `@Component`, `@Configuration`-annotated -classes are automatically candidates for component scanning. Using the same scenario as -described in the previous example, we can redefine `system-test-config.xml` to take advantage of component-scanning. -Note that, in this case, we need not explicitly declare -``, because `` enables the same -functionality. - -The following example shows the modified `system-test-config.xml` file: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - ----- --- - -[[beans-java-combining-java-centric]] -===== `@Configuration` Class-centric Use of XML with `@ImportResource` - -In applications where `@Configuration` classes are the primary mechanism for configuring -the container, it is still likely necessary to use at least some XML. In these -scenarios, you can use `@ImportResource` and define only as much XML as you need. Doing -so achieves a "`Java-centric`" approach to configuring the container and keeps XML to a -bare minimum. The following example (which includes a configuration class, an XML file -that defines a bean, a properties file, and the `main` class) shows how to use -the `@ImportResource` annotation to achieve "`Java-centric`" configuration that uses XML -as needed: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @ImportResource("classpath:/com/acme/properties-config.xml") - public class AppConfig { - - @Value("${jdbc.url}") - private String url; - - @Value("${jdbc.username}") - private String username; - - @Value("${jdbc.password}") - private String password; - - @Bean - public DataSource dataSource() { - return new DriverManagerDataSource(url, username, password); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @ImportResource("classpath:/com/acme/properties-config.xml") - class AppConfig { - - @Value("\${jdbc.url}") - private lateinit var url: String - - @Value("\${jdbc.username}") - private lateinit var username: String - - @Value("\${jdbc.password}") - private lateinit var password: String - - @Bean - fun dataSource(): DataSource { - return DriverManagerDataSource(url, username, password) - } - } ----- - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - properties-config.xml - - - ----- - -[literal,subs="verbatim,quotes"] ----- -jdbc.properties -jdbc.url=jdbc:hsqldb:hsql://localhost/xdb -jdbc.username=sa -jdbc.password= ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static void main(String[] args) { - ApplicationContext ctx = new AnnotationConfigApplicationContext(AppConfig.class); - TransferService transferService = ctx.getBean(TransferService.class); - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - import org.springframework.beans.factory.getBean - - fun main() { - val ctx = AnnotationConfigApplicationContext(AppConfig::class.java) - val transferService = ctx.getBean() - // ... - } ----- - - - -[[beans-environment]] -== Environment Abstraction - -The {api-spring-framework}/core/env/Environment.html[`Environment`] interface -is an abstraction integrated in the container that models two key -aspects of the application environment: <> -and <>. - -A profile is a named, logical group of bean definitions to be registered with the -container only if the given profile is active. Beans may be assigned to a profile -whether defined in XML or with annotations. The role of the `Environment` object with -relation to profiles is in determining which profiles (if any) are currently active, -and which profiles (if any) should be active by default. - -Properties play an important role in almost all applications and may originate from -a variety of sources: properties files, JVM system properties, system environment -variables, JNDI, servlet context parameters, ad-hoc `Properties` objects, `Map` objects, and so -on. The role of the `Environment` object with relation to properties is to provide the -user with a convenient service interface for configuring property sources and resolving -properties from them. - - - -[[beans-definition-profiles]] -=== Bean Definition Profiles - -Bean definition profiles provide a mechanism in the core container that allows for -registration of different beans in different environments. The word, "`environment,`" -can mean different things to different users, and this feature can help with many -use cases, including: - -* Working against an in-memory datasource in development versus looking up that same -datasource from JNDI when in QA or production. -* Registering monitoring infrastructure only when deploying an application into a -performance environment. -* Registering customized implementations of beans for customer A versus customer -B deployments. - -Consider the first use case in a practical application that requires a -`DataSource`. In a test environment, the configuration might resemble the following: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Bean - public DataSource dataSource() { - return new EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("my-schema.sql") - .addScript("my-test-data.sql") - .build(); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Bean - fun dataSource(): DataSource { - return EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("my-schema.sql") - .addScript("my-test-data.sql") - .build() - } ----- - -Now consider how this application can be deployed into a QA or production -environment, assuming that the datasource for the application is registered -with the production application server's JNDI directory. Our `dataSource` bean -now looks like the following listing: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Bean(destroyMethod = "") - public DataSource dataSource() throws Exception { - Context ctx = new InitialContext(); - return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource"); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Bean(destroyMethod = "") - fun dataSource(): DataSource { - val ctx = InitialContext() - return ctx.lookup("java:comp/env/jdbc/datasource") as DataSource - } ----- - -The problem is how to switch between using these two variations based on the -current environment. Over time, Spring users have devised a number of ways to -get this done, usually relying on a combination of system environment variables -and XML `` statements containing pass:q[`${placeholder}`] tokens that resolve -to the correct configuration file path depending on the value of an environment -variable. Bean definition profiles is a core container feature that provides a -solution to this problem. - -If we generalize the use case shown in the preceding example of environment-specific bean -definitions, we end up with the need to register certain bean definitions in -certain contexts but not in others. You could say that you want to register a -certain profile of bean definitions in situation A and a different profile in -situation B. We start by updating our configuration to reflect this need. - - -[[beans-definition-profiles-java]] -==== Using `@Profile` - -The {api-spring-framework}/context/annotation/Profile.html[`@Profile`] -annotation lets you indicate that a component is eligible for registration -when one or more specified profiles are active. Using our preceding example, we -can rewrite the `dataSource` configuration as follows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @Profile("development") - public class StandaloneDataConfig { - - @Bean - public DataSource dataSource() { - return new EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .addScript("classpath:com/bank/config/sql/test-data.sql") - .build(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @Profile("development") - class StandaloneDataConfig { - - @Bean - fun dataSource(): DataSource { - return EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .addScript("classpath:com/bank/config/sql/test-data.sql") - .build() - } - } ----- --- - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @Profile("production") - public class JndiDataConfig { - - @Bean(destroyMethod = "") // <1> - public DataSource dataSource() throws Exception { - Context ctx = new InitialContext(); - return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource"); - } - } ----- -<1> `@Bean(destroyMethod = "")` disables default destroy method inference. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @Profile("production") - class JndiDataConfig { - - @Bean(destroyMethod = "") // <1> - fun dataSource(): DataSource { - val ctx = InitialContext() - return ctx.lookup("java:comp/env/jdbc/datasource") as DataSource - } - } ----- -<1> `@Bean(destroyMethod = "")` disables default destroy method inference. --- - -NOTE: As mentioned earlier, with `@Bean` methods, you typically choose to use programmatic -JNDI lookups, by using either Spring's `JndiTemplate`/`JndiLocatorDelegate` helpers or the -straight JNDI `InitialContext` usage shown earlier but not the `JndiObjectFactoryBean` -variant, which would force you to declare the return type as the `FactoryBean` type. - -The profile string may contain a simple profile name (for example, `production`) or a -profile expression. A profile expression allows for more complicated profile logic to be -expressed (for example, `production & us-east`). The following operators are supported in -profile expressions: - -* `!`: A logical `NOT` of the profile -* `&`: A logical `AND` of the profiles -* `|`: A logical `OR` of the profiles - -NOTE: You cannot mix the `&` and `|` operators without using parentheses. For example, -`production & us-east | eu-central` is not a valid expression. It must be expressed as -`production & (us-east | eu-central)`. - -You can use `@Profile` as a <> for the purpose -of creating a custom composed annotation. The following example defines a custom -`@Production` annotation that you can use as a drop-in replacement for -`@Profile("production")`: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Target(ElementType.TYPE) - @Retention(RetentionPolicy.RUNTIME) - @Profile("production") - public @interface Production { - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Target(AnnotationTarget.CLASS) - @Retention(AnnotationRetention.RUNTIME) - @Profile("production") - annotation class Production ----- --- - -TIP: If a `@Configuration` class is marked with `@Profile`, all of the `@Bean` methods and -`@Import` annotations associated with that class are bypassed unless one or more of -the specified profiles are active. If a `@Component` or `@Configuration` class is marked -with `@Profile({"p1", "p2"})`, that class is not registered or processed unless -profiles 'p1' or 'p2' have been activated. If a given profile is prefixed with the -NOT operator (`!`), the annotated element is registered only if the profile is not -active. For example, given `@Profile({"p1", "!p2"})`, registration will occur if profile -'p1' is active or if profile 'p2' is not active. - -`@Profile` can also be declared at the method level to include only one particular bean -of a configuration class (for example, for alternative variants of a particular bean), as -the following example shows: - --- -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - public class AppConfig { - - @Bean("dataSource") - @Profile("development") // <1> - public DataSource standaloneDataSource() { - return new EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .addScript("classpath:com/bank/config/sql/test-data.sql") - .build(); - } - - @Bean("dataSource") - @Profile("production") // <2> - public DataSource jndiDataSource() throws Exception { - Context ctx = new InitialContext(); - return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource"); - } - } ----- -<1> The `standaloneDataSource` method is available only in the `development` profile. -<2> The `jndiDataSource` method is available only in the `production` profile. - -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - class AppConfig { - - @Bean("dataSource") - @Profile("development") // <1> - fun standaloneDataSource(): DataSource { - return EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .addScript("classpath:com/bank/config/sql/test-data.sql") - .build() - } - - @Bean("dataSource") - @Profile("production") // <2> - fun jndiDataSource() = - InitialContext().lookup("java:comp/env/jdbc/datasource") as DataSource - } ----- -<1> The `standaloneDataSource` method is available only in the `development` profile. -<2> The `jndiDataSource` method is available only in the `production` profile. --- - -[NOTE] -==== -With `@Profile` on `@Bean` methods, a special scenario may apply: In the case of -overloaded `@Bean` methods of the same Java method name (analogous to constructor -overloading), a `@Profile` condition needs to be consistently declared on all -overloaded methods. If the conditions are inconsistent, only the condition on the -first declaration among the overloaded methods matters. Therefore, `@Profile` can -not be used to select an overloaded method with a particular argument signature over -another. Resolution between all factory methods for the same bean follows Spring's -constructor resolution algorithm at creation time. - -If you want to define alternative beans with different profile conditions, -use distinct Java method names that point to the same bean name by using the `@Bean` name -attribute, as shown in the preceding example. If the argument signatures are all -the same (for example, all of the variants have no-arg factory methods), this is the only -way to represent such an arrangement in a valid Java class in the first place -(since there can only be one method of a particular name and argument signature). -==== - - -[[beans-definition-profiles-xml]] -==== XML Bean Definition Profiles - -The XML counterpart is the `profile` attribute of the `` element. Our preceding sample -configuration can be rewritten in two XML files, as follows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - ----- - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - ----- - -It is also possible to avoid that split and nest `` elements within the same file, -as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - ----- - -The `spring-bean.xsd` has been constrained to allow such elements only as the -last ones in the file. This should help provide flexibility without incurring -clutter in the XML files. - -[NOTE] -===== -The XML counterpart does not support the profile expressions described earlier. It is possible, -however, to negate a profile by using the `!` operator. It is also possible to apply a logical -"`and`" by nesting the profiles, as the following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - ----- - -In the preceding example, the `dataSource` bean is exposed if both the `production` and -`us-east` profiles are active. -===== - - -[[beans-definition-profiles-enable]] -==== Activating a Profile - -Now that we have updated our configuration, we still need to instruct Spring which -profile is active. If we started our sample application right now, we would see -a `NoSuchBeanDefinitionException` thrown, because the container could not find -the Spring bean named `dataSource`. - -Activating a profile can be done in several ways, but the most straightforward is to do -it programmatically against the `Environment` API which is available through an -`ApplicationContext`. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); - ctx.getEnvironment().setActiveProfiles("development"); - ctx.register(SomeConfig.class, StandaloneDataConfig.class, JndiDataConfig.class); - ctx.refresh(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val ctx = AnnotationConfigApplicationContext().apply { - environment.setActiveProfiles("development") - register(SomeConfig::class.java, StandaloneDataConfig::class.java, JndiDataConfig::class.java) - refresh() - } ----- - -In addition, you can also declaratively activate profiles through the -`spring.profiles.active` property, which may be specified through system environment -variables, JVM system properties, servlet context parameters in `web.xml`, or even as an -entry in JNDI (see <>). In integration tests, active -profiles can be declared by using the `@ActiveProfiles` annotation in the `spring-test` -module (see <>). - -Note that profiles are not an "`either-or`" proposition. You can activate multiple -profiles at once. Programmatically, you can provide multiple profile names to the -`setActiveProfiles()` method, which accepts `String...` varargs. The following example -activates multiple profiles: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ctx.getEnvironment().setActiveProfiles("profile1", "profile2"); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - ctx.getEnvironment().setActiveProfiles("profile1", "profile2") ----- - -Declaratively, `spring.profiles.active` may accept a comma-separated list of profile names, -as the following example shows: - -[literal,indent=0,subs="verbatim,quotes"] ----- - -Dspring.profiles.active="profile1,profile2" ----- - - -[[beans-definition-profiles-default]] -==== Default Profile - -The default profile represents the profile that is enabled by default. Consider the -following example: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @Profile("default") - public class DefaultDataConfig { - - @Bean - public DataSource dataSource() { - return new EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .build(); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @Profile("default") - class DefaultDataConfig { - - @Bean - fun dataSource(): DataSource { - return EmbeddedDatabaseBuilder() - .setType(EmbeddedDatabaseType.HSQL) - .addScript("classpath:com/bank/config/sql/schema.sql") - .build() - } - } ----- - -If no profile is active, the `dataSource` is created. You can see this -as a way to provide a default definition for one or more beans. If any -profile is enabled, the default profile does not apply. - -You can change the name of the default profile by using `setDefaultProfiles()` on -the `Environment` or, declaratively, by using the `spring.profiles.default` property. - - - -[[beans-property-source-abstraction]] -=== `PropertySource` Abstraction - -Spring's `Environment` abstraction provides search operations over a configurable -hierarchy of property sources. Consider the following listing: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - ApplicationContext ctx = new GenericApplicationContext(); - Environment env = ctx.getEnvironment(); - boolean containsMyProperty = env.containsProperty("my-property"); - System.out.println("Does my environment contain the 'my-property' property? " + containsMyProperty); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val ctx = GenericApplicationContext() - val env = ctx.environment - val containsMyProperty = env.containsProperty("my-property") - println("Does my environment contain the 'my-property' property? $containsMyProperty") ----- - -In the preceding snippet, we see a high-level way of asking Spring whether the `my-property` property is -defined for the current environment. To answer this question, the `Environment` object performs -a search over a set of {api-spring-framework}/core/env/PropertySource.html[`PropertySource`] -objects. A `PropertySource` is a simple abstraction over any source of key-value pairs, and -Spring's {api-spring-framework}/core/env/StandardEnvironment.html[`StandardEnvironment`] -is configured with two PropertySource objects -- one representing the set of JVM system properties -(`System.getProperties()`) and one representing the set of system environment variables -(`System.getenv()`). - -NOTE: These default property sources are present for `StandardEnvironment`, for use in standalone -applications. {api-spring-framework}/web/context/support/StandardServletEnvironment.html[`StandardServletEnvironment`] -is populated with additional default property sources including servlet config, servlet -context parameters, and a {api-spring-framework}/jndi/JndiPropertySource.html[`JndiPropertySource`] -if JNDI is available. - -Concretely, when you use the `StandardEnvironment`, the call to `env.containsProperty("my-property")` -returns true if a `my-property` system property or `my-property` environment variable is present at -runtime. - -[TIP] -==== -The search performed is hierarchical. By default, system properties have precedence over -environment variables. So, if the `my-property` property happens to be set in both places during -a call to `env.getProperty("my-property")`, the system property value "`wins`" and is returned. -Note that property values are not merged -but rather completely overridden by a preceding entry. - -For a common `StandardServletEnvironment`, the full hierarchy is as follows, with the -highest-precedence entries at the top: - -. ServletConfig parameters (if applicable -- for example, in case of a `DispatcherServlet` context) -. ServletContext parameters (web.xml context-param entries) -. JNDI environment variables (`java:comp/env/` entries) -. JVM system properties (`-D` command-line arguments) -. JVM system environment (operating system environment variables) -==== - -Most importantly, the entire mechanism is configurable. Perhaps you have a custom source -of properties that you want to integrate into this search. To do so, implement -and instantiate your own `PropertySource` and add it to the set of `PropertySources` for the -current `Environment`. The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- -ConfigurableApplicationContext ctx = new GenericApplicationContext(); -MutablePropertySources sources = ctx.getEnvironment().getPropertySources(); -sources.addFirst(new MyPropertySource()); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val ctx = GenericApplicationContext() - val sources = ctx.environment.propertySources - sources.addFirst(MyPropertySource()) ----- - -In the preceding code, `MyPropertySource` has been added with highest precedence in the -search. If it contains a `my-property` property, the property is detected and returned, in favor of -any `my-property` property in any other `PropertySource`. The -{api-spring-framework}/core/env/MutablePropertySources.html[`MutablePropertySources`] -API exposes a number of methods that allow for precise manipulation of the set of -property sources. - - - -[[beans-using-propertysource]] -=== Using `@PropertySource` - -The {api-spring-framework}/context/annotation/PropertySource.html[`@PropertySource`] -annotation provides a convenient and declarative mechanism for adding a `PropertySource` -to Spring's `Environment`. - -Given a file called `app.properties` that contains the key-value pair `testbean.name=myTestBean`, -the following `@Configuration` class uses `@PropertySource` in such a way that -a call to `testBean.getName()` returns `myTestBean`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @PropertySource("classpath:/com/myco/app.properties") - public class AppConfig { - - @Autowired - Environment env; - - @Bean - public TestBean testBean() { - TestBean testBean = new TestBean(); - testBean.setName(env.getProperty("testbean.name")); - return testBean; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @PropertySource("classpath:/com/myco/app.properties") - class AppConfig { - - @Autowired - private lateinit var env: Environment - - @Bean - fun testBean() = TestBean().apply { - name = env.getProperty("testbean.name")!! - } - } ----- - -Any `${...}` placeholders present in a `@PropertySource` resource location are -resolved against the set of property sources already registered against the -environment, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @PropertySource("classpath:/com/${my.placeholder:default/path}/app.properties") - public class AppConfig { - - @Autowired - Environment env; - - @Bean - public TestBean testBean() { - TestBean testBean = new TestBean(); - testBean.setName(env.getProperty("testbean.name")); - return testBean; - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @PropertySource("classpath:/com/\${my.placeholder:default/path}/app.properties") - class AppConfig { - - @Autowired - private lateinit var env: Environment - - @Bean - fun testBean() = TestBean().apply { - name = env.getProperty("testbean.name")!! - } - } ----- - -Assuming that `my.placeholder` is present in one of the property sources already -registered (for example, system properties or environment variables), the placeholder is -resolved to the corresponding value. If not, then `default/path` is used -as a default. If no default is specified and a property cannot be resolved, an -`IllegalArgumentException` is thrown. - -NOTE: The `@PropertySource` annotation is repeatable, according to Java 8 conventions. -However, all such `@PropertySource` annotations need to be declared at the same -level, either directly on the configuration class or as meta-annotations within the -same custom annotation. Mixing direct annotations and meta-annotations is not -recommended, since direct annotations effectively override meta-annotations. - - - -[[beans-placeholder-resolution-in-statements]] -=== Placeholder Resolution in Statements - -Historically, the value of placeholders in elements could be resolved only against -JVM system properties or environment variables. This is no longer the case. Because -the `Environment` abstraction is integrated throughout the container, it is easy to -route resolution of placeholders through it. This means that you may configure the -resolution process in any way you like. You can change the precedence of searching through -system properties and environment variables or remove them entirely. You can also add your -own property sources to the mix, as appropriate. - -Concretely, the following statement works regardless of where the `customer` -property is defined, as long as it is available in the `Environment`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - - - - -[[context-load-time-weaver]] -== Registering a `LoadTimeWeaver` - -The `LoadTimeWeaver` is used by Spring to dynamically transform classes as they are -loaded into the Java virtual machine (JVM). - -To enable load-time weaving, you can add the `@EnableLoadTimeWeaving` to one of your -`@Configuration` classes, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @Configuration - @EnableLoadTimeWeaving - public class AppConfig { - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @Configuration - @EnableLoadTimeWeaving - class AppConfig ----- - -Alternatively, for XML configuration, you can use the `context:load-time-weaver` element: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - ----- - -Once configured for the `ApplicationContext`, any bean within that `ApplicationContext` -may implement `LoadTimeWeaverAware`, thereby receiving a reference to the load-time -weaver instance. This is particularly useful in combination with -<> where load-time weaving may be -necessary for JPA class transformation. -Consult the -{api-spring-framework}/orm/jpa/LocalContainerEntityManagerFactoryBean.html[`LocalContainerEntityManagerFactoryBean`] -javadoc for more detail. For more on AspectJ load-time weaving, see <>. - - - - -[[context-introduction]] -== Additional Capabilities of the `ApplicationContext` - -As discussed in the <>, the `org.springframework.beans.factory` -package provides basic functionality for managing and manipulating beans, including in a -programmatic way. The `org.springframework.context` package adds the -{api-spring-framework}/context/ApplicationContext.html[`ApplicationContext`] -interface, which extends the `BeanFactory` interface, in addition to extending other -interfaces to provide additional functionality in a more application -framework-oriented style. Many people use the `ApplicationContext` in a completely -declarative fashion, not even creating it programmatically, but instead relying on -support classes such as `ContextLoader` to automatically instantiate an -`ApplicationContext` as part of the normal startup process of a Jakarta EE web application. - -To enhance `BeanFactory` functionality in a more framework-oriented style, the context -package also provides the following functionality: - -* Access to messages in i18n-style, through the `MessageSource` interface. -* Access to resources, such as URLs and files, through the `ResourceLoader` interface. -* Event publication, namely to beans that implement the `ApplicationListener` interface, - through the use of the `ApplicationEventPublisher` interface. -* Loading of multiple (hierarchical) contexts, letting each be focused on one - particular layer, such as the web layer of an application, through the - `HierarchicalBeanFactory` interface. - - - -[[context-functionality-messagesource]] -=== Internationalization using `MessageSource` - -The `ApplicationContext` interface extends an interface called `MessageSource` and, -therefore, provides internationalization ("`i18n`") functionality. Spring also provides the -`HierarchicalMessageSource` interface, which can resolve messages hierarchically. -Together, these interfaces provide the foundation upon which Spring effects message -resolution. The methods defined on these interfaces include: - -* `String getMessage(String code, Object[] args, String default, Locale loc)`: The basic - method used to retrieve a message from the `MessageSource`. When no message is found - for the specified locale, the default message is used. Any arguments passed in become - replacement values, using the `MessageFormat` functionality provided by the standard - library. -* `String getMessage(String code, Object[] args, Locale loc)`: Essentially the same as - the previous method but with one difference: No default message can be specified. If - the message cannot be found, a `NoSuchMessageException` is thrown. -* `String getMessage(MessageSourceResolvable resolvable, Locale locale)`: All properties - used in the preceding methods are also wrapped in a class named - `MessageSourceResolvable`, which you can use with this method. - -When an `ApplicationContext` is loaded, it automatically searches for a `MessageSource` -bean defined in the context. The bean must have the name `messageSource`. If such a bean -is found, all calls to the preceding methods are delegated to the message source. If no -message source is found, the `ApplicationContext` attempts to find a parent containing a -bean with the same name. If it does, it uses that bean as the `MessageSource`. If the -`ApplicationContext` cannot find any source for messages, an empty -`DelegatingMessageSource` is instantiated in order to be able to accept calls to the -methods defined above. - -Spring provides three `MessageSource` implementations, `ResourceBundleMessageSource`, `ReloadableResourceBundleMessageSource` -and `StaticMessageSource`. All of them implement `HierarchicalMessageSource` in order to do nested -messaging. The `StaticMessageSource` is rarely used but provides programmatic ways to -add messages to the source. The following example shows `ResourceBundleMessageSource`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - format - exceptions - windows - - - - ----- - -The example assumes that you have three resource bundles called `format`, `exceptions` and `windows` -defined in your classpath. Any request to resolve a message is -handled in the JDK-standard way of resolving messages through `ResourceBundle` objects. For the -purposes of the example, assume the contents of two of the above resource bundle files -are as follows: - -[source,properties,indent=0,subs="verbatim,quotes"] ----- - # in format.properties - message=Alligators rock! ----- - -[source,properties,indent=0,subs="verbatim,quotes"] ----- - # in exceptions.properties - argument.required=The {0} argument is required. ----- - -The next example shows a program to run the `MessageSource` functionality. -Remember that all `ApplicationContext` implementations are also `MessageSource` -implementations and so can be cast to the `MessageSource` interface. - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static void main(String[] args) { - MessageSource resources = new ClassPathXmlApplicationContext("beans.xml"); - String message = resources.getMessage("message", null, "Default", Locale.ENGLISH); - System.out.println(message); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun main() { - val resources = ClassPathXmlApplicationContext("beans.xml") - val message = resources.getMessage("message", null, "Default", Locale.ENGLISH) - println(message) - } ----- - -The resulting output from the above program is as follows: - -[literal,subs="verbatim,quotes"] ----- -Alligators rock! ----- - -To summarize, the `MessageSource` is defined in a file called `beans.xml`, which -exists at the root of your classpath. The `messageSource` bean definition refers to a -number of resource bundles through its `basenames` property. The three files that are -passed in the list to the `basenames` property exist as files at the root of your -classpath and are called `format.properties`, `exceptions.properties`, and -`windows.properties`, respectively. - -The next example shows arguments passed to the message lookup. These arguments are -converted into `String` objects and inserted into placeholders in the lookup message. - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - - - - - - ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class Example { - - private MessageSource messages; - - public void setMessages(MessageSource messages) { - this.messages = messages; - } - - public void execute() { - String message = this.messages.getMessage("argument.required", - new Object [] {"userDao"}, "Required", Locale.ENGLISH); - System.out.println(message); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class Example { - - lateinit var messages: MessageSource - - fun execute() { - val message = messages.getMessage("argument.required", - arrayOf("userDao"), "Required", Locale.ENGLISH) - println(message) - } -} ----- - -The resulting output from the invocation of the `execute()` method is as follows: - -[literal,subs="verbatim,quotes"] ----- -The userDao argument is required. ----- - -With regard to internationalization ("`i18n`"), Spring's various `MessageSource` -implementations follow the same locale resolution and fallback rules as the standard JDK -`ResourceBundle`. In short, and continuing with the example `messageSource` defined -previously, if you want to resolve messages against the British (`en-GB`) locale, you -would create files called `format_en_GB.properties`, `exceptions_en_GB.properties`, and -`windows_en_GB.properties`, respectively. - -Typically, locale resolution is managed by the surrounding environment of the -application. In the following example, the locale against which (British) messages are -resolved is specified manually: - -[literal,subs="verbatim,quotes"] ----- -# in exceptions_en_GB.properties -argument.required=Ebagum lad, the ''{0}'' argument is required, I say, required. ----- - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public static void main(final String[] args) { - MessageSource resources = new ClassPathXmlApplicationContext("beans.xml"); - String message = resources.getMessage("argument.required", - new Object [] {"userDao"}, "Required", Locale.UK); - System.out.println(message); - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun main() { - val resources = ClassPathXmlApplicationContext("beans.xml") - val message = resources.getMessage("argument.required", - arrayOf("userDao"), "Required", Locale.UK) - println(message) - } ----- - -The resulting output from the running of the above program is as follows: - -[literal,subs="verbatim,quotes"] ----- -Ebagum lad, the 'userDao' argument is required, I say, required. ----- - -You can also use the `MessageSourceAware` interface to acquire a reference to any -`MessageSource` that has been defined. Any bean that is defined in an -`ApplicationContext` that implements the `MessageSourceAware` interface is injected with -the application context's `MessageSource` when the bean is created and configured. - -NOTE: Because Spring's `MessageSource` is based on Java's `ResourceBundle`, it does not merge -bundles with the same base name, but will only use the first bundle found. -Subsequent message bundles with the same base name are ignored. - -NOTE: As an alternative to `ResourceBundleMessageSource`, Spring provides a -`ReloadableResourceBundleMessageSource` class. This variant supports the same bundle -file format but is more flexible than the standard JDK based -`ResourceBundleMessageSource` implementation. In particular, it allows for reading -files from any Spring resource location (not only from the classpath) and supports hot -reloading of bundle property files (while efficiently caching them in between). -See the {api-spring-framework}/context/support/ReloadableResourceBundleMessageSource.html[`ReloadableResourceBundleMessageSource`] -javadoc for details. - - - -[[context-functionality-events]] -=== Standard and Custom Events - -Event handling in the `ApplicationContext` is provided through the `ApplicationEvent` -class and the `ApplicationListener` interface. If a bean that implements the -`ApplicationListener` interface is deployed into the context, every time an -`ApplicationEvent` gets published to the `ApplicationContext`, that bean is notified. -Essentially, this is the standard Observer design pattern. - -TIP: As of Spring 4.2, the event infrastructure has been significantly improved and offers -an <> as well as the -ability to publish any arbitrary event (that is, an object that does not necessarily -extend from `ApplicationEvent`). When such an object is published, we wrap it in an -event for you. - -The following table describes the standard events that Spring provides: - -[[beans-ctx-events-tbl]] -.Built-in Events -[cols="30%,70%"] -|=== -| Event| Explanation - -| `ContextRefreshedEvent` -| Published when the `ApplicationContext` is initialized or refreshed (for example, by - using the `refresh()` method on the `ConfigurableApplicationContext` interface). - Here, "`initialized`" means that all beans are loaded, post-processor beans are detected - and activated, singletons are pre-instantiated, and the `ApplicationContext` object is - ready for use. As long as the context has not been closed, a refresh can be triggered - multiple times, provided that the chosen `ApplicationContext` actually supports such - "`hot`" refreshes. For example, `XmlWebApplicationContext` supports hot refreshes, but - `GenericApplicationContext` does not. - -| `ContextStartedEvent` -| Published when the `ApplicationContext` is started by using the `start()` method on the - `ConfigurableApplicationContext` interface. Here, "`started`" means that all `Lifecycle` - beans receive an explicit start signal. Typically, this signal is used to restart beans - after an explicit stop, but it may also be used to start components that have not been - configured for autostart (for example, components that have not already started on - initialization). - -| `ContextStoppedEvent` -| Published when the `ApplicationContext` is stopped by using the `stop()` method on the - `ConfigurableApplicationContext` interface. Here, "`stopped`" means that all `Lifecycle` - beans receive an explicit stop signal. A stopped context may be restarted through a - `start()` call. - -| `ContextClosedEvent` -| Published when the `ApplicationContext` is being closed by using the `close()` method - on the `ConfigurableApplicationContext` interface or via a JVM shutdown hook. Here, - "closed" means that all singleton beans will be destroyed. Once the context is closed, - it reaches its end of life and cannot be refreshed or restarted. - -| `RequestHandledEvent` -| A web-specific event telling all beans that an HTTP request has been serviced. This - event is published after the request is complete. This event is only applicable to - web applications that use Spring's `DispatcherServlet`. - -| `ServletRequestHandledEvent` -| A subclass of `RequestHandledEvent` that adds Servlet-specific context information. - -|=== - -You can also create and publish your own custom events. The following example shows a -simple class that extends Spring's `ApplicationEvent` base class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class BlockedListEvent extends ApplicationEvent { - - private final String address; - private final String content; - - public BlockedListEvent(Object source, String address, String content) { - super(source); - this.address = address; - this.content = content; - } - - // accessor and other methods... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class BlockedListEvent(source: Any, - val address: String, - val content: String) : ApplicationEvent(source) ----- - -To publish a custom `ApplicationEvent`, call the `publishEvent()` method on an -`ApplicationEventPublisher`. Typically, this is done by creating a class that implements -`ApplicationEventPublisherAware` and registering it as a Spring bean. The following -example shows such a class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class EmailService implements ApplicationEventPublisherAware { - - private List blockedList; - private ApplicationEventPublisher publisher; - - public void setBlockedList(List blockedList) { - this.blockedList = blockedList; - } - - public void setApplicationEventPublisher(ApplicationEventPublisher publisher) { - this.publisher = publisher; - } - - public void sendEmail(String address, String content) { - if (blockedList.contains(address)) { - publisher.publishEvent(new BlockedListEvent(this, address, content)); - return; - } - // send email... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class EmailService : ApplicationEventPublisherAware { - - private lateinit var blockedList: List - private lateinit var publisher: ApplicationEventPublisher - - fun setBlockedList(blockedList: List) { - this.blockedList = blockedList - } - - override fun setApplicationEventPublisher(publisher: ApplicationEventPublisher) { - this.publisher = publisher - } - - fun sendEmail(address: String, content: String) { - if (blockedList!!.contains(address)) { - publisher!!.publishEvent(BlockedListEvent(this, address, content)) - return - } - // send email... - } - } ----- - -At configuration time, the Spring container detects that `EmailService` implements -`ApplicationEventPublisherAware` and automatically calls -`setApplicationEventPublisher()`. In reality, the parameter passed in is the Spring -container itself. You are interacting with the application context through its -`ApplicationEventPublisher` interface. - -To receive the custom `ApplicationEvent`, you can create a class that implements -`ApplicationListener` and register it as a Spring bean. The following example -shows such a class: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class BlockedListNotifier implements ApplicationListener { - - private String notificationAddress; - - public void setNotificationAddress(String notificationAddress) { - this.notificationAddress = notificationAddress; - } - - public void onApplicationEvent(BlockedListEvent event) { - // notify appropriate parties via notificationAddress... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class BlockedListNotifier : ApplicationListener { - - lateinit var notificationAddress: String - - override fun onApplicationEvent(event: BlockedListEvent) { - // notify appropriate parties via notificationAddress... - } - } ----- - -Notice that `ApplicationListener` is generically parameterized with the type of your -custom event (`BlockedListEvent` in the preceding example). This means that the -`onApplicationEvent()` method can remain type-safe, avoiding any need for downcasting. -You can register as many event listeners as you wish, but note that, by default, event -listeners receive events synchronously. This means that the `publishEvent()` method -blocks until all listeners have finished processing the event. One advantage of this -synchronous and single-threaded approach is that, when a listener receives an event, it -operates inside the transaction context of the publisher if a transaction context is -available. If another strategy for event publication becomes necessary, see the javadoc -for Spring's -{api-spring-framework}/context/event/ApplicationEventMulticaster.html[`ApplicationEventMulticaster`] interface -and {api-spring-framework}/context/event/SimpleApplicationEventMulticaster.html[`SimpleApplicationEventMulticaster`] -implementation for configuration options. - -The following example shows the bean definitions used to register and configure each of -the classes above: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - known.spammer@example.org - known.hacker@example.org - john.doe@example.org - - - - - - - ----- - -Putting it all together, when the `sendEmail()` method of the `emailService` bean is -called, if there are any email messages that should be blocked, a custom event of type -`BlockedListEvent` is published. The `blockedListNotifier` bean is registered as an -`ApplicationListener` and receives the `BlockedListEvent`, at which point it can -notify appropriate parties. - -NOTE: Spring's eventing mechanism is designed for simple communication between Spring beans -within the same application context. However, for more sophisticated enterprise -integration needs, the separately maintained -https://projects.spring.io/spring-integration/[Spring Integration] project provides -complete support for building lightweight, -https://www.enterpriseintegrationpatterns.com[pattern-oriented], event-driven -architectures that build upon the well-known Spring programming model. - - -[[context-functionality-events-annotation]] -==== Annotation-based Event Listeners - -You can register an event listener on any method of a managed bean by using the -`@EventListener` annotation. The `BlockedListNotifier` can be rewritten as follows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class BlockedListNotifier { - - private String notificationAddress; - - public void setNotificationAddress(String notificationAddress) { - this.notificationAddress = notificationAddress; - } - - @EventListener - public void processBlockedListEvent(BlockedListEvent event) { - // notify appropriate parties via notificationAddress... - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class BlockedListNotifier { - - lateinit var notificationAddress: String - - @EventListener - fun processBlockedListEvent(event: BlockedListEvent) { - // notify appropriate parties via notificationAddress... - } - } ----- - -The method signature once again declares the event type to which it listens, -but, this time, with a flexible name and without implementing a specific listener interface. -The event type can also be narrowed through generics as long as the actual event type -resolves your generic parameter in its implementation hierarchy. - -If your method should listen to several events or if you want to define it with no -parameter at all, the event types can also be specified on the annotation itself. The -following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @EventListener({ContextStartedEvent.class, ContextRefreshedEvent.class}) - public void handleContextStart() { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @EventListener(ContextStartedEvent::class, ContextRefreshedEvent::class) - fun handleContextStart() { - // ... - } ----- - -It is also possible to add additional runtime filtering by using the `condition` attribute -of the annotation that defines a <>, which should match -to actually invoke the method for a particular event. - -The following example shows how our notifier can be rewritten to be invoked only if the -`content` attribute of the event is equal to `my-event`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @EventListener(condition = "#blEvent.content == 'my-event'") - public void processBlockedListEvent(BlockedListEvent blEvent) { - // notify appropriate parties via notificationAddress... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @EventListener(condition = "#blEvent.content == 'my-event'") - fun processBlockedListEvent(blEvent: BlockedListEvent) { - // notify appropriate parties via notificationAddress... - } ----- - -Each `SpEL` expression evaluates against a dedicated context. The following table lists the -items made available to the context so that you can use them for conditional event processing: - -[[context-functionality-events-annotation-tbl]] -.Event SpEL available metadata -|=== -| Name| Location| Description| Example - -| Event -| root object -| The actual `ApplicationEvent`. -| `#root.event` or `event` - -| Arguments array -| root object -| The arguments (as an object array) used to invoke the method. -| `#root.args` or `args`; `args[0]` to access the first argument, etc. - -| __Argument name__ -| evaluation context -| The name of any of the method arguments. If, for some reason, the names are not available - (for example, because there is no debug information in the compiled byte code), individual - arguments are also available using the `#a<#arg>` syntax where `<#arg>` stands for the - argument index (starting from 0). -| `#blEvent` or `#a0` (you can also use `#p0` or `#p<#arg>` parameter notation as an alias) -|=== - -Note that `#root.event` gives you access to the underlying event, even if your method -signature actually refers to an arbitrary object that was published. - -If you need to publish an event as the result of processing another event, you can change the -method signature to return the event that should be published, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @EventListener - public ListUpdateEvent handleBlockedListEvent(BlockedListEvent event) { - // notify appropriate parties via notificationAddress and - // then publish a ListUpdateEvent... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @EventListener - fun handleBlockedListEvent(event: BlockedListEvent): ListUpdateEvent { - // notify appropriate parties via notificationAddress and - // then publish a ListUpdateEvent... - } ----- - -NOTE: This feature is not supported for -<>. - -The `handleBlockedListEvent()` method publishes a new `ListUpdateEvent` for every -`BlockedListEvent` that it handles. If you need to publish several events, you can return -a `Collection` or an array of events instead. - - -[[context-functionality-events-async]] -==== Asynchronous Listeners - -If you want a particular listener to process events asynchronously, you can reuse the -<>. -The following example shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @EventListener - @Async - public void processBlockedListEvent(BlockedListEvent event) { - // BlockedListEvent is processed in a separate thread - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @EventListener - @Async - fun processBlockedListEvent(event: BlockedListEvent) { - // BlockedListEvent is processed in a separate thread - } ----- - -Be aware of the following limitations when using asynchronous events: - -* If an asynchronous event listener throws an `Exception`, it is not propagated to the - caller. See - {api-spring-framework}/aop/interceptor/AsyncUncaughtExceptionHandler.html[`AsyncUncaughtExceptionHandler`] - for more details. -* Asynchronous event listener methods cannot publish a subsequent event by returning a - value. If you need to publish another event as the result of the processing, inject an - {api-spring-framework}/context/ApplicationEventPublisher.html[`ApplicationEventPublisher`] - to publish the event manually. - - -[[context-functionality-events-order]] -==== Ordering Listeners - -If you need one listener to be invoked before another one, you can add the `@Order` -annotation to the method declaration, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @EventListener - @Order(42) - public void processBlockedListEvent(BlockedListEvent event) { - // notify appropriate parties via notificationAddress... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @EventListener - @Order(42) - fun processBlockedListEvent(event: BlockedListEvent) { - // notify appropriate parties via notificationAddress... - } ----- - - -[[context-functionality-events-generics]] -==== Generic Events - -You can also use generics to further define the structure of your event. Consider using an -`EntityCreatedEvent` where `T` is the type of the actual entity that got created. For example, you -can create the following listener definition to receive only `EntityCreatedEvent` for a -`Person`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - @EventListener - public void onPersonCreated(EntityCreatedEvent event) { - // ... - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - @EventListener - fun onPersonCreated(event: EntityCreatedEvent) { - // ... - } ----- - -Due to type erasure, this works only if the event that is fired resolves the generic -parameters on which the event listener filters (that is, something like -`class PersonCreatedEvent extends EntityCreatedEvent { ... }`). - -In certain circumstances, this may become quite tedious if all events follow the same -structure (as should be the case for the event in the preceding example). In such a case, -you can implement `ResolvableTypeProvider` to guide the framework beyond what the runtime -environment provides. The following event shows how to do so: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - public class EntityCreatedEvent extends ApplicationEvent implements ResolvableTypeProvider { - - public EntityCreatedEvent(T entity) { - super(entity); - } - - @Override - public ResolvableType getResolvableType() { - return ResolvableType.forClassWithGenerics(getClass(), ResolvableType.forInstance(getSource())); - } - } ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - class EntityCreatedEvent(entity: T) : ApplicationEvent(entity), ResolvableTypeProvider { - - override fun getResolvableType(): ResolvableType? { - return ResolvableType.forClassWithGenerics(javaClass, ResolvableType.forInstance(getSource())) - } - } ----- - -TIP: This works not only for `ApplicationEvent` but any arbitrary object that you send as -an event. - - - -[[context-functionality-resources]] -=== Convenient Access to Low-level Resources - -For optimal usage and understanding of application contexts, you should familiarize -yourself with Spring's `Resource` abstraction, as described in <>. - -An application context is a `ResourceLoader`, which can be used to load `Resource` objects. -A `Resource` is essentially a more feature rich version of the JDK `java.net.URL` class. -In fact, the implementations of the `Resource` wrap an instance of `java.net.URL`, where -appropriate. A `Resource` can obtain low-level resources from almost any location in a -transparent fashion, including from the classpath, a filesystem location, anywhere -describable with a standard URL, and some other variations. If the resource location -string is a simple path without any special prefixes, where those resources come from is -specific and appropriate to the actual application context type. - -You can configure a bean deployed into the application context to implement the special -callback interface, `ResourceLoaderAware`, to be automatically called back at -initialization time with the application context itself passed in as the `ResourceLoader`. -You can also expose properties of type `Resource`, to be used to access static resources. -They are injected into it like any other properties. You can specify those `Resource` -properties as simple `String` paths and rely on automatic conversion from those text -strings to actual `Resource` objects when the bean is deployed. - -The location path or paths supplied to an `ApplicationContext` constructor are actually -resource strings and, in simple form, are treated appropriately according to the specific -context implementation. For example `ClassPathXmlApplicationContext` treats a simple -location path as a classpath location. You can also use location paths (resource strings) -with special prefixes to force loading of definitions from the classpath or a URL, -regardless of the actual context type. - - - -[[context-functionality-startup]] -=== Application Startup Tracking - -The `ApplicationContext` manages the lifecycle of Spring applications and provides a rich -programming model around components. As a result, complex applications can have equally -complex component graphs and startup phases. - -Tracking the application startup steps with specific metrics can help understand where -time is being spent during the startup phase, but it can also be used as a way to better -understand the context lifecycle as a whole. - -The `AbstractApplicationContext` (and its subclasses) is instrumented with an -`ApplicationStartup`, which collects `StartupStep` data about various startup phases: - -* application context lifecycle (base packages scanning, config classes management) -* beans lifecycle (instantiation, smart initialization, post processing) -* application events processing - -Here is an example of instrumentation in the `AnnotationConfigApplicationContext`: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - // create a startup step and start recording - StartupStep scanPackages = this.getApplicationStartup().start("spring.context.base-packages.scan"); - // add tagging information to the current step - scanPackages.tag("packages", () -> Arrays.toString(basePackages)); - // perform the actual phase we're instrumenting - this.scanner.scan(basePackages); - // end the current step - scanPackages.end(); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - // create a startup step and start recording - val scanPackages = this.getApplicationStartup().start("spring.context.base-packages.scan") - // add tagging information to the current step - scanPackages.tag("packages", () -> Arrays.toString(basePackages)) - // perform the actual phase we're instrumenting - this.scanner.scan(basePackages) - // end the current step - scanPackages.end() ----- - -The application context is already instrumented with multiple steps. -Once recorded, these startup steps can be collected, displayed and analyzed with specific tools. -For a complete list of existing startup steps, you can check out the -<>. - -The default `ApplicationStartup` implementation is a no-op variant, for minimal overhead. -This means no metrics will be collected during application startup by default. -Spring Framework ships with an implementation for tracking startup steps with Java Flight Recorder: -`FlightRecorderApplicationStartup`. To use this variant, you must configure an instance of it -to the `ApplicationContext` as soon as it's been created. - -Developers can also use the `ApplicationStartup` infrastructure if they're providing their own -`AbstractApplicationContext` subclass, or if they wish to collect more precise data. - -WARNING: `ApplicationStartup` is meant to be only used during application startup and for -the core container; this is by no means a replacement for Java profilers or -metrics libraries like https://micrometer.io[Micrometer]. - -To start collecting custom `StartupStep`, components can either get the `ApplicationStartup` -instance from the application context directly, make their component implement `ApplicationStartupAware`, -or ask for the `ApplicationStartup` type on any injection point. - -NOTE: Developers should not use the `"spring.*"` namespace when creating custom startup steps. -This namespace is reserved for internal Spring usage and is subject to change. - -[[context-create]] -=== Convenient ApplicationContext Instantiation for Web Applications - -You can create `ApplicationContext` instances declaratively by using, for example, a -`ContextLoader`. Of course, you can also create `ApplicationContext` instances -programmatically by using one of the `ApplicationContext` implementations. - -You can register an `ApplicationContext` by using the `ContextLoaderListener`, as the -following example shows: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - contextConfigLocation - /WEB-INF/daoContext.xml /WEB-INF/applicationContext.xml - - - - org.springframework.web.context.ContextLoaderListener - ----- - -The listener inspects the `contextConfigLocation` parameter. If the parameter does not -exist, the listener uses `/WEB-INF/applicationContext.xml` as a default. When the -parameter does exist, the listener separates the `String` by using predefined -delimiters (comma, semicolon, and whitespace) and uses the values as locations where -application contexts are searched. Ant-style path patterns are supported as well. -Examples are `/WEB-INF/{asterisk}Context.xml` (for all files with names that end with -`Context.xml` and that reside in the `WEB-INF` directory) and `/WEB-INF/**/*Context.xml` -(for all such files in any subdirectory of `WEB-INF`). - - - -[[context-deploy-rar]] -=== Deploying a Spring `ApplicationContext` as a Jakarta EE RAR File - -It is possible to deploy a Spring `ApplicationContext` as a RAR file, encapsulating the -context and all of its required bean classes and library JARs in a Jakarta EE RAR deployment -unit. This is the equivalent of bootstrapping a stand-alone `ApplicationContext` (only hosted -in Jakarta EE environment) being able to access the Jakarta EE servers facilities. RAR deployment -is a more natural alternative to a scenario of deploying a headless WAR file -- in effect, -a WAR file without any HTTP entry points that is used only for bootstrapping a Spring -`ApplicationContext` in a Jakarta EE environment. - -RAR deployment is ideal for application contexts that do not need HTTP entry points but -rather consist only of message endpoints and scheduled jobs. Beans in such a context can -use application server resources such as the JTA transaction manager and JNDI-bound JDBC -`DataSource` instances and JMS `ConnectionFactory` instances and can also register with -the platform's JMX server -- all through Spring's standard transaction management and JNDI -and JMX support facilities. Application components can also interact with the application -server's JCA `WorkManager` through Spring's `TaskExecutor` abstraction. - -See the javadoc of the -{api-spring-framework}/jca/context/SpringContextResourceAdapter.html[`SpringContextResourceAdapter`] -class for the configuration details involved in RAR deployment. - -For a simple deployment of a Spring ApplicationContext as a Jakarta EE RAR file: - -. Package -all application classes into a RAR file (which is a standard JAR file with a different -file extension). -. Add all required library JARs into the root of the RAR archive. -. Add a -`META-INF/ra.xml` deployment descriptor (as shown in the {api-spring-framework}/jca/context/SpringContextResourceAdapter.html[javadoc for `SpringContextResourceAdapter`]) -and the corresponding Spring XML bean definition file(s) (typically -`META-INF/applicationContext.xml`). -. Drop the resulting RAR file into your -application server's deployment directory. - -NOTE: Such RAR deployment units are usually self-contained. They do not expose components -to the outside world, not even to other modules of the same application. Interaction with a -RAR-based `ApplicationContext` usually occurs through JMS destinations that it shares with -other modules. A RAR-based `ApplicationContext` may also, for example, schedule some jobs -or react to new files in the file system (or the like). If it needs to allow synchronous -access from the outside, it could (for example) export RMI endpoints, which may be used -by other application modules on the same machine. - - - - -[[beans-beanfactory]] -== The `BeanFactory` API - -The `BeanFactory` API provides the underlying basis for Spring's IoC functionality. -Its specific contracts are mostly used in integration with other parts of Spring and -related third-party frameworks, and its `DefaultListableBeanFactory` implementation -is a key delegate within the higher-level `GenericApplicationContext` container. - -`BeanFactory` and related interfaces (such as `BeanFactoryAware`, `InitializingBean`, -`DisposableBean`) are important integration points for other framework components. -By not requiring any annotations or even reflection, they allow for very efficient -interaction between the container and its components. Application-level beans may -use the same callback interfaces but typically prefer declarative dependency -injection instead, either through annotations or through programmatic configuration. - -Note that the core `BeanFactory` API level and its `DefaultListableBeanFactory` -implementation do not make assumptions about the configuration format or any -component annotations to be used. All of these flavors come in through extensions -(such as `XmlBeanDefinitionReader` and `AutowiredAnnotationBeanPostProcessor`) and -operate on shared `BeanDefinition` objects as a core metadata representation. -This is the essence of what makes Spring's container so flexible and extensible. - - - -[[context-introduction-ctx-vs-beanfactory]] -=== `BeanFactory` or `ApplicationContext`? - -This section explains the differences between the `BeanFactory` and -`ApplicationContext` container levels and the implications on bootstrapping. - -You should use an `ApplicationContext` unless you have a good reason for not doing so, with -`GenericApplicationContext` and its subclass `AnnotationConfigApplicationContext` -as the common implementations for custom bootstrapping. These are the primary entry -points to Spring's core container for all common purposes: loading of configuration -files, triggering a classpath scan, programmatically registering bean definitions -and annotated classes, and (as of 5.0) registering functional bean definitions. - -Because an `ApplicationContext` includes all the functionality of a `BeanFactory`, it is -generally recommended over a plain `BeanFactory`, except for scenarios where full -control over bean processing is needed. Within an `ApplicationContext` (such as the -`GenericApplicationContext` implementation), several kinds of beans are detected -by convention (that is, by bean name or by bean type -- in particular, post-processors), -while a plain `DefaultListableBeanFactory` is agnostic about any special beans. - -For many extended container features, such as annotation processing and AOP proxying, -the <> is essential. -If you use only a plain `DefaultListableBeanFactory`, such post-processors do not -get detected and activated by default. This situation could be confusing, because -nothing is actually wrong with your bean configuration. Rather, in such a scenario, -the container needs to be fully bootstrapped through additional setup. - -The following table lists features provided by the `BeanFactory` and -`ApplicationContext` interfaces and implementations. - -[[context-introduction-ctx-vs-beanfactory-feature-matrix]] -.Feature Matrix -[cols="50%,25%,25%"] -|=== -| Feature | `BeanFactory` | `ApplicationContext` - -| Bean instantiation/wiring -| Yes -| Yes - -| Integrated lifecycle management -| No -| Yes - -| Automatic `BeanPostProcessor` registration -| No -| Yes - -| Automatic `BeanFactoryPostProcessor` registration -| No -| Yes - -| Convenient `MessageSource` access (for internationalization) -| No -| Yes - -| Built-in `ApplicationEvent` publication mechanism -| No -| Yes -|=== - -To explicitly register a bean post-processor with a `DefaultListableBeanFactory`, -you need to programmatically call `addBeanPostProcessor`, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - DefaultListableBeanFactory factory = new DefaultListableBeanFactory(); - // populate the factory with bean definitions - - // now register any needed BeanPostProcessor instances - factory.addBeanPostProcessor(new AutowiredAnnotationBeanPostProcessor()); - factory.addBeanPostProcessor(new MyBeanPostProcessor()); - - // now start using the factory ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val factory = DefaultListableBeanFactory() - // populate the factory with bean definitions - - // now register any needed BeanPostProcessor instances - factory.addBeanPostProcessor(AutowiredAnnotationBeanPostProcessor()) - factory.addBeanPostProcessor(MyBeanPostProcessor()) - - // now start using the factory ----- - -To apply a `BeanFactoryPostProcessor` to a plain `DefaultListableBeanFactory`, -you need to call its `postProcessBeanFactory` method, as the following example shows: - -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java ----- - DefaultListableBeanFactory factory = new DefaultListableBeanFactory(); - XmlBeanDefinitionReader reader = new XmlBeanDefinitionReader(factory); - reader.loadBeanDefinitions(new FileSystemResource("beans.xml")); - - // bring in some property values from a Properties file - PropertySourcesPlaceholderConfigurer cfg = new PropertySourcesPlaceholderConfigurer(); - cfg.setLocation(new FileSystemResource("jdbc.properties")); - - // now actually do the replacement - cfg.postProcessBeanFactory(factory); ----- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - val factory = DefaultListableBeanFactory() - val reader = XmlBeanDefinitionReader(factory) - reader.loadBeanDefinitions(FileSystemResource("beans.xml")) - - // bring in some property values from a Properties file - val cfg = PropertySourcesPlaceholderConfigurer() - cfg.setLocation(FileSystemResource("jdbc.properties")) - - // now actually do the replacement - cfg.postProcessBeanFactory(factory) ----- - -In both cases, the explicit registration steps are inconvenient, which is -why the various `ApplicationContext` variants are preferred over a plain -`DefaultListableBeanFactory` in Spring-backed applications, especially when -relying on `BeanFactoryPostProcessor` and `BeanPostProcessor` instances for extended -container functionality in a typical enterprise setup. - -[NOTE] -==== -An `AnnotationConfigApplicationContext` has all common annotation post-processors -registered and may bring in additional processors underneath the -covers through configuration annotations, such as `@EnableTransactionManagement`. -At the abstraction level of Spring's annotation-based configuration model, -the notion of bean post-processors becomes a mere internal container detail. -==== diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc new file mode 100644 index 000000000000..5c6d43e19d10 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc @@ -0,0 +1,81 @@ +[[beans-annotation-config]] += Annotation-based Container Configuration + +.Are annotations better than XML for configuring Spring? +**** +The introduction of annotation-based configuration raised the question of whether this +approach is "`better`" than XML. The short answer is "`it depends.`" The long answer is +that each approach has its pros and cons, and, usually, it is up to the developer to +decide which strategy suits them better. Due to the way they are defined, annotations +provide a lot of context in their declaration, leading to shorter and more concise +configuration. However, XML excels at wiring up components without touching their source +code or recompiling them. Some developers prefer having the wiring close to the source +while others argue that annotated classes are no longer POJOs and, furthermore, that the +configuration becomes decentralized and harder to control. + +No matter the choice, Spring can accommodate both styles and even mix them together. +It is worth pointing out that through its <> option, Spring lets +annotations be used in a non-invasive way, without touching the target components' +source code and that, in terms of tooling, all configuration styles are supported by +https://spring.io/tools[Spring Tools] for Eclipse, Visual Studio Code, and Theia. +**** + +An alternative to XML setup is provided by annotation-based configuration, which relies +on bytecode metadata for wiring up components instead of XML declarations. Instead of +using XML to describe a bean wiring, the developer moves the configuration into the +component class itself by using annotations on the relevant class, method, or field +declaration. As mentioned in <>, using a +`BeanPostProcessor` in conjunction with annotations is a common means of extending the +Spring IoC container. For example, the <> +annotation provides the same capabilities as described in <> but +with more fine-grained control and wider applicability. In addition, Spring provides +support for JSR-250 annotations, such as `@PostConstruct` and `@PreDestroy`, as well as +support for JSR-330 (Dependency Injection for Java) annotations contained in the +`jakarta.inject` package such as `@Inject` and `@Named`. Details about those annotations +can be found in the <>. + +[NOTE] +==== +Annotation injection is performed before XML injection. Thus, the XML configuration +overrides the annotations for properties wired through both approaches. +==== + +As always, you can register the post-processors as individual bean definitions, but they +can also be implicitly registered by including the following tag in an XML-based Spring +configuration (notice the inclusion of the `context` namespace): + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + +---- + +The `` element implicitly registers the following post-processors: + +* {api-spring-framework}/context/annotation/ConfigurationClassPostProcessor.html[`ConfigurationClassPostProcessor`] +* {api-spring-framework}/beans/factory/annotation/AutowiredAnnotationBeanPostProcessor.html[`AutowiredAnnotationBeanPostProcessor`] +* {api-spring-framework}/context/annotation/CommonAnnotationBeanPostProcessor.html[`CommonAnnotationBeanPostProcessor`] +* {api-spring-framework}/orm/jpa/support/PersistenceAnnotationBeanPostProcessor.html[`PersistenceAnnotationBeanPostProcessor`] +* {api-spring-framework}/context/event/EventListenerMethodProcessor.html[`EventListenerMethodProcessor`] + +[NOTE] +==== +`` only looks for annotations on beans in the same +application context in which it is defined. This means that, if you put +`` in a `WebApplicationContext` for a `DispatcherServlet`, +it only checks for `@Autowired` beans in your controllers, and not your services. See +<> for more information. +==== + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-primary.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-primary.adoc new file mode 100644 index 000000000000..7843d9835d65 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-primary.adoc @@ -0,0 +1,102 @@ +[[beans-autowired-annotation-primary]] += Fine-tuning Annotation-based Autowiring with `@Primary` + +Because autowiring by type may lead to multiple candidates, it is often necessary to have +more control over the selection process. One way to accomplish this is with Spring's +`@Primary` annotation. `@Primary` indicates that a particular bean should be given +preference when multiple beans are candidates to be autowired to a single-valued +dependency. If exactly one primary bean exists among the candidates, it becomes the +autowired value. + +Consider the following configuration that defines `firstMovieCatalog` as the +primary `MovieCatalog`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class MovieConfiguration { + + @Bean + @Primary + public MovieCatalog firstMovieCatalog() { ... } + + @Bean + public MovieCatalog secondMovieCatalog() { ... } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class MovieConfiguration { + + @Bean + @Primary + fun firstMovieCatalog(): MovieCatalog { ... } + + @Bean + fun secondMovieCatalog(): MovieCatalog { ... } + + // ... + } +---- + +With the preceding configuration, the following `MovieRecommender` is autowired with the +`firstMovieCatalog`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + @Autowired + private MovieCatalog movieCatalog; + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +class MovieRecommender { + + @Autowired + private lateinit var movieCatalog: MovieCatalog + + // ... +} +---- + +The corresponding bean definitions follow: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc new file mode 100644 index 000000000000..5d2c314078d1 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc @@ -0,0 +1,532 @@ +[[beans-autowired-annotation-qualifiers]] += Fine-tuning Annotation-based Autowiring with Qualifiers + +`@Primary` is an effective way to use autowiring by type with several instances when one +primary candidate can be determined. When you need more control over the selection process, +you can use Spring's `@Qualifier` annotation. You can associate qualifier values +with specific arguments, narrowing the set of type matches so that a specific bean is +chosen for each argument. In the simplest case, this can be a plain descriptive value, as +shown in the following example: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + @Autowired + @Qualifier("main") + private MovieCatalog movieCatalog; + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender { + + @Autowired + @Qualifier("main") + private lateinit var movieCatalog: MovieCatalog + + // ... + } +---- +-- + +You can also specify the `@Qualifier` annotation on individual constructor arguments or +method parameters, as shown in the following example: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + private final MovieCatalog movieCatalog; + + private final CustomerPreferenceDao customerPreferenceDao; + + @Autowired + public void prepare(@Qualifier("main") MovieCatalog movieCatalog, + CustomerPreferenceDao customerPreferenceDao) { + this.movieCatalog = movieCatalog; + this.customerPreferenceDao = customerPreferenceDao; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender { + + private lateinit var movieCatalog: MovieCatalog + + private lateinit var customerPreferenceDao: CustomerPreferenceDao + + @Autowired + fun prepare(@Qualifier("main") movieCatalog: MovieCatalog, + customerPreferenceDao: CustomerPreferenceDao) { + this.movieCatalog = movieCatalog + this.customerPreferenceDao = customerPreferenceDao + } + + // ... + } +---- +-- + +The following example shows corresponding bean definitions. + +-- +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + <1> + + + + + + <2> + + + + + + + +---- +<1> The bean with the `main` qualifier value is wired with the constructor argument that +is qualified with the same value. +<2> The bean with the `action` qualifier value is wired with the constructor argument that +is qualified with the same value. +-- + +For a fallback match, the bean name is considered a default qualifier value. Thus, you +can define the bean with an `id` of `main` instead of the nested qualifier element, leading +to the same matching result. However, although you can use this convention to refer to +specific beans by name, `@Autowired` is fundamentally about type-driven injection with +optional semantic qualifiers. This means that qualifier values, even with the bean name +fallback, always have narrowing semantics within the set of type matches. They do not +semantically express a reference to a unique bean `id`. Good qualifier values are `main` +or `EMEA` or `persistent`, expressing characteristics of a specific component that are +independent from the bean `id`, which may be auto-generated in case of an anonymous bean +definition such as the one in the preceding example. + +Qualifiers also apply to typed collections, as discussed earlier -- for example, to +`Set`. In this case, all matching beans, according to the declared +qualifiers, are injected as a collection. This implies that qualifiers do not have to be +unique. Rather, they constitute filtering criteria. For example, you can define +multiple `MovieCatalog` beans with the same qualifier value "`action`", all of which are +injected into a `Set` annotated with `@Qualifier("action")`. + +[TIP] +==== +Letting qualifier values select against target bean names, within the type-matching +candidates, does not require a `@Qualifier` annotation at the injection point. +If there is no other resolution indicator (such as a qualifier or a primary marker), +for a non-unique dependency situation, Spring matches the injection point name +(that is, the field name or parameter name) against the target bean names and chooses the +same-named candidate, if any. +==== + +That said, if you intend to express annotation-driven injection by name, do not +primarily use `@Autowired`, even if it is capable of selecting by bean name among +type-matching candidates. Instead, use the JSR-250 `@Resource` annotation, which is +semantically defined to identify a specific target component by its unique name, with +the declared type being irrelevant for the matching process. `@Autowired` has rather +different semantics: After selecting candidate beans by type, the specified `String` +qualifier value is considered within those type-selected candidates only (for example, +matching an `account` qualifier against beans marked with the same qualifier label). + +For beans that are themselves defined as a collection, `Map`, or array type, `@Resource` +is a fine solution, referring to the specific collection or array bean by unique name. +That said, as of 4.3, you can match collection, `Map`, and array types through Spring's +`@Autowired` type matching algorithm as well, as long as the element type information +is preserved in `@Bean` return type signatures or collection inheritance hierarchies. +In this case, you can use qualifier values to select among same-typed collections, +as outlined in the previous paragraph. + +As of 4.3, `@Autowired` also considers self references for injection (that is, references +back to the bean that is currently injected). Note that self injection is a fallback. +Regular dependencies on other components always have precedence. In that sense, self +references do not participate in regular candidate selection and are therefore in +particular never primary. On the contrary, they always end up as lowest precedence. +In practice, you should use self references as a last resort only (for example, for +calling other methods on the same instance through the bean's transactional proxy). +Consider factoring out the affected methods to a separate delegate bean in such a scenario. +Alternatively, you can use `@Resource`, which may obtain a proxy back to the current bean +by its unique name. + +[NOTE] +==== +Trying to inject the results from `@Bean` methods on the same configuration class is +effectively a self-reference scenario as well. Either lazily resolve such references +in the method signature where it is actually needed (as opposed to an autowired field +in the configuration class) or declare the affected `@Bean` methods as `static`, +decoupling them from the containing configuration class instance and its lifecycle. +Otherwise, such beans are only considered in the fallback phase, with matching beans +on other configuration classes selected as primary candidates instead (if available). +==== + +`@Autowired` applies to fields, constructors, and multi-argument methods, allowing for +narrowing through qualifier annotations at the parameter level. In contrast, `@Resource` +is supported only for fields and bean property setter methods with a single argument. +As a consequence, you should stick with qualifiers if your injection target is a +constructor or a multi-argument method. + +You can create your own custom qualifier annotations. To do so, define an annotation and +provide the `@Qualifier` annotation within your definition, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target({ElementType.FIELD, ElementType.PARAMETER}) + @Retention(RetentionPolicy.RUNTIME) + @Qualifier + public @interface Genre { + + String value(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER) + @Retention(AnnotationRetention.RUNTIME) + @Qualifier + annotation class Genre(val value: String) +---- +-- + +Then you can provide the custom qualifier on autowired fields and parameters, as the +following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + @Autowired + @Genre("Action") + private MovieCatalog actionCatalog; + + private MovieCatalog comedyCatalog; + + @Autowired + public void setComedyCatalog(@Genre("Comedy") MovieCatalog comedyCatalog) { + this.comedyCatalog = comedyCatalog; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender { + + @Autowired + @Genre("Action") + private lateinit var actionCatalog: MovieCatalog + + private lateinit var comedyCatalog: MovieCatalog + + @Autowired + fun setComedyCatalog(@Genre("Comedy") comedyCatalog: MovieCatalog) { + this.comedyCatalog = comedyCatalog + } + + // ... + } +---- +-- + +Next, you can provide the information for the candidate bean definitions. You can add +`` tags as sub-elements of the `` tag and then specify the `type` and +`value` to match your custom qualifier annotations. The type is matched against the +fully-qualified class name of the annotation. Alternately, as a convenience if no risk of +conflicting names exists, you can use the short class name. The following example +demonstrates both approaches: + +-- +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + + + +---- +-- + +In <>, you can see an annotation-based alternative to +providing the qualifier metadata in XML. Specifically, see <>. + +In some cases, using an annotation without a value may suffice. This can be +useful when the annotation serves a more generic purpose and can be applied across +several different types of dependencies. For example, you may provide an offline +catalog that can be searched when no Internet connection is available. First, define +the simple annotation, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target({ElementType.FIELD, ElementType.PARAMETER}) + @Retention(RetentionPolicy.RUNTIME) + @Qualifier + public @interface Offline { + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER) + @Retention(AnnotationRetention.RUNTIME) + @Qualifier + annotation class Offline +---- +-- + +Then add the annotation to the field or property to be autowired, as shown in the +following example: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + @Autowired + @Offline // <1> + private MovieCatalog offlineCatalog; + + // ... + } +---- +<1> This line adds the `@Offline` annotation. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +class MovieRecommender { + + @Autowired + @Offline // <1> + private lateinit var offlineCatalog: MovieCatalog + + // ... +} +---- +<1> This line adds the `@Offline` annotation. +-- + +Now the bean definition only needs a qualifier `type`, as shown in the following example: + +-- +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + <1> + + +---- +<1> This element specifies the qualifier. +-- + + +You can also define custom qualifier annotations that accept named attributes in +addition to or instead of the simple `value` attribute. If multiple attribute values are +then specified on a field or parameter to be autowired, a bean definition must match +all such attribute values to be considered an autowire candidate. As an example, +consider the following annotation definition: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target({ElementType.FIELD, ElementType.PARAMETER}) + @Retention(RetentionPolicy.RUNTIME) + @Qualifier + public @interface MovieQualifier { + + String genre(); + + Format format(); + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER) + @Retention(AnnotationRetention.RUNTIME) + @Qualifier + annotation class MovieQualifier(val genre: String, val format: Format) +---- +-- + +In this case `Format` is an enum, defined as follows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public enum Format { + VHS, DVD, BLURAY + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + enum class Format { + VHS, DVD, BLURAY + } +---- +-- + +The fields to be autowired are annotated with the custom qualifier and include values +for both attributes: `genre` and `format`, as the following example shows: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + @Autowired + @MovieQualifier(format=Format.VHS, genre="Action") + private MovieCatalog actionVhsCatalog; + + @Autowired + @MovieQualifier(format=Format.VHS, genre="Comedy") + private MovieCatalog comedyVhsCatalog; + + @Autowired + @MovieQualifier(format=Format.DVD, genre="Action") + private MovieCatalog actionDvdCatalog; + + @Autowired + @MovieQualifier(format=Format.BLURAY, genre="Comedy") + private MovieCatalog comedyBluRayCatalog; + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender { + + @Autowired + @MovieQualifier(format = Format.VHS, genre = "Action") + private lateinit var actionVhsCatalog: MovieCatalog + + @Autowired + @MovieQualifier(format = Format.VHS, genre = "Comedy") + private lateinit var comedyVhsCatalog: MovieCatalog + + @Autowired + @MovieQualifier(format = Format.DVD, genre = "Action") + private lateinit var actionDvdCatalog: MovieCatalog + + @Autowired + @MovieQualifier(format = Format.BLURAY, genre = "Comedy") + private lateinit var comedyBluRayCatalog: MovieCatalog + + // ... + } +---- +-- + +Finally, the bean definitions should contain matching qualifier values. This example +also demonstrates that you can use bean meta attributes instead of the +`` elements. If available, the `` element and its attributes take +precedence, but the autowiring mechanism falls back on the values provided within the +`` tags if no such qualifier is present, as in the last two bean definitions in +the following example: + +-- +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +---- +-- + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc new file mode 100644 index 000000000000..d63163b1957b --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc @@ -0,0 +1,432 @@ +[[beans-autowired-annotation]] += Using `@Autowired` + +[NOTE] +==== +JSR 330's `@Inject` annotation can be used in place of Spring's `@Autowired` annotation in the +examples included in this section. See <> for more details. +==== + +You can apply the `@Autowired` annotation to constructors, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + private final CustomerPreferenceDao customerPreferenceDao; + + @Autowired + public MovieRecommender(CustomerPreferenceDao customerPreferenceDao) { + this.customerPreferenceDao = customerPreferenceDao; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender @Autowired constructor( + private val customerPreferenceDao: CustomerPreferenceDao) +---- + +[NOTE] +==== +As of Spring Framework 4.3, an `@Autowired` annotation on such a constructor is no longer +necessary if the target bean defines only one constructor to begin with. However, if +several constructors are available and there is no primary/default constructor, at least +one of the constructors must be annotated with `@Autowired` in order to instruct the +container which one to use. See the discussion on +<> for details. +==== + +You can also apply the `@Autowired` annotation to _traditional_ setter methods, +as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleMovieLister { + + private MovieFinder movieFinder; + + @Autowired + public void setMovieFinder(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SimpleMovieLister { + + @set:Autowired + lateinit var movieFinder: MovieFinder + + // ... + + } +---- + +You can also apply the annotation to methods with arbitrary names and multiple +arguments, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + private MovieCatalog movieCatalog; + + private CustomerPreferenceDao customerPreferenceDao; + + @Autowired + public void prepare(MovieCatalog movieCatalog, + CustomerPreferenceDao customerPreferenceDao) { + this.movieCatalog = movieCatalog; + this.customerPreferenceDao = customerPreferenceDao; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender { + + private lateinit var movieCatalog: MovieCatalog + + private lateinit var customerPreferenceDao: CustomerPreferenceDao + + @Autowired + fun prepare(movieCatalog: MovieCatalog, + customerPreferenceDao: CustomerPreferenceDao) { + this.movieCatalog = movieCatalog + this.customerPreferenceDao = customerPreferenceDao + } + + // ... + } +---- + +You can apply `@Autowired` to fields as well and even mix it with constructors, as the +following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + private final CustomerPreferenceDao customerPreferenceDao; + + @Autowired + private MovieCatalog movieCatalog; + + @Autowired + public MovieRecommender(CustomerPreferenceDao customerPreferenceDao) { + this.customerPreferenceDao = customerPreferenceDao; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender @Autowired constructor( + private val customerPreferenceDao: CustomerPreferenceDao) { + + @Autowired + private lateinit var movieCatalog: MovieCatalog + + // ... + } +---- + +[TIP] +==== +Make sure that your target components (for example, `MovieCatalog` or `CustomerPreferenceDao`) +are consistently declared by the type that you use for your `@Autowired`-annotated +injection points. Otherwise, injection may fail due to a "no type match found" error at runtime. + +For XML-defined beans or component classes found via classpath scanning, the container +usually knows the concrete type up front. However, for `@Bean` factory methods, you need +to make sure that the declared return type is sufficiently expressive. For components +that implement several interfaces or for components potentially referred to by their +implementation type, consider declaring the most specific return type on your factory +method (at least as specific as required by the injection points referring to your bean). +==== + +You can also instruct Spring to provide all beans of a particular type from the +`ApplicationContext` by adding the `@Autowired` annotation to a field or method that +expects an array of that type, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + @Autowired + private MovieCatalog[] movieCatalogs; + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender { + + @Autowired + private lateinit var movieCatalogs: Array + + // ... + } +---- + +The same applies for typed collections, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + private Set movieCatalogs; + + @Autowired + public void setMovieCatalogs(Set movieCatalogs) { + this.movieCatalogs = movieCatalogs; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender { + + @Autowired + lateinit var movieCatalogs: Set + + // ... + } +---- + +[[beans-factory-ordered]] +[TIP] +==== +Your target beans can implement the `org.springframework.core.Ordered` interface or use +the `@Order` or standard `@Priority` annotation if you want items in the array or list +to be sorted in a specific order. Otherwise, their order follows the registration +order of the corresponding target bean definitions in the container. + +You can declare the `@Order` annotation at the target class level and on `@Bean` methods, +potentially for individual bean definitions (in case of multiple definitions that +use the same bean class). `@Order` values may influence priorities at injection points, +but be aware that they do not influence singleton startup order, which is an +orthogonal concern determined by dependency relationships and `@DependsOn` declarations. + +Note that the standard `jakarta.annotation.Priority` annotation is not available at the +`@Bean` level, since it cannot be declared on methods. Its semantics can be modeled +through `@Order` values in combination with `@Primary` on a single bean for each type. +==== + +Even typed `Map` instances can be autowired as long as the expected key type is `String`. +The map values contain all beans of the expected type, and the keys contain the +corresponding bean names, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + private Map movieCatalogs; + + @Autowired + public void setMovieCatalogs(Map movieCatalogs) { + this.movieCatalogs = movieCatalogs; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender { + + @Autowired + lateinit var movieCatalogs: Map + + // ... + } +---- + +By default, autowiring fails when no matching candidate beans are available for a given +injection point. In the case of a declared array, collection, or map, at least one +matching element is expected. + +The default behavior is to treat annotated methods and fields as indicating required +dependencies. You can change this behavior as demonstrated in the following example, +enabling the framework to skip a non-satisfiable injection point through marking it as +non-required (i.e., by setting the `required` attribute in `@Autowired` to `false`): + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleMovieLister { + + private MovieFinder movieFinder; + + @Autowired(required = false) + public void setMovieFinder(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SimpleMovieLister { + + @Autowired(required = false) + var movieFinder: MovieFinder? = null + + // ... + } +---- + +[NOTE] +==== +A non-required method will not be called at all if its dependency (or one of its +dependencies, in case of multiple arguments) is not available. A non-required field will +not get populated at all in such cases, leaving its default value in place. + +In other words, setting the `required` attribute to `false` indicates that the +corresponding property is _optional_ for autowiring purposes, and the property will be +ignored if it cannot be autowired. This allows properties to be assigned default values +that can be optionally overridden via dependency injection. +==== + + +[[beans-autowired-annotation-constructor-resolution]] + +Injected constructor and factory method arguments are a special case since the `required` +attribute in `@Autowired` has a somewhat different meaning due to Spring's constructor +resolution algorithm that may potentially deal with multiple constructors. Constructor +and factory method arguments are effectively required by default but with a few special +rules in a single-constructor scenario, such as multi-element injection points (arrays, +collections, maps) resolving to empty instances if no matching beans are available. This +allows for a common implementation pattern where all dependencies can be declared in a +unique multi-argument constructor — for example, declared as a single public constructor +without an `@Autowired` annotation. + +[NOTE] +==== +Only one constructor of any given bean class may declare `@Autowired` with the `required` +attribute set to `true`, indicating _the_ constructor to autowire when used as a Spring +bean. As a consequence, if the `required` attribute is left at its default value `true`, +only a single constructor may be annotated with `@Autowired`. If multiple constructors +declare the annotation, they will all have to declare `required=false` in order to be +considered as candidates for autowiring (analogous to `autowire=constructor` in XML). +The constructor with the greatest number of dependencies that can be satisfied by matching +beans in the Spring container will be chosen. If none of the candidates can be satisfied, +then a primary/default constructor (if present) will be used. Similarly, if a class +declares multiple constructors but none of them is annotated with `@Autowired`, then a +primary/default constructor (if present) will be used. If a class only declares a single +constructor to begin with, it will always be used, even if not annotated. Note that an +annotated constructor does not have to be public. +==== + +Alternatively, you can express the non-required nature of a particular dependency +through Java 8's `java.util.Optional`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + public class SimpleMovieLister { + + @Autowired + public void setMovieFinder(Optional movieFinder) { + ... + } + } +---- + +As of Spring Framework 5.0, you can also use a `@Nullable` annotation (of any kind +in any package -- for example, `javax.annotation.Nullable` from JSR-305) or just leverage +Kotlin built-in null-safety support: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleMovieLister { + + @Autowired + public void setMovieFinder(@Nullable MovieFinder movieFinder) { + ... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SimpleMovieLister { + + @Autowired + var movieFinder: MovieFinder? = null + + // ... + } +---- + +You can also use `@Autowired` for interfaces that are well-known resolvable +dependencies: `BeanFactory`, `ApplicationContext`, `Environment`, `ResourceLoader`, +`ApplicationEventPublisher`, and `MessageSource`. These interfaces and their extended +interfaces, such as `ConfigurableApplicationContext` or `ResourcePatternResolver`, are +automatically resolved, with no special setup necessary. The following example autowires +an `ApplicationContext` object: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + @Autowired + private ApplicationContext context; + + public MovieRecommender() { + } + + // ... + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +class MovieRecommender { + + @Autowired + lateinit var context: ApplicationContext + + // ... +} +---- + +[NOTE] +==== +The `@Autowired`, `@Inject`, `@Value`, and `@Resource` annotations are handled by Spring +`BeanPostProcessor` implementations. This means that you cannot apply these annotations +within your own `BeanPostProcessor` or `BeanFactoryPostProcessor` types (if any). +These types must be 'wired up' explicitly by using XML or a Spring `@Bean` method. +==== + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/custom-autowire-configurer.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/custom-autowire-configurer.adoc new file mode 100644 index 000000000000..34d63d008483 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/custom-autowire-configurer.adoc @@ -0,0 +1,33 @@ +[[beans-custom-autowire-configurer]] += Using `CustomAutowireConfigurer` + +{api-spring-framework}/beans/factory/annotation/CustomAutowireConfigurer.html[`CustomAutowireConfigurer`] +is a `BeanFactoryPostProcessor` that lets you register your own custom qualifier +annotation types, even if they are not annotated with Spring's `@Qualifier` annotation. +The following example shows how to use `CustomAutowireConfigurer`: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + example.CustomQualifier + + + +---- + +The `AutowireCandidateResolver` determines autowire candidates by: + +* The `autowire-candidate` value of each bean definition +* Any `default-autowire-candidates` patterns available on the `` element +* The presence of `@Qualifier` annotations and any custom annotations registered +with the `CustomAutowireConfigurer` + +When multiple beans qualify as autowire candidates, the determination of a "`primary`" is +as follows: If exactly one bean definition among the candidates has a `primary` +attribute set to `true`, it is selected. + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/generics-as-qualifiers.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/generics-as-qualifiers.adoc new file mode 100644 index 000000000000..0f081e2d3be9 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/generics-as-qualifiers.adoc @@ -0,0 +1,83 @@ +[[beans-generics-as-qualifiers]] += Using Generics as Autowiring Qualifiers + +In addition to the `@Qualifier` annotation, you can use Java generic types +as an implicit form of qualification. For example, suppose you have the following +configuration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class MyConfiguration { + + @Bean + public StringStore stringStore() { + return new StringStore(); + } + + @Bean + public IntegerStore integerStore() { + return new IntegerStore(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class MyConfiguration { + + @Bean + fun stringStore() = StringStore() + + @Bean + fun integerStore() = IntegerStore() + } +---- + +Assuming that the preceding beans implement a generic interface, (that is, `Store` and +`Store`), you can `@Autowire` the `Store` interface and the generic is +used as a qualifier, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Autowired + private Store s1; // qualifier, injects the stringStore bean + + @Autowired + private Store s2; // qualifier, injects the integerStore bean +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Autowired + private lateinit var s1: Store // qualifier, injects the stringStore bean + + @Autowired + private lateinit var s2: Store // qualifier, injects the integerStore bean +---- + +Generic qualifiers also apply when autowiring lists, `Map` instances and arrays. The +following example autowires a generic `List`: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // Inject all Store beans as long as they have an generic + // Store beans will not appear in this list + @Autowired + private List> s; +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + // Inject all Store beans as long as they have an generic + // Store beans will not appear in this list + @Autowired + private lateinit var s: List> +---- + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc new file mode 100644 index 000000000000..919410020245 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc @@ -0,0 +1,64 @@ +[[beans-postconstruct-and-predestroy-annotations]] += Using `@PostConstruct` and `@PreDestroy` + +The `CommonAnnotationBeanPostProcessor` not only recognizes the `@Resource` annotation +but also the JSR-250 lifecycle annotations: `jakarta.annotation.PostConstruct` and +`jakarta.annotation.PreDestroy`. Introduced in Spring 2.5, the support for these +annotations offers an alternative to the lifecycle callback mechanism described in +<> and +<>. Provided that the +`CommonAnnotationBeanPostProcessor` is registered within the Spring `ApplicationContext`, +a method carrying one of these annotations is invoked at the same point in the lifecycle +as the corresponding Spring lifecycle interface method or explicitly declared callback +method. In the following example, the cache is pre-populated upon initialization and +cleared upon destruction: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class CachingMovieLister { + + @PostConstruct + public void populateMovieCache() { + // populates the movie cache upon initialization... + } + + @PreDestroy + public void clearMovieCache() { + // clears the movie cache upon destruction... + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class CachingMovieLister { + + @PostConstruct + fun populateMovieCache() { + // populates the movie cache upon initialization... + } + + @PreDestroy + fun clearMovieCache() { + // clears the movie cache upon destruction... + } + } +---- + +For details about the effects of combining various lifecycle mechanisms, see +<>. + +[NOTE] +==== +Like `@Resource`, the `@PostConstruct` and `@PreDestroy` annotation types were a part +of the standard Java libraries from JDK 6 to 8. However, the entire `javax.annotation` +package got separated from the core Java modules in JDK 9 and eventually removed in +JDK 11. As of Jakarta EE 9, the package lives in `jakarta.annotation` now. If needed, +the `jakarta.annotation-api` artifact needs to be obtained via Maven Central now, +simply to be added to the application's classpath like any other library. +==== + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/resource.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/resource.adoc new file mode 100644 index 000000000000..1a3f02af6cfc --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/resource.adoc @@ -0,0 +1,129 @@ +[[beans-resource-annotation]] += Injection with `@Resource` + +Spring also supports injection by using the JSR-250 `@Resource` annotation +(`jakarta.annotation.Resource`) on fields or bean property setter methods. +This is a common pattern in Jakarta EE: for example, in JSF-managed beans and JAX-WS +endpoints. Spring supports this pattern for Spring-managed objects as well. + +`@Resource` takes a name attribute. By default, Spring interprets that value as +the bean name to be injected. In other words, it follows by-name semantics, +as demonstrated in the following example: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleMovieLister { + + private MovieFinder movieFinder; + + @Resource(name="myMovieFinder") // <1> + public void setMovieFinder(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + } +---- +<1> This line injects a `@Resource`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- +class SimpleMovieLister { + + @Resource(name="myMovieFinder") // <1> + private lateinit var movieFinder:MovieFinder +} +---- +<1> This line injects a `@Resource`. +-- + + +If no name is explicitly specified, the default name is derived from the field name or +setter method. In case of a field, it takes the field name. In case of a setter method, +it takes the bean property name. The following example is going to have the bean +named `movieFinder` injected into its setter method: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class SimpleMovieLister { + + private MovieFinder movieFinder; + + @Resource + public void setMovieFinder(MovieFinder movieFinder) { + this.movieFinder = movieFinder; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class SimpleMovieLister { + + @set:Resource + private lateinit var movieFinder: MovieFinder + + } +---- +-- + +NOTE: The name provided with the annotation is resolved as a bean name by the +`ApplicationContext` of which the `CommonAnnotationBeanPostProcessor` is aware. +The names can be resolved through JNDI if you configure Spring's +{api-spring-framework}/jndi/support/SimpleJndiBeanFactory.html[`SimpleJndiBeanFactory`] +explicitly. However, we recommend that you rely on the default behavior and +use Spring's JNDI lookup capabilities to preserve the level of indirection. + +In the exclusive case of `@Resource` usage with no explicit name specified, and similar +to `@Autowired`, `@Resource` finds a primary type match instead of a specific named bean +and resolves well known resolvable dependencies: the `BeanFactory`, +`ApplicationContext`, `ResourceLoader`, `ApplicationEventPublisher`, and `MessageSource` +interfaces. + +Thus, in the following example, the `customerPreferenceDao` field first looks for a bean +named "customerPreferenceDao" and then falls back to a primary type match for the type +`CustomerPreferenceDao`: + +-- +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + public class MovieRecommender { + + @Resource + private CustomerPreferenceDao customerPreferenceDao; + + @Resource + private ApplicationContext context; // <1> + + public MovieRecommender() { + } + + // ... + } +---- +<1> The `context` field is injected based on the known resolvable dependency type: +`ApplicationContext`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + class MovieRecommender { + + @Resource + private lateinit var customerPreferenceDao: CustomerPreferenceDao + + + @Resource + private lateinit var context: ApplicationContext // <1> + + // ... + } +---- +<1> The `context` field is injected based on the known resolvable dependency type: +`ApplicationContext`. +-- + diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc new file mode 100644 index 000000000000..7a5dd0a83a6e --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc @@ -0,0 +1,200 @@ +[[beans-value-annotations]] += Using `@Value` + +`@Value` is typically used to inject externalized properties: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + public class MovieRecommender { + + private final String catalog; + + public MovieRecommender(@Value("${catalog.name}") String catalog) { + this.catalog = catalog; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + class MovieRecommender(@Value("\${catalog.name}") private val catalog: String) +---- + +With the following configuration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + @PropertySource("classpath:application.properties") + public class AppConfig { } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + @PropertySource("classpath:application.properties") + class AppConfig +---- + +And the following `application.properties` file: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + catalog.name=MovieCatalog +---- + +In that case, the `catalog` parameter and field will be equal to the `MovieCatalog` value. + +A default lenient embedded value resolver is provided by Spring. It will try to resolve the +property value and if it cannot be resolved, the property name (for example `${catalog.name}`) +will be injected as the value. If you want to maintain strict control over nonexistent +values, you should declare a `PropertySourcesPlaceholderConfigurer` bean, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public static PropertySourcesPlaceholderConfigurer propertyPlaceholderConfigurer() { + return new PropertySourcesPlaceholderConfigurer(); + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun propertyPlaceholderConfigurer() = PropertySourcesPlaceholderConfigurer() + } +---- + +NOTE: When configuring a `PropertySourcesPlaceholderConfigurer` using JavaConfig, the +`@Bean` method must be `static`. + +Using the above configuration ensures Spring initialization failure if any `${}` +placeholder could not be resolved. It is also possible to use methods like +`setPlaceholderPrefix`, `setPlaceholderSuffix`, or `setValueSeparator` to customize +placeholders. + +NOTE: Spring Boot configures by default a `PropertySourcesPlaceholderConfigurer` bean that +will get properties from `application.properties` and `application.yml` files. + +Built-in converter support provided by Spring allows simple type conversion (to `Integer` +or `int` for example) to be automatically handled. Multiple comma-separated values can be +automatically converted to `String` array without extra effort. + +It is possible to provide a default value as following: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + public class MovieRecommender { + + private final String catalog; + + public MovieRecommender(@Value("${catalog.name:defaultCatalog}") String catalog) { + this.catalog = catalog; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + class MovieRecommender(@Value("\${catalog.name:defaultCatalog}") private val catalog: String) +---- + +A Spring `BeanPostProcessor` uses a `ConversionService` behind the scenes to handle the +process for converting the `String` value in `@Value` to the target type. If you want to +provide conversion support for your own custom type, you can provide your own +`ConversionService` bean instance as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Configuration + public class AppConfig { + + @Bean + public ConversionService conversionService() { + DefaultFormattingConversionService conversionService = new DefaultFormattingConversionService(); + conversionService.addConverter(new MyCustomConverter()); + return conversionService; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Configuration + class AppConfig { + + @Bean + fun conversionService(): ConversionService { + return DefaultFormattingConversionService().apply { + addConverter(MyCustomConverter()) + } + } + } +---- + +When `@Value` contains a <> the value will be dynamically +computed at runtime as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + public class MovieRecommender { + + private final String catalog; + + public MovieRecommender(@Value("#{systemProperties['user.catalog'] + 'Catalog' }") String catalog) { + this.catalog = catalog; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + class MovieRecommender( + @Value("#{systemProperties['user.catalog'] + 'Catalog' }") private val catalog: String) +---- + +SpEL also enables the use of more complex data structures: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Component + public class MovieRecommender { + + private final Map countOfMoviesPerCatalog; + + public MovieRecommender( + @Value("#{{'Thriller': 100, 'Comedy': 300}}") Map countOfMoviesPerCatalog) { + this.countOfMoviesPerCatalog = countOfMoviesPerCatalog; + } + } +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Component + class MovieRecommender( + @Value("#{{'Thriller': 100, 'Comedy': 300}}") private val countOfMoviesPerCatalog: Map) +---- + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/basics.adoc b/framework-docs/modules/ROOT/pages/core/beans/basics.adoc new file mode 100644 index 000000000000..d0c464344851 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/basics.adoc @@ -0,0 +1,390 @@ +[[beans-basics]] += Container Overview + +The `org.springframework.context.ApplicationContext` interface represents the Spring IoC +container and is responsible for instantiating, configuring, and assembling the +beans. The container gets its instructions on what objects to +instantiate, configure, and assemble by reading configuration metadata. The +configuration metadata is represented in XML, Java annotations, or Java code. It lets +you express the objects that compose your application and the rich interdependencies +between those objects. + +Several implementations of the `ApplicationContext` interface are supplied +with Spring. In stand-alone applications, it is common to create an +instance of +{api-spring-framework}/context/support/ClassPathXmlApplicationContext.html[`ClassPathXmlApplicationContext`] +or {api-spring-framework}/context/support/FileSystemXmlApplicationContext.html[`FileSystemXmlApplicationContext`]. +While XML has been the traditional format for defining configuration metadata, you can +instruct the container to use Java annotations or code as the metadata format by +providing a small amount of XML configuration to declaratively enable support for these +additional metadata formats. + +In most application scenarios, explicit user code is not required to instantiate one or +more instances of a Spring IoC container. For example, in a web application scenario, a +simple eight (or so) lines of boilerplate web descriptor XML in the `web.xml` file +of the application typically suffices (see <>). If you use the +https://spring.io/tools[Spring Tools for Eclipse] (an Eclipse-powered development +environment), you can easily create this boilerplate configuration with a few mouse clicks or +keystrokes. + +The following diagram shows a high-level view of how Spring works. Your application classes +are combined with configuration metadata so that, after the `ApplicationContext` is +created and initialized, you have a fully configured and executable system or +application. + +.The Spring IoC container +image::container-magic.png[] + + + +[[beans-factory-metadata]] +== Configuration Metadata + +As the preceding diagram shows, the Spring IoC container consumes a form of +configuration metadata. This configuration metadata represents how you, as an +application developer, tell the Spring container to instantiate, configure, and assemble +the objects in your application. + +Configuration metadata is traditionally supplied in a simple and intuitive XML format, +which is what most of this chapter uses to convey key concepts and features of the +Spring IoC container. + +NOTE: XML-based metadata is not the only allowed form of configuration metadata. +The Spring IoC container itself is totally decoupled from the format in which this +configuration metadata is actually written. These days, many developers choose +<> for their Spring applications. + +For information about using other forms of metadata with the Spring container, see: + +* <>: define beans using + annotation-based configuration metadata. +* <>: define beans external to your application + classes by using Java rather than XML files. To use these features, see the + {api-spring-framework}/context/annotation/Configuration.html[`@Configuration`], + {api-spring-framework}/context/annotation/Bean.html[`@Bean`], + {api-spring-framework}/context/annotation/Import.html[`@Import`], + and {api-spring-framework}/context/annotation/DependsOn.html[`@DependsOn`] annotations. + +Spring configuration consists of at least one and typically more than one bean +definition that the container must manage. XML-based configuration metadata configures these +beans as `` elements inside a top-level `` element. Java +configuration typically uses `@Bean`-annotated methods within a `@Configuration` class. + +These bean definitions correspond to the actual objects that make up your application. +Typically, you define service layer objects, persistence layer objects such as +repositories or data access objects (DAOs), presentation objects such as Web controllers, +infrastructure objects such as a JPA `EntityManagerFactory`, JMS queues, and so forth. +Typically, one does not configure fine-grained domain objects in the container, because +it is usually the responsibility of repositories and business logic to create and load +domain objects. + +The following example shows the basic structure of XML-based configuration metadata: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + <1> <2> + + + + + + + + + + +---- + +<1> The `id` attribute is a string that identifies the individual bean definition. +<2> The `class` attribute defines the type of the bean and uses the fully qualified +class name. + +The value of the `id` attribute can be used to refer to collaborating objects. The XML +for referring to collaborating objects is not shown in this example. See +<> for more information. + + + +[[beans-factory-instantiation]] +== Instantiating a Container + +The location path or paths +supplied to an `ApplicationContext` constructor are resource strings that let +the container load configuration metadata from a variety of external resources, such +as the local file system, the Java `CLASSPATH`, and so on. + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ApplicationContext context = new ClassPathXmlApplicationContext("services.xml", "daos.xml"); +---- +.Kotlin +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +---- + val context = ClassPathXmlApplicationContext("services.xml", "daos.xml") +---- + +[NOTE] +==== +After you learn about Spring's IoC container, you may want to know more about Spring's +`Resource` abstraction (as described in <>), which provides a convenient +mechanism for reading an InputStream from locations defined in a URI syntax. In particular, +`Resource` paths are used to construct applications contexts, as described in <>. +==== + +The following example shows the service layer objects `(services.xml)` configuration file: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + +---- + +The following example shows the data access objects `daos.xml` file: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + +---- + +In the preceding example, the service layer consists of the `PetStoreServiceImpl` class +and two data access objects of the types `JpaAccountDao` and `JpaItemDao` (based +on the JPA Object-Relational Mapping standard). The `property name` element refers to the +name of the JavaBean property, and the `ref` element refers to the name of another bean +definition. This linkage between `id` and `ref` elements expresses the dependency between +collaborating objects. For details of configuring an object's dependencies, see +<>. + + +[[beans-factory-xml-import]] +=== Composing XML-based Configuration Metadata + +It can be useful to have bean definitions span multiple XML files. Often, each individual +XML configuration file represents a logical layer or module in your architecture. + +You can use the application context constructor to load bean definitions from all these +XML fragments. This constructor takes multiple `Resource` locations, as was shown in the +<>. Alternatively, use one or more +occurrences of the `` element to load bean definitions from another file or +files. The following example shows how to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + +---- + +In the preceding example, external bean definitions are loaded from three files: +`services.xml`, `messageSource.xml`, and `themeSource.xml`. All location paths are +relative to the definition file doing the importing, so `services.xml` must be in the +same directory or classpath location as the file doing the importing, while +`messageSource.xml` and `themeSource.xml` must be in a `resources` location below the +location of the importing file. As you can see, a leading slash is ignored. However, given +that these paths are relative, it is better form not to use the slash at all. The +contents of the files being imported, including the top level `` element, must +be valid XML bean definitions, according to the Spring Schema. + +[NOTE] +==== +It is possible, but not recommended, to reference files in parent directories using a +relative "../" path. Doing so creates a dependency on a file that is outside the current +application. In particular, this reference is not recommended for `classpath:` URLs (for +example, `classpath:../services.xml`), where the runtime resolution process chooses the +"`nearest`" classpath root and then looks into its parent directory. Classpath +configuration changes may lead to the choice of a different, incorrect directory. + +You can always use fully qualified resource locations instead of relative paths: for +example, `file:C:/config/services.xml` or `classpath:/config/services.xml`. However, be +aware that you are coupling your application's configuration to specific absolute +locations. It is generally preferable to keep an indirection for such absolute +locations -- for example, through "${...}" placeholders that are resolved against JVM +system properties at runtime. +==== + +The namespace itself provides the import directive feature. Further +configuration features beyond plain bean definitions are available in a selection +of XML namespaces provided by Spring -- for example, the `context` and `util` namespaces. + + +[[groovy-bean-definition-dsl]] +=== The Groovy Bean Definition DSL + +As a further example for externalized configuration metadata, bean definitions can also +be expressed in Spring's Groovy Bean Definition DSL, as known from the Grails framework. +Typically, such configuration live in a ".groovy" file with the structure shown in the +following example: + +[source,groovy,indent=0,subs="verbatim,quotes"] +---- + beans { + dataSource(BasicDataSource) { + driverClassName = "org.hsqldb.jdbcDriver" + url = "jdbc:hsqldb:mem:grailsDB" + username = "sa" + password = "" + settings = [mynew:"setting"] + } + sessionFactory(SessionFactory) { + dataSource = dataSource + } + myService(MyService) { + nestedBean = { AnotherBean bean -> + dataSource = dataSource + } + } + } +---- + +This configuration style is largely equivalent to XML bean definitions and even +supports Spring's XML configuration namespaces. It also allows for importing XML +bean definition files through an `importBeans` directive. + + + +[[beans-factory-client]] +== Using the Container + +The `ApplicationContext` is the interface for an advanced factory capable of maintaining +a registry of different beans and their dependencies. By using the method +`T getBean(String name, Class requiredType)`, you can retrieve instances of your beans. + +The `ApplicationContext` lets you read bean definitions and access them, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + // create and configure beans + ApplicationContext context = new ClassPathXmlApplicationContext("services.xml", "daos.xml"); + + // retrieve configured instance + PetStoreService service = context.getBean("petStore", PetStoreService.class); + + // use configured instance + List userList = service.getUsernameList(); +---- +.Kotlin +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +---- + import org.springframework.beans.factory.getBean + + // create and configure beans + val context = ClassPathXmlApplicationContext("services.xml", "daos.xml") + + // retrieve configured instance + val service = context.getBean("petStore") + + // use configured instance + var userList = service.getUsernameList() +---- + +With Groovy configuration, bootstrapping looks very similar. It has a different context +implementation class which is Groovy-aware (but also understands XML bean definitions). +The following example shows Groovy configuration: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + ApplicationContext context = new GenericGroovyApplicationContext("services.groovy", "daos.groovy"); +---- +.Kotlin +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +---- +val context = GenericGroovyApplicationContext("services.groovy", "daos.groovy") +---- + +The most flexible variant is `GenericApplicationContext` in combination with reader +delegates -- for example, with `XmlBeanDefinitionReader` for XML files, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + GenericApplicationContext context = new GenericApplicationContext(); + new XmlBeanDefinitionReader(context).loadBeanDefinitions("services.xml", "daos.xml"); + context.refresh(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val context = GenericApplicationContext() + XmlBeanDefinitionReader(context).loadBeanDefinitions("services.xml", "daos.xml") + context.refresh() +---- + +You can also use the `GroovyBeanDefinitionReader` for Groovy files, as the following +example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + GenericApplicationContext context = new GenericApplicationContext(); + new GroovyBeanDefinitionReader(context).loadBeanDefinitions("services.groovy", "daos.groovy"); + context.refresh(); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val context = GenericApplicationContext() + GroovyBeanDefinitionReader(context).loadBeanDefinitions("services.groovy", "daos.groovy") + context.refresh() +---- + +You can mix and match such reader delegates on the same `ApplicationContext`, +reading bean definitions from diverse configuration sources. + +You can then use `getBean` to retrieve instances of your beans. The `ApplicationContext` +interface has a few other methods for retrieving beans, but, ideally, your application +code should never use them. Indeed, your application code should have no calls to the +`getBean()` method at all and thus have no dependency on Spring APIs at all. For example, +Spring's integration with web frameworks provides dependency injection for various web +framework components such as controllers and JSF-managed beans, letting you declare +a dependency on a specific bean through metadata (such as an autowiring annotation). + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc b/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc new file mode 100644 index 000000000000..b8ca8fc3f274 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc @@ -0,0 +1,159 @@ +[[beans-beanfactory]] += The `BeanFactory` API + +The `BeanFactory` API provides the underlying basis for Spring's IoC functionality. +Its specific contracts are mostly used in integration with other parts of Spring and +related third-party frameworks, and its `DefaultListableBeanFactory` implementation +is a key delegate within the higher-level `GenericApplicationContext` container. + +`BeanFactory` and related interfaces (such as `BeanFactoryAware`, `InitializingBean`, +`DisposableBean`) are important integration points for other framework components. +By not requiring any annotations or even reflection, they allow for very efficient +interaction between the container and its components. Application-level beans may +use the same callback interfaces but typically prefer declarative dependency +injection instead, either through annotations or through programmatic configuration. + +Note that the core `BeanFactory` API level and its `DefaultListableBeanFactory` +implementation do not make assumptions about the configuration format or any +component annotations to be used. All of these flavors come in through extensions +(such as `XmlBeanDefinitionReader` and `AutowiredAnnotationBeanPostProcessor`) and +operate on shared `BeanDefinition` objects as a core metadata representation. +This is the essence of what makes Spring's container so flexible and extensible. + + + +[[context-introduction-ctx-vs-beanfactory]] +== `BeanFactory` or `ApplicationContext`? + +This section explains the differences between the `BeanFactory` and +`ApplicationContext` container levels and the implications on bootstrapping. + +You should use an `ApplicationContext` unless you have a good reason for not doing so, with +`GenericApplicationContext` and its subclass `AnnotationConfigApplicationContext` +as the common implementations for custom bootstrapping. These are the primary entry +points to Spring's core container for all common purposes: loading of configuration +files, triggering a classpath scan, programmatically registering bean definitions +and annotated classes, and (as of 5.0) registering functional bean definitions. + +Because an `ApplicationContext` includes all the functionality of a `BeanFactory`, it is +generally recommended over a plain `BeanFactory`, except for scenarios where full +control over bean processing is needed. Within an `ApplicationContext` (such as the +`GenericApplicationContext` implementation), several kinds of beans are detected +by convention (that is, by bean name or by bean type -- in particular, post-processors), +while a plain `DefaultListableBeanFactory` is agnostic about any special beans. + +For many extended container features, such as annotation processing and AOP proxying, +the <> is essential. +If you use only a plain `DefaultListableBeanFactory`, such post-processors do not +get detected and activated by default. This situation could be confusing, because +nothing is actually wrong with your bean configuration. Rather, in such a scenario, +the container needs to be fully bootstrapped through additional setup. + +The following table lists features provided by the `BeanFactory` and +`ApplicationContext` interfaces and implementations. + +[[context-introduction-ctx-vs-beanfactory-feature-matrix]] +.Feature Matrix +[cols="50%,25%,25%"] +|=== +| Feature | `BeanFactory` | `ApplicationContext` + +| Bean instantiation/wiring +| Yes +| Yes + +| Integrated lifecycle management +| No +| Yes + +| Automatic `BeanPostProcessor` registration +| No +| Yes + +| Automatic `BeanFactoryPostProcessor` registration +| No +| Yes + +| Convenient `MessageSource` access (for internationalization) +| No +| Yes + +| Built-in `ApplicationEvent` publication mechanism +| No +| Yes +|=== + +To explicitly register a bean post-processor with a `DefaultListableBeanFactory`, +you need to programmatically call `addBeanPostProcessor`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + DefaultListableBeanFactory factory = new DefaultListableBeanFactory(); + // populate the factory with bean definitions + + // now register any needed BeanPostProcessor instances + factory.addBeanPostProcessor(new AutowiredAnnotationBeanPostProcessor()); + factory.addBeanPostProcessor(new MyBeanPostProcessor()); + + // now start using the factory +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val factory = DefaultListableBeanFactory() + // populate the factory with bean definitions + + // now register any needed BeanPostProcessor instances + factory.addBeanPostProcessor(AutowiredAnnotationBeanPostProcessor()) + factory.addBeanPostProcessor(MyBeanPostProcessor()) + + // now start using the factory +---- + +To apply a `BeanFactoryPostProcessor` to a plain `DefaultListableBeanFactory`, +you need to call its `postProcessBeanFactory` method, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + DefaultListableBeanFactory factory = new DefaultListableBeanFactory(); + XmlBeanDefinitionReader reader = new XmlBeanDefinitionReader(factory); + reader.loadBeanDefinitions(new FileSystemResource("beans.xml")); + + // bring in some property values from a Properties file + PropertySourcesPlaceholderConfigurer cfg = new PropertySourcesPlaceholderConfigurer(); + cfg.setLocation(new FileSystemResource("jdbc.properties")); + + // now actually do the replacement + cfg.postProcessBeanFactory(factory); +---- +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + val factory = DefaultListableBeanFactory() + val reader = XmlBeanDefinitionReader(factory) + reader.loadBeanDefinitions(FileSystemResource("beans.xml")) + + // bring in some property values from a Properties file + val cfg = PropertySourcesPlaceholderConfigurer() + cfg.setLocation(FileSystemResource("jdbc.properties")) + + // now actually do the replacement + cfg.postProcessBeanFactory(factory) +---- + +In both cases, the explicit registration steps are inconvenient, which is +why the various `ApplicationContext` variants are preferred over a plain +`DefaultListableBeanFactory` in Spring-backed applications, especially when +relying on `BeanFactoryPostProcessor` and `BeanPostProcessor` instances for extended +container functionality in a typical enterprise setup. + +[NOTE] +==== +An `AnnotationConfigApplicationContext` has all common annotation post-processors +registered and may bring in additional processors underneath the +covers through configuration annotations, such as `@EnableTransactionManagement`. +At the abstraction level of Spring's annotation-based configuration model, +the notion of bean post-processors becomes a mere internal container detail. +==== diff --git a/framework-docs/modules/ROOT/pages/core/beans/child-bean-definitions.adoc b/framework-docs/modules/ROOT/pages/core/beans/child-bean-definitions.adoc new file mode 100644 index 000000000000..2c4d287a08f4 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/child-bean-definitions.adoc @@ -0,0 +1,84 @@ +[[beans-child-bean-definitions]] += Bean Definition Inheritance + +A bean definition can contain a lot of configuration information, including constructor +arguments, property values, and container-specific information, such as the initialization +method, a static factory method name, and so on. A child bean definition inherits +configuration data from a parent definition. The child definition can override some +values or add others as needed. Using parent and child bean definitions can save a lot +of typing. Effectively, this is a form of templating. + +If you work with an `ApplicationContext` interface programmatically, child bean +definitions are represented by the `ChildBeanDefinition` class. Most users do not work +with them on this level. Instead, they configure bean definitions declaratively in a class +such as the `ClassPathXmlApplicationContext`. When you use XML-based configuration +metadata, you can indicate a child bean definition by using the `parent` attribute, +specifying the parent bean as the value of this attribute. The following example shows how +to do so: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + <1> + + + +---- +<1> Note the `parent` attribute. + +A child bean definition uses the bean class from the parent definition if none is +specified but can also override it. In the latter case, the child bean class must be +compatible with the parent (that is, it must accept the parent's property values). + +A child bean definition inherits scope, constructor argument values, property values, and +method overrides from the parent, with the option to add new values. Any scope, initialization +method, destroy method, or `static` factory method settings that you specify +override the corresponding parent settings. + +The remaining settings are always taken from the child definition: depends on, +autowire mode, dependency check, singleton, and lazy init. + +The preceding example explicitly marks the parent bean definition as abstract by using +the `abstract` attribute. If the parent definition does not specify a class, explicitly +marking the parent bean definition as `abstract` is required, as the following example +shows: + +[source,xml,indent=0,subs="verbatim,quotes"] +---- + + + + + + + + + +---- + +The parent bean cannot be instantiated on its own because it is incomplete, and it is +also explicitly marked as `abstract`. When a definition is `abstract`, it is +usable only as a pure template bean definition that serves as a parent definition for +child definitions. Trying to use such an `abstract` parent bean on its own, by referring +to it as a ref property of another bean or doing an explicit `getBean()` call with the +parent bean ID returns an error. Similarly, the container's internal +`preInstantiateSingletons()` method ignores bean definitions that are defined as +abstract. + +NOTE: `ApplicationContext` pre-instantiates all singletons by default. Therefore, it is +important (at least for singleton beans) that if you have a (parent) bean definition +which you intend to use only as a template, and this definition specifies a class, you +must make sure to set the __abstract__ attribute to __true__, otherwise the application +context will actually (attempt to) pre-instantiate the `abstract` bean. + + + + diff --git a/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc b/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc new file mode 100644 index 000000000000..64b3bcf146ab --- /dev/null +++ b/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc @@ -0,0 +1,937 @@ +[[beans-classpath-scanning]] += Classpath Scanning and Managed Components + +Most examples in this chapter use XML to specify the configuration metadata that produces +each `BeanDefinition` within the Spring container. The previous section +(<>) demonstrates how to provide a lot of the configuration +metadata through source-level annotations. Even in those examples, however, the "base" +bean definitions are explicitly defined in the XML file, while the annotations drive only +the dependency injection. This section describes an option for implicitly detecting the +candidate components by scanning the classpath. Candidate components are classes that +match against a filter criteria and have a corresponding bean definition registered with +the container. This removes the need to use XML to perform bean registration. Instead, you +can use annotations (for example, `@Component`), AspectJ type expressions, or your own +custom filter criteria to select which classes have bean definitions registered with +the container. + +[NOTE] +==== +You can define beans using Java rather than using XML files. Take a look at the +`@Configuration`, `@Bean`, `@Import`, and `@DependsOn` annotations for examples of how to +use these features. +==== + + + +[[beans-stereotype-annotations]] +== `@Component` and Further Stereotype Annotations + +The `@Repository` annotation is a marker for any class that fulfills the role or +stereotype of a repository (also known as Data Access Object or DAO). Among the uses +of this marker is the automatic translation of exceptions, as described in +<>. + +Spring provides further stereotype annotations: `@Component`, `@Service`, and +`@Controller`. `@Component` is a generic stereotype for any Spring-managed component. +`@Repository`, `@Service`, and `@Controller` are specializations of `@Component` for +more specific use cases (in the persistence, service, and presentation +layers, respectively). Therefore, you can annotate your component classes with +`@Component`, but, by annotating them with `@Repository`, `@Service`, or `@Controller` +instead, your classes are more properly suited for processing by tools or associating +with aspects. For example, these stereotype annotations make ideal targets for +pointcuts. `@Repository`, `@Service`, and `@Controller` can also +carry additional semantics in future releases of the Spring Framework. Thus, if you are +choosing between using `@Component` or `@Service` for your service layer, `@Service` is +clearly the better choice. Similarly, as stated earlier, `@Repository` is already +supported as a marker for automatic exception translation in your persistence layer. + + + +[[beans-meta-annotations]] +== Using Meta-annotations and Composed Annotations + +Many of the annotations provided by Spring can be used as meta-annotations in your +own code. A meta-annotation is an annotation that can be applied to another annotation. +For example, the `@Service` annotation mentioned <> +is meta-annotated with `@Component`, as the following example shows: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target(ElementType.TYPE) + @Retention(RetentionPolicy.RUNTIME) + @Documented + @Component // <1> + public @interface Service { + + // ... + } +---- +<1> The `@Component` causes `@Service` to be treated in the same way as `@Component`. + +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +.Kotlin +---- + @Target(AnnotationTarget.TYPE) + @Retention(AnnotationRetention.RUNTIME) + @MustBeDocumented + @Component // <1> + annotation class Service { + + // ... + } +---- +<1> The `@Component` causes `@Service` to be treated in the same way as `@Component`. + +You can also combine meta-annotations to create "`composed annotations`". For example, +the `@RestController` annotation from Spring MVC is composed of `@Controller` and +`@ResponseBody`. + +In addition, composed annotations can optionally redeclare attributes from +meta-annotations to allow customization. This can be particularly useful when you +want to only expose a subset of the meta-annotation's attributes. For example, Spring's +`@SessionScope` annotation hard codes the scope name to `session` but still allows +customization of the `proxyMode`. The following listing shows the definition of the +`SessionScope` annotation: + +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +.Java +---- + @Target({ElementType.TYPE, ElementType.METHOD}) + @Retention(RetentionPolicy.RUNTIME) + @Documented + @Scope(WebApplicationContext.SCOPE_SESSION) + public @interface SessionScope { + + /** + * Alias for {@link Scope#proxyMode}. + *