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

Extract recurring asciidoc links to attributes, cleanup old doc files

Browse Source 
This commit extract spring-related links and recurring external links
into asciidoctor attributes to be used by the Antora toolchain.

It notably homogenizes links to:
 - IETF RFCs
 - Java Community Process JSRs
 - the Java API Documentation (on the Java 17 version)
 - Kotlin documentations (on the Kotlinlang.org version)
 - the Spring Boot reference guide (on the `html` version)

This commit also reworks most link attributes to follow a
Project-Category-Misc syntax. For example, `spring-boot-docs` rather
than `docs-spring-boot`.

Finally, it makes an effort to clean up remainders from the previous
documentation toolchain, namely the `docs/asciidoc` folder and 
`modules/ROOT/pages/attributes.adoc` file.

Closes gh-26864
Closes gh-31619
This commit is contained in:
Simon Baslé
2023-11-21 15:59:24 +01:00
committed by GitHub
parent 4cc43b4ddc
commit 8567402969
202 changed files with 594 additions and 2837 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc vendored
View File

@@ -67,7 +67,7 @@ To provide a different default key generator, you need to implement the
The default key generation strategy changed with the release of Spring 4.0. Earlier
versions of Spring used a key generation strategy that, for multiple key parameters,
considered only the `hashCode()` of parameters and not `equals()`. This could cause
unexpected key collisions (see https://jira.spring.io/browse/SPR-10237[SPR-10237]
unexpected key collisions (see {spring-framework-issues}/14870[spring-framework#14870]
for background). The new `SimpleKeyGenerator` uses a compound key for such scenarios.
If you want to keep using the previous key strategy, you can configure the deprecated
@@ -566,7 +566,7 @@ switching to `aspectj` mode in combination with compile-time or load-time weavin
NOTE: For more detail about advanced customizations (using Java configuration) that are
required to implement `CachingConfigurer`, see the
{api-spring-framework}/cache/annotation/CachingConfigurer.html[javadoc].
{spring-framework-api}/cache/annotation/CachingConfigurer.html[javadoc].
[[cache-annotation-driven-settings]]
.Cache annotation settings
@@ -575,7 +575,7 @@ required to implement `CachingConfigurer`, see the
| XML Attribute | Annotation Attribute | Default | Description
| `cache-manager`
| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc)
| N/A (see the {spring-framework-api}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc)
| `cacheManager`
| The name of the cache manager to use. A default `CacheResolver` is initialized behind
the scenes with this cache manager (or `cacheManager` if not set). For more
@@ -583,19 +583,19 @@ required to implement `CachingConfigurer`, see the
attribute.
| `cache-resolver`
| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc)
| N/A (see the {spring-framework-api}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc)
| A `SimpleCacheResolver` using the configured `cacheManager`.
| The bean name of the CacheResolver that is to be used to resolve the backing caches.
This attribute is not required and needs to be specified only as an alternative to
the 'cache-manager' attribute.
| `key-generator`
| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc)
| N/A (see the {spring-framework-api}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc)
| `SimpleKeyGenerator`
| Name of the custom key generator to use.
| `error-handler`
| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc)
| N/A (see the {spring-framework-api}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc)
| `SimpleCacheErrorHandler`
| The name of the custom cache error handler to use. By default, any exception thrown during
a cache related operation is thrown back at the client.

2
framework-docs/modules/ROOT/pages/integration/email.adoc
View File

@@ -26,7 +26,7 @@ interface. A simple value object that encapsulates the properties of a simple ma
as `from` and `to` (plus many others) is the `SimpleMailMessage` class. This package
also contains a hierarchy of checked exceptions that provide a higher level of
abstraction over the lower level mail system exceptions, with the root exception being
`MailException`. See the {api-spring-framework}/mail/MailException.html[javadoc]
`MailException`. See the {spring-framework-api}/mail/MailException.html[javadoc]
for more information on the rich mail exception hierarchy.
The `org.springframework.mail.javamail.JavaMailSender` interface adds specialized

2
framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc
View File

@@ -64,7 +64,7 @@ You can customize the listener container factory to use for each annotation or y
configure an explicit default by implementing the `JmsListenerConfigurer` interface.
The default is required only if at least one endpoint is registered without a specific
container factory. See the javadoc of classes that implement
{api-spring-framework}/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`]
{spring-framework-api}/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`]
for details and examples.
If you prefer xref:integration/jms/namespace.adoc[XML configuration], you can use the `<jms:annotation-driven>`

8
framework-docs/modules/ROOT/pages/integration/jms/jca-message-endpoint-manager.adoc
View File

@@ -64,9 +64,9 @@ In some environments, you can instead obtain the entire `ResourceAdapter` object
(by using `<jee:jndi-lookup>`). The Spring-based message listeners can then interact with
the server-hosted `ResourceAdapter`, which also use the server's built-in `WorkManager`.
See the javadoc for {api-spring-framework}/jms/listener/endpoint/JmsMessageEndpointManager.html[`JmsMessageEndpointManager`],
{api-spring-framework}/jms/listener/endpoint/JmsActivationSpecConfig.html[`JmsActivationSpecConfig`],
and {api-spring-framework}/jca/support/ResourceAdapterFactoryBean.html[`ResourceAdapterFactoryBean`]
See the javadoc for {spring-framework-api}/jms/listener/endpoint/JmsMessageEndpointManager.html[`JmsMessageEndpointManager`],
{spring-framework-api}/jms/listener/endpoint/JmsActivationSpecConfig.html[`JmsActivationSpecConfig`],
and {spring-framework-api}/jca/support/ResourceAdapterFactoryBean.html[`ResourceAdapterFactoryBean`]
for more details.
Spring also provides a generic JCA message endpoint manager that is not tied to JMS:
@@ -74,7 +74,7 @@ Spring also provides a generic JCA message endpoint manager that is not tied to
for using any message listener type (such as a JMS `MessageListener`) and any
provider-specific `ActivationSpec` object. See your JCA provider's documentation to
find out about the actual capabilities of your connector, and see the
{api-spring-framework}/jca/endpoint/GenericMessageEndpointManager.html[`GenericMessageEndpointManager`]
{spring-framework-api}/jca/endpoint/GenericMessageEndpointManager.html[`GenericMessageEndpointManager`]
javadoc for the Spring-specific configuration details.
NOTE: JCA-based message endpoint management is very analogous to EJB 2.1 Message-Driven Beans.

4
framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc
View File

@@ -113,7 +113,7 @@ as the following example shows:
----
The following table describes all available attributes. See the class-level javadoc
of the {api-spring-framework}/jms/listener/AbstractMessageListenerContainer.html[`AbstractMessageListenerContainer`]
of the {spring-framework-api}/jms/listener/AbstractMessageListenerContainer.html[`AbstractMessageListenerContainer`]
and its concrete subclasses for more details on the individual properties. The javadoc
also provides a discussion of transaction choices and message redelivery scenarios.
@@ -254,7 +254,7 @@ The following table describes the available configuration options for the JCA va
| `activation-spec-factory`
| A reference to the `JmsActivationSpecFactory`. The default is to autodetect the JMS
provider and its `ActivationSpec` class (see {api-spring-framework}/jms/listener/endpoint/DefaultJmsActivationSpecFactory.html[`DefaultJmsActivationSpecFactory`]).
provider and its `ActivationSpec` class (see {spring-framework-api}/jms/listener/endpoint/DefaultJmsActivationSpecFactory.html[`DefaultJmsActivationSpecFactory`]).
| `destination-resolver`
| A reference to the `DestinationResolver` strategy for resolving JMS `Destinations`.

2
framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc
View File

@@ -76,7 +76,7 @@ containers that ships with Spring (in this case, `DefaultMessageListenerContaine
----
See the Spring javadoc of the various message listener containers (all of which implement
{api-spring-framework}/jms/listener/MessageListenerContainer.html[MessageListenerContainer])
{spring-framework-api}/jms/listener/MessageListenerContainer.html[MessageListenerContainer])
for a full description of the features supported by each implementation.

2
framework-docs/modules/ROOT/pages/integration/jms/using.adoc
View File

@@ -234,7 +234,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.
{spring-framework-api}/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example.
NOTE: Like its sibling (xref:integration/jms/using.adoc#jms-mdp-simple[`SimpleMessageListenerContainer`]),
`DefaultMessageListenerContainer` supports native JMS transactions and allows for

2
framework-docs/modules/ROOT/pages/integration/jmx/notifications.adoc
View File

@@ -246,7 +246,7 @@ instance. The `NotificationPublisherAware` interface supplies an instance of a
which the bean can then use to publish `Notifications`.
As stated in the javadoc of the
{api-spring-framework}/jmx/export/notification/NotificationPublisher.html[`NotificationPublisher`]
{spring-framework-api}/jmx/export/notification/NotificationPublisher.html[`NotificationPublisher`]
interface, managed beans that publish events through the `NotificationPublisher`
mechanism are not responsible for the state management of notification listeners.
Spring's JMX support takes care of handling all the JMX infrastructure issues.

6
framework-docs/modules/ROOT/pages/integration/jmx/resources.adoc
View File

@@ -6,10 +6,8 @@ This section contains links to further resources about JMX:
* The https://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[JMX
homepage] at Oracle.
* The https://jcp.org/aboutJava/communityprocess/final/jsr003/index3.html[JMX
specification] (JSR-000003).
* The https://jcp.org/aboutJava/communityprocess/final/jsr160/index.html[JMX Remote API
specification] (JSR-000160).
* The {JSR}003[JMX specification] (JSR-000003).
* The {JSR}160[JMX Remote API specification] (JSR-000160).
* The http://mx4j.sourceforge.net/[MX4J homepage]. (MX4J is an open-source implementation of
various JMX specs.)

2
framework-docs/modules/ROOT/pages/integration/observability.adoc
View File

@@ -7,7 +7,7 @@ Metrics can help you to track error rates, usage patterns, performance, and more
Traces provide a holistic view of an entire system, crossing application boundaries; you can zoom in on particular user requests and follow their entire completion across applications.
Spring Framework instruments various parts of its own codebase to publish observations if an `ObservationRegistry` is configured.
You can learn more about {docs-spring-boot}/html/actuator.html#actuator.metrics[configuring the observability infrastructure in Spring Boot].
You can learn more about {spring-boot-docs}/actuator.html#actuator.metrics[configuring the observability infrastructure in Spring Boot].
[[observability.list]]

6
framework-docs/modules/ROOT/pages/integration/rest-clients.adoc
View File

@@ -344,7 +344,7 @@ The `spring-web` module contains the `HttpMessageConverter` interface for readin
Concrete implementations for the main media (MIME) types are provided in the framework and are, by default, registered with the `RestClient` and `RestTemplate` on the client side and with `RequestMappingHandlerAdapter` on the server side (see xref:web/webmvc/mvc-config/message-converters.adoc[Configuring Message Converters]).
Several implementations of `HttpMessageConverter` are described below.
Refer to the {api-spring-framework}/http/converter/HttpMessageConverter.html[`HttpMessageConverter` Javadoc] for the complete list.
Refer to the {spring-framework-api}/http/converter/HttpMessageConverter.html[`HttpMessageConverter` Javadoc] for the complete list.
For all converters, a default media type is used, but you can override it by setting the `supportedMediaTypes` property.
[[rest-message-converters-tbl]]
@@ -384,7 +384,7 @@ When you need further control (for cases where custom JSON serializers/deseriali
By default, this converter supports `application/json`.
| `MappingJackson2XmlHttpMessageConverter`
| An `HttpMessageConverter` implementation that can read and write XML by using https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML] extension's `XmlMapper`.
| An `HttpMessageConverter` implementation that can read and write XML by using {jackson-github-org}/jackson-dataformat-xml[Jackson XML] extension's `XmlMapper`.
You can customize XML mapping as needed through the use of JAXB or Jackson's provided annotations.
When you need further control (for cases where custom XML serializers/deserializers need to be provided for specific types), you can inject a custom `XmlMapper` through the `ObjectMapper` property.
By default, this converter supports `application/xml`.
@@ -401,7 +401,7 @@ You can also set the message converters to use explicitly, by using `messageConv
==== Jackson JSON Views
To serialize only a subset of the object properties, you can specify a https://www.baeldung.com/jackson-json-view-annotation[Jackson JSON View], as the following example shows:
To serialize only a subset of the object properties, you can specify a {baeldung-blog}/jackson-json-view-annotation[Jackson JSON View], as the following example shows:
[source,java,indent=0,subs="verbatim"]
----

8
framework-docs/modules/ROOT/pages/integration/scheduling.adoc
View File

@@ -282,8 +282,8 @@ You can pick and choose the relevant annotations for your application. For examp
if you need only support for `@Scheduled`, you can omit `@EnableAsync`. For more
fine-grained control, you can additionally implement the `SchedulingConfigurer`
interface, the `AsyncConfigurer` interface, or both. See the
{api-spring-framework}/scheduling/annotation/SchedulingConfigurer.html[`SchedulingConfigurer`]
and {api-spring-framework}/scheduling/annotation/AsyncConfigurer.html[`AsyncConfigurer`]
{spring-framework-api}/scheduling/annotation/SchedulingConfigurer.html[`SchedulingConfigurer`]
and {spring-framework-api}/scheduling/annotation/AsyncConfigurer.html[`AsyncConfigurer`]
javadoc for full details.
If you prefer XML configuration, you can use the `<task:annotation-driven>` element,
@@ -722,7 +722,7 @@ In the preceding configuration, a `queue-capacity` value has also been provided.
The configuration of the thread pool should also be considered in light of the
executor's queue capacity. For the full description of the relationship between pool
size and queue capacity, see the documentation for
https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ThreadPoolExecutor.html[`ThreadPoolExecutor`].
{java-api}/java.base/java/util/concurrent/ThreadPoolExecutor.html[`ThreadPoolExecutor`].
The main idea is that, when a task is submitted, the executor first tries to use a
free thread if the number of active threads is currently less than the core size.
If the core size has been reached, the task is added to the queue, as long as its
@@ -1093,7 +1093,7 @@ we need to set up the `SchedulerFactoryBean`, as the following example shows:
More properties are available for the `SchedulerFactoryBean`, such as the calendars used by the
job details, properties to customize Quartz with, and a Spring-provided JDBC DataSource. See
the {api-spring-framework}/scheduling/quartz/SchedulerFactoryBean.html[`SchedulerFactoryBean`]
the {spring-framework-api}/scheduling/quartz/SchedulerFactoryBean.html[`SchedulerFactoryBean`]
javadoc for more information.
NOTE: `SchedulerFactoryBean` also recognizes a `quartz.properties` file in the classpath,