Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update API version and package references for Jakarta EE 9

Browse Source 
Closes gh-27689
See gh-25354
This commit is contained in:
Juergen Hoeller
2021-11-17 12:39:23 +01:00
parent 555807ea9c
commit b88ed7f4bb
45 changed files with 303 additions and 352 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/docs/asciidoc/core/core-aop.adoc
View File

@@ -3570,7 +3570,7 @@ visibility may be annotated, including private methods. Annotating non-public me
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 `javax.transaction.Transactional` annotation. Check
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

4
src/docs/asciidoc/core/core-appendix.adoc
View File

@@ -125,7 +125,7 @@ The following example enumeration shows how easy injecting an enum value is:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
----
package javax.persistence;
package jakarta.persistence;
public enum PersistenceContextType {
@@ -136,7 +136,7 @@ The following example enumeration shows how easy injecting an enum value is:
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
package javax.persistence
package jakarta.persistence
enum class PersistenceContextType {

100
src/docs/asciidoc/core/core-beans.adoc
View File

@@ -2835,12 +2835,11 @@ If you access scoped beans within Spring Web MVC, in effect, within a request th
processed by the Spring `DispatcherServlet`, no special setup is necessary.
`DispatcherServlet` already exposes all relevant state.
If you use a Servlet 2.5 web container, with requests processed outside of Spring's
If you use a Servlet web container, with requests processed outside of Spring's
`DispatcherServlet` (for example, when using JSF or Struts), you need to register the
`org.springframework.web.context.request.RequestContextListener` `ServletRequestListener`.
For Servlet 3.0+, this can be done programmatically by using the `WebApplicationInitializer`
interface. Alternatively, or for older containers, add the following declaration to
your web application's `web.xml` file:
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"]
----
@@ -4598,8 +4597,8 @@ injection. Essentially, the `@Autowired` annotation provides the same capabiliti
described in <<beans-factory-autowire>> but with more fine-grained control and wider
applicability. Spring 2.5 also added support for JSR-250 annotations, such as
`@PostConstruct` and `@PreDestroy`. Spring 3.0 added support for JSR-330 (Dependency
Injection for Java) annotations contained in the `javax.inject` package such as `@Inject`
and `@Named`. Details about those annotations can be found in the
Injection for Java) annotations contained in the `jakarta.inject` package such as
`@Inject` and `@Named`. Details about those annotations can be found in the
<<beans-standard-annotations,relevant section>>.
[NOTE]
@@ -4938,7 +4937,7 @@ use the same bean class). `@Order` values may influence priorities at injection
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 `javax.annotation.Priority` annotation is not available at the
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.
====
@@ -5863,8 +5862,8 @@ attribute set to `true`, it is selected.
=== Injection with `@Resource`
Spring also supports injection by using the JSR-250 `@Resource` annotation
(`javax.annotation.Resource`) on fields or bean property setter methods.
This is a common pattern in Java EE: for example, in JSF-managed beans and JAX-WS
(`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
@@ -6186,8 +6185,8 @@ SpEL also enables the use of more complex data structures:
=== Using `@PostConstruct` and `@PreDestroy`
The `CommonAnnotationBeanPostProcessor` not only recognizes the `@Resource` annotation
but also the JSR-250 lifecycle annotations: `javax.annotation.PostConstruct` and
`javax.annotation.PreDestroy`. Introduced in Spring 2.5, the support for these
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
<<beans-factory-lifecycle-initializingbean,initialization callbacks>> and
<<beans-factory-lifecycle-disposablebean,destruction callbacks>>. Provided that the
@@ -6238,8 +6237,9 @@ For details about the effects of combining various lifecycle mechanisms, see
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. If needed, the `javax.annotation-api` artifact needs to be obtained via Maven
Central now, simply to be added to the application's classpath like any other library.
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.
====
@@ -7192,16 +7192,16 @@ annotations. To use them, you need to have the relevant jars in your classpath.
[NOTE]
=====
If you use Maven, the `javax.inject` artifact is available in the standard Maven
If you use Maven, the `jakarta.inject` artifact is available in the standard Maven
repository (
https://repo1.maven.org/maven2/javax/inject/javax.inject/1/[https://repo1.maven.org/maven2/javax/inject/javax.inject/1/]).
https://repo1.maven.org/maven2/jakarta/inject/jakarta.inject-api/2.0.0/[https://repo1.maven.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"]
----
<dependency>
<groupId>javax.inject</groupId>
<artifactId>javax.inject</artifactId>
<groupId>jakarta.inject</groupId>
<artifactId>jakarta.inject-api</artifactId>
<version>1</version>
</dependency>
----
@@ -7212,12 +7212,12 @@ You can add the following dependency to your file pom.xml:
[[beans-inject-named]]
=== Dependency Injection with `@Inject` and `@Named`
Instead of `@Autowired`, you can use `@javax.inject.Inject` as follows:
Instead of `@Autowired`, you can use `@jakarta.inject.Inject` as follows:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
----
import javax.inject.Inject;
import jakarta.inject.Inject;
public class SimpleMovieLister {
@@ -7237,7 +7237,7 @@ Instead of `@Autowired`, you can use `@javax.inject.Inject` as follows:
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
import javax.inject.Inject
import jakarta.inject.Inject
class SimpleMovieLister {
@@ -7261,8 +7261,8 @@ preceding example:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
----
import javax.inject.Inject;
import javax.inject.Provider;
import jakarta.inject.Inject;
import jakarta.inject.Provider;
public class SimpleMovieLister {
@@ -7282,7 +7282,7 @@ preceding example:
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
import javax.inject.Inject
import jakarta.inject.Inject
class SimpleMovieLister {
@@ -7303,8 +7303,8 @@ you should use the `@Named` annotation, as the following example shows:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
----
import javax.inject.Inject;
import javax.inject.Named;
import jakarta.inject.Inject;
import jakarta.inject.Named;
public class SimpleMovieLister {
@@ -7321,8 +7321,8 @@ you should use the `@Named` annotation, as the following example shows:
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
import javax.inject.Inject
import javax.inject.Named
import jakarta.inject.Inject
import jakarta.inject.Named
class SimpleMovieLister {
@@ -7379,14 +7379,14 @@ a `required` attribute. The following pair of examples show how to use `@Inject`
[[beans-named]]
=== `@Named` and `@ManagedBean`: Standard Equivalents to the `@Component` Annotation
Instead of `@Component`, you can use `@javax.inject.Named` or `javax.annotation.ManagedBean`,
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 javax.inject.Inject;
import javax.inject.Named;
import jakarta.inject.Inject;
import jakarta.inject.Named;
@Named("movieListener") // @ManagedBean("movieListener") could be used as well
public class SimpleMovieLister {
@@ -7404,8 +7404,8 @@ as the following example shows:
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
import javax.inject.Inject
import javax.inject.Named
import jakarta.inject.Inject
import jakarta.inject.Named
@Named("movieListener") // @ManagedBean("movieListener") could be used as well
class SimpleMovieLister {
@@ -7423,8 +7423,8 @@ It is very common to use `@Component` without specifying a name for the componen
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
----
import javax.inject.Inject;
import javax.inject.Named;
import jakarta.inject.Inject;
import jakarta.inject.Named;
@Named
public class SimpleMovieLister {
@@ -7442,8 +7442,8 @@ It is very common to use `@Component` without specifying a name for the componen
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
import javax.inject.Inject
import javax.inject.Named
import jakarta.inject.Inject
import jakarta.inject.Named
@Named
class SimpleMovieLister {
@@ -7492,7 +7492,7 @@ features are not available, as the following table shows:
[[annotations-comparison]]
.Spring component model elements versus JSR-330 variants
|===
| Spring| javax.inject.*| javax.inject restrictions / comments
| Spring| jakarta.inject.*| jakarta.inject restrictions / comments
| @Autowired
| @Inject
@@ -7507,15 +7507,15 @@ features are not available, as the following table shows:
| 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. `javax.inject` also provides a
https://download.oracle.com/javaee/6/api/javax/inject/Scope.html[@Scope] annotation.
Nevertheless, this one is only intended to be used for creating your own annotations.
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
| `javax.inject.Qualifier` is just a meta-annotation for building custom qualifiers.
| `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 `javax.inject.Named`.
through `jakarta.inject.Named`.
| @Value
| -
@@ -7531,7 +7531,7 @@ features are not available, as the following table shows:
| ObjectFactory
| Provider
| `javax.inject.Provider` is a direct alternative to Spring's `ObjectFactory`,
| `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.
|===
@@ -8124,7 +8124,7 @@ 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 Java EE application servers.
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`:
@@ -10178,7 +10178,7 @@ 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 Java EE web application.
`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:
@@ -11071,15 +11071,15 @@ Examples are `/WEB-INF/{asterisk}Context.xml` (for all files with names that end
[[context-deploy-rar]]
=== Deploying a Spring `ApplicationContext` as a Java EE RAR File
=== 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 Java EE RAR deployment
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 Java EE environment) being able to access the Java EE servers facilities. RAR deployment
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 Java EE environment.
`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
@@ -11093,7 +11093,7 @@ 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 Java EE RAR file:
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

20
src/docs/asciidoc/core/core-validation.adoc
View File

@@ -1738,8 +1738,8 @@ bean, keep reading.
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
`javax.validation.ValidatorFactory` or `javax.validation.Validator` wherever validation is
needed in your application.
`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:
@@ -1773,18 +1773,18 @@ Validator, is expected to be present in the classpath and is automatically detec
[[validation-beanvalidation-spring-inject]]
==== Injecting a Validator
`LocalValidatorFactoryBean` implements both `javax.validation.ValidatorFactory` and
`javax.validation.Validator`, as well as Spring's `org.springframework.validation.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 `javax.validation.Validator` if you prefer to work with the Bean
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 javax.validation.Validator;
import jakarta.validation.Validator;
@Service
public class MyService {
@@ -1796,7 +1796,7 @@ Validation API directly, as the following example shows:
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
import javax.validation.Validator;
import jakarta.validation.Validator;
@Service
class MyService(@Autowired private val validator: Validator)
@@ -1833,7 +1833,7 @@ requires the Spring Validation API, as the following example shows:
Each bean validation constraint consists of two parts:
* A `@Constraint` annotation that declares the constraint and its configurable properties.
* An implementation of the `javax.validation.ConstraintValidator` interface that implements
* An implementation of the `jakarta.validation.ConstraintValidator` interface that implements
the constraint's behavior.
To associate a declaration with an implementation, each `@Constraint` annotation
@@ -1869,7 +1869,7 @@ The following example shows a custom `@Constraint` declaration followed by an as
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
----
import javax.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidator;
public class MyConstraintValidator implements ConstraintValidator {
@@ -1882,7 +1882,7 @@ The following example shows a custom `@Constraint` declaration followed by an as
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin
----
import javax.validation.ConstraintValidator
import jakarta.validation.ConstraintValidator
class MyConstraintValidator(private val aDependency: Foo) : ConstraintValidator {

67
src/docs/asciidoc/data-access.adoc
View File

@@ -58,7 +58,7 @@ and <<transaction-solutions-to-common-problems, solutions to common problems>>.
[[transaction-motivation]]
=== Advantages of the Spring Framework's Transaction Support Model
Traditionally, Java EE developers have had two choices for transaction management:
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
@@ -133,7 +133,7 @@ applications. Many high-end applications use a single, highly scalable database
Oracle RAC) instead. Stand-alone transaction managers (such as
https://www.atomikos.com/[Atomikos Transactions] and http://jotm.objectweb.org/[JOTM])
are other options. Of course, you may need other application server capabilities, such as
Java Message Service (JMS) and Java EE Connector Architecture (JCA).
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
@@ -189,7 +189,7 @@ The `getTransaction(..)` method returns a `TransactionStatus` object, depending
`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
Java EE transaction contexts, a `TransactionStatus` is associated with a thread of
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
@@ -295,7 +295,7 @@ The related `PlatformTransactionManager` bean definition then has a reference to
</bean>
----
If you use JTA in a Java EE container, then you use a container `DataSource`, obtained
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:
@@ -349,8 +349,8 @@ The `DataSource` bean definition is similar to the local JDBC example shown prev
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 Java EE container, it should be non-transactional, because the
Spring Framework (rather than the Java EE container) manages the transactions.
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
@@ -378,7 +378,7 @@ example declares `sessionFactory` and `txManager` beans:
</bean>
----
If you use Hibernate and Java EE container-managed JTA transactions, you should use the
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:
@@ -502,7 +502,7 @@ behind the scenes and you need not write any special code.
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 Java EE server.
`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
@@ -1297,8 +1297,8 @@ source code puts the declarations much closer to the affected code. There is not
danger of undue coupling, because code that is meant to be used transactionally is
almost always deployed that way anyway.
NOTE: The standard `javax.transaction.Transactional` annotation is also supported as a
drop-in replacement to Spring's own annotation. Please refer to JTA 1.2 documentation
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
@@ -2750,7 +2750,7 @@ 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 Java EE application
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
@@ -3108,7 +3108,7 @@ class and the related support classes. See <<jdbc-core>>, <<jdbc-advanced-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 Java EE container. A subpackage
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>>.
@@ -4249,7 +4249,7 @@ The `DriverManagerDataSource` class is an implementation of the standard `DataSo
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 Java EE
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,
@@ -4263,7 +4263,7 @@ environment, that it is almost always preferable to use such a connection pool o
`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 Java EE server.
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,
@@ -4285,7 +4285,7 @@ specified data source to the currently executing thread, potentially allowing fo
thread connection per data source.
Application code is required to retrieve the JDBC connection through
`DataSourceUtils.getConnection(DataSource)` instead of Java EE's standard
`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
@@ -7809,7 +7809,7 @@ resource definitions in the container or locally within the application is mainl
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 Java EE server's management infrastructure, but does
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
@@ -7819,11 +7819,7 @@ local transaction support is a lightweight and powerful alternative to JTA. When
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 Java EE environment.
JTA does not involve only container dependencies in terms of JTA itself and of
JNDI `DataSource` instances. For non-Spring, JTA-driven Hibernate transactions, you have
to use the Hibernate JCA connector or extra Hibernate transaction code with the
`TransactionManagerLookup` configured for proper JVM-level caching.
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
@@ -7831,12 +7827,7 @@ single database. Thus, you need only use Spring's JTA transaction strategy when
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. Also, you often need the Enterprise Edition
of your container if you use, for example, WebLogic Express, which does not
provide JCA. A Spring application with local resources and transactions that span one
single database works in any Java EE web container (without JTA, JCA, or EJB), such as
Tomcat, Resin, or even plain Jetty. Additionally, you can easily reuse such a middle
tier in desktop applications or test suites.
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
@@ -7964,11 +7955,11 @@ the JPA specification is designed.
[[orm-jpa-setup-jndi]]
===== Obtaining an EntityManagerFactory from JNDI
You can use this option when deploying to a Java EE server. Check your server's documentation
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 Java EE environment),
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"]
@@ -7978,13 +7969,13 @@ is a matter of changing the XML configuration, as the following example shows:
</beans>
----
This action assumes standard Java EE bootstrapping. The Java EE server auto-detects
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 Java EE deployment descriptor (for example,
`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 Java EE server. The JDBC
(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
@@ -8056,12 +8047,12 @@ so on. However, it also imposes requirements on the runtime environment, such as
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 Java EE server. In a
full Java EE environment, consider obtaining your `EntityManagerFactory` from JNDI.
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 Java EE server looks only for default
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.)
@@ -8343,7 +8334,7 @@ protected, or private) does not matter.
What about class-level annotations?
On the Java EE platform, they are used for dependency declaration and not for resource
On the Jakarta EE platform, they are used for dependency declaration and not for resource
injection.
****
@@ -8416,13 +8407,13 @@ more details of its operations and how they are used within Spring's JPA support
==== 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 Java EE environment or with a
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 Java EE environment,
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.

86
src/docs/asciidoc/integration.adoc
View File

@@ -534,7 +534,7 @@ shows our class that extends `SpringBeanAutowiringSupport`:
* the @Autowired annotation) is the simplest JAX-WS compliant way.
*
* This is the class registered with the server-side JAX-WS implementation.
* In the case of a Java EE server, this would simply be defined as a servlet
* In the case of a Jakarta EE server, this would simply be defined as a servlet
* in web.xml, with the server detecting that this is a JAX-WS endpoint and reacting
* accordingly. The servlet name usually needs to match the specified WS service name.
*
@@ -564,7 +564,7 @@ shows our class that extends `SpringBeanAutowiringSupport`:
Our `AccountServiceEndpoint` needs to run in the same web application as the Spring
context to allow for access to Spring's facilities. This is the case by default in Java
EE environments, using the standard contract for JAX-WS servlet endpoint deployment.
See the various Java EE web service tutorials for details.
See the various Jakarta EE web service tutorials for details.
[[remoting-web-services-jaxws-export-standalone]]
@@ -631,12 +631,12 @@ Spring-managed beans, similar to the standalone mode discussed in the
<<remoting-web-services-jaxws-export-standalone, previous section>> --
but this time in a Servlet environment.
NOTE: This is not portable in a Java EE environment. It is mainly intended for non-EE
NOTE: This is not portable in a Jakarta EE environment. It is mainly intended for non-EE
environments, such as Tomcat, that embed the JAX-WS RI as part of the web application.
The differences from the standard style of exporting servlet-based endpoints are that
the lifecycle of the endpoint instances themselves are managed by Spring and that there
is only one JAX-WS servlet defined in `web.xml`. With the standard Java EE style (as
is only one JAX-WS servlet defined in `web.xml`. With the standard Jakarta EE style (as
shown earlier), you have one servlet definition per service endpoint, with each endpoint
typically delegating to Spring beans (through the use of `@Autowired`, as shown earlier).
@@ -1444,7 +1444,7 @@ the same way as Spring's integration does for the JDBC API.
JMS can be roughly divided into two areas of functionality, namely the production and
consumption of messages. The `JmsTemplate` class is used for message production and
synchronous message reception. For asynchronous reception similar to Java EE's
synchronous message reception. For asynchronous reception similar to Jakarta EE's
message-driven bean style, Spring provides a number of message-listener containers that
you can use to create Message-Driven POJOs (MDPs). Spring also provides a declarative way
to create message listeners.
@@ -1461,8 +1461,8 @@ the user.
The `org.springframework.jms.support` package provides `JMSException` translation
functionality. The translation converts the checked `JMSException` hierarchy to a
mirrored hierarchy of unchecked exceptions. If any provider-specific
subclasses of the checked `javax.jms.JMSException` exist, this exception is wrapped in the
mirrored hierarchy of unchecked exceptions. If any provider-specific subclasses
of the checked `jakarta.jms.JMSException` exist, this exception is wrapped in the
unchecked `UncategorizedJmsException`.
The `org.springframework.jms.support.converter` package provides a `MessageConverter`
@@ -1562,7 +1562,7 @@ 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, Java EE containers
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
@@ -1689,7 +1689,7 @@ the standard JMS `MessageConsumer.setMessageListener()` method, and leaves it up
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 Java EE's JMS restrictions.
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,
@@ -1717,7 +1717,7 @@ Each received message is registered with an XA transaction when configured with
`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 Java EE environments.
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
@@ -1762,7 +1762,7 @@ Connection/Session pair from the specified `ConnectionFactory` to the thread.
`JmsTemplate` automatically detects such transactional resources and operates
on them accordingly.
In a Java EE environment, the `ConnectionFactory` pools Connection and Session instances,
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
@@ -1772,7 +1772,7 @@ 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 Java EE server's or JMS provider's documentation.)
(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
@@ -1791,7 +1791,7 @@ transactional JMS `Session`.
=== Sending a Message
The `JmsTemplate` contains many convenience methods to send a message. Send
methods specify the destination by using a `javax.jms.Destination` object, and others
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.
@@ -1800,11 +1800,11 @@ supplied `Session` object:
[source,java,indent=0,subs="verbatim,quotes"]
----
import javax.jms.ConnectionFactory;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.Queue;
import javax.jms.Session;
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;
@@ -1949,17 +1949,17 @@ 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 `javax.jms.MessageListener` interface. Note that, if your POJO receives messages
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 javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageListener;
import javax.jms.TextMessage;
import jakarta.jms.JMSException;
import jakarta.jms.Message;
import jakarta.jms.MessageListener;
import jakarta.jms.TextMessage;
public class ExampleListener implements MessageListener {
@@ -2202,10 +2202,10 @@ transaction manager and use a listener container that supports externally manage
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 Java EE
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
Java EE server's configuration of JNDI resources.) This lets message reception as well
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).
@@ -2265,7 +2265,7 @@ Alternatively, you can set up a `JmsMessageEndpointManager` with a given
<property name="activationSpec">
<bean class="org.apache.activemq.ra.ActiveMQActivationSpec">
<property name="destination" value="myQueue"/>
<property name="destinationType" value="javax.jms.Queue"/>
<property name="destinationType" value="jakarta.jms.Queue"/>
</bean>
</property>
<property name="messageListener" ref="myMessageListener"/>
@@ -2338,7 +2338,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
`javax.jms.Destination` `myDestination`, the `processOrder` method is invoked
`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).
@@ -2462,9 +2462,9 @@ a custom header:
The main elements you can inject in JMS listener endpoints are as follows:
* The raw `javax.jms.Message` or any of its subclasses (provided that it
* The raw `jakarta.jms.Message` or any of its subclasses (provided that it
matches the incoming message type).
* The `javax.jms.Session` for optional access to the native JMS API (for example, for sending
* 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
@@ -2521,7 +2521,7 @@ annotate the payload with `@Valid` and configure the necessary validator, as the
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 `javax.jms.Message`, sent either in the destination specified
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.
@@ -2772,7 +2772,7 @@ also provides a discussion of transaction choices and message redelivery scenari
| 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 Java EE-style transaction management, where the given
default will be `none` (assuming Jakarta EE-style transaction management, where the given
ConnectionFactory is an XA-aware pool).
| `acknowledge`
@@ -2884,7 +2884,7 @@ The following table describes the available configuration options for the JCA va
| `transaction-manager`
| A reference to a Spring `JtaTransactionManager` or a
`javax.transaction.TransactionManager` for kicking off an XA transaction for each
`jakarta.transaction.TransactionManager` for kicking off an XA transaction for each
incoming message. If not specified, native acknowledging is used (see the
`acknowledge` attribute).
@@ -4427,12 +4427,12 @@ callback interface. In the following example, the `mailSender` property is of ty
[source,java,indent=0,subs="verbatim,quotes"]
----
import javax.mail.Message;
import javax.mail.MessagingException;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;
import jakarta.mail.Message;
import jakarta.mail.MessagingException;
import jakarta.mail.internet.InternetAddress;
import jakarta.mail.internet.MimeMessage;
import javax.mail.internet.MimeMessage;
import jakarta.mail.internet.MimeMessage;
import org.springframework.mail.MailException;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.mail.javamail.MimeMessagePreparator;
@@ -4604,7 +4604,7 @@ tasks with the `TaskExecutor` and `TaskScheduler` interfaces, respectively. Spri
features implementations of those interfaces that support thread pools or delegation to
CommonJ within an application server environment. Ultimately, the use of these
implementations behind the common interfaces abstracts away the differences between Java
SE 5, Java SE 6, and Java EE environments.
SE 5, Java SE 6, and Jakarta EE environments.
Spring also features integration classes to support scheduling with the `Timer`
(part of the JDK since 1.3) and the Quartz Scheduler ( https://www.quartz-scheduler.org/[]).
@@ -4622,7 +4622,7 @@ operation).
Executors are the JDK name for the concept of thread pools. The "`executor`" naming is
due to the fact that there is no guarantee that the underlying implementation is
actually a pool. An executor may be single-threaded or even synchronous. Spring's
abstraction hides implementation details between the Java SE and Java EE environments.
abstraction hides implementation details between the Java SE and Jakarta EE environments.
Spring's `TaskExecutor` interface is identical to the `java.util.concurrent.Executor`
interface. In fact, originally, its primary reason for existence was to abstract away
@@ -4664,13 +4664,9 @@ The variants that Spring provides are as follows:
configuring a `java.util.concurrent.ThreadPoolExecutor` and wraps it in a `TaskExecutor`.
If you need to adapt to a different kind of `java.util.concurrent.Executor`, we
recommend that you use a `ConcurrentTaskExecutor` instead.
* `WorkManagerTaskExecutor`:
This implementation uses a CommonJ `WorkManager` as its backing service provider
and is the central convenience class for setting up CommonJ-based thread pool
integration on WebLogic or WebSphere within a Spring application context.
* `DefaultManagedTaskExecutor`:
This implementation uses a JNDI-obtained `ManagedExecutorService` in a JSR-236
compatible runtime environment (such as a Java EE 7+ application server),
compatible runtime environment (such as a Jakarta EE application server),
replacing a CommonJ WorkManager for that purpose.
@@ -4850,7 +4846,7 @@ application server environment where threads should not be created directly by t
application itself. For such scenarios, Spring provides a `TimerManagerTaskScheduler`
that delegates to a CommonJ `TimerManager` on WebLogic or WebSphere as well as a more recent
`DefaultManagedTaskScheduler` that delegates to a JSR-236 `ManagedScheduledExecutorService`
in a Java EE 7+ environment. Both are typically configured with a JNDI lookup.
in a Jakarta EE environment. Both are typically configured with a JNDI lookup.
Whenever external thread management is not a requirement, a simpler alternative is
a local `ScheduledExecutorService` setup within the application, which can be adapted

2
src/docs/asciidoc/integration/integration-appendix.adoc
View File

@@ -13,7 +13,7 @@ This part of the appendix lists XML schemas related to integration technologies.
[[xsd-schemas-jee]]
=== The `jee` Schema
The `jee` elements deal with issues related to Java EE (Java Enterprise Edition) configuration,
The `jee` elements deal with issues related to Jakarta EE (Enterprise Edition) configuration,
such as looking up a JNDI object and defining EJB references.
To use the elements in the `jee` schema, you need to have the following preamble at the top

31
src/docs/asciidoc/overview.adoc
View File

@@ -56,9 +56,10 @@ Of course, Spring's framework jars keep working fine on the classpath on both JD
Spring came into being in 2003 as a response to the complexity of the early
https://en.wikipedia.org/wiki/Java_Platform,_Enterprise_Edition[J2EE] specifications.
While some consider Java EE and Spring to be in competition, Spring is, in fact, complementary
to Java EE. The Spring programming model does not embrace the Java EE platform specification;
rather, it integrates with carefully selected individual specifications from the EE umbrella:
While some consider Java EE and its modern-day successor Jakarta EE to be in
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])
@@ -71,19 +72,21 @@ rather, it integrates with carefully selected individual specifications from the
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 developers
may choose to use instead of the Spring-specific mechanisms provided by the Spring Framework.
(https://jcp.org/en/jsr/detail?id=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.
As of Spring Framework 5.0, Spring requires the Java EE 7 level (e.g. Servlet 3.1+, JPA 2.1+)
as a minimum - while at the same time providing out-of-the-box integration with newer APIs
at the Java EE 8 level (e.g. Servlet 4.0, JSON Binding API) when encountered at runtime.
This keeps Spring fully compatible with e.g. Tomcat 8 and 9, WebSphere 9, and JBoss EAP 7.
As of Spring Framework 6.0, Spring has been upgraded to the Jakarta EE 9 level
(e.g. Servlet 5.0+, JPA 3.0+), based on the `jakarta` namespace instead of the
traditional `javax` packages. With EE 9 as the minimum, Spring is prepared to
provide out-of-the-box support for further API evolution in EE 10+ once available.
This makes Spring Framework 6 fully compatible with e.g. Tomcat 10+ and Jetty 11+.
Over time, the role of Java EE in application development has evolved. In the early days of
Java EE and Spring, applications were created to be deployed to an application server.
Today, with the help of Spring Boot, applications are created in a devops- and
cloud-friendly way, with the Servlet container embedded and trivial to change.
As of Spring Framework 5, a WebFlux application does not even use the Servlet API directly
Over time, the role of Java/Jakarta EE in application development has evolved. In the
early days of J2EE and Spring, applications were created to be deployed to an application
server. Today, with the help of Spring Boot, applications are created in a devops- and
cloud-friendly way, with the Servlet container embedded and trivial to change. As of
Spring Framework 5, a WebFlux application does not even use the Servlet API directly
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

28
src/docs/asciidoc/testing.adoc
View File

@@ -32,8 +32,8 @@ manual.)
== Unit Testing
Dependency injection should make your code less dependent on the container than it would
be with traditional 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`
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 <<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
@@ -78,7 +78,7 @@ out-of-container tests for code that depends on environment-specific properties.
The `org.springframework.mock.jndi` package contains a partial implementation of the JNDI
SPI, which you can use to set up a simple JNDI environment for test suites or stand-alone
applications. If, for example, JDBC `DataSource` instances get bound to the same JNDI
names in test code as they do in a Java EE container, you can reuse both application code
names in test code as they do in a Jakarta EE container, you can reuse both application code
and configuration in testing scenarios without modification.
WARNING: The mock JNDI support in the `org.springframework.mock.jndi` package is
@@ -1476,12 +1476,12 @@ and can be used anywhere in the Spring Framework.
* `@Autowired`
* `@Qualifier`
* `@Value`
* `@Resource` (javax.annotation) if JSR-250 is present
* `@ManagedBean` (javax.annotation) if JSR-250 is present
* `@Inject` (javax.inject) if JSR-330 is present
* `@Named` (javax.inject) if JSR-330 is present
* `@PersistenceContext` (javax.persistence) if JPA is present
* `@PersistenceUnit` (javax.persistence) if JPA is present
* `@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
* `@Required`
* `@Transactional` (org.springframework.transaction.annotation)
_with <<testcontext-tx-attribute-support, limited attribute support>>_
@@ -3088,7 +3088,7 @@ 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 `javax.inject` 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
@@ -7424,10 +7424,10 @@ If using MockMvc through the <<webtestclient>>, there is nothing special to do t
asynchronous requests work as the `WebTestClient` automatically does what is described
in this section.
Servlet 3.0 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.
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.

2
src/docs/asciidoc/web-reactive.adoc
View File

@@ -7,7 +7,7 @@
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 3.1+ containers. Individual chapters cover
servers, such as Netty, Undertow, and Servlet containers. Individual chapters cover
the <<webflux.adoc#webflux, Spring WebFlux>> framework,
the reactive <<webflux-client, `WebClient`>>, support for <<webflux-test, testing>>,
and <<webflux-reactive-libraries, reactive libraries>>. For Servlet-stack web applications,

4
src/docs/asciidoc/web/integration.adoc
View File

@@ -36,7 +36,7 @@ context`"). This section details how you can configure a Spring container (a
Moving on to specifics, all you need to do is declare a
{api-spring-framework}/web/context/ContextLoaderListener.html[`ContextLoaderListener`]
in the standard Java EE servlet `web.xml` file of your web application and add a
in the standard Jakarta EE servlet `web.xml` file of your web application and add a
`contextConfigLocation`<context-param/> section (in the same file) that defines which
set of Spring XML configuration files to load.
@@ -102,7 +102,7 @@ on its specific integration strategies.
== JSF
JavaServer Faces (JSF) is the JCP's standard component-based, event-driven web
user interface framework. It is an official part of the Java EE umbrella but also
user interface framework. It is an official part of the Jakarta EE umbrella but also
individually usable, e.g. through embedding Mojarra or MyFaces within Tomcat.
Please note that recent versions of JSF became closely tied to CDI infrastructure

50
src/docs/asciidoc/web/webflux.adoc
View File

@@ -6,7 +6,7 @@ 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,
Spring WebFlux, was added later in version 5.0. It is fully non-blocking, supports
https://www.reactive-streams.org/[Reactive Streams] back pressure, and runs on such servers as
Netty, Undertow, and Servlet 3.1+ containers.
Netty, Undertow, and Servlet containers.
Both web frameworks mirror the names of their source modules
({spring-framework-main-code}/spring-webmvc[spring-webmvc] and
@@ -23,16 +23,16 @@ in some cases, both -- for example, Spring MVC controllers with the reactive `We
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 3.1 did provide
an API for non-blocking I/O. However, using it 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.
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.
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 http://reactivex.io/[ReactiveX]) that allow declarative
composition of asynchronous logic. At the programming-model level, Java 8 enabled Spring
@@ -149,7 +149,7 @@ 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 3.1+ containers), a choice of programming models
(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).
@@ -187,7 +187,7 @@ unsure what benefits to look for, start by learning about how non-blocking I/O w
[[webflux-server-choice]]
=== Servers
Spring WebFlux is supported on Tomcat, Jetty, Servlet 3.1+ containers, as well as on
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.
@@ -205,7 +205,7 @@ used in the asynchronous, non-blocking space and lets a client and a server shar
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 3.1 non-blocking I/O and uses the Servlet API behind a low-level
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.
@@ -305,7 +305,7 @@ 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 3.1+ container.
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.
@@ -344,16 +344,16 @@ The following table describes the supported server APIs:
| spring-web: Undertow to Reactive Streams bridge
| Tomcat
| Servlet 3.1 non-blocking I/O; Tomcat API to read and write ByteBuffers vs byte[]
| spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge
| 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 3.1 non-blocking I/O; Jetty API to write ByteBuffers vs byte[]
| spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge
| Servlet non-blocking I/O; Jetty API to write ByteBuffers vs byte[]
| spring-web: Servlet non-blocking I/O to Reactive Streams bridge
| Servlet 3.1 container
| Servlet 3.1 non-blocking I/O
| spring-web: Servlet 3.1 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
@@ -484,9 +484,9 @@ The code snippets below show using the `HttpHandler` adapters with each server A
server.start()
----
*Servlet 3.1+ Container*
*Servlet Container*
To deploy as a WAR to any Servlet 3.1+ container, you can extend and include
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`.
@@ -2400,7 +2400,7 @@ immediately next to the `@ModelAttribute`, as the following example shows:
<1> Adding a `BindingResult`.
You can automatically apply validation after data binding by adding the
`javax.validation.Valid` annotation or Spring's `@Validated` annotation (see also
`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:
@@ -2747,7 +2747,7 @@ you can declare a concrete target `Object`, instead of `Part`, as the following
----
<1> Using `@RequestPart` to get the metadata.
You can use `@RequestPart` in combination with `javax.validation.Valid` or Spring's
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
@@ -2869,7 +2869,7 @@ and fully non-blocking reading and (client-to-server) streaming.
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 `javax.validation.Valid` or Spring's
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

34
src/docs/asciidoc/web/webmvc.adoc
View File

@@ -14,7 +14,7 @@ whose name, "`Spring WebFlux,`" is also based on its source module
This section covers Spring Web MVC. The <<web-reactive.adoc#spring-web-reactive, next section>>
covers Spring WebFlux.
For baseline information and compatibility with Servlet container and Java EE version
For baseline information and compatibility with Servlet container and Jakarta EE version
ranges, see the Spring Framework
https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Versions[Wiki].
@@ -315,9 +315,9 @@ provides many extra convenient options.
[[mvc-container-config]]
=== Servlet Config
In a Servlet 3.0+ 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`:
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
@@ -1132,7 +1132,7 @@ request with a simple request parameter.
`MultipartResolver` from the `org.springframework.web.multipart` package is a strategy
for parsing multipart requests including file uploads. There is one implementation
based on https://commons.apache.org/proper/commons-fileupload[Commons FileUpload] and
another based on Servlet 3.0 multipart request parsing.
another based on Servlet multipart request parsing.
To enable multipart handling, you need to declare a `MultipartResolver` bean in your
`DispatcherServlet` Spring configuration with a name of `multipartResolver`.
@@ -1163,9 +1163,9 @@ javadoc for details and configuration options.
[[mvc-multipart-resolver-standard]]
==== Servlet 3.0
==== Servlet Multipart Parsing
Servlet 3.0 multipart parsing needs to be enabled through Servlet container configuration.
Servlet multipart parsing needs to be enabled through Servlet container configuration.
To do so:
* In Java, set a `MultipartConfigElement` on the Servlet registration.
@@ -1205,7 +1205,7 @@ The following example shows how to set a `MultipartConfigElement` on the Servlet
}
----
Once the Servlet 3.0 configuration is in place, you can add a bean of type
Once the Servlet multipart configuration is in place, you can add a bean of type
`StandardServletMultipartResolver` with a name of `multipartResolver`.
[NOTE]
@@ -2777,7 +2777,7 @@ alternatively, set `@ModelAttribute(binding=false)`, as the following example sh
<1> Setting `@ModelAttribute(binding=false)`.
You can automatically apply validation after data binding by adding the
`javax.validation.Valid` annotation or Spring's `@Validated` annotation
`jakarta.validation.Valid` annotation or Spring's `@Validated` annotation
(<<core.adoc#validation-beanvalidation, Bean Validation>> and
<<core.adoc#validation, Spring validation>>). The following example shows how to do so:
@@ -3116,7 +3116,7 @@ When the `@RequestParam` annotation is declared as a `Map<String, MultipartFile>
`MultiValueMap<String, MultipartFile>`, 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 3.0 multipart parsing, you may also declare `jakarta.servlet.http.Part`
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
@@ -3218,7 +3218,7 @@ probably want it deserialized from JSON (similar to `@RequestBody`). Use the
}
----
You can use `@RequestPart` in combination with `javax.validation.Valid` or use Spring's
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
@@ -3275,7 +3275,7 @@ The following example uses a `@RequestBody` argument:
You can use the <<mvc-config-message-converters>> option of the <<mvc-config>> to
configure or customize message conversion.
You can use `@RequestBody` in combination with `javax.validation.Valid` or Spring's
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
@@ -4350,7 +4350,7 @@ capital letters of the class and the method name (for example, the `getThing` me
== Asynchronous Requests
[.small]#<<mvc-ann-async-vs-webflux, Compared to WebFlux>>#
Spring MVC has an extensive integration with Servlet 3.0 asynchronous request
Spring MVC has an extensive integration with Servlet asynchronous request
<<mvc-ann-async-processing,processing>>:
* <<mvc-ann-async-deferredresult, `DeferredResult`>> and <<mvc-ann-async-callable, `Callable`>>
@@ -4524,10 +4524,10 @@ methods for timeout and completion callbacks.
==== Compared to WebFlux
The Servlet API was originally built for making a single pass through the Filter-Servlet
chain. Asynchronous request processing, added in Servlet 3.0, 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
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.

2
src/docs/asciidoc/web/websocket.adoc
View File

@@ -1258,7 +1258,7 @@ The following table describes the method arguments:
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 `@javax.validation.Valid` or Spring's `@Validated`,
You can annotate payload arguments with `@jakarta.validation.Valid` or Spring's `@Validated`,
to have the payload arguments be automatically validated.
| `@Header`