Extract recurring asciidoc links to attributes, cleanup old doc files
This commit extract spring-related links and recurring external links
into asciidoctor attributes to be used by the Antora toolchain.
It notably homogenizes links to:
- IETF RFCs
- Java Community Process JSRs
- the Java API Documentation (on the Java 17 version)
- Kotlin documentations (on the Kotlinlang.org version)
- the Spring Boot reference guide (on the `html` version)
This commit also reworks most link attributes to follow a
Project-Category-Misc syntax. For example, `spring-boot-docs` rather
than `docs-spring-boot`.
Finally, it makes an effort to clean up remainders from the previous
documentation toolchain, namely the `docs/asciidoc` folder and
`modules/ROOT/pages/attributes.adoc` file.
Closes gh-26864
Closes gh-31619
@ -8,7 +8,7 @@ within the core Spring Framework.
@@ -8,7 +8,7 @@ within the core Spring Framework.
[[appendix-spring-properties]]
== Spring Properties
{api-spring-framework}/core/SpringProperties.html[`SpringProperties`] is a static holder
{spring-framework-api}/core/SpringProperties.html[`SpringProperties`] is a static holder
for properties that control certain low-level aspects of the Spring Framework. Users can
configure these properties via JVM system properties or programmatically via the
`SpringProperties.setProperty(String key, String value)` method. The latter may be
@ -25,7 +25,7 @@ The following table lists all currently supported Spring properties.
@@ -25,7 +25,7 @@ The following table lists all currently supported Spring properties.
| `spring.beaninfo.ignore`
| Instructs Spring to use the `Introspector.IGNORE_ALL_BEANINFO` mode when calling the
@ -47,12 +47,12 @@ See the note in xref:data-access/jdbc/advanced.adoc#jdbc-batch-list[Batch Operat
@@ -47,12 +47,12 @@ See the note in xref:data-access/jdbc/advanced.adoc#jdbc-batch-list[Batch Operat
| Instructs Spring to ignore a default JNDI environment, as an optimization for scenarios
where nothing is ever to be found for such JNDI fallback searches to begin with, avoiding
@ -12,5 +12,5 @@ support for new custom advice types be added without changing the core framework
@@ -12,5 +12,5 @@ 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`]
See the {spring-framework-api}/aop/framework/adapter/package-summary.html[`org.springframework.aop.framework.adapter`]
@ -482,7 +482,7 @@ The `JoinPoint` interface provides a number of useful methods:
@@ -482,7 +482,7 @@ The `JoinPoint` interface provides a number of useful methods:
* `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.
See the {aspectj-api}/org/aspectj/lang/JoinPoint.html[javadoc] for more detail.
[[aop-ataspectj-advice-params-passing]]
=== Passing Parameters to Advice
@ -730,7 +730,7 @@ of determining parameter names, an exception will be thrown.
@@ -730,7 +730,7 @@ of determining parameter names, an exception will be thrown.
flag for `javac`. Recommended approach on Java 8+.
`AspectJAdviceParameterNameDiscoverer` :: Deduces parameter names from the pointcut
expression, `returning`, and `throwing` clauses. See the
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).
@ -392,7 +392,7 @@ method that takes no parameters, whereas `(..)` matches any number (zero or more
@@ -392,7 +392,7 @@ method that takes no parameters, whereas `(..)` matches any number (zero or more
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
@ -136,7 +136,7 @@ using Spring in accordance with the properties of the annotation". In this conte
@@ -136,7 +136,7 @@ using Spring in accordance with the properties of the annotation". In this conte
"initialization" refers to newly instantiated objects (for example, objects instantiated
with the `new` operator) as well as to `Serializable` objects that are undergoing
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
{aspectj-docs-devguide}/antTasks.html[AspectJ Development
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
@ -399,7 +398,7 @@ The focus of this section is on configuring and using LTW in the specific contex
@@ -399,7 +398,7 @@ The focus of this section is on configuring and using LTW in the specific contex
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
{aspectj-docs-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
@ -421,7 +420,7 @@ who typically are in charge of the deployment configuration, such as the launch
@@ -421,7 +420,7 @@ who typically are in charge of the deployment configuration, such as the launch
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
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
@ -721,7 +720,7 @@ The AspectJ LTW infrastructure is configured by using one or more `META-INF/aop.
@@ -721,7 +720,7 @@ The AspectJ LTW infrastructure is configured by using one or more `META-INF/aop.
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
@ -17,7 +17,7 @@ Applying such optimizations early implies the following restrictions:
@@ -17,7 +17,7 @@ Applying such optimizations early implies the following restrictions:
* The beans defined in your application cannot change at runtime, meaning:
** `@Profile`, in particular profile-specific configuration needs to be chosen at build time.
** `Environment` properties that impact the presence of a bean (`@Conditional`) are only considered at build time.
* Bean definitions with instance suppliers (lambdas or method references) cannot be transformed ahead-of-time (see related https://github.com/spring-projects/spring-framework/issues/29555[spring-framework#29555] issue).
* Bean definitions with instance suppliers (lambdas or method references) cannot be transformed ahead-of-time (see related {spring-framework-issues}/29555[spring-framework#29555] issue).
* Make sure that the bean type is as precise as possible.
TIP: See also the xref:core/aot.adoc#aot.bestpractices[] section.
@ -27,7 +27,7 @@ A Spring AOT processed application typically generates:
@@ -27,7 +27,7 @@ A Spring AOT processed application typically generates:
* Java source code
* Bytecode (usually for dynamic proxies)
* {api-spring-framework}/aot/hint/RuntimeHints.html[`RuntimeHints`] for the use of reflection, resource loading, serialization, and JDK proxies.
* {spring-framework-api}/aot/hint/RuntimeHints.html[`RuntimeHints`] for the use of reflection, resource loading, serialization, and JDK proxies.
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.
@ -35,7 +35,7 @@ We intend to support more JVM-based use cases in future generations.
@@ -35,7 +35,7 @@ We intend to support more JVM-based use cases in future generations.
[[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`]:
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 {spring-framework-api}/aot/generate/GenerationContext.html[`GenerationContext`]:
* Refresh an `ApplicationContext` for AOT processing. Contrary to a traditional refresh, this version only creates bean definitions, not bean instances.
* Invoke the available `BeanFactoryInitializationAotProcessor` implementations and apply their contributions against the `GenerationContext`.
@ -81,7 +81,7 @@ Once this part completes, the `BeanFactory` contains the bean definitions that a
@@ -81,7 +81,7 @@ Once this part completes, the `BeanFactory` contains the bean definitions that a
[[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.
Components that want to participate in this step can implement the {spring-framework-api}/beans/factory/aot/BeanFactoryInitializationAotProcessor.html[`BeanFactoryInitializationAotProcessor`] interface.
Each implementation can return an AOT contribution, based on the state of the bean factory.
An AOT contribution is a component that contributes generated code that reproduces a particular behavior.
@ -261,7 +261,7 @@ If you are registering bean definitions programmatically, consider using `RootBe
@@ -261,7 +261,7 @@ If you are registering bean definitions programmatically, consider using `RootBe
The container is able to choose the most appropriate constructor to use based on several candidates.
However, this is not a best practice and flagging the preferred constructor with `@Autowired` if necessary is preferred.
In case you are working on a code base that you can't modify, you can set the {api-spring-framework}/beans/factory/support/AbstractBeanDefinition.html#PREFERRED_CONSTRUCTORS_ATTRIBUTE[`preferredConstructors` attribute] on the related bean definition to indicate which constructor should be used.
In case you are working on a code base that you can't modify, you can set the {spring-framework-api}/beans/factory/support/AbstractBeanDefinition.html#PREFERRED_CONSTRUCTORS_ATTRIBUTE[`preferredConstructors` attribute] on the related bean definition to indicate which constructor should be used.
[[aot.bestpractices.factory-bean]]
=== FactoryBean
@ -379,7 +379,7 @@ For instance, GraalVM needs to know ahead of time if a component uses reflection
@@ -379,7 +379,7 @@ For instance, GraalVM needs to know ahead of time if a component uses reflection
Similarly, classpath resources are not shipped in a native image unless specified explicitly.
Consequently, if the application needs to load a resource, it must be referenced from the corresponding GraalVM native image configuration file.
The {api-spring-framework}/aot/hint/RuntimeHints.html[`RuntimeHints`] API collects the need for reflection, resource loading, serialization, and JDK proxies at runtime.
The {spring-framework-api}/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]
@ -417,7 +417,7 @@ It is also possible to register an implementation statically by adding an entry
@@ -417,7 +417,7 @@ It is also possible to register an implementation statically by adding an entry
[[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.
{spring-framework-api}/aot/hint/annotation/Reflective.html[`@Reflective`] provides an idiomatic way to flag the need for reflection on an annotated element.
For instance, `@EventListener` is meta-annotated with `@Reflective` since the underlying implementation invokes the annotated method using reflection.
By default, only Spring beans are considered and an invocation hint is registered for the annotated element.
@ -431,7 +431,7 @@ If components other than Spring beans need to be processed, a `BeanFactoryInitia
@@ -431,7 +431,7 @@ If components other than Spring beans need to be processed, a `BeanFactoryInitia
[[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.
{spring-framework-api}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`] is a specialization of `@Reflective` that registers the need for serializing arbitrary types.
A typical use case is the use of DTOs that the container cannot infer, such as using a web client within a method body.
`@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.
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.
You can learn more about the global runtime behavior of an application by running its test suite (or the app itself) with the {docs-graalvm}/native-image/metadata/AutomaticMetadataCollection/[GraalVM tracing agent].
You can learn more about the global runtime behavior of an application by running its test suite (or the app itself) with the {graalvm-docs}/native-image/metadata/AutomaticMetadataCollection/[GraalVM tracing agent].
This agent will record all relevant calls requiring GraalVM hints at runtime and write them out as JSON configuration files.
For more targeted discovery and testing, Spring Framework ships a dedicated module with core AOT testing utilities, `"org.springframework:spring-core-test"`.
@ -765,7 +765,7 @@ want to add an additional attribute to the existing bean definition element.
@@ -765,7 +765,7 @@ 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
{JSR}107[JCache], and you want to ensure that the
named JCache instance is eagerly started within the surrounding cluster.
@ -66,13 +66,13 @@ developer's intent ("`inject this constant value`"), and it reads better:
@@ -66,13 +66,13 @@ developer's intent ("`inject this constant value`"), and it reads better:
[[xsd-schemas-util-frfb]]
==== Setting a Bean Property or Constructor Argument from a Field Value
@ -109,7 +109,7 @@ to be specified for the bean reference, as the following example shows:
@@ -109,7 +109,7 @@ to be specified for the bean reference, as the following example shows:
You can also access a non-static (instance) field of another bean, as
@ -17,7 +17,7 @@ No matter the choice, Spring can accommodate both styles and even mix them toget
@@ -17,7 +17,7 @@ No matter the choice, Spring can accommodate both styles and even mix them toget
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.
{spring-site-tools}[Spring Tools] for Eclipse, Visual Studio Code, and Theia.
****
An alternative to XML setup is provided by annotation-based configuration, which relies
@ -62,11 +62,11 @@ configuration (notice the inclusion of the `context` namespace):
@@ -62,11 +62,11 @@ configuration (notice the inclusion of the `context` namespace):
The `<context:annotation-config/>` element implicitly registers the following post-processors:
or {spring-framework-api}/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
@ -24,7 +24,7 @@ more instances of a Spring IoC container. For example, in a web application scen
@@ -24,7 +24,7 @@ more instances of a Spring IoC container. For example, in a web application scen
simple eight (or so) lines of boilerplate web descriptor XML in the `web.xml` file
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
If you use the {spring-site-tools}[Spring Tools for Eclipse] (an Eclipse-powered
development environment), you can easily create this boilerplate configuration with a
few mouse clicks or keystrokes.
@ -61,10 +61,10 @@ For information about using other forms of metadata with the Spring container, s
@@ -61,10 +61,10 @@ For information about using other forms of metadata with the Spring container, s
annotation-based configuration metadata.
* 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
@ -315,7 +315,7 @@ entries in the classpath. When you build JARs with Ant, make sure that you do no
@@ -315,7 +315,7 @@ entries in the classpath. When you build JARs with Ant, make sure that you do no
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
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
@ -269,7 +269,7 @@ file format but is more flexible than the standard JDK based
@@ -269,7 +269,7 @@ 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`]
See the {spring-framework-api}/context/support/ReloadableResourceBundleMessageSource.html[`ReloadableResourceBundleMessageSource`]
javadoc for details.
@ -485,8 +485,8 @@ This means that the `publishEvent()` method blocks until all listeners have fini
@@ -485,8 +485,8 @@ This means that the `publishEvent()` method blocks until all listeners have fini
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, e.g. asynchronous event processing by default,
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
see the javadoc for Spring's {spring-framework-api}/context/event/ApplicationEventMulticaster.html[`ApplicationEventMulticaster`] interface
and {spring-framework-api}/context/event/SimpleApplicationEventMulticaster.html[`SimpleApplicationEventMulticaster`] implementation
for configuration options which can be applied to a custom "applicationEventMulticaster" bean definition.
In these cases, ThreadLocals and logging context are not propagated for the event processing.
See xref:integration/observability.adoc#observability.application-events[the `@EventListener` Observability section]
architectures that build upon the well-known Spring programming model.
@ -742,11 +742,11 @@ Be aware of the following limitations when using asynchronous events:
@@ -742,11 +742,11 @@ Be aware of the following limitations when using asynchronous events:
* If an asynchronous event listener throws an `Exception`, it is not propagated to the
* ThreadLocals and logging context are not propagated by default for the event processing.
See xref:integration/observability.adoc#observability.application-events[the `@EventListener` Observability section]
@ -1040,7 +1040,7 @@ and JMX support facilities. Application components can also interact with the ap
@@ -1040,7 +1040,7 @@ and JMX support facilities. Application components can also interact with the ap
server's JCA `WorkManager` through Spring's `TaskExecutor` abstraction.
class for the configuration details involved in RAR deployment.
For a simple deployment of a Spring ApplicationContext as a Jakarta EE RAR file:
@ -1050,7 +1050,7 @@ all application classes into a RAR file (which is a standard JAR file with a dif
@@ -1050,7 +1050,7 @@ all application classes into a RAR file (which is a standard JAR file with a dif
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`])
`META-INF/ra.xml` deployment descriptor (as shown in the {spring-framework-api}/jca/context/SpringContextResourceAdapter.html[javadoc for `SpringContextResourceAdapter`])
and the corresponding Spring XML bean definition file(s) (typically
@ -44,7 +44,7 @@ weaver instance. This is particularly useful in combination with
@@ -44,7 +44,7 @@ weaver instance. This is particularly useful in combination with
xref:data-access/orm/jpa.adoc[Spring's JPA support] where load-time weaving may be
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].
The {api-spring-framework}/core/env/Environment.html[`Environment`] interface
The {spring-framework-api}/core/env/Environment.html[`Environment`] interface
is an abstraction integrated in the container that models two key
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].
@ -118,7 +118,7 @@ situation B. We start by updating our configuration to reflect this need.
@@ -118,7 +118,7 @@ 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`]
The {spring-framework-api}/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:
@ -22,8 +22,8 @@ in which these `BeanPostProcessor` instances run by setting the `order` property
@@ -22,8 +22,8 @@ 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
and {spring-framework-api}/core/Ordered.html[`Ordered`] interfaces. See also the note on
xref:core/beans/factory-extension.adoc#beans-factory-programmatically-registering-beanpostprocessors[programmatic registration of `BeanPostProcessor` instances].
[NOTE]
@ -272,8 +272,8 @@ which these `BeanFactoryPostProcessor` instances run by setting the `order` prop
@@ -272,8 +272,8 @@ which these `BeanFactoryPostProcessor` instances run by setting the `order` prop
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
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].
@ -559,7 +559,7 @@ To integrate your custom scopes into the Spring container, you need to implement
@@ -559,7 +559,7 @@ To integrate your custom scopes into the Spring container, you need to implement
`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
@ -13,10 +13,10 @@ construction of classes or a mechanism such as the Service Locator pattern.
@@ -13,10 +13,10 @@ construction of classes or a mechanism such as the Service Locator pattern.
The `org.springframework.beans` and `org.springframework.context` packages are the basis
@ -552,7 +552,7 @@ Sometimes, it is helpful to provide a more detailed textual description of a bea
@@ -552,7 +552,7 @@ Sometimes, it is helpful to provide a more detailed textual description of a bea
be particularly useful when beans are exposed (perhaps through JMX) for monitoring purposes.
To add a description to a `@Bean`, you can use the
@ -225,7 +225,7 @@ Also, be particularly careful with `BeanPostProcessor` and `BeanFactoryPostProce
@@ -225,7 +225,7 @@ Also, be particularly careful with `BeanPostProcessor` and `BeanFactoryPostProce
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
The following example shows how one bean can be autowired to another bean:
@ -338,7 +338,7 @@ modularity, but determining exactly where the autowired bean definitions are dec
@@ -338,7 +338,7 @@ modularity, but determining exactly where the autowired bean definitions are dec
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
{spring-site-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.
@ -519,7 +519,7 @@ profile has been enabled in the Spring `Environment` (see xref:core/beans/enviro
@@ -519,7 +519,7 @@ profile has been enabled in the Spring `Environment` (see xref:core/beans/enviro
for details).
The `@Profile` annotation is actually implemented by using a much more flexible annotation
called {api-spring-framework}/context/annotation/Conditional.html[`@Conditional`].
called {spring-framework-api}/context/annotation/Conditional.html[`@Conditional`].
The `@Conditional` annotation indicates specific
`org.springframework.context.annotation.Condition` implementations that should be
@ -11,7 +11,7 @@ EL, to name a few -- the Spring Expression Language was created to provide the S
@@ -11,7 +11,7 @@ EL, to name a few -- the Spring Expression Language was created to provide the S
community with a single well supported expression language that can be used across all
the products in the Spring portfolio. Its language features are driven by the
requirements of the projects in the Spring portfolio, including tooling requirements
for code completion support within the https://spring.io/tools[Spring Tools for Eclipse].
for code completion support within the {spring-site-tools}[Spring Tools for Eclipse].
That said, SpEL is based on a technology-agnostic API that lets other expression language
implementations be integrated, should the need arise.
@ -5,14 +5,14 @@ Although Java does not let you express null-safety with its type system, the Spr
@@ -5,14 +5,14 @@ Although Java does not let you express null-safety with its type system, the Spr
provides the following annotations in the `org.springframework.lang` package to let you
declare nullability of APIs and fields:
* {api-spring-framework}/lang/Nullable.html[`@Nullable`]: Annotation to indicate that a
* {spring-framework-api}/lang/Nullable.html[`@Nullable`]: Annotation to indicate that a
specific parameter, return value, or field can be `null`.
* {api-spring-framework}/lang/NonNull.html[`@NonNull`]: Annotation to indicate that a specific
* {spring-framework-api}/lang/NonNull.html[`@NonNull`]: Annotation to indicate that a specific
parameter, return value, or field cannot be `null` (not needed on parameters, return values,
and fields where `@NonNullApi` and `@NonNullFields` apply, respectively).
* {api-spring-framework}/lang/NonNullApi.html[`@NonNullApi`]: Annotation at the package level
* {spring-framework-api}/lang/NonNullApi.html[`@NonNullApi`]: Annotation at the package level
that declares non-null as the default semantics for parameters and return values.
* {api-spring-framework}/lang/NonNullFields.html[`@NonNullFields`]: Annotation at the package
* {spring-framework-api}/lang/NonNullFields.html[`@NonNullFields`]: Annotation at the package
level that declares non-null as the default semantics for fields.
The Spring Framework itself leverages these annotations, but they can also be used in any
@ -37,7 +37,7 @@ these annotations can be used by an IDE (such as IDEA or Eclipse) to provide use
@@ -37,7 +37,7 @@ these annotations can be used by an IDE (such as IDEA or Eclipse) to provide use
warnings related to null-safety in order to avoid `NullPointerException` at runtime.
They are also used to make Spring APIs null-safe in Kotlin projects, since Kotlin natively
supports https://kotlinlang.org/docs/null-safety.html[null-safety]. More details
supports {kotlin-docs}/null-safety.html[null-safety]. More details
are available in the xref:languages/kotlin/null-safety.adoc[Kotlin support documentation].
@ -46,7 +46,7 @@ are available in the xref:languages/kotlin/null-safety.adoc[Kotlin support docum
@@ -46,7 +46,7 @@ are available in the xref:languages/kotlin/null-safety.adoc[Kotlin support docum
[[jsr-305-meta-annotations]]
== JSR-305 meta-annotations
Spring annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305]
Spring annotations are meta-annotated with {JSR}305[JSR 305]
annotations (a dormant but widespread JSR). JSR-305 meta-annotations let tooling vendors
like IDEA or Kotlin provide null-safety support in a generic way, without having to
@ -37,7 +37,7 @@ such as a method to check for the existence of the resource being pointed to.
@@ -37,7 +37,7 @@ such as a method to check for the existence of the resource being pointed to.
Spring's `Resource` interface located in the `org.springframework.core.io.` package is
meant to be a more capable interface for abstracting access to low-level resources. The
following listing provides an overview of the `Resource` interface. See the
{api-spring-framework}/core/io/Resource.html[`Resource`] javadoc for further details.
{spring-framework-api}/core/io/Resource.html[`Resource`] javadoc for further details.
[source,java,indent=0,subs="verbatim,quotes"]
@ -104,7 +104,7 @@ resource (if the underlying implementation is compatible and supports that
@@ -104,7 +104,7 @@ resource (if the underlying implementation is compatible and supports that
functionality).
Some implementations of the `Resource` interface also implement the extended
Spring itself uses the `Resource` abstraction extensively, as an argument type in
@ -143,7 +143,7 @@ Spring includes several built-in `Resource` implementations:
@@ -143,7 +143,7 @@ Spring includes several built-in `Resource` implementations:
For a complete list of `Resource` implementations available in Spring, consult the
See the {api-spring-framework}/context/support/ClassPathXmlApplicationContext.html[`ClassPathXmlApplicationContext`]
See the {spring-framework-api}/context/support/ClassPathXmlApplicationContext.html[`ClassPathXmlApplicationContext`]
javadoc for details on the various constructors.
@ -903,7 +903,7 @@ entries in the classpath. When you build JARs with Ant, do not activate the `fil
@@ -903,7 +903,7 @@ entries in the classpath. When you build JARs with Ant, do not activate the `fil
switch of the JAR task. Also, classpath directories may not get exposed based on security
policies in some environments -- for example, stand-alone applications on JDK 1.7.0_45
and higher (which requires 'Trusted-Library' to be set up in your manifests. See
@ -9,7 +9,7 @@ known as _JUL_ or `java.util.logging`) if neither Log4j 2.x nor SLF4J is availab
@@ -9,7 +9,7 @@ known as _JUL_ or `java.util.logging`) if neither Log4j 2.x nor SLF4J is availab
Put Log4j 2.x or Logback (or another SLF4J provider) in your classpath, without any extra
bridges, and let the framework auto-adapt to your choice. For further information see the
@ -51,7 +51,7 @@ A JavaBean is a class with a default no-argument constructor and that follows
@@ -51,7 +51,7 @@ 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
One quite important class in the beans package is the `BeanWrapper` interface and its
corresponding implementation (`BeanWrapperImpl`). As quoted from the javadoc, the
@ -249,7 +249,7 @@ behavior can be achieved by registering custom editors of type
@@ -249,7 +249,7 @@ 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].
`PropertyEditor`, see {java-api}/java.desktop/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:
@ -355,7 +355,7 @@ com
@@ -355,7 +355,7 @@ com
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
{java-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:
@ -19,8 +19,8 @@ of the field). This is done as a convenience to aid developers when targeting er
@@ -19,8 +19,8 @@ of the field). This is done as a convenience to aid developers when targeting er
More information on the `MessageCodesResolver` and the default strategy can be found
in the javadoc of
{api-spring-framework}/validation/MessageCodesResolver.html[`MessageCodesResolver`] and
@ -199,7 +199,7 @@ participating in Spring managed transactions. It is generally preferable to writ
@@ -199,7 +199,7 @@ participating in Spring managed transactions. It is generally preferable to writ
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`]
See the {spring-framework-api}/jdbc/datasource/TransactionAwareDataSourceProxy.html[`TransactionAwareDataSourceProxy`]
@ -51,7 +51,7 @@ corresponding to the fully qualified class name of the template instance (typica
@@ -51,7 +51,7 @@ corresponding to the fully qualified class name of the template instance (typica
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.
See the attendant {spring-framework-api}/jdbc/core/JdbcTemplate.html[javadoc] for that.
See the {api-spring-framework}/jdbc/datasource/embedded/EmbeddedDatabaseBuilder.html[javadoc for `EmbeddedDatabaseBuilder`]
See the {spring-framework-api}/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
@ -288,7 +288,7 @@ You can extend Spring JDBC embedded database support in two ways:
@@ -288,7 +288,7 @@ You can extend Spring JDBC embedded database support in two ways:
connection pool to manage embedded database connections.
We encourage you to contribute extensions to the Spring community at
@ -58,8 +58,8 @@ The benefits of using the Spring Framework to create your ORM DAOs include:
@@ -58,8 +58,8 @@ The benefits of using the Spring Framework to create your ORM DAOs include:
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
{spring-site-projects}/spring-data/[Spring Data] suite of projects. If you are
a JPA user, the {spring-site-guides}/gs/accessing-data-jpa/[Getting Started Accessing
Data with JPA] guide from https://spring.io provides a great introduction.
@ -157,7 +157,7 @@ The `LoadTimeWeaver` interface is a Spring-provided class that lets JPA
@@ -157,7 +157,7 @@ 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`
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.
@ -541,8 +541,8 @@ way of auto-configuring an `EntityManagerFactory` setup for Hibernate or Eclipse
@@ -541,8 +541,8 @@ way of auto-configuring an `EntityManagerFactory` setup for Hibernate or Eclipse
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
See the {spring-framework-api}/orm/jpa/JpaDialect.html[`JpaDialect`] and
{spring-framework-api}/orm/jpa/JpaVendorAdapter.html[`JpaVendorAdapter`] javadoc for
more details of its operations and how they are used within Spring's JPA support.
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
Spring's O-X mapping operates through two global interfaces: {spring-framework-api}/oxm/Marshaller.html[`Marshaller`] and
{spring-framework-api}/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
@ -557,7 +557,7 @@ set the `supportedClasses` property on the `XStreamMarshaller`, as the following
@@ -557,7 +557,7 @@ set the `supportedClasses` property on the `XStreamMarshaller`, as the following
Doing so ensures that only the registered classes are eligible for unmarshalling.
@ -95,7 +95,7 @@ parameter to database bind marker translation.
@@ -95,7 +95,7 @@ parameter to database bind marker translation.
run.
* `….namedParameters(false)`: Disable named parameter expansion. Enabled by default.
TIP: Dialects are resolved by {api-spring-framework}/r2dbc/core/binding/BindMarkersFactoryResolver.html[`BindMarkersFactoryResolver`]
TIP: Dialects are resolved by {spring-framework-api}/r2dbc/core/binding/BindMarkersFactoryResolver.html[`BindMarkersFactoryResolver`]
from a `ConnectionFactory`, typically by inspecting `ConnectionFactoryMetadata`.
+
You can let Spring auto-discover your `BindMarkersFactory` by registering a
@ -120,7 +120,7 @@ the reactive sequence to aid debugging.
@@ -120,7 +120,7 @@ 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.
See the attendant {spring-framework-api}/r2dbc/core/DatabaseClient.html[javadoc] for that.
[[r2dbc-DatabaseClient-examples-statement]]
==== Executing Statements
@ -752,7 +752,7 @@ the same time, have this client participating in Spring managed transactions. It
@@ -752,7 +752,7 @@ the same time, have this client participating in Spring managed transactions. It
preferable to integrate a R2DBC client with proper access to `ConnectionFactoryUtils`
for resource management.
See the {api-spring-framework}/r2dbc/connection/TransactionAwareConnectionFactoryProxy.html[`TransactionAwareConnectionFactoryProxy`]
See the {spring-framework-api}/r2dbc/connection/TransactionAwareConnectionFactoryProxy.html[`TransactionAwareConnectionFactoryProxy`]
@ -7,7 +7,7 @@ the JTA `UserTransaction` and `TransactionManager` objects) autodetects the loca
@@ -7,7 +7,7 @@ the JTA `UserTransaction` and `TransactionManager` objects) autodetects the loca
the latter object, which varies by application server. Having access to the JTA
`TransactionManager` allows for enhanced transaction semantics -- in particular,
In XML configuration, the `<tx:annotation-driven/>` tag provides similar convenience:
@ -262,7 +262,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method.
@@ -262,7 +262,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method.
| XML Attribute| Annotation Attribute| Default| Description
| `transaction-manager`
| N/A (see {api-spring-framework}/transaction/annotation/TransactionManagementConfigurer.html[`TransactionManagementConfigurer`] javadoc)
| N/A (see {spring-framework-api}/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.
@ -57,8 +57,7 @@ transaction semantics given by the class annotation (if present). You can annota
@@ -57,8 +57,7 @@ transaction semantics given by the class annotation (if present). You can annota
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
your application with AspectJ (see the {aspectj-docs-devguide}/index.html[AspectJ Development
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.
@ -75,6 +75,6 @@ that it can roll back to. Such partial rollbacks let an inner transaction scope
@@ -75,6 +75,6 @@ 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`].
transactions. See Spring's {spring-framework-api}/jdbc/datasource/DataSourceTransactionManager.html[`DataSourceTransactionManager`].
@ -63,7 +63,7 @@ For the former, listeners are guaranteed to see the current thread-bound transac
@@ -63,7 +63,7 @@ For the former, listeners are guaranteed to see the current thread-bound transac
Since the latter uses the Reactor context instead of thread-local variables, the transaction
context needs to be included in the published event instance as the event source.
@ -67,7 +67,7 @@ To provide a different default key generator, you need to implement the
@@ -67,7 +67,7 @@ To provide a different default key generator, you need to implement the
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]
unexpected key collisions (see {spring-framework-issues}/14870[spring-framework#14870]
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
@ -566,7 +566,7 @@ switching to `aspectj` mode in combination with compile-time or load-time weavin
@@ -566,7 +566,7 @@ switching to `aspectj` mode in combination with compile-time or load-time weavin
NOTE: For more detail about advanced customizations (using Java configuration) that are
required to implement `CachingConfigurer`, see the
@ -26,7 +26,7 @@ interface. A simple value object that encapsulates the properties of a simple ma
@@ -26,7 +26,7 @@ interface. A simple value object that encapsulates the properties of a simple ma
as `from` and `to` (plus many others) is the `SimpleMailMessage` class. This package
also contains a hierarchy of checked exceptions that provide a higher level of
abstraction over the lower level mail system exceptions, with the root exception being
`MailException`. See the {api-spring-framework}/mail/MailException.html[javadoc]
`MailException`. See the {spring-framework-api}/mail/MailException.html[javadoc]
for more information on the rich mail exception hierarchy.
The `org.springframework.mail.javamail.JavaMailSender` interface adds specialized
@ -64,7 +64,7 @@ You can customize the listener container factory to use for each annotation or y
@@ -64,7 +64,7 @@ You can customize the listener container factory to use for each annotation or y
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
@ -64,9 +64,9 @@ In some environments, you can instead obtain the entire `ResourceAdapter` object
@@ -64,9 +64,9 @@ In some environments, you can instead obtain the entire `ResourceAdapter` object
(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`],
and {spring-framework-api}/jca/support/ResourceAdapterFactoryBean.html[`ResourceAdapterFactoryBean`]
for more details.
Spring also provides a generic JCA message endpoint manager that is not tied to JMS:
@ -74,7 +74,7 @@ Spring also provides a generic JCA message endpoint manager that is not tied to
@@ -74,7 +74,7 @@ Spring also provides a generic JCA message endpoint manager that is not tied to
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
@ -113,7 +113,7 @@ as the following example shows:
@@ -113,7 +113,7 @@ as the following example shows:
----
The following table describes all available attributes. See the class-level javadoc
of the {api-spring-framework}/jms/listener/AbstractMessageListenerContainer.html[`AbstractMessageListenerContainer`]
of the {spring-framework-api}/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.
@ -254,7 +254,7 @@ The following table describes the available configuration options for the JCA va
@@ -254,7 +254,7 @@ The following table describes the available configuration options for the JCA va
| `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`]).
provider and its `ActivationSpec` class (see {spring-framework-api}/jms/listener/endpoint/DefaultJmsActivationSpecFactory.html[`DefaultJmsActivationSpecFactory`]).
| `destination-resolver`
| A reference to the `DestinationResolver` strategy for resolving JMS `Destinations`.
@ -76,7 +76,7 @@ containers that ships with Spring (in this case, `DefaultMessageListenerContaine
@@ -76,7 +76,7 @@ containers that ships with Spring (in this case, `DefaultMessageListenerContaine
----
See the Spring javadoc of the various message listener containers (all of which implement
@ -246,7 +246,7 @@ instance. The `NotificationPublisherAware` interface supplies an instance of a
@@ -246,7 +246,7 @@ instance. The `NotificationPublisherAware` interface supplies an instance of a
which the bean can then use to publish `Notifications`.
@ -6,10 +6,8 @@ This section contains links to further resources about JMX:
@@ -6,10 +6,8 @@ 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 {JSR}003[JMX specification] (JSR-000003).
* The {JSR}160[JMX Remote API specification] (JSR-000160).
* The http://mx4j.sourceforge.net/[MX4J homepage]. (MX4J is an open-source implementation of
@ -7,7 +7,7 @@ Metrics can help you to track error rates, usage patterns, performance, and more
@@ -7,7 +7,7 @@ Metrics can help you to track error rates, usage patterns, performance, and more
Traces provide a holistic view of an entire system, crossing application boundaries; you can zoom in on particular user requests and follow their entire completion across applications.
Spring Framework instruments various parts of its own codebase to publish observations if an `ObservationRegistry` is configured.
You can learn more about {docs-spring-boot}/html/actuator.html#actuator.metrics[configuring the observability infrastructure in Spring Boot].
You can learn more about {spring-boot-docs}/actuator.html#actuator.metrics[configuring the observability infrastructure in Spring Boot].
@ -344,7 +344,7 @@ The `spring-web` module contains the `HttpMessageConverter` interface for readin
@@ -344,7 +344,7 @@ The `spring-web` module contains the `HttpMessageConverter` interface for readin
Concrete implementations for the main media (MIME) types are provided in the framework and are, by default, registered with the `RestClient` and `RestTemplate` on the client side and with `RequestMappingHandlerAdapter` on the server side (see xref:web/webmvc/mvc-config/message-converters.adoc[Configuring Message Converters]).
Several implementations of `HttpMessageConverter` are described below.
Refer to the {api-spring-framework}/http/converter/HttpMessageConverter.html[`HttpMessageConverter` Javadoc] for the complete list.
Refer to the {spring-framework-api}/http/converter/HttpMessageConverter.html[`HttpMessageConverter` Javadoc] for the complete list.
For all converters, a default media type is used, but you can override it by setting the `supportedMediaTypes` property.
[[rest-message-converters-tbl]]
@ -384,7 +384,7 @@ When you need further control (for cases where custom JSON serializers/deseriali
@@ -384,7 +384,7 @@ When you need further control (for cases where custom JSON serializers/deseriali
By default, this converter supports `application/json`.
| `MappingJackson2XmlHttpMessageConverter`
| An `HttpMessageConverter` implementation that can read and write XML by using https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML] extension's `XmlMapper`.
| An `HttpMessageConverter` implementation that can read and write XML by using {jackson-github-org}/jackson-dataformat-xml[Jackson XML] extension's `XmlMapper`.
You can customize XML mapping as needed through the use of JAXB or Jackson's provided annotations.
When you need further control (for cases where custom XML serializers/deserializers need to be provided for specific types), you can inject a custom `XmlMapper` through the `ObjectMapper` property.
By default, this converter supports `application/xml`.
@ -401,7 +401,7 @@ You can also set the message converters to use explicitly, by using `messageConv
@@ -401,7 +401,7 @@ You can also set the message converters to use explicitly, by using `messageConv
==== Jackson JSON Views
To serialize only a subset of the object properties, you can specify a https://www.baeldung.com/jackson-json-view-annotation[Jackson JSON View], as the following example shows:
To serialize only a subset of the object properties, you can specify a {baeldung-blog}/jackson-json-view-annotation[Jackson JSON View], as the following example shows:
@ -282,8 +282,8 @@ You can pick and choose the relevant annotations for your application. For examp
@@ -282,8 +282,8 @@ You can pick and choose the relevant annotations for your application. For examp
if you need only support for `@Scheduled`, you can omit `@EnableAsync`. For more
fine-grained control, you can additionally implement the `SchedulingConfigurer`
interface, the `AsyncConfigurer` interface, or both. See the
and {spring-framework-api}/scheduling/annotation/AsyncConfigurer.html[`AsyncConfigurer`]
javadoc for full details.
If you prefer XML configuration, you can use the `<task:annotation-driven>` element,
@ -722,7 +722,7 @@ In the preceding configuration, a `queue-capacity` value has also been provided.
@@ -722,7 +722,7 @@ In the preceding configuration, a `queue-capacity` value has also been provided.
The configuration of the thread pool should also be considered in light of the
executor's queue capacity. For the full description of the relationship between pool
size and queue capacity, see the documentation for
The main idea is that, when a task is submitted, the executor first tries to use a
free thread if the number of active threads is currently less than the core size.
If the core size has been reached, the task is added to the queue, as long as its
@ -1093,7 +1093,7 @@ we need to set up the `SchedulerFactoryBean`, as the following example shows:
@@ -1093,7 +1093,7 @@ we need to set up the `SchedulerFactoryBean`, as the following example shows:
More properties are available for the `SchedulerFactoryBean`, such as the calendars used by the
job details, properties to customize Quartz with, and a Spring-provided JDBC DataSource. See
the {api-spring-framework}/scheduling/quartz/SchedulerFactoryBean.html[`SchedulerFactoryBean`]
the {spring-framework-api}/scheduling/quartz/SchedulerFactoryBean.html[`SchedulerFactoryBean`]
javadoc for more information.
NOTE: `SchedulerFactoryBean` also recognizes a `quartz.properties` file in the classpath,
https://kotlinlang.org[Kotlin] is a statically typed language that targets the JVM
{kotlin-site}[Kotlin] is a statically typed language that targets the JVM
(and other platforms) which allows writing concise and elegant code while providing
very good https://kotlinlang.org/docs/reference/java-interop.html[interoperability]
very good {kotlin-docs}/java-interop.html[interoperability]
with existing libraries written in Java.
The Spring Framework provides first-class support for Kotlin and lets developers write
@ -13,13 +13,13 @@ Most of the code samples of the reference documentation are
@@ -13,13 +13,13 @@ Most of the code samples of the reference documentation are
provided in Kotlin in addition to Java.
The easiest way to build a Spring application with Kotlin is to leverage Spring Boot and
its https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-kotlin.html[dedicated Kotlin support].
The Spring Framework also takes advantage of https://kotlinlang.org/docs/reference/null-safety.html[Kotlin null-safety]
The Spring Framework also takes advantage of {kotlin-docs}/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.
@ -20,9 +20,9 @@ type `Car` may or may not exist. The same behavior applies to autowired construc
@@ -20,9 +20,9 @@ type `Car` may or may not exist. The same behavior applies to autowired construc
NOTE: If you use bean validation on classes with properties or a primary constructor
@ -51,7 +51,7 @@ the constructor parameters will be autowired by type:
@@ -51,7 +51,7 @@ the constructor parameters will be autowired by type:
----
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]
a {spring-framework-api-kdoc}/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.
@ -104,10 +104,10 @@ as the following example shows:
@@ -104,10 +104,10 @@ as the following example shows:
----
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],
{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].
See {stackoverflow-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 {spring-github-org}/spring-fu[Spring Fu incubator].
@ -12,7 +12,7 @@ compiler flag to be enabled during compilation. (For completeness, we neverthele
@@ -12,7 +12,7 @@ compiler flag to be enabled during compilation. (For completeness, we neverthele
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],
{kotlin-docs}/nested-classes.html[top level or nested but not inner],
since the later requires a reference to the outer class.
and types like {kotlin-coroutines-api}/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`
* {kotlin-coroutines-api}/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html[Deferred] and {kotlin-coroutines-api}/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.
* Extensions for WebFlux {spring-framework-api-kdoc}/spring-webflux/org.springframework.web.reactive.function.client/index.html[client] and {spring-framework-api-kdoc}/spring-webflux/org.springframework.web.reactive.function.server/index.html[server] functional API.
* 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`]
* Extensions for {spring-framework-api-kdoc}/spring-messaging/org.springframework.messaging.rsocket/index.html[`RSocketRequester`]
@ -53,17 +53,17 @@ For input parameters:
@@ -53,17 +53,17 @@ 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:
{kotlin-coroutines-api}/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
* `Flow` has only a {kotlin-coroutines-api}/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/collect.html[single suspending `collect` method] and operators are implemented as {kotlin-docs}/extensions.html[extensions]
* {kotlin-github-org}/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
* {kotlin-coroutines-api}/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]
Read this blog post about {spring-site-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.
@ -170,7 +170,7 @@ class CoroutinesViewController(banner: Banner) {
@@ -170,7 +170,7 @@ class CoroutinesViewController(banner: Banner) {
[[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.
Here is an example of Coroutines router defined via the {spring-framework-api-kdoc}/spring-webflux/org.springframework.web.reactive.function.server/co-router.html[coRouter { }] DSL and related handlers.
Kotlin https://kotlinlang.org/docs/reference/extensions.html[extensions] provide the ability
Kotlin {kotlin-docs}/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
The {spring-framework-api-kdoc}/[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,
@ -13,8 +13,8 @@ for example, that the `GenericApplicationContext.registerBean` Kotlin extension
@@ -13,8 +13,8 @@ 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],
For example, {kotlin-docs}/inline-functions.html#reified-type-parameters[Kotlin reified type parameters]
provide a workaround for JVM {java-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
https://kotlinlang.org/docs/reference/java-interop.html#jsr-305-support[Kotlin support for JSR-305 annotations]
{kotlin-docs}/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.
@ -30,7 +30,7 @@ API nullability declaration could evolve even between minor releases and that mo
@@ -30,7 +30,7 @@ API nullability declaration could evolve even between minor releases and that mo
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]
but should be in an upcoming release. See {kotlin-github-org}/KEEP/issues/79[this discussion]
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]
* {kotlin-docs}[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]
* {stackoverflow-spring-kotlin-tags}[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]
@ -34,12 +34,12 @@ The following Github projects offer examples that you can learn from and possibl
@@ -34,12 +34,12 @@ The following Github projects offer examples that you can learn from and possibl
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]
** {spring-framework-issues}/20606[Unable to use WebTestClient with mock server in Kotlin]
** {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]
** {kotlin-issues}/KT-6380[Parent issue for Spring Framework support]
** {kotlin-issues}/KT-5464[Kotlin requires type inference where Java doesn't]
** {kotlin-issues}/KT-20283[Smart cast regression with open classes]
** {kotlin-issues}/KT-14984[Impossible to pass not all SAM argument as function]
** {kotlin-issues}/KT-15125[Support JSR 223 bindings directly via script variables]
** {kotlin-issues}/KT-6653[Kotlin properties do not override Java-style getters and setters]
@ -21,10 +21,10 @@ member function of Spring beans that are proxied by CGLIB, which can
@@ -21,10 +21,10 @@ 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.
See {spring-framework-api}/context/annotation/Configuration.html#proxyBeanMethods--[`proxyBeanMethods` Javadoc] for more details.
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:
@ -59,7 +59,7 @@ within the primary constructor, as in the following example:
@@ -59,7 +59,7 @@ within the primary constructor, as in the following example:
class Person(val name: String, val age: Int)
----
You can optionally add https://kotlinlang.org/docs/reference/data-classes.html[the `data` keyword]
You can optionally add {kotlin-docs}/data-classes.html[the `data` keyword]
to make the compiler automatically derive the following members from all properties declared
in the primary constructor:
@ -80,12 +80,12 @@ As the following example shows, this allows for easy changes to individual prope
@@ -80,12 +80,12 @@ As the following example shows, this allows for easy changes to individual prope
Common persistence technologies (such as JPA) require a default constructor, preventing this
kind of design. Fortunately, there is a workaround for this
since Kotlin provides a {kotlin-docs}/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`]
the {kotlin-docs}/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
@ -98,7 +98,7 @@ does not require the `kotlin-noarg` plugin if the module uses Spring Data object
@@ -98,7 +98,7 @@ does not require the `kotlin-noarg` plugin if the module uses Spring Data object
== 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],
non-nullable when possible) {kotlin-docs}/properties.html[properties],
as the following example shows:
[source,kotlin,indent=0]
@ -137,13 +137,13 @@ as the following example shows:
@@ -137,13 +137,13 @@ as the following example shows:
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
As an alternative, you can customize the property placeholder prefix by declaring the
@ -177,14 +177,14 @@ that uses the `${...}` syntax, with configuration beans, as the following exampl
@@ -177,14 +177,14 @@ that uses the `${...}` syntax, with configuration beans, as the following exampl
[[checked-exceptions]]
== Checked Exceptions
Java and https://kotlinlang.org/docs/reference/exceptions.html[Kotlin exception handling]
Java and {kotlin-docs}/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
to specify explicitly the checked exceptions thrown (for example `@Throws(IOException::class)`).
@ -194,7 +194,7 @@ to specify explicitly the checked exceptions thrown (for example `@Throws(IOExce
@@ -194,7 +194,7 @@ to specify explicitly the checked exceptions thrown (for example `@Throws(IOExce
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
{kotlin-docs}/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
@ -240,13 +240,13 @@ be matched, not only the `GET` method.
@@ -240,13 +240,13 @@ be matched, not only the `GET` method.
== Declaration-site variance
Dealing with generic types in Spring applications written in Kotlin may require, for some use cases, to understand
This needs to be taken into account by using the `out` Kotlin keyword on generic types when using Java classes,
for example when writing a `org.springframework.core.convert.converter.Converter` from a Kotlin type to a Java type.
@ -267,7 +267,7 @@ class ListOfAnyConverter : Converter<List<*>, CustomJavaList<*>> {
@@ -267,7 +267,7 @@ class ListOfAnyConverter : Converter<List<*>, CustomJavaList<*>> {
----
NOTE: Spring Framework does not leverage yet declaration-site variance type information for injecting beans,
subscribe to https://github.com/spring-projects/spring-framework/issues/22313[spring-framework#22313] to track related
subscribe to {spring-framework-issues}/22313[spring-framework#22313] to track related
progresses.
@ -280,7 +280,7 @@ The recommended testing framework is https://junit.org/junit5/[JUnit 5] along wi
@@ -280,7 +280,7 @@ The recommended testing framework is https://junit.org/junit5/[JUnit 5] along wi
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].
{spring-boot-docs}/features.html#features.kotlin.testing[this related documentation].
@ -57,18 +57,18 @@ competition with Spring, they are in fact complementary. The Spring programming
@@ -57,18 +57,18 @@ competition with Spring, they are in fact complementary. The Spring programming
model does not embrace the Jakarta EE platform specification; rather, it integrates
with carefully selected individual specifications from the traditional EE umbrella:
* Servlet API (https://jcp.org/en/jsr/detail?id=340[JSR 340])
* WebSocket API (https://www.jcp.org/en/jsr/detail?id=356[JSR 356])
* as well as JTA/JCA setups for transaction coordination, if necessary.
The Spring Framework also supports the Dependency Injection
(https://www.jcp.org/en/jsr/detail?id=330[JSR 330]) and Common Annotations
(https://jcp.org/en/jsr/detail?id=250[JSR 250]) specifications, which application
({JSR}330[JSR 330]) and Common Annotations
({JSR}250[JSR 250]) specifications, which application
developers may choose to use instead of the Spring-specific mechanisms provided
by the Spring Framework. Originally, those were based on common `javax` packages.
@ -89,7 +89,7 @@ and can run on servers (such as Netty) that are not Servlet containers.
@@ -89,7 +89,7 @@ and can run on servers (such as Netty) that are not Servlet containers.
Spring continues to innovate and to evolve. Beyond the Spring Framework, there are other
projects, such as Spring Boot, Spring Security, Spring Data, Spring Cloud, Spring Batch,
among others. It’s important to remember that each project has its own source code repository,
issue tracker, and release cadence. See https://spring.io/projects[spring.io/projects] for
issue tracker, and release cadence. See {spring-site-projects}[spring.io/projects] for
the complete list of Spring projects.
@ -125,17 +125,17 @@ clean code structure with no circular dependencies between packages.
@@ -125,17 +125,17 @@ clean code structure with no circular dependencies between packages.
== Feedback and Contributions
For how-to questions or diagnosing or debugging issues, we suggest using Stack Overflow. Click
@ -23,7 +23,7 @@ while the above interactions are called "request streams" or simply "requests".
@@ -23,7 +23,7 @@ while the above interactions are called "request streams" or simply "requests".
These are the key features and benefits of the RSocket protocol:
* https://www.reactive-streams.org/[Reactive Streams] semantics across network boundary --
* {reactive-streams-site}/[Reactive Streams] semantics across network boundary --
for streaming requests such as `Request-Stream` and `Channel`, back pressure signals
travel between requester and responder, allowing a requester to slow down a responder at
the source, hence reducing reliance on network layer congestion control, and the need
@ -38,9 +38,9 @@ the amount of state required.
@@ -38,9 +38,9 @@ the amount of state required.
* Fragmentation and re-assembly of large messages.
* Keepalive (heartbeats).
RSocket has {gh-rsocket}[implementations] in multiple languages. The
{gh-rsocket-java}[Java library] is built on https://projectreactor.io/[Project Reactor],
and https://github.com/reactor/reactor-netty[Reactor Netty] for the transport. That means
RSocket has {rsocket-github-org}[implementations] in multiple languages. The
{rsocket-java}[Java library] is built on {reactor-site}/[Project Reactor],
and {reactor-github-org}/reactor-netty[Reactor Netty] for the transport. That means
signals from Reactive Streams Publishers in your application propagate transparently
through RSocket across the network.
@ -50,8 +50,8 @@ through RSocket across the network.
@@ -50,8 +50,8 @@ through RSocket across the network.
=== The Protocol
One of the benefits of RSocket is that it has well defined behavior on the wire and an
easy to read https://rsocket.io/about/protocol[specification] along with some protocol
{gh-rsocket}/rsocket/tree/master/Extensions[extensions]. Therefore it is
easy to read {rsocket-site}/about/protocol[specification] along with some protocol
{rsocket-protocol-extensions}[extensions]. Therefore it is
a good idea to read the spec, independent of language implementations and higher level
framework APIs. This section provides a succinct overview to establish some context.
@ -96,18 +96,18 @@ and therefore only included in the first message on a request, i.e. with one of
@@ -96,18 +96,18 @@ and therefore only included in the first message on a request, i.e. with one of
Protocol extensions define common metadata formats for use in applications:
* {gh-rsocket-extensions}/Routing.md[Routing] -- the route for a request.
* {rsocket-protocol-extensions}/Routing.md[Routing] -- the route for a request.
[[rsocket-java]]
=== Java Implementation
The {gh-rsocket-java}[Java implementation] for RSocket is built on
https://projectreactor.io/[Project Reactor]. The transports for TCP and WebSocket are
built on https://github.com/reactor/reactor-netty[Reactor Netty]. As a Reactive Streams
The {rsocket-java}[Java implementation] for RSocket is built on
{reactor-site}/[Project Reactor]. The transports for TCP and WebSocket are
built on {reactor-github-org}/reactor-netty[Reactor Netty]. As a Reactive Streams
library, Reactor simplifies the job of implementing the protocol. For applications it is
a natural fit to use `Flux` and `Mono` with declarative operators and transparent back
pressure support.
@ -117,7 +117,7 @@ features and leaves the application programming model (e.g. RPC codegen vs other
@@ -117,7 +117,7 @@ features and leaves the application programming model (e.g. RPC codegen vs other
models the four request interaction types with `Mono` representing a promise for a
single message, `Flux` a stream of messages, and `io.rsocket.Payload` the actual
message with access to data and metadata as byte buffers. The `RSocket` contract is used
@ -127,7 +127,7 @@ requests with. For responding, the application implements `RSocket` to handle re
@@ -127,7 +127,7 @@ requests with. For responding, the application implements `RSocket` to handle re
This is not meant to be a thorough introduction. For the most part, Spring applications
will not have to use its API directly. However it may be important to see or experiment
with RSocket independent of Spring. The RSocket Java repository contains a number of
{gh-rsocket-java}/tree/master/rsocket-examples[sample apps] that
{rsocket-java-code}/rsocket-examples[sample apps] that
demonstrate its API and protocol features.
@ -152,7 +152,7 @@ Spring Boot 2.2 supports standing up an RSocket server over TCP or WebSocket, in
@@ -152,7 +152,7 @@ Spring Boot 2.2 supports standing up an RSocket server over TCP or WebSocket, in
the option to expose RSocket over WebSocket in a WebFlux server. There is also client
support and auto-configuration for an `RSocketRequester.Builder` and `RSocketStrategies`.
@ -74,6 +74,6 @@ and registering it by using the `resolver` attribute of `@ActiveProfiles`.
@@ -74,6 +74,6 @@ and registering it by using the `resolver` attribute of `@ActiveProfiles`.
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
{spring-framework-api}/test/context/ActiveProfiles.html[`@ActiveProfiles`] javadoc for
By default, `@ContextCustomizerFactories` provides support for inheriting factories from
superclasses or enclosing classes. See
xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] and the
@ -70,6 +70,6 @@ If you need to merge or override the configuration for a given level of the cont
@@ -70,6 +70,6 @@ If you need to merge or override the configuration for a given level of the cont
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 xref:testing/testcontext-framework/ctx-management/hierarchies.adoc[Context Hierarchies] and the
@ -6,7 +6,7 @@ _dynamic_ properties to be added to the set of `PropertySources` in the `Environ
@@ -6,7 +6,7 @@ _dynamic_ properties to be added to the set of `PropertySources` in the `Environ
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
@ -9,6 +9,6 @@ _Spring TestContext Framework_ to record all application events that are publish
@@ -9,6 +9,6 @@ _Spring TestContext Framework_ to record all application events that are publish
The recorded events can be accessed via the `ApplicationEvents` API within tests.
See xref:testing/testcontext-framework/application-events.adoc[Application Events] and the
By default, `@TestExecutionListeners` provides support for inheriting listeners from
superclasses or enclosing classes. See
xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] and the
@ -8,7 +8,7 @@ See the following resources for more information about testing:
@@ -8,7 +8,7 @@ See the following resources for more information about testing:
* 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 xref:testing/testcontext-framework.adoc[Spring TestContext Framework]
* https://assertj.github.io/doc/[AssertJ]: "Fluent assertions for Java",
* {assertj-docs}[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.
* http://www.mockobjects.com/[MockObjects.com]: Web site dedicated to mock objects, a
@ -24,7 +24,7 @@ See the following resources for more information about testing:
@@ -24,7 +24,7 @@ See the following resources for more information about testing:
* https://www.dbunit.org/[DbUnit]: JUnit extension (also usable with Ant and Maven) that
is targeted at database-driven projects and, among other things, puts your database into
a known state between test runs.
* https://www.testcontainers.org/[Testcontainers]: Java library that supports JUnit
* {testcontainers-site}[Testcontainers]: Java library that supports JUnit
tests, providing lightweight, throwaway instances of common databases, Selenium web
browsers, or anything else that can run in a Docker container.
@ -211,5 +211,5 @@ configuration. Check for the support for code completion on static members.
@@ -211,5 +211,5 @@ configuration. Check for the support for code completion on static members.
// Not possible in Kotlin until https://youtrack.jetbrains.com/issue/KT-22208 is fixed
// Not possible in Kotlin until {kotlin-issues}/KT-22208 is fixed
----
======
@ -192,7 +192,7 @@ Note that common expectations are always applied and cannot be overridden withou
@@ -192,7 +192,7 @@ Note that common expectations are always applied and cannot be overridden withou
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
{spring-github-org}/spring-hateoas[Spring HATEOAS], you can verify the
resulting links by using JsonPath expressions, as the following example shows:
@ -362,7 +362,7 @@ annotation to look up our submit button with a `css` selector (*input[type=submi
@@ -362,7 +362,7 @@ annotation to look up our submit button with a `css` selector (*input[type=submi
--
Finally, we can verify that a new message was created successfully. The following
assertions use the https://assertj.github.io/doc/[AssertJ] assertion library:
assertions use the {assertj-docs}[AssertJ] assertion library:
@ -21,7 +21,7 @@ for rendering JSON, XML, and other formats through `@ResponseBody` methods.
@@ -21,7 +21,7 @@ for rendering JSON, XML, and other formats through `@ResponseBody` methods.
Alternatively, you may consider the full end-to-end integration testing support from
Simon Baslé
2 years ago
committed by
GitHub