Replace 'e.g.' with 'for example' in documentation and comments
Closes gh-33515
This commit is contained in:
committed by
Sam Brannen
parent
e55fe9077f
commit
8941e2876e
@@ -9,7 +9,7 @@ You can make an introduction by using the `@DeclareParents` annotation. This ann
|
||||
is used to declare that matching types have a new parent (hence the name). For example,
|
||||
given an interface named `UsageTracked` and an implementation of that interface named
|
||||
`DefaultUsageTracked`, the following aspect declares that all implementors of service
|
||||
interfaces also implement the `UsageTracked` interface (e.g. for statistics via JMX):
|
||||
interfaces also implement the `UsageTracked` interface (for example, for statistics via JMX):
|
||||
|
||||
[tabs]
|
||||
======
|
||||
|
||||
@@ -65,7 +65,7 @@ with less potential for errors. For example, you do not need to invoke the `proc
|
||||
method on the `JoinPoint` used for around advice, and, hence, you cannot fail to invoke it.
|
||||
|
||||
All advice parameters are statically typed so that you work with advice parameters of
|
||||
the appropriate type (e.g. the type of the return value from a method execution) rather
|
||||
the appropriate type (for example, the type of the return value from a method execution) rather
|
||||
than `Object` arrays.
|
||||
|
||||
The concept of join points matched by pointcuts is the key to AOP, which distinguishes
|
||||
|
||||
@@ -20,7 +20,7 @@ can be found in the xref:core/beans/standard-annotations.adoc[relevant section].
|
||||
[NOTE]
|
||||
====
|
||||
Annotation injection is performed before external property injection. Thus, external
|
||||
configuration (e.g. XML-specified bean properties) effectively overrides the annotations
|
||||
configuration (for example, XML-specified bean properties) effectively overrides the annotations
|
||||
for properties when wired through mixed approaches.
|
||||
====
|
||||
|
||||
|
||||
@@ -484,7 +484,7 @@ You can register as many event listeners as you wish, but note that, by default,
|
||||
This means that the `publishEvent()` method blocks until all listeners have finished processing the event.
|
||||
One advantage of this synchronous and single-threaded approach is that, when a listener receives an event,
|
||||
it operates inside the transaction context of the publisher if a transaction context is available.
|
||||
If another strategy for event publication becomes necessary, e.g. asynchronous event processing by default,
|
||||
If another strategy for event publication becomes necessary, for example, asynchronous event processing by default,
|
||||
see the javadoc for Spring's {spring-framework-api}/context/event/ApplicationEventMulticaster.html[`ApplicationEventMulticaster`] interface
|
||||
and {spring-framework-api}/context/event/SimpleApplicationEventMulticaster.html[`SimpleApplicationEventMulticaster`] implementation
|
||||
for configuration options which can be applied to a custom "applicationEventMulticaster" bean definition.
|
||||
@@ -864,7 +864,7 @@ Finally, as with classic `ApplicationListener` implementations, the actual multi
|
||||
happens via a context-wide `ApplicationEventMulticaster` at runtime. By default, this is a
|
||||
`SimpleApplicationEventMulticaster` with synchronous event publication in the caller thread.
|
||||
This can be replaced/customized through an "applicationEventMulticaster" bean definition,
|
||||
e.g. for processing all events asynchronously and/or for handling listener exceptions:
|
||||
for example, for processing all events asynchronously and/or for handling listener exceptions:
|
||||
|
||||
[source,java,indent=0,subs="verbatim,quotes"]
|
||||
----
|
||||
|
||||
@@ -144,7 +144,7 @@ based on the given configuration but no further activity with external bean acce
|
||||
Otherwise there is a risk for an initialization deadlock.
|
||||
|
||||
For a scenario where expensive post-initialization activity is to be triggered,
|
||||
e.g. asynchronous database preparation steps, your bean should either implement
|
||||
for example, asynchronous database preparation steps, your bean should either implement
|
||||
`SmartInitializingSingleton.afterSingletonsInstantiated()` or rely on the context
|
||||
refresh event: implementing `ApplicationListener<ContextRefreshedEvent>` or
|
||||
declaring its annotation equivalent `@EventListener(ContextRefreshedEvent.class)`.
|
||||
@@ -607,7 +607,7 @@ bean creation phase and its subsequent initial publication, they need to be decl
|
||||
`volatile` or guarded by a common lock whenever accessed.
|
||||
|
||||
Note that concurrent access to such configuration state in singleton bean instances,
|
||||
e.g. for controller instances or repository instances, is perfectly thread-safe after
|
||||
for example, for controller instances or repository instances, is perfectly thread-safe after
|
||||
such safe initial publication from the container side. This includes common singleton
|
||||
`FactoryBean` instances which are processed within the general singleton lock as well.
|
||||
|
||||
@@ -617,7 +617,7 @@ structures (or in `volatile` fields for simple cases) as per common Java guideli
|
||||
|
||||
Deeper `Lifecycle` integration as shown above involves runtime-mutable state such as
|
||||
a `runnable` field which will have to be declared as `volatile`. While the common
|
||||
lifecycle callbacks follow a certain order, e.g. a start callback is guaranteed to
|
||||
lifecycle callbacks follow a certain order, for example, a start callback is guaranteed to
|
||||
only happen after full initialization and a stop callback only after an initial start,
|
||||
there is a special case with the common stop before destroy arrangement: It is strongly
|
||||
recommended that the internal state in any such bean also allows for an immediate
|
||||
|
||||
@@ -219,7 +219,7 @@ parameter-based injection, as in the preceding example.
|
||||
Avoid access to locally defined beans within a `@PostConstruct` method on the same configuration
|
||||
class. This effectively leads to a circular reference since non-static `@Bean` methods semantically
|
||||
require a fully initialized configuration class instance to be called on. With circular references
|
||||
disallowed (e.g. in Spring Boot 2.6+), this may trigger a `BeanCurrentlyInCreationException`.
|
||||
disallowed (for example, in Spring Boot 2.6+), this may trigger a `BeanCurrentlyInCreationException`.
|
||||
|
||||
Also, be particularly careful with `BeanPostProcessor` and `BeanFactoryPostProcessor` definitions
|
||||
through `@Bean`. Those should usually be declared as `static @Bean` methods, not triggering the
|
||||
|
||||
@@ -29,7 +29,7 @@ a `DataBuffer` implementation and that does not involve allocation.
|
||||
|
||||
Note that WebFlux applications do not create a `DataBufferFactory` directly but instead
|
||||
access it through the `ServerHttpResponse` or the `ClientHttpRequest` on the client side.
|
||||
The type of factory depends on the underlying client or server, e.g.
|
||||
The type of factory depends on the underlying client or server, for example,
|
||||
`NettyDataBufferFactory` for Reactor Netty, `DefaultDataBufferFactory` for others.
|
||||
|
||||
|
||||
@@ -82,7 +82,7 @@ to use the convenience methods in `DataBufferUtils` that apply release or retain
|
||||
|
||||
`DataBufferUtils` offers a number of utility methods to operate on data buffers:
|
||||
|
||||
* Join a stream of data buffers into a single buffer possibly with zero copy, e.g. via
|
||||
* Join a stream of data buffers into a single buffer possibly with zero copy, for example, via
|
||||
composite buffers, if that's supported by the underlying byte buffer API.
|
||||
* Turn `InputStream` or NIO `Channel` into `Flux<DataBuffer>`, and vice versa a
|
||||
`Publisher<DataBuffer>` into `OutputStream` or NIO `Channel`.
|
||||
|
||||
@@ -38,7 +38,7 @@ manner, but through a nested property path. That means constructor binding creat
|
||||
the target object and any objects it contains.
|
||||
|
||||
Constructor binding supports `List`, `Map`, and array arguments either converted from
|
||||
a single string, e.g. comma-separated list, or based on indexed keys such as
|
||||
a single string, for example, comma-separated list, or based on indexed keys such as
|
||||
`accounts[2].name` or `account[KEY].name`.
|
||||
|
||||
Binding and conversion errors are reflected in the `BindingResult` of the `DataBinder`.
|
||||
|
||||
@@ -318,7 +318,7 @@ Kotlin::
|
||||
The `FormatterRegistry` is an SPI for registering formatters and converters.
|
||||
`FormattingConversionService` is an implementation of `FormatterRegistry` suitable for
|
||||
most environments. You can programmatically or declaratively configure this variant
|
||||
as a Spring bean, e.g. by using `FormattingConversionServiceFactoryBean`. Because this
|
||||
as a Spring bean, for example, by using `FormattingConversionServiceFactoryBean`. Because this
|
||||
implementation also implements `ConversionService`, you can directly configure it
|
||||
for use with Spring's `DataBinder` and the Spring Expression Language (SpEL).
|
||||
|
||||
|
||||
@@ -200,7 +200,7 @@ not involving a binding process. As of 6.1, this has been simplified through a n
|
||||
`Validator.validateObject(Object)` method which is available by default now, returning
|
||||
a simple ´Errors` representation which can be inspected: typically calling `hasErrors()`
|
||||
or the new `failOnError` method for turning the error summary message into an exception
|
||||
(e.g. `validator.validateObject(myObject).failOnError(IllegalArgumentException::new)`).
|
||||
(for example, `validator.validateObject(myObject).failOnError(IllegalArgumentException::new)`).
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -223,7 +223,7 @@ As of 6.1.2, Spring bypasses the default `getParameterType` resolution on Postgr
|
||||
MS SQL Server. This is a common optimization to avoid further roundtrips to the DBMS just
|
||||
for parameter type resolution which is known to make a very significant difference on
|
||||
PostgreSQL and MS SQL Server specifically, in particular for batch operations. If you
|
||||
happen to see a side effect e.g. when setting a byte array to null without specific type
|
||||
happen to see a side effect, for example, when setting a byte array to null without specific type
|
||||
indication, you may explicitly set the `spring.jdbc.getParameterType.ignore=false` flag
|
||||
as a system property (see above) to restore full `getParameterType` resolution.
|
||||
|
||||
|
||||
@@ -177,7 +177,7 @@ corresponding `DataSource` proxy class for the target connection pool: see
|
||||
This is particularly useful for potentially empty transactions without actual statement
|
||||
execution (never fetching an actual resource in such a scenario), and also in front of
|
||||
a routing `DataSource` which means to take the transaction-synchronized read-only flag
|
||||
and/or isolation level into account (e.g. `IsolationLevelDataSourceRouter`).
|
||||
and/or isolation level into account (for example, `IsolationLevelDataSourceRouter`).
|
||||
|
||||
`LazyConnectionDataSourceProxy` also provides special support for a read-only connection
|
||||
pool to use during a read-only transaction, avoiding the overhead of switching the JDBC
|
||||
|
||||
@@ -175,7 +175,7 @@ a context-wide `LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation
|
||||
`context:load-time-weaver` XML element. Such a global weaver is automatically picked up
|
||||
by all JPA `LocalContainerEntityManagerFactoryBean` instances. The following example
|
||||
shows the preferred way of setting up a load-time weaver, delivering auto-detection
|
||||
of the platform (e.g. Tomcat's weaving-capable class loader or Spring's JVM agent)
|
||||
of the platform (for example, Tomcat's weaving-capable class loader or Spring's JVM agent)
|
||||
and automatic propagation of the weaver to all weaver-aware beans:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes"]
|
||||
@@ -469,7 +469,7 @@ a non-invasiveness perspective and can feel more natural to JPA developers.
|
||||
What about providing JPA resources via constructors and other `@Autowired` injection points?
|
||||
|
||||
`EntityManagerFactory` can easily be injected via constructors and `@Autowired` fields/methods
|
||||
as long as the target is defined as a bean, e.g. via `LocalContainerEntityManagerFactoryBean`.
|
||||
as long as the target is defined as a bean, for example, via `LocalContainerEntityManagerFactoryBean`.
|
||||
The injection point matches the original `EntityManagerFactory` definition by type as-is.
|
||||
|
||||
However, an `@PersistenceContext`-style shared `EntityManager` reference is not available for
|
||||
|
||||
@@ -469,10 +469,10 @@ Kotlin::
|
||||
|
||||
NOTE: R2DBC itself does not support Collection-like values. Nevertheless,
|
||||
expanding a given `List` in the example above works for named parameters
|
||||
in Spring's R2DBC support, e.g. for use in `IN` clauses as shown above.
|
||||
However, inserting or updating array-typed columns (e.g. in Postgres)
|
||||
in Spring's R2DBC support, for example, for use in `IN` clauses as shown above.
|
||||
However, inserting or updating array-typed columns (for example, in Postgres)
|
||||
requires an array type that is supported by the underlying R2DBC driver:
|
||||
typically a Java array, e.g. `String[]` to update a `text[]` column.
|
||||
typically a Java array, for example, `String[]` to update a `text[]` column.
|
||||
Do not pass `Collection<String>` or the like as an array parameter.
|
||||
|
||||
[[r2dbc-DatabaseClient-filter]]
|
||||
|
||||
@@ -250,7 +250,7 @@ the proxy are intercepted. This means that self-invocation (in effect, a method
|
||||
the target object calling another method of the target object) does not lead to an actual
|
||||
transaction at runtime even if the invoked method is marked with `@Transactional`. Also,
|
||||
the proxy must be fully initialized to provide the expected behavior, so you should not
|
||||
rely on this feature in your initialization code -- e.g. in a `@PostConstruct` method.
|
||||
rely on this feature in your initialization code -- for example, in a `@PostConstruct` method.
|
||||
|
||||
Consider using AspectJ mode (see the `mode` attribute in the following table) if you
|
||||
expect self-invocations to be wrapped with transactions as well. In this case, there is
|
||||
@@ -564,7 +564,7 @@ transaction definitions from a base class as well. This effectively overrides
|
||||
the default transaction manager choice for any unqualified base class methods.
|
||||
|
||||
Last but not least, such a type-level bean qualifier can serve multiple purposes,
|
||||
e.g. with a value of "order" it can be used for autowiring purposes (identifying
|
||||
for example, with a value of "order" it can be used for autowiring purposes (identifying
|
||||
the order repository) as well as transaction manager selection, as long as the
|
||||
target beans for autowiring as well as the associated transaction manager
|
||||
definitions declare the same qualifier value. Such a qualifier value only needs
|
||||
|
||||
@@ -41,7 +41,7 @@ operations need to execute within the same Reactor context in the same reactive
|
||||
|
||||
When configured with a `ReactiveTransactionManager`, all transaction-demarcated methods
|
||||
are expected to return a reactive pipeline. Void methods or regular return types need
|
||||
to be associated with a regular `PlatformTransactionManager`, e.g. through the
|
||||
to be associated with a regular `PlatformTransactionManager`, for example, through the
|
||||
`transactionManager` attribute of the corresponding `@Transactional` declarations.
|
||||
====
|
||||
|
||||
|
||||
@@ -501,12 +501,12 @@ Placing this annotation on the class does not turn on any caching operation.
|
||||
An operation-level customization always overrides a customization set on `@CacheConfig`.
|
||||
Therefore, this gives three levels of customizations for each cache operation:
|
||||
|
||||
* Globally configured, e.g. through `CachingConfigurer`: see next section.
|
||||
* Globally configured, for example, through `CachingConfigurer`: see next section.
|
||||
* At the class level, using `@CacheConfig`.
|
||||
* At the operation level.
|
||||
|
||||
NOTE: Provider-specific settings are typically available on the `CacheManager` bean,
|
||||
e.g. on `CaffeineCacheManager`. These are effectively also global.
|
||||
for example, on `CaffeineCacheManager`. These are effectively also global.
|
||||
|
||||
|
||||
[[cache-annotation-enable]]
|
||||
|
||||
@@ -433,7 +433,7 @@ If no request factory is specified when the `RestClient` was built, it will use
|
||||
Otherwise, if the `java.net.http` module is loaded, it will use Java's `HttpClient`.
|
||||
Finally, it will resort to the simple default.
|
||||
|
||||
TIP: Note that the `SimpleClientHttpRequestFactory` may raise an exception when accessing the status of a response that represents an error (e.g. 401).
|
||||
TIP: Note that the `SimpleClientHttpRequestFactory` may raise an exception when accessing the status of a response that represents an error (for example, 401).
|
||||
If this is an issue, use any of the alternative request factories.
|
||||
|
||||
[[rest-webclient]]
|
||||
@@ -966,7 +966,7 @@ method parameters:
|
||||
|
||||
| `@RequestPart`
|
||||
| Add a request part, which may be a String (form field), `Resource` (file part),
|
||||
Object (entity to be encoded, e.g. as JSON), `HttpEntity` (part content and headers),
|
||||
Object (entity to be encoded, for example, as JSON), `HttpEntity` (part content and headers),
|
||||
a Spring `Part`, or Reactive Streams `Publisher` of any of the above.
|
||||
|
||||
| `MultipartFile`
|
||||
|
||||
@@ -483,7 +483,7 @@ seconds:
|
||||
====
|
||||
When destroying the annotated bean or closing the application context, Spring Framework cancels
|
||||
scheduled tasks, which includes the next scheduled subscription to the `Publisher` as well
|
||||
as any past subscription that is still currently active (e.g. for long-running publishers
|
||||
as any past subscription that is still currently active (for example, for long-running publishers
|
||||
or even infinite publishers).
|
||||
====
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ objects.
|
||||
Spring's scripting support primarily targets Groovy and BeanShell. Beyond those
|
||||
specifically supported languages, the JSR-223 scripting mechanism is supported
|
||||
for integration with any JSR-223 capable language provider (as of Spring 4.2),
|
||||
e.g. JRuby.
|
||||
for example, JRuby.
|
||||
|
||||
You can find fully working examples of where this dynamic language support can be
|
||||
immediately useful in xref:languages/dynamic.adoc#dynamic-language-scenarios[Scenarios].
|
||||
@@ -179,7 +179,7 @@ Each of the supported languages has a corresponding `<lang:language/>` element:
|
||||
|
||||
* `<lang:groovy/>` (Groovy)
|
||||
* `<lang:bsh/>` (BeanShell)
|
||||
* `<lang:std/>` (JSR-223, e.g. with JRuby)
|
||||
* `<lang:std/>` (JSR-223, for example, with JRuby)
|
||||
|
||||
The exact attributes and child elements that are available for configuration depends on
|
||||
exactly which language the bean has been defined in (the language-specific sections
|
||||
|
||||
@@ -73,7 +73,7 @@ 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 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
|
||||
(for example, Servlet 5.0+, JPA 3.0+), based on the `jakarta` namespace instead of the
|
||||
traditional `javax` packages. With EE 9 as the minimum and EE 10 supported already,
|
||||
Spring is prepared to provide out-of-the-box support for the further evolution of
|
||||
the Jakarta EE APIs. Spring Framework 6.0 is fully compatible with Tomcat 10.1,
|
||||
|
||||
@@ -113,7 +113,7 @@ a natural fit to use `Flux` and `Mono` with declarative operators and transparen
|
||||
pressure support.
|
||||
|
||||
The API in RSocket Java is intentionally minimal and basic. It focuses on protocol
|
||||
features and leaves the application programming model (e.g. RPC codegen vs other) as a
|
||||
features and leaves the application programming model (for example, RPC codegen vs other) as a
|
||||
higher level, independent concern.
|
||||
|
||||
The main contract
|
||||
@@ -271,7 +271,7 @@ Kotlin::
|
||||
----
|
||||
======
|
||||
|
||||
`RSocketStrategies` is designed for re-use. In some scenarios, e.g. client and server in
|
||||
`RSocketStrategies` is designed for re-use. In some scenarios, for example, client and server in
|
||||
the same application, it may be preferable to declare it in Spring configuration.
|
||||
|
||||
|
||||
@@ -361,7 +361,7 @@ Kotlin::
|
||||
======
|
||||
|
||||
For the above you may also need to use `setHandlerPredicate` in `RSocketMessageHandler` to
|
||||
switch to a different strategy for detecting client responders, e.g. based on a custom
|
||||
switch to a different strategy for detecting client responders, for example, based on a custom
|
||||
annotation such as `@RSocketClientResponder` vs the default `@Controller`. This
|
||||
is necessary in scenarios with client and server, or multiple clients in the same
|
||||
application.
|
||||
@@ -798,7 +798,7 @@ use the following method arguments:
|
||||
| Requester for making requests to the remote end.
|
||||
|
||||
| `@DestinationVariable`
|
||||
| Value extracted from the route based on variables in the mapping pattern, e.g.
|
||||
| Value extracted from the route based on variables in the mapping pattern, for example,
|
||||
pass:q[`@MessageMapping("find.radar.{id}")`].
|
||||
|
||||
| `@Header`
|
||||
@@ -955,7 +955,7 @@ xref:rsocket.adoc#rsocket-requester-server[Server Requester] for details.
|
||||
|
||||
Responders must interpret metadata.
|
||||
{rsocket-protocol-extensions}/CompositeMetadata.md[Composite metadata] allows independently
|
||||
formatted metadata values (e.g. for routing, security, tracing) each with its own mime
|
||||
formatted metadata values (for example, for routing, security, tracing) each with its own mime
|
||||
type. Applications need a way to configure metadata mime types to support, and a way
|
||||
to access extracted values.
|
||||
|
||||
|
||||
@@ -193,7 +193,7 @@ Then we define expectations with two kinds of responses:
|
||||
* a response obtained through a call to the `/quoteOfTheDay` endpoint
|
||||
|
||||
In the second case, the request is executed through the `ClientHttpRequestFactory` that was
|
||||
captured earlier. This generates a response that could e.g. come from an actual remote server,
|
||||
captured earlier. This generates a response that could, for example, come from an actual remote server,
|
||||
depending on how the `RestTemplate` was originally configured.
|
||||
|
||||
[[spring-mvc-test-client-static-imports]]
|
||||
|
||||
@@ -403,7 +403,7 @@ Java::
|
||||
.expectStatus().isOk()
|
||||
.expectBody(Person.class)
|
||||
.consumeWith(result -> {
|
||||
// custom assertions (e.g. AssertJ)...
|
||||
// custom assertions (for example, AssertJ)...
|
||||
});
|
||||
----
|
||||
|
||||
@@ -416,7 +416,7 @@ Kotlin::
|
||||
.expectStatus().isOk()
|
||||
.expectBody<Person>()
|
||||
.consumeWith {
|
||||
// custom assertions (e.g. AssertJ)...
|
||||
// custom assertions (for example, AssertJ)...
|
||||
}
|
||||
----
|
||||
======
|
||||
|
||||
@@ -103,7 +103,7 @@ on its specific integration strategies.
|
||||
|
||||
JavaServer Faces (JSF) is the JCP's standard component-based, event-driven web
|
||||
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.
|
||||
individually usable, for example, through embedding Mojarra or MyFaces within Tomcat.
|
||||
|
||||
Please note that recent versions of JSF became closely tied to CDI infrastructure
|
||||
in application servers, with some new JSF functionality only working in such an
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
|
||||
xref:web/webflux-webclient/client-attributes.adoc[Attributes] provide a convenient way to pass information to the filter
|
||||
chain but they only influence the current request. If you want to pass information that
|
||||
propagates to additional requests that are nested, e.g. via `flatMap`, or executed after,
|
||||
e.g. via `concatMap`, then you'll need to use the Reactor `Context`.
|
||||
propagates to additional requests that are nested, for example, via `flatMap`, or executed after,
|
||||
for example, via `concatMap`, then you'll need to use the Reactor `Context`.
|
||||
|
||||
The Reactor `Context` needs to be populated at the end of a reactive chain in order to
|
||||
apply to all operations. For example:
|
||||
|
||||
@@ -64,7 +64,7 @@ this `Map`.
|
||||
|
||||
You can also extend `ProblemDetail` to add dedicated non-standard properties.
|
||||
The copy constructor in `ProblemDetail` allows a subclass to make it easy to be created
|
||||
from an existing `ProblemDetail`. This could be done centrally, e.g. from an
|
||||
from an existing `ProblemDetail`. This could be done centrally, for example, from an
|
||||
`@ControllerAdvice` such as `ResponseEntityExceptionHandler` that re-creates the
|
||||
`ProblemDetail` of an exception into a subclass with the additional non-standard fields.
|
||||
|
||||
@@ -107,7 +107,7 @@ Message codes and arguments for each error are also resolved via `MessageSource`
|
||||
|
||||
| `MissingRequestValueException`
|
||||
| (default)
|
||||
| `+{0}+` a label for the value (e.g. "request header", "cookie value", ...), `+{1}+` the value name
|
||||
| `+{0}+` a label for the value (for example, "request header", "cookie value", ...), `+{1}+` the value name
|
||||
|
||||
| `NotAcceptableStatusException`
|
||||
| (default)
|
||||
|
||||
@@ -657,7 +657,7 @@ include the version of the jar and can also match against incoming URLs without
|
||||
-- for example, from `/webjars/jquery/jquery.min.js` to `/webjars/jquery/1.2.0/jquery.min.js`.
|
||||
|
||||
TIP: The Java configuration based on `ResourceHandlerRegistry` provides further options
|
||||
for fine-grained control, e.g. last-modified behavior and optimized resource resolution.
|
||||
for fine-grained control, for example, last-modified behavior and optimized resource resolution.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -82,10 +82,10 @@ parameters. While `@BindParam` is supported out of the box, you can also use a
|
||||
different annotation by setting a `DataBinder.NameResolver` on `DataBinder`
|
||||
|
||||
Constructor binding supports `List`, `Map`, and array arguments either converted from
|
||||
a single string, e.g. comma-separated list, or based on indexed keys such as
|
||||
a single string, for example, comma-separated list, or based on indexed keys such as
|
||||
`accounts[2].name` or `account[KEY].name`.
|
||||
|
||||
WebFlux, unlike Spring MVC, supports reactive types in the model, e.g. `Mono<Account>`.
|
||||
WebFlux, unlike Spring MVC, supports reactive types in the model, for example, `Mono<Account>`.
|
||||
You can declare a `@ModelAttribute` argument with or without a reactive type wrapper, and
|
||||
it will be resolved accordingly to the actual value.
|
||||
|
||||
|
||||
@@ -343,7 +343,7 @@ You can declare a shared `produces` attribute at the class level. Unlike most ot
|
||||
mapping attributes, however, when used at the class level, a method-level `produces` attribute
|
||||
overrides rather than extend the class level declaration.
|
||||
|
||||
TIP: `MediaType` provides constants for commonly used media types -- e.g.
|
||||
TIP: `MediaType` provides constants for commonly used media types -- for example,
|
||||
`APPLICATION_JSON_VALUE`, `APPLICATION_XML_VALUE`.
|
||||
|
||||
|
||||
|
||||
@@ -170,7 +170,7 @@ A `HandlerAdapter` may expose its exception handling mechanism as a
|
||||
|
||||
A `HandlerAdapter` may also choose to implement `DispatchExceptionHandler`. In that case
|
||||
`DispatcherHandler` will apply it to exceptions that arise before a handler is mapped,
|
||||
e.g. during handler mapping, or earlier, e.g. in a `WebFilter`.
|
||||
for example, during handler mapping, or earlier, for example, in a `WebFilter`.
|
||||
|
||||
See also xref:web/webflux/controller/ann-exceptions.adoc[Exceptions] in the "`Annotated Controller`" section or
|
||||
xref:web/webflux/reactive-spring.adoc#webflux-exception-handler[Exceptions] in the WebHandler API section.
|
||||
|
||||
@@ -468,7 +468,7 @@ to encode and decode HTTP message content.
|
||||
* An `Encoder` can be wrapped with `EncoderHttpMessageWriter` to adapt it for use in a web
|
||||
application, while a `Decoder` can be wrapped with `DecoderHttpMessageReader`.
|
||||
* {spring-framework-api}/core/io/buffer/DataBuffer.html[`DataBuffer`] abstracts different
|
||||
byte buffer representations (e.g. Netty `ByteBuf`, `java.nio.ByteBuffer`, etc.) and is
|
||||
byte buffer representations (for example, Netty `ByteBuf`, `java.nio.ByteBuffer`, etc.) and is
|
||||
what all codecs work on. See xref:core/databuffer-codec.adoc[Data Buffers and Codecs] in the
|
||||
"Spring Core" section for more on this topic.
|
||||
|
||||
@@ -493,8 +493,8 @@ The `Jackson2Decoder` works as follows:
|
||||
* Jackson's asynchronous, non-blocking parser is used to aggregate a stream of byte chunks
|
||||
into ``TokenBuffer``'s each representing a JSON object.
|
||||
* Each `TokenBuffer` is passed to Jackson's `ObjectMapper` to create a higher level object.
|
||||
* When decoding to a single-value publisher (e.g. `Mono`), there is one `TokenBuffer`.
|
||||
* When decoding to a multi-value publisher (e.g. `Flux`), each `TokenBuffer` is passed to
|
||||
* When decoding to a single-value publisher (for example, `Mono`), there is one `TokenBuffer`.
|
||||
* When decoding to a multi-value publisher (for example, `Flux`), each `TokenBuffer` is passed to
|
||||
the `ObjectMapper` as soon as enough bytes are received for a fully formed object. The
|
||||
input content can be a JSON array, or any
|
||||
https://en.wikipedia.org/wiki/JSON_streaming[line-delimited JSON] format such as NDJSON,
|
||||
@@ -502,7 +502,7 @@ JSON Lines, or JSON Text Sequences.
|
||||
|
||||
The `Jackson2Encoder` works as follows:
|
||||
|
||||
* For a single value publisher (e.g. `Mono`), simply serialize it through the
|
||||
* For a single value publisher (for example, `Mono`), simply serialize it through the
|
||||
`ObjectMapper`.
|
||||
* For a multi-value publisher with `application/json`, by default collect the values with
|
||||
`Flux#collectToList()` and then serialize the resulting collection.
|
||||
|
||||
@@ -88,7 +88,7 @@ class- or method-level `@CrossOrigin` annotations (other handlers can implement
|
||||
|
||||
The rules for combining global and local configuration are generally additive -- for example,
|
||||
all global and all local origins. For those attributes where only a single value can be
|
||||
accepted, e.g. `allowCredentials` and `maxAge`, the local overrides the global value. See
|
||||
accepted, for example, `allowCredentials` and `maxAge`, the local overrides the global value. See
|
||||
{spring-framework-api}/web/cors/CorsConfiguration.html#combine-org.springframework.web.cors.CorsConfiguration-[`CorsConfiguration#combine(CorsConfiguration)`]
|
||||
for more details.
|
||||
|
||||
|
||||
@@ -64,7 +64,7 @@ this `Map`.
|
||||
|
||||
You can also extend `ProblemDetail` to add dedicated non-standard properties.
|
||||
The copy constructor in `ProblemDetail` allows a subclass to make it easy to be created
|
||||
from an existing `ProblemDetail`. This could be done centrally, e.g. from an
|
||||
from an existing `ProblemDetail`. This could be done centrally, for example, from an
|
||||
`@ControllerAdvice` such as `ResponseEntityExceptionHandler` that re-creates the
|
||||
`ProblemDetail` of an exception into a subclass with the additional non-standard fields.
|
||||
|
||||
|
||||
@@ -58,7 +58,7 @@ include the version of the jar and can also match against incoming URLs without
|
||||
-- for example, from `/webjars/jquery/jquery.min.js` to `/webjars/jquery/1.2.0/jquery.min.js`.
|
||||
|
||||
TIP: The Java configuration based on `ResourceHandlerRegistry` provides further options
|
||||
for fine-grained control, e.g. last-modified behavior and optimized resource resolution.
|
||||
for fine-grained control, for example, last-modified behavior and optimized resource resolution.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -13,8 +13,8 @@ include-code::./SimpleController[indent=0]
|
||||
[[mvc-ann-exceptionhandler-exc]]
|
||||
== Exception Mapping
|
||||
|
||||
The exception may match against a top-level exception being propagated (e.g. a direct
|
||||
`IOException` being thrown) or against a nested cause within a wrapper exception (e.g.
|
||||
The exception may match against a top-level exception being propagated (for example, a direct
|
||||
`IOException` being thrown) or against a nested cause within a wrapper exception (for example,
|
||||
an `IOException` wrapped inside an `IllegalStateException`). As of 5.3, this can match
|
||||
at arbitrary cause levels, whereas previously only an immediate cause was considered.
|
||||
|
||||
|
||||
@@ -117,7 +117,7 @@ parameters. While `@BindParam` is supported out of the box, you can also use a
|
||||
different annotation by setting a `DataBinder.NameResolver` on `DataBinder`
|
||||
|
||||
Constructor binding supports `List`, `Map`, and array arguments either converted from
|
||||
a single string, e.g. comma-separated list, or based on indexed keys such as
|
||||
a single string, for example, comma-separated list, or based on indexed keys such as
|
||||
`accounts[2].name` or `account[KEY].name`.
|
||||
|
||||
In some cases, you may want access to a model attribute without data binding. For such
|
||||
|
||||
@@ -42,7 +42,7 @@ content of the provided resource to the response `OutputStream`. Note that the
|
||||
`InputStream` should be lazily retrieved by the `Resource` handle in order to reliably
|
||||
close it after it has been copied to the response. If you are using `InputStreamResource`
|
||||
for such a purpose, make sure to construct it with an on-demand `InputStreamSource`
|
||||
(e.g. through a lambda expression that retrieves the actual `InputStream`).
|
||||
(for example, through a lambda expression that retrieves the actual `InputStream`).
|
||||
|
||||
You can use `@ResponseBody` with reactive types.
|
||||
See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types] for more details.
|
||||
|
||||
@@ -33,14 +33,14 @@ Kotlin::
|
||||
======
|
||||
|
||||
The body will usually be provided as a value object to be rendered to a corresponding
|
||||
response representation (e.g. JSON) by one of the registered `HttpMessageConverters`.
|
||||
response representation (for example, JSON) by one of the registered `HttpMessageConverters`.
|
||||
|
||||
A `ResponseEntity<Resource>` can be returned for file content, copying the `InputStream`
|
||||
content of the provided resource to the response `OutputStream`. Note that the
|
||||
`InputStream` should be lazily retrieved by the `Resource` handle in order to reliably
|
||||
close it after it has been copied to the response. If you are using `InputStreamResource`
|
||||
for such a purpose, make sure to construct it with an on-demand `InputStreamSource`
|
||||
(e.g. through a lambda expression that retrieves the actual `InputStream`). Also, custom
|
||||
(for example, through a lambda expression that retrieves the actual `InputStream`). Also, custom
|
||||
subclasses of `InputStreamResource` are only supported in combination with a custom
|
||||
`contentLength()` implementation which avoids consuming the stream for that purpose.
|
||||
|
||||
|
||||
@@ -93,9 +93,9 @@ supported for all return values.
|
||||
`ResponseEntity`. See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-http-streaming[HTTP Streaming].
|
||||
|
||||
| Reactor and other reactive types registered via `ReactiveAdapterRegistry`
|
||||
| A single value type, e.g. `Mono`, is comparable to returning `DeferredResult`.
|
||||
A multi-value type, e.g. `Flux`, may be treated as a stream depending on the requested
|
||||
media type, e.g. "text/event-stream", "application/json+stream", or otherwise is
|
||||
| A single value type, for example, `Mono`, is comparable to returning `DeferredResult`.
|
||||
A multi-value type, for example, `Flux`, may be treated as a stream depending on the requested
|
||||
media type, for example, "text/event-stream", "application/json+stream", or otherwise is
|
||||
collected to a List and rendered as a single value. See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and
|
||||
xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types].
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ method intends to accept a null value as well, either declare your argument as `
|
||||
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`
|
||||
Alternatively, you may specifically handle, for example, the resulting `MissingPathVariableException`
|
||||
in the case of a required `@PathVariable`. A null value after conversion will be treated like
|
||||
an empty original value, so the corresponding `Missing...Exception` variants will be thrown.
|
||||
====
|
||||
|
||||
@@ -105,7 +105,7 @@ default from version 6.0. See xref:web/webmvc/mvc-config/path-matching.adoc[MVC
|
||||
customizations of path matching options.
|
||||
|
||||
`PathPattern` supports the same pattern syntax as `AntPathMatcher`. In addition, it also
|
||||
supports the capturing pattern, e.g. `+{*spring}+`, for matching 0 or more path segments
|
||||
supports the capturing pattern, for example, `+{*spring}+`, for matching 0 or more path segments
|
||||
at the end of a path. `PathPattern` also restricts the use of `+**+` for matching multiple
|
||||
path segments such that it's only allowed at the end of a pattern. This eliminates many
|
||||
cases of ambiguity when choosing the best matching pattern for a given request.
|
||||
@@ -272,7 +272,7 @@ To completely disable the use of path extensions in versions prior to 5.3, set t
|
||||
* `favorPathExtension(false)`, see xref:web/webmvc/mvc-config/content-negotiation.adoc[ContentNegotiationConfigurer]
|
||||
|
||||
Having a way to request content types other than through the `"Accept"` header can still
|
||||
be useful, e.g. when typing a URL in a browser. A safe alternative to path extensions is
|
||||
be useful, for example, when typing a URL in a browser. A safe alternative to path extensions is
|
||||
to use the query parameter strategy. If you must use file extensions, consider restricting
|
||||
them to a list of explicitly registered extensions through the `mediaTypes` property of
|
||||
xref:web/webmvc/mvc-config/content-negotiation.adoc[ContentNegotiationConfigurer].
|
||||
|
||||
@@ -47,7 +47,7 @@ The following table provides more details on the `ViewResolver` hierarchy:
|
||||
| Implementation of the `ViewResolver` interface that interprets a view name as a
|
||||
bean name in the current application context. This is a very flexible variant which
|
||||
allows for mixing and matching different view types based on distinct view names.
|
||||
Each such `View` can be defined as a bean e.g. in XML or in configuration classes.
|
||||
Each such `View` can be defined as a bean, for example, in XML or in configuration classes.
|
||||
|===
|
||||
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ WebSocket support does not depend on Spring MVC. It is relatively simple to
|
||||
integrate a `WebSocketHandler` into other HTTP-serving environments with the help of
|
||||
{spring-framework-api}/web/socket/server/support/WebSocketHttpRequestHandler.html[`WebSocketHttpRequestHandler`].
|
||||
|
||||
When using the `WebSocketHandler` API directly vs indirectly, e.g. through the
|
||||
When using the `WebSocketHandler` API directly vs indirectly, for example, through the
|
||||
xref:web/websocket/stomp.adoc[STOMP] messaging, the application must synchronize the sending of messages
|
||||
since the underlying standard WebSocket session (JSR-356) does not allow concurrent
|
||||
sending. One option is to wrap the `WebSocketSession` with
|
||||
|
||||
@@ -38,7 +38,7 @@ to inform the server that the original port was `443`.
|
||||
==== X-Forwarded-Proto
|
||||
|
||||
While not standard, https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto[`X-Forwarded-Proto: (https|http)`]
|
||||
is a de-facto standard header that is used to communicate the original protocol (e.g. https / https)
|
||||
is a de-facto standard header that is used to communicate the original protocol (for example, https / https)
|
||||
to a downstream server. For example, if a request of `https://example.com/resource` is sent to
|
||||
a proxy which forwards the request to `http://localhost:8080/resource`, then a header of
|
||||
`X-Forwarded-Proto: https` can be sent to inform the server that the original protocol was `https`.
|
||||
@@ -48,7 +48,7 @@ a proxy which forwards the request to `http://localhost:8080/resource`, then a h
|
||||
==== X-Forwarded-Ssl
|
||||
|
||||
While not standard, `X-Forwarded-Ssl: (on|off)` is a de-facto standard header that is used to communicate the
|
||||
original protocol (e.g. https / https) to a downstream server. For example, if a request of
|
||||
original protocol (for example, https / https) to a downstream server. For example, if a request of
|
||||
`https://example.com/resource` is sent to a proxy which forwards the request to
|
||||
`http://localhost:8080/resource`, then a header of `X-Forwarded-Ssl: on` to inform the server that the
|
||||
original protocol was `https`.
|
||||
@@ -103,7 +103,7 @@ applications on the same server. However, this should not be visible in URL path
|
||||
the public API where applications may use different subdomains that provides benefits
|
||||
such as:
|
||||
|
||||
* Added security, e.g. same origin policy
|
||||
* Added security, for example, same origin policy
|
||||
* Independent scaling of applications (different domain points to different IP address)
|
||||
====
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ A complete introduction of how WebSockets work is beyond the scope of this docum
|
||||
See RFC 6455, the WebSocket chapter of HTML5, or any of the many introductions and
|
||||
tutorials on the Web.
|
||||
|
||||
Note that, if a WebSocket server is running behind a web server (e.g. nginx), you
|
||||
Note that, if a WebSocket server is running behind a web server (for example, nginx), you
|
||||
likely need to configure it to pass WebSocket upgrade requests on to the WebSocket
|
||||
server. Likewise, if the application runs in a cloud environment, check the
|
||||
instructions of the cloud provider related to WebSocket support.
|
||||
|
||||
Reference in New Issue
Block a user