From c09079673a9f08e7de9e7e89be4eb7fcdd4a9dc1 Mon Sep 17 00:00:00 2001 From: Dmitriy Bogdanov Date: Fri, 10 Sep 2021 17:38:42 +0400 Subject: [PATCH 1/2] Fix some typos and mistakes in docs --- src/docs/asciidoc/core/core-aop.adoc | 4 +- src/docs/asciidoc/core/core-beans.adoc | 81 ++++++++++--------- .../asciidoc/core/core-databuffer-codec.adoc | 6 +- src/docs/asciidoc/core/core-expressions.adoc | 2 +- src/docs/asciidoc/core/core-validation.adoc | 5 +- src/docs/asciidoc/data-access.adoc | 30 ++++--- src/docs/asciidoc/integration.adoc | 25 +++--- src/docs/asciidoc/overview.adoc | 2 +- src/docs/asciidoc/testing.adoc | 1 + src/docs/asciidoc/web/integration.adoc | 6 +- src/docs/asciidoc/web/web-uris.adoc | 2 +- src/docs/asciidoc/web/webflux-view.adoc | 2 +- src/docs/asciidoc/web/webmvc-cors.adoc | 2 +- src/docs/asciidoc/web/webmvc-functional.adoc | 4 +- src/docs/asciidoc/web/webmvc-view.adoc | 4 +- src/docs/asciidoc/web/webmvc.adoc | 25 +++--- src/docs/asciidoc/web/websocket.adoc | 6 +- 17 files changed, 105 insertions(+), 102 deletions(-) diff --git a/src/docs/asciidoc/core/core-aop.adoc b/src/docs/asciidoc/core/core-aop.adoc index a6412096e492..6479f329b5d9 100644 --- a/src/docs/asciidoc/core/core-aop.adoc +++ b/src/docs/asciidoc/core/core-aop.adoc @@ -366,7 +366,7 @@ the https://www.eclipse.org/aspectj/doc/released/progguide/index.html[AspectJ Programming Guide] (and, for extensions, the https://www.eclipse.org/aspectj/doc/released/adk15notebook/index.html[AspectJ 5 Developer's Notebook]) or one of the books on AspectJ (such as _Eclipse AspectJ_, by Colyer -et. al., or _AspectJ in Action_, by Ramnivas Laddad). +et al., or _AspectJ in Action_, by Ramnivas Laddad). [[aop-pointcuts-designators]] @@ -893,7 +893,7 @@ scoping). You can include the contextual designators to match based on join point context or bind that context for use in the advice. Supplying only a kinded designator or only a contextual designator works but could affect weaving performance (time and memory used), due to extra processing and analysis. Scoping -designators are very fast to match, and using them usage means AspectJ can very quickly +designators are very fast to match, and using them means AspectJ can very quickly dismiss groups of join points that should not be further processed. A good pointcut should always include one if possible. diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 2a8c526d2617..2d49f0d2a2bc 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -1024,7 +1024,7 @@ by type without help. Consider the following class: class ExampleBean( private val years: Int, // Number of years to calculate the Ultimate Answer - private val ultimateAnswer: String// The Answer to Life, the Universe, and Everything + private val ultimateAnswer: String // The Answer to Life, the Universe, and Everything ) ---- @@ -1608,7 +1608,7 @@ listings shows how to use the `parent` attribute: ---- - + ---- @@ -1690,7 +1690,7 @@ respectively. The following example shows how to use them: - + @@ -2028,7 +2028,7 @@ not commonly used since the plain order of declaration is usually sufficient the In practice, the constructor resolution <> is quite efficient in matching arguments, so unless you really need to, we recommend using the name notation -through-out your configuration. +throughout your configuration. [[beans-compound-property-names]] @@ -2604,9 +2604,9 @@ interface provides the new method definition, as the following example shows: .Kotlin ---- /** - * meant to be used to override the existing computeValue(String) - * implementation in MyValueCalculator - */ + * meant to be used to override the existing computeValue(String) + * implementation in MyValueCalculator + */ class ReplacementComputeValue : MethodReplacer { override fun reimplement(obj: Any, method: Method, args: Array): Any { @@ -2806,7 +2806,7 @@ prototype-scoped bean repeatedly at runtime. You cannot dependency-inject a prototype-scoped bean into your singleton bean, because that injection occurs only once, when the Spring container instantiates the singleton bean and resolves and injects its dependencies. If you need a new instance of a prototype bean at -runtime more than once, see <> +runtime more than once, see <>. @@ -2984,7 +2984,7 @@ The Spring container creates a new instance of the `AppPreferences` bean by usin `appPreferences` bean is scoped at the `ServletContext` level and stored as a regular `ServletContext` attribute. This is somewhat similar to a Spring singleton bean but differs in two important ways: It is a singleton per `ServletContext`, not per Spring -'ApplicationContext' (for which there may be several in any given web application), +`ApplicationContext` (for which there may be several in any given web application), and it is actually exposed and therefore visible as a `ServletContext` attribute. When using annotation-driven components or Java configuration, you can use the @@ -3100,7 +3100,7 @@ to the HTTP `Session`-scoped bean (`userPreferences`). The salient point here is `userManager` bean is a singleton: it is instantiated exactly once per container, and its dependencies (in this case only one, the `userPreferences` bean) are also injected only once. This means that the `userManager` bean operates only on the -exact same `userPreferences` object (that is, the one with which it was originally injected. +exact same `userPreferences` object (that is, the one with which it was originally injected). This is not the behavior you want when injecting a shorter-lived scoped bean into a longer-lived scoped bean (for example, injecting an HTTP `Session`-scoped collaborating @@ -3928,7 +3928,7 @@ shows the definition of the BeanNameAware interface: ---- The callback is invoked after population of normal bean properties but before an -initialization callback such as `InitializingBean`, `afterPropertiesSet`, or a custom +initialization callback such as `InitializingBean.afterPropertiesSet()` or a custom init-method. @@ -4142,7 +4142,7 @@ or it may wrap a bean with a proxy. Some Spring AOP infrastructure classes are implemented as bean post-processors in order to provide proxy-wrapping logic. An `ApplicationContext` automatically detects any beans that are defined in the -configuration metadata that implements the `BeanPostProcessor` interface. The +configuration metadata that implement the `BeanPostProcessor` interface. The `ApplicationContext` registers these beans as post-processors so that they can be called later, upon bean creation. Bean post-processors can be deployed in the container in the same fashion as any other beans. @@ -4673,11 +4673,11 @@ example: ---- class SimpleMovieLister { - @Required - lateinit var movieFinder: MovieFinder + @Required + lateinit var movieFinder: MovieFinder - // ... -} + // ... + } ---- This annotation indicates that the affected bean property must be populated at @@ -5373,7 +5373,7 @@ Letting qualifier values select against target bean names, within the type-match candidates, does not require a `@Qualifier` annotation at the injection point. If there is no other resolution indicator (such as a qualifier or a primary marker), for a non-unique dependency situation, Spring matches the injection point name -(that is, the field name or parameter name) against the target bean names and choose the +(that is, the field name or parameter name) against the target bean names and chooses the same-named candidate, if any. ==== @@ -6042,14 +6042,14 @@ example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java ---- - @Configuration - public class AppConfig { + @Configuration + public class AppConfig { - @Bean - public static PropertySourcesPlaceholderConfigurer propertyPlaceholderConfigurer() { - return new PropertySourcesPlaceholderConfigurer(); - } - } + @Bean + public static PropertySourcesPlaceholderConfigurer propertyPlaceholderConfigurer() { + return new PropertySourcesPlaceholderConfigurer(); + } + } ---- [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] .Kotlin @@ -6099,7 +6099,7 @@ It is possible to provide a default value as following: class MovieRecommender(@Value("\${catalog.name:defaultCatalog}") private val catalog: String) ---- -A Spring `BeanPostProcessor` uses a `ConversionService` behind the scene to handle the +A Spring `BeanPostProcessor` uses a `ConversionService` behind the scenes to handle the process for converting the String value in `@Value` to the target type. If you want to provide conversion support for your own custom type, you can provide your own `ConversionService` bean instance as the following example shows: @@ -6126,7 +6126,7 @@ provide conversion support for your own custom type, you can provide your own @Bean fun conversionService(): ConversionService { - return DefaultFormattingConversionService().apply { + return DefaultFormattingConversionService().apply { addConverter(MyCustomConverter()) } } @@ -6315,7 +6315,7 @@ is meta-annotated with `@Component`, as the following example shows: // ... } ---- -<1> The `Component` causes `@Service` to be treated in the same way as `@Component`. +<1> The `@Component` causes `@Service` to be treated in the same way as `@Component`. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] .Kotlin @@ -6329,7 +6329,7 @@ is meta-annotated with `@Component`, as the following example shows: // ... } ---- -<1> The `Component` causes `@Service` to be treated in the same way as `@Component`. +<1> The `@Component` causes `@Service` to be treated in the same way as `@Component`. You can also combine meta-annotations to create "`composed annotations`". For example, the `@RestController` annotation from Spring MVC is composed of `@Controller` and @@ -7157,7 +7157,7 @@ configuration, as shown in the following example: With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example: -[source,groovy,indent=0subs="verbatim,quotes,attributes"] +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] ---- dependencies { annotationProcessor "org.springframework:spring-context-indexer:{spring-version}" @@ -7631,7 +7631,7 @@ to reduce subtle bugs that can be hard to track down when operating in "`lite`" **** The `@Bean` and `@Configuration` annotations are discussed in depth in the following sections. -First, however, we cover the various ways of creating a spring container using by +First, however, we cover the various ways of creating a spring container by using Java-based configuration. @@ -7892,6 +7892,7 @@ init-param): `@Bean` is a method-level annotation and a direct analog of the XML `` element. The annotation supports some of the attributes offered by ``, such as: + * <> * <> * <> @@ -7980,7 +7981,7 @@ return type, as the following example shows: However, this limits the visibility for advance type prediction to the specified interface type (`TransferService`). Then, with the full type (`TransferServiceImpl`) -known to the container only once, the affected singleton bean has been instantiated. +known to the container only once the affected singleton bean has been instantiated. Non-lazy singleton beans get instantiated according to their declaration order, so you may see different type matching results depending on when another component tries to match by a non-declared type (such as `@Autowired TransferServiceImpl`, @@ -8388,7 +8389,7 @@ annotation, as the following example shows: === Using the `@Configuration` annotation `@Configuration` is a class-level annotation indicating that an object is a source of -bean definitions. `@Configuration` classes declare beans through `@Bean` annotated +bean definitions. `@Configuration` classes declare beans through `@Bean`-annotated methods. Calls to `@Bean` methods on `@Configuration` classes can also be used to define inter-bean dependencies. See <> for a general introduction. @@ -9137,7 +9138,7 @@ method that returns `true` or `false`. For example, the following listing shows val attrs = metadata.getAllAnnotationAttributes(Profile::class.java.name) if (attrs != null) { for (value in attrs["value"]!!) { - if (context.environment.acceptsProfiles(Profiles .of(*value as Array))) { + if (context.environment.acceptsProfiles(Profiles.of(*value as Array))) { return true } } @@ -9901,7 +9902,7 @@ as a way to provide a default definition for one or more beans. If any profile is enabled, the default profile does not apply. You can change the name of the default profile by using `setDefaultProfiles()` on -the `Environment` or ,declaratively, by using the `spring.profiles.default` property. +the `Environment` or, declaratively, by using the `spring.profiles.default` property. @@ -10720,7 +10721,7 @@ following example shows how to do so: ---- It is also possible to add additional runtime filtering by using the `condition` attribute -of the annotation that defines a <> , which should match +of the annotation that defines a <>, which should match to actually invoke the method for a particular event. The following example shows how our notifier can be rewritten to be invoked only if the @@ -10832,10 +10833,12 @@ The following example shows how to do so: Be aware of the following limitations when using asynchronous events: * If an asynchronous event listener throws an `Exception`, it is not propagated to the - caller. See `AsyncUncaughtExceptionHandler` for more details. + caller. See + {api-spring-framework}/aop/interceptor/AsyncUncaughtExceptionHandler.html[`AsyncUncaughtExceptionHandler`] + for more details. * Asynchronous event listener methods cannot publish a subsequent event by returning a value. If you need to publish another event as the result of the processing, inject an - {api-spring-framework}/aop/interceptor/AsyncUncaughtExceptionHandler.html[`ApplicationEventPublisher`] + {api-spring-framework}/context/ApplicationEventPublisher.html[`ApplicationEventPublisher`] to publish the event manually. @@ -11093,8 +11096,8 @@ For a simple deployment of a Spring ApplicationContext as a Java EE RAR file: . Package all application classes into a RAR file (which is a standard JAR file with a different file extension). -.Add all required library JARs into the root of the RAR archive. -.Add a +. Add all required library JARs into the root of the RAR archive. +. Add a `META-INF/ra.xml` deployment descriptor (as shown in the {api-spring-framework}/jca/context/SpringContextResourceAdapter.html[javadoc for `SpringContextResourceAdapter`]) and the corresponding Spring XML bean definition file(s) (typically `META-INF/applicationContext.xml`). diff --git a/src/docs/asciidoc/core/core-databuffer-codec.adoc b/src/docs/asciidoc/core/core-databuffer-codec.adoc index ca5065144961..7abf40a0cdaa 100644 --- a/src/docs/asciidoc/core/core-databuffer-codec.adoc +++ b/src/docs/asciidoc/core/core-databuffer-codec.adoc @@ -12,7 +12,7 @@ APIs as follows: * <> represents a byte buffer, which may be <>. * <> offers utility methods for data buffers. -* <> decode or encode streams data buffer streams into higher level objects. +* <> decode or encode data buffer streams into higher level objects. @@ -127,9 +127,9 @@ others that prefetch and cache data items internally, or is using operators such `filter`, `skip`, and others that leave out items, then `doOnDiscard(PooledDataBuffer.class, DataBufferUtils::release)` must be added to the composition chain to ensure such buffers are released prior to being discarded, possibly -also as a result an error or cancellation signal. +also as a result of an error or cancellation signal. . If a `Decoder` holds on to one or more data buffers in any other way, it must -ensure they are released when fully read, or in case an error or cancellation signals that +ensure they are released when fully read, or in case of an error or cancellation signals that take place before the cached data buffers have been read and released. Note that `DataBufferUtils#join` offers a safe and efficient way to aggregate a data diff --git a/src/docs/asciidoc/core/core-expressions.adoc b/src/docs/asciidoc/core/core-expressions.adoc index c0cd157e2fb2..7396c5bf93b7 100644 --- a/src/docs/asciidoc/core/core-expressions.adoc +++ b/src/docs/asciidoc/core/core-expressions.adoc @@ -357,7 +357,7 @@ the list: // Turn on: // - auto null reference initialization // - auto collection growing - SpelParserConfiguration config = new SpelParserConfiguration(true,true); + SpelParserConfiguration config = new SpelParserConfiguration(true, true); ExpressionParser parser = new SpelExpressionParser(config); diff --git a/src/docs/asciidoc/core/core-validation.adoc b/src/docs/asciidoc/core/core-validation.adoc index 5d80f2a0820a..8563b05ee1fc 100644 --- a/src/docs/asciidoc/core/core-validation.adoc +++ b/src/docs/asciidoc/core/core-validation.adoc @@ -790,7 +790,7 @@ The following example shows how to create your own `PropertyEditorRegistrar` imp See also the `org.springframework.beans.support.ResourceEditorRegistrar` for an example `PropertyEditorRegistrar` implementation. Notice how in its implementation of the -`registerCustomEditors(..)` method ,it creates new instances of each property editor. +`registerCustomEditors(..)` method, it creates new instances of each property editor. The next example shows how to configure a `CustomEditorConfigurer` and inject an instance of our `CustomPropertyEditorRegistrar` into it: @@ -1347,6 +1347,7 @@ listing shows the definition of the `AnnotationFormatterFactory` interface: ---- To create an implementation: + . Parameterize A to be the field `annotationType` with which you wish to associate formatting logic -- for example `org.springframework.format.annotation.DateTimeFormat`. . Have `getFieldTypes()` return the types of fields on which the annotation can be used. @@ -1470,7 +1471,7 @@ The following example uses `@DateTimeFormat` to format a `java.util.Date` as an .Kotlin ---- class MyModel( - @DateTimeFormat(iso= ISO.DATE) private val date: Date + @DateTimeFormat(iso=ISO.DATE) private val date: Date ) ---- diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index 61c8b6330c6f..00e724f2e4c0 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/src/docs/asciidoc/data-access.adoc @@ -445,7 +445,7 @@ relevant `TransactionManager`. [[tx-resource-synchronization-high]] ==== High-level Synchronization Approach -The preferred approach is to use Spring's highest-level template based persistence +The preferred approach is to use Spring's highest-level template-based persistence integration APIs or to use native ORM APIs with transaction-aware factory beans or proxies for managing the native resource factories. These transaction-aware solutions internally handle resource creation and reuse, cleanup, optional transaction @@ -2121,7 +2121,7 @@ declarative approach: - + @@ -2164,7 +2164,7 @@ container by means of an AspectJ aspect. To do so, first annotate your classes (and optionally your classes' methods) with the `@Transactional` annotation, and then link (weave) your application with the `org.springframework.transaction.aspectj.AnnotationTransactionAspect` defined in the -`spring-aspects.jar` file. You must also configure The aspect with a transaction +`spring-aspects.jar` file. You must also configure the aspect with a transaction manager. You can use the Spring Framework's IoC container to take care of dependency-injecting the aspect. The simplest way to configure the transaction management aspect is to use the `` element and specify the `mode` @@ -3295,7 +3295,7 @@ For example, it may be better to write the preceding code snippet as follows: }; public List findAllActors() { - return this.jdbcTemplate.query( "select first_name, last_name from t_actor", actorRowMapper); + return this.jdbcTemplate.query("select first_name, last_name from t_actor", actorRowMapper); } ---- [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -3605,7 +3605,7 @@ variable and the corresponding value that is plugged into the `namedParameters` variable (of type `MapSqlParameterSource`). Alternatively, you can pass along named parameters and their corresponding values to a -`NamedParameterJdbcTemplate` instance by using the `Map`-based style.The remaining +`NamedParameterJdbcTemplate` instance by using the `Map`-based style. The remaining methods exposed by the `NamedParameterJdbcOperations` and implemented by the `NamedParameterJdbcTemplate` class follow a similar pattern and are not covered here. @@ -3799,9 +3799,9 @@ You can extend `SQLErrorCodeSQLExceptionTranslator`, as the following example sh override fun customTranslate(task: String, sql: String?, sqlEx: SQLException): DataAccessException? { if (sqlEx.errorCode == -12345) { - return DeadlockLoserDataAccessException(task, sqlEx) - } - return null; + return DeadlockLoserDataAccessException(task, sqlEx) + } + return null } } ---- @@ -4034,7 +4034,7 @@ The following example updates a column for a certain primary key: In the preceding example, an SQL statement has placeholders for row parameters. You can pass the parameter values -in as varargs or ,alternatively, as an array of objects. Thus, you should explicitly wrap primitives +in as varargs or, alternatively, as an array of objects. Thus, you should explicitly wrap primitives in the primitive wrapper classes, or you should use auto-boxing. @@ -4577,7 +4577,7 @@ The following example shows a batch update that uses a batch size of 100: } ---- -The batch update methods for this call returns an array of `int` arrays that contains an +The batch update method for this call returns an array of `int` arrays that contains an array entry for each batch with an array of the number of affected rows for each update. The top-level array's length indicates the number of batches run, and the second level array's length indicates the number of updates in that batch. The number of updates in @@ -5173,11 +5173,9 @@ as the following example shows: ---- public class JdbcActorDao implements ActorDao { - private JdbcTemplate jdbcTemplate; private SimpleJdbcCall funcGetActorName; public void setDataSource(DataSource dataSource) { - this.jdbcTemplate = new JdbcTemplate(dataSource); JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); jdbcTemplate.setResultsMapCaseInsensitive(true); this.funcGetActorName = new SimpleJdbcCall(jdbcTemplate) @@ -5443,7 +5441,7 @@ example shows such a method: The `SqlUpdate` class encapsulates an SQL update. As with a query, an update object is reusable, and, as with all `RdbmsOperation` classes, an update can have parameters and is defined in SQL. This class provides a number of `update(..)` methods analogous to the -`execute(..)` methods of query objects. The `SQLUpdate` class is concrete. It can be +`execute(..)` methods of query objects. The `SqlUpdate` class is concrete. It can be subclassed -- for example, to add a custom update method. However, you do not have to subclass the `SqlUpdate` class, since it can easily be parameterized by setting SQL and declaring parameters. @@ -7427,7 +7425,7 @@ cover the other ORM technologies and show brief examples. NOTE: As of Spring Framework 5.3, Spring requires Hibernate ORM 5.2+ for Spring's `HibernateJpaVendorAdapter` as well as for a native Hibernate `SessionFactory` setup. -Is is strongly recommended to go with Hibernate ORM 5.4 for a newly started application. +It is strongly recommended to go with Hibernate ORM 5.4 for a newly started application. For use with `HibernateJpaVendorAdapter`, Hibernate Search needs to be upgraded to 5.11.6. @@ -7958,7 +7956,7 @@ persistence unit name. The following XML example configures such a bean: This form of JPA deployment is the simplest and the most limited. You cannot refer to an existing JDBC `DataSource` bean definition, and no support for global transactions exists. Furthermore, weaving (byte-code transformation) of persistent classes is -provider-specific, often requiring a specific JVM agent to specified on startup. This +provider-specific, often requiring a specific JVM agent to be specified on startup. This option is sufficient only for stand-alone applications and test environments, for which the JPA specification is designed. @@ -8093,7 +8091,7 @@ more insight regarding the `LoadTimeWeaver` implementations and their setup, eit generic or customized to various platforms (such as Tomcat, JBoss and WebSphere). As described in <>, you can configure -a context-wide `LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation of the +a context-wide `LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation or the `context:load-time-weaver` XML element. Such a global weaver is automatically picked up by all JPA `LocalContainerEntityManagerFactoryBean` instances. The following example shows the preferred way of setting up a load-time weaver, delivering auto-detection diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index aa17752e28e5..523cc1db59d6 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -390,7 +390,7 @@ model and corresponding services: [source,java,indent=0,subs="verbatim,quotes"] ---- - public class Account implements Serializable{ + public class Account implements Serializable { private String name; @@ -445,7 +445,7 @@ section of the Spring AMQP reference. [[remoting-autodection-remote-interfaces]] [NOTE] ==== -Auto-detection is not implemented for remote interfaces +Auto-detection is not implemented for remote interfaces. The main reason why auto-detection of implemented interfaces does not occur for remote interfaces is to avoid opening too many doors to remote callers. The target object might @@ -514,7 +514,7 @@ Spring provides full support for the standard Java web services APIs: * Accessing web services using JAX-WS In addition to stock support for JAX-WS in Spring Core, the Spring portfolio also -features http://www.springframework.org/spring-ws[Spring Web Services], which is a solution for +features https://projects.spring.io/spring-ws[Spring Web Services], which is a solution for contract-first, document-driven web services -- highly recommended for building modern, future-proof web services. @@ -711,7 +711,7 @@ as the following example shows: ---- NOTE: The above is slightly simplified in that JAX-WS requires endpoint interfaces -and implementation classes to be annotated with `@WebService`, `@SOAPBinding` etc +and implementation classes to be annotated with `@WebService`, `@SOAPBinding`, etc. annotations. This means that you cannot (easily) use plain Java interfaces and implementation classes as JAX-WS endpoint artifacts; you need to annotate them accordingly first. Check the JAX-WS documentation for details on those requirements. @@ -1610,7 +1610,7 @@ cache size is set to `1`. You can use the `sessionCacheSize` property to increas cached sessions. Note that the number of actual cached sessions is more than that number, as sessions are cached based on their acknowledgment mode, so there can be up to four cached session instances (one for each -acknowledgment mode) when `sessionCacheSize` is set to one . `MessageProducer` and `MessageConsumer` instances are cached within their +acknowledgment mode) when `sessionCacheSize` is set to one. `MessageProducer` and `MessageConsumer` instances are cached within their owning session and also take into account the unique properties of the producers and consumers when caching. MessageProducers are cached based on their destination. MessageConsumers are cached based on a key composed of the destination, selector, @@ -1621,7 +1621,7 @@ noLocal delivery flag, and the durable subscription name (if creating durable co ==== Destination Management Destinations, as `ConnectionFactory` instances, are JMS administered objects that you can store -and retrieved in JNDI. When configuring a Spring application context, you can use the +and retrieve in JNDI. When configuring a Spring application context, you can use the JNDI `JndiObjectFactoryBean` factory class or `` to perform dependency injection on your object's references to JMS destinations. However, this strategy is often cumbersome if there are a large number of destinations in the application or if there @@ -1734,7 +1734,7 @@ use a proper cache level in such a case. This container also has recoverable capabilities when the broker goes down. By default, a simple `BackOff` implementation retries every five seconds. You can specify a custom `BackOff` implementation for more fine-grained recovery options. See -api-spring-framework/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example. +{api-spring-framework}/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example. NOTE: Like its sibling (<>), `DefaultMessageListenerContainer` supports native JMS transactions and allows for @@ -1864,7 +1864,7 @@ content. The overloaded methods `convertAndSend()` and `receiveAndConvert()` met `JmsTemplate` delegate the conversion process to an instance of the `MessageConverter` interface. This interface defines a simple contract to convert between Java objects and JMS messages. The default implementation (`SimpleMessageConverter`) supports conversion -between `String` and `TextMessage`, `byte[]` and `BytesMesssage`, and `java.util.Map` +between `String` and `TextMessage`, `byte[]` and `BytesMessage`, and `java.util.Map` and `MapMessage`. By using the converter, you and your application code can focus on the business object that is being sent or received through JMS and not be concerned with the details of how it is represented as a JMS message. @@ -4392,7 +4392,7 @@ email when someone places an order: + order.getCustomer().getLastName() + ", thank you for placing order. Your order number is " + order.getOrderNumber()); - try{ + try { this.mailSender.send(msg); } catch (MailException ex) { @@ -5646,15 +5646,16 @@ compliant caches (such as Ehcache 3.x). See <> for more information plugging in other cache stores and providers. IMPORTANT: The caching abstraction has no special handling for multi-threaded and -multi-process environments, as such features are handled by the cache implementation. . +multi-process environments, as such features are handled by the cache implementation. If you have a multi-process environment (that is, an application deployed on several nodes), you need to configure your cache provider accordingly. Depending on your use cases, a copy of the same data on several nodes can be enough. However, if you change the data during the course of the application, you may need to enable other propagation mechanisms. -Caching a particular item is a direct equivalent of the typical get-if-not-found-then- -proceed-and-put-eventually code blocks found with programmatic cache interaction. +Caching a particular item is a direct equivalent of the typical +get-if-not-found-then-proceed-and-put-eventually code blocks +found with programmatic cache interaction. No locks are applied, and several threads may try to load the same item concurrently. The same applies to eviction. If several threads are trying to update or evict data concurrently, you may use stale data. Certain cache providers offer advanced features diff --git a/src/docs/asciidoc/overview.adoc b/src/docs/asciidoc/overview.adoc index ba74cd35647b..fb24ceef6352 100644 --- a/src/docs/asciidoc/overview.adoc +++ b/src/docs/asciidoc/overview.adoc @@ -44,7 +44,7 @@ parallel, the Spring WebFlux reactive web framework. A note about modules: Spring's framework jars allow for deployment to JDK 9's module path ("Jigsaw"). For use in Jigsaw-enabled applications, the Spring Framework 5 jars come with "Automatic-Module-Name" manifest entries which define stable language-level module names -("spring.core", "spring.context" etc) independent from jar artifact names (the jars follow +("spring.core", "spring.context", etc.) independent from jar artifact names (the jars follow the same naming pattern with "-" instead of ".", e.g. "spring-core" and "spring-context"). Of course, Spring's framework jars keep working fine on the classpath on both JDK 8 and 9+. diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc index 64f07918d46e..6c03726905f5 100644 --- a/src/docs/asciidoc/testing.adoc +++ b/src/docs/asciidoc/testing.adoc @@ -503,6 +503,7 @@ The following example shows such a case: // class body... } ---- +<1> Declaring an initializer class. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] .Kotlin diff --git a/src/docs/asciidoc/web/integration.adoc b/src/docs/asciidoc/web/integration.adoc index 3bac6bb28b96..62d0ef27516b 100644 --- a/src/docs/asciidoc/web/integration.adoc +++ b/src/docs/asciidoc/web/integration.adoc @@ -29,12 +29,12 @@ entry points into a server-side application, and it delegates to service objects (facades) that are defined in a service layer to satisfy business-specific (and presentation-technology agnostic) use cases. In Spring, these service objects, any other business-specific objects, data-access objects, and others exist in a distinct "`business -context`", which contains no web or presentation layer objects (presentation objects -,such as Spring MVC controllers, are typically configured in a distinct "`presentation +context`", which contains no web or presentation layer objects (presentation objects, +such as Spring MVC controllers, are typically configured in a distinct "`presentation context`"). This section details how you can configure a Spring container (a `WebApplicationContext`) that contains all of the 'business beans' in your application. -Moving on to specifics, all you one need to do is declare 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 `contextConfigLocation` section (in the same file) that defines which diff --git a/src/docs/asciidoc/web/web-uris.adoc b/src/docs/asciidoc/web/web-uris.adoc index a36394043b10..33236e76da07 100644 --- a/src/docs/asciidoc/web/web-uris.adoc +++ b/src/docs/asciidoc/web/web-uris.adoc @@ -278,7 +278,7 @@ You can shorten it further still with a full URI template, as the following exam ---- The `WebClient` and the `RestTemplate` expand and encode URI templates internally through -the `UriBuilderFactory` strategy. Both can be configured with a custom strategy. +the `UriBuilderFactory` strategy. Both can be configured with a custom strategy, as the following example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] diff --git a/src/docs/asciidoc/web/webflux-view.adoc b/src/docs/asciidoc/web/webflux-view.adoc index 51a7a1500879..379d5e1a29ff 100644 --- a/src/docs/asciidoc/web/webflux-view.adoc +++ b/src/docs/asciidoc/web/webflux-view.adoc @@ -232,7 +232,7 @@ Java 8+. Using the latest update release available is highly recommended. line should be added for Kotlin script support. See https://github.com/sdeleuze/kotlin-script-templating[this example] for more detail. -You need to have the script templating library. One way to do that for Javascript is +You need to have the script templating library. One way to do that for JavaScript is through https://www.webjars.org/[WebJars]. diff --git a/src/docs/asciidoc/web/webmvc-cors.adoc b/src/docs/asciidoc/web/webmvc-cors.adoc index f86e775c39c6..c73e88bebf22 100644 --- a/src/docs/asciidoc/web/webmvc-cors.adoc +++ b/src/docs/asciidoc/web/webmvc-cors.adoc @@ -50,7 +50,7 @@ Each `HandlerMapping` can be {api-spring-framework}/web/servlet/handler/AbstractHandlerMapping.html#setCorsConfigurations-java.util.Map-[configured] individually with URL pattern-based `CorsConfiguration` mappings. In most cases, applications use the MVC Java configuration or the XML namespace to declare such mappings, which results -in a single global map being passed to all `HandlerMappping` instances. +in a single global map being passed to all `HandlerMapping` instances. You can combine global CORS configuration at the `HandlerMapping` level with more fine-grained, handler-level CORS configuration. For example, annotated controllers can use diff --git a/src/docs/asciidoc/web/webmvc-functional.adoc b/src/docs/asciidoc/web/webmvc-functional.adoc index 1dd3779e1ed4..e40758a781e6 100644 --- a/src/docs/asciidoc/web/webmvc-functional.adoc +++ b/src/docs/asciidoc/web/webmvc-functional.adoc @@ -103,7 +103,7 @@ as the following example shows: If you register the `RouterFunction` as a bean, for instance by exposing it in a -@Configuration class, it will be auto-detected by the servlet, as explained in <>. +`@Configuration` class, it will be auto-detected by the servlet, as explained in <>. @@ -475,7 +475,7 @@ For instance, the router function builder offers the method `GET(String, Handler Besides HTTP method-based mapping, the route builder offers a way to introduce additional predicates when mapping to requests. For each HTTP method there is an overloaded variant that takes a `RequestPredicate` as a -parameter, though which additional constraints can be expressed. +parameter, through which additional constraints can be expressed. [[webmvc-fn-predicates]] diff --git a/src/docs/asciidoc/web/webmvc-view.adoc b/src/docs/asciidoc/web/webmvc-view.adoc index fdca1d02bca4..c127d1ffe43a 100644 --- a/src/docs/asciidoc/web/webmvc-view.adoc +++ b/src/docs/asciidoc/web/webmvc-view.adoc @@ -615,7 +615,7 @@ Java 8+. Using the latest update release available is highly recommended. line should be added for Kotlin script support. See https://github.com/sdeleuze/kotlin-script-templating[this example] for more details. -You need to have the script templating library. One way to do that for Javascript is +You need to have the script templating library. One way to do that for JavaScript is through https://www.webjars.org/[WebJars]. @@ -1697,7 +1697,7 @@ located in the `WEB-INF/defs` directory. At initialization of the `WebApplicatio the files are loaded, and the definitions factory are initialized. After that has been done, the Tiles included in the definition files can be used as views within your Spring web application. To be able to use the views, you have to have a `ViewResolver` -as with any other view technology in Spring : typically a convenient `TilesViewResolver`. +as with any other view technology in Spring: typically a convenient `TilesViewResolver`. You can specify locale-specific Tiles definitions by adding an underscore and then the locale, as the following example shows: diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc index 077bcf39cc56..729dfb214898 100644 --- a/src/docs/asciidoc/web/webmvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -787,7 +787,7 @@ The following table provides more details on the `ViewResolver` hierarchy: you can use the `removeFromCache(String viewName, Locale loc)` method. | `UrlBasedViewResolver` -| Simple implementation of the `ViewResolver` interface that affects the direct +| Simple implementation of the `ViewResolver` interface that effects the direct resolution of logical view names to URLs without an explicit mapping definition. This is appropriate if your logical names match the names of your view resources in a straightforward manner, without the need for arbitrary mappings. @@ -1723,7 +1723,7 @@ one of the following depending on whether use of parsed `PathPattern` is enabled * {api-spring-framework}/web/util/pattern/PathPattern.html#SPECIFICITY_COMPARATOR[`PathPattern.SPECIFICITY_COMPARATOR`] * {api-spring-framework}/util/AntPathMatcher.html#getPatternComparator-java.lang.String-[`AntPathMatcher.getPatternComparator(String path)`] -Both help to sorts patterns with more specific ones on top. A pattern is less specific if +Both help to sort patterns with more specific ones on top. A pattern is less specific if it has a lower count of URI variables (counted as 1), single wildcards (counted as 1), and double wildcards (counted as 2). Given an equal score, the longer pattern is chosen. Given the same score and length, the pattern with more URI variables than wildcards is @@ -1752,7 +1752,7 @@ using the `Accept` header should be the preferred choice. Over time, the use of file name extensions has proven problematic in a variety of ways. It can cause ambiguity when overlain with the use of URI variables, path parameters, and URI encoding. Reasoning about URL-based authorization -and security (see next section for more details) also become more difficult. +and security (see next section for more details) also becomes more difficult. To completely disable the use of path extensions in versions prior to 5.3, set the following: @@ -2171,7 +2171,7 @@ and others) and is equivalent to `required=false`. | If a method argument is not matched to any of the earlier values in this table and it is a simple type (as determined by {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], - it is a resolved as a `@RequestParam`. Otherwise, it is resolved as a `@ModelAttribute`. + it is resolved as a `@RequestParam`. Otherwise, it is resolved as a `@ModelAttribute`. |=== @@ -2777,8 +2777,8 @@ 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 ( -<> and +`javax.validation.Valid` annotation or Spring's `@Validated` annotation +(<> and <>). The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -2841,7 +2841,7 @@ The following example uses the `@SessionAttributes` annotation: ---- @Controller @SessionAttributes("pet") // <1> - public class EditPetForm { + class EditPetForm { // ... } ---- @@ -2866,9 +2866,8 @@ storage, as the following example shows: if (errors.hasErrors) { // ... } - status.setComplete(); // <2> - // ... - } + status.setComplete(); // <2> + // ... } } ---- @@ -4357,7 +4356,7 @@ Spring MVC has an extensive integration with Servlet 3.0 asynchronous request <>: * <> and <> -return values in controller methods and provide basic support for a single asynchronous +return values in controller methods provide basic support for a single asynchronous return value. * Controllers can <> multiple values, including <> and <>. @@ -4889,7 +4888,7 @@ use case-oriented approach that focuses on the common scenarios: val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic() ---- -`WebContentGenerator` also accept a simpler `cachePeriod` property (defined in seconds) that +`WebContentGenerator` also accepts a simpler `cachePeriod` property (defined in seconds) that works as follows: * A `-1` value does not generate a `Cache-Control` response header. @@ -4941,7 +4940,7 @@ settings to a `ResponseEntity`, as the following example shows: } ---- -The preceding example sends an 304 (NOT_MODIFIED) response with an empty body if the comparison +The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison to the conditional request headers indicates that the content has not changed. Otherwise, the `ETag` and `Cache-Control` headers are added to the response. diff --git a/src/docs/asciidoc/web/websocket.adoc b/src/docs/asciidoc/web/websocket.adoc index 07751ff57317..e4ee1e49c055 100644 --- a/src/docs/asciidoc/web/websocket.adoc +++ b/src/docs/asciidoc/web/websocket.adoc @@ -1118,7 +1118,7 @@ Contract for sending a message that enables loose coupling between producers and `SubscribableChannel` that uses an `Executor` for delivering messages. Both the Java configuration (that is, `@EnableWebSocketMessageBroker`) and the XML namespace configuration -(that is,``) use the preceding components to assemble a message +(that is, ``) use the preceding components to assemble a message workflow. The following diagram shows the components used when the simple built-in message broker is enabled: @@ -1191,7 +1191,7 @@ is established, STOMP frames begin to flow on it. . The client sends a SUBSCRIBE frame with a destination header of `/topic/greeting`. Once received and decoded, the message is sent to the `clientInboundChannel` and is then routed to the message broker, which stores the client subscription. -. The client sends a aSEND frame to `/app/greeting`. The `/app` prefix helps to route it to +. The client sends a SEND frame to `/app/greeting`. The `/app` prefix helps to route it to annotated controllers. After the `/app` prefix is stripped, the remaining `/greeting` part of the destination is mapped to the `@MessageMapping` method in `GreetingController`. . The value returned from `GreetingController` is turned into a Spring `Message` with @@ -1768,7 +1768,7 @@ WebSocket and SockJS requests. Therefore, applications that wish to avoid the use of cookies may not have any good alternatives for authentication at the HTTP protocol level. Instead of using cookies, -they may prefer to authenticate with headers at the STOMP messaging protocol level +they may prefer to authenticate with headers at the STOMP messaging protocol level. Doing so requires two simple steps: . Use the STOMP client to pass authentication headers at connect time. From d85a8f8c6b007931398714b238c92a2593878e00 Mon Sep 17 00:00:00 2001 From: Dmitriy Bogdanov Date: Sat, 11 Sep 2021 20:41:51 +0400 Subject: [PATCH 2/2] Fix more typos and mistakes in docs --- src/docs/asciidoc/core/core-beans.adoc | 18 +++++++++--------- src/docs/asciidoc/core/core-expressions.adoc | 2 +- src/docs/asciidoc/core/core-validation.adoc | 4 ++-- src/docs/asciidoc/data-access.adoc | 13 +++++++------ src/docs/asciidoc/integration.adoc | 2 +- src/docs/asciidoc/web/web-uris.adoc | 4 ++-- src/docs/asciidoc/web/webmvc.adoc | 13 +++++++------ 7 files changed, 29 insertions(+), 27 deletions(-) diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 2d49f0d2a2bc..5ba741761f28 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -1834,7 +1834,7 @@ class SomeClass { When the `accounts` property of the `something` bean is prepared for injection, the generics information about the element type of the strongly-typed `Map` is available by reflection. Thus, Spring's type conversion infrastructure recognizes the -various value elements as being of type `Float`, and the string values (`9.99, 2.75`, and +various value elements as being of type `Float`, and the string values (`9.99`, `2.75`, and `3.99`) are converted into an actual `Float` type. @@ -2503,13 +2503,13 @@ declared return type of the lookup method: public abstract class CommandManager { public Object process(Object commandState) { - MyCommand command = createCommand(); + Command command = createCommand(); command.setState(commandState); return command.execute(); } @Lookup - protected abstract MyCommand createCommand(); + protected abstract Command createCommand(); } ---- [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -3960,7 +3960,7 @@ dependency type. The following table summarizes the most important `Aware` inter | `BeanFactoryAware` | Declaring `BeanFactory`. -| <> +| <> | `BeanNameAware` | Name of the declaring bean. @@ -6075,7 +6075,7 @@ will get properties from `application.properties` and `application.yml` files. Built-in converter support provided by Spring allows simple type conversion (to `Integer` or `int` for example) to be automatically handled. Multiple comma-separated values can be -automatically converted to String array without extra effort. +automatically converted to `String` array without extra effort. It is possible to provide a default value as following: @@ -6100,7 +6100,7 @@ It is possible to provide a default value as following: ---- A Spring `BeanPostProcessor` uses a `ConversionService` behind the scenes to handle the -process for converting the String value in `@Value` to the target type. If you want to +process for converting the `String` value in `@Value` to the target type. If you want to provide conversion support for your own custom type, you can provide your own `ConversionService` bean instance as the following example shows: @@ -6591,7 +6591,7 @@ and using "`stub`" repositories instead: includeFilters = @Filter(type = FilterType.REGEX, pattern = ".*Stub.*Repository"), excludeFilters = @Filter(Repository.class)) public class AppConfig { - ... + // ... } ---- [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] @@ -7758,7 +7758,7 @@ To enable component scanning, you can annotate your `@Configuration` class as fo @Configuration @ComponentScan(basePackages = "com.acme") // <1> public class AppConfig { - ... + // ... } ---- <1> This annotation enables component scanning. @@ -8296,7 +8296,7 @@ as the following example shows: @Configuration public class AppConfig { - @Bean(name = "myThing") + @Bean("myThing") public Thing thing() { return new Thing(); } diff --git a/src/docs/asciidoc/core/core-expressions.adoc b/src/docs/asciidoc/core/core-expressions.adoc index 7396c5bf93b7..074523d392d1 100644 --- a/src/docs/asciidoc/core/core-expressions.adoc +++ b/src/docs/asciidoc/core/core-expressions.adoc @@ -465,7 +465,7 @@ following example shows how to do so: .Java ---- SpelParserConfiguration config = new SpelParserConfiguration(SpelCompilerMode.IMMEDIATE, - this.getClass().getClassLoader()); + this.getClass().getClassLoader()); SpelExpressionParser parser = new SpelExpressionParser(config); diff --git a/src/docs/asciidoc/core/core-validation.adoc b/src/docs/asciidoc/core/core-validation.adoc index 8563b05ee1fc..cded5e664ee0 100644 --- a/src/docs/asciidoc/core/core-validation.adoc +++ b/src/docs/asciidoc/core/core-validation.adoc @@ -382,7 +382,7 @@ properties: ---- The following code snippets show some examples of how to retrieve and manipulate some of -the properties of instantiated `Companies` and `Employees`: +the properties of instantiated ``Company``s and ``Employee``s: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -629,7 +629,7 @@ Note that all bean factories and application contexts automatically use a number built-in property editors, through their use of a `BeanWrapper` to handle property conversions. The standard property editors that the `BeanWrapper` registers are listed in the <>. -Additionally, `ApplicationContexts` also override or add additional editors to handle +Additionally, ``ApplicationContext``s also override or add additional editors to handle resource lookups in a manner appropriate to the specific application context type. Standard JavaBeans `PropertyEditor` instances are used to convert property values diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index 00e724f2e4c0..388e4bbf5cd8 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/src/docs/asciidoc/data-access.adoc @@ -1878,7 +1878,7 @@ rollback rules, timeouts, and other features. ==== Transaction Propagation This section describes some semantics of transaction propagation in Spring. Note -that this section is not an introduction to transaction propagation proper. Rather, it +that this section is not a proper introduction to transaction propagation. Rather, it details some of the semantics regarding transaction propagation in Spring. In Spring-managed transactions, be aware of the difference between physical and @@ -2585,8 +2585,7 @@ following example shows how to do so: TransactionStatus status = txManager.getTransaction(def); try { // put your business logic here - } - catch (MyException ex) { + } catch (MyException ex) { txManager.rollback(status); throw ex; } @@ -3743,7 +3742,7 @@ See also <> for guidelines on using the ==== Using `SQLExceptionTranslator` `SQLExceptionTranslator` is an interface to be implemented by classes that can translate -between `SQLExceptions` and Spring's own `org.springframework.dao.DataAccessException`, +between ``SQLException``s and Spring's own `org.springframework.dao.DataAccessException`, which is agnostic in regard to data access strategy. Implementations can be generic (for example, using SQLState codes for JDBC) or proprietary (for example, using Oracle error codes) for greater precision. @@ -6029,7 +6028,7 @@ limit is 1000. In addition to the primitive values in the value list, you can create a `java.util.List` of object arrays. This list can support multiple expressions being defined for the `in` clause, such as `select * from T_ACTOR where (id, last_name) in \((1, 'Johnson'), (2, -'Harrop'\))`. This, of course, requires that your database supports this syntax. +'Harrop'))`. This, of course, requires that your database supports this syntax. [[jdbc-complex-types]] @@ -7091,7 +7090,7 @@ databases, you may want multiple `DatabaseClient` instances, which requires mult instances. [[r2dbc-auto-generated-keys]] -== Retrieving Auto-generated Keys +=== Retrieving Auto-generated Keys `INSERT` statements may generate keys when inserting rows into a table that defines an auto-increment or identity column. To get full control over @@ -7385,7 +7384,9 @@ examples (one for Java configuration and one for XML configuration) show how to ---- @Repository class ProductDaoImpl : ProductDao { + // class body here... + } ---- diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 523cc1db59d6..883acc17867a 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -1747,7 +1747,7 @@ Any such arrangements are significantly more efficient than the alternative: wrapping your entire processing with an XA transaction (through configuring your `DefaultMessageListenerContainer` with an `JtaTransactionManager`) to cover the reception of the JMS message as well as the execution of the business logic in your -message listener (including database operations etc). +message listener (including database operations, etc.). IMPORTANT: The default `AUTO_ACKNOWLEDGE` mode does not provide proper reliability guarantees. Messages can get lost when listener execution fails (since the provider automatically diff --git a/src/docs/asciidoc/web/web-uris.adoc b/src/docs/asciidoc/web/web-uris.adoc index 33236e76da07..11fffde9226f 100644 --- a/src/docs/asciidoc/web/web-uris.adoc +++ b/src/docs/asciidoc/web/web-uris.adoc @@ -95,8 +95,8 @@ You can shorten it further still with a full URI template, as the following exam .Kotlin ---- val uri = UriComponentsBuilder - .fromUriString("https://example.com/hotels/{hotel}?q={q}") - .build("Westin", "123") + .fromUriString("https://example.com/hotels/{hotel}?q={q}") + .build("Westin", "123") ---- diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc index 729dfb214898..d12b6ab923e8 100644 --- a/src/docs/asciidoc/web/webmvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -580,12 +580,12 @@ itself, excluding the `contextPath` and any `servletMapping` prefix, if present. The `servletPath` and `pathInfo` are decoded and that makes them impossible to compare directly to the full `requestURI` in order to derive the lookupPath and that makes it -necessary to decode the `requestUri`. However this introduces its own issues because the +necessary to decode the `requestURI`. However this introduces its own issues because the path may contain encoded reserved characters such as `"/"` or `";"` that can in turn alter the structure of the path after they are decoded which can also lead to security issues. In addition, Servlet containers may normalize the `servletPath` to varying degrees which makes it further impossible to perform `startsWith` comparisons against -the `requestUri`. +the `requestURI`. This is why it is best to avoid reliance on the `servletPath` which comes with the prefix-based `servletPath` mapping type. If the `DispatcherServlet` is mapped as the @@ -597,7 +597,7 @@ a `UrlPathHelper` with `alwaysUseFullPath=true` via <> the MVC config. Fortunately the default Servlet mapping `"/"` is a good choice. However, there is still -an issue in that the `requestUri` needs to be decoded to make it possible to compare to +an issue in that the `requestURI` needs to be decoded to make it possible to compare to controller mappings. This is again undesirable because of the potential to decode reserved characters that alter the path structure. If such characters are not expected, then you can reject them (like the Spring Security HTTP firewall), or you can configure @@ -1545,8 +1545,8 @@ There are also HTTP method specific shortcut variants of `@RequestMapping`: The shortcuts are <> that are provided because, arguably, most controller methods should be mapped to a specific HTTP method versus -using `@RequestMapping`, which, by default, matches to all HTTP methods. At the same, -a `@RequestMapping` is still needed at the class level to express shared mappings. +using `@RequestMapping`, which, by default, matches to all HTTP methods. +A `@RequestMapping` is still needed at the class level to express shared mappings. The following example has type and method level mappings: @@ -2300,7 +2300,7 @@ argument as `@Nullable`. ==== As of 5.3, non-null arguments will be enforced even after type conversion. If your handler method intends to accept a null value as well, either declare your argument as `@Nullable` -or mark it as `required=false` in the corresponding `@RequestParam` etc annotation. This is +or mark it as `required=false` in the corresponding `@RequestParam`, etc. annotation. This is a best practice and the recommended solution for regressions encountered in a 5.3 upgrade. Alternatively, you may specifically handle e.g. the resulting `MissingPathVariableException` @@ -5103,6 +5103,7 @@ following example shows: @Configuration @EnableWebMvc class WebConfig : WebMvcConfigurer { + // Implement configuration methods... } ----