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

Fix cross references

Browse Source
This commit is contained in:
Rob Winch
2023-04-19 10:26:17 -05:00
committed by rstoyanchev
parent 6b341ddf19
commit 139cde47e2
296 changed files with 1505 additions and 1505 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc
View File

@@ -127,7 +127,7 @@ The following example shows the XML configuration equivalent of the preceding ex
----
The preceding example is for use in Spring MVC applications and should be included in the
configuration of a <<mvc-servlet, `DispatcherServlet`>>. However, Spring's WebSocket
configuration of a xref:web/webmvc/mvc-servlet.adoc[`DispatcherServlet`]. However, Spring's WebSocket
and SockJS support does not depend on Spring MVC. It is relatively simple to
integrate into other HTTP serving environments with the help of
{api-spring-framework}/web/socket/sockjs/support/SockJsHttpRequestHandler.html[`SockJsHttpRequestHandler`].
@@ -273,7 +273,7 @@ log category to TRACE.
[[websocket-fallback-cors]]
== SockJS and CORS
If you allow cross-origin requests (see <<websocket-server-allowed-origins>>), the SockJS protocol
If you allow cross-origin requests (see xref:web/websocket/server.adoc#websocket-server-allowed-origins[Allowed Origins]), the SockJS protocol
uses CORS for cross-domain support in the XHR streaming and polling transports. Therefore,
CORS headers are added automatically, unless the presence of CORS headers in the response
is detected. So, if an application is already configured to provide CORS support (for example,

16
framework-docs/modules/ROOT/pages/web/websocket/server.adoc
View File

@@ -1,7 +1,7 @@
[[websocket-server]]
= WebSocket API
[.small]#<<web-reactive.adoc#webflux-websocket-server, See equivalent in the Reactive stack>>#
[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server[See equivalent in the Reactive stack]#
The Spring Framework provides a WebSocket API that you can use to write client- and
server-side applications that handle WebSocket messages.
@@ -10,7 +10,7 @@ server-side applications that handle WebSocket messages.
[[websocket-server-handler]]
== `WebSocketHandler`
[.small]#<<web-reactive.adoc#webflux-websocket-server-handler, See equivalent in the Reactive stack>>#
[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-handler[See equivalent in the Reactive stack]#
Creating a WebSocket server is as simple as implementing `WebSocketHandler` or, more
likely, extending either `TextWebSocketHandler` or `BinaryWebSocketHandler`. The following
@@ -81,13 +81,13 @@ The following example shows the XML configuration equivalent of the preceding ex
----
The preceding example is for use in Spring MVC applications and should be included
in the configuration of a <<mvc-servlet, `DispatcherServlet`>>. However, Spring's
in the configuration of a xref:web/webmvc/mvc-servlet.adoc[`DispatcherServlet`]. However, Spring's
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
{api-spring-framework}/web/socket/server/support/WebSocketHttpRequestHandler.html[`WebSocketHttpRequestHandler`].
When using the `WebSocketHandler` API directly vs indirectly, e.g. through the
<<websocket-stomp>> messaging, the application must synchronize the sending of messages
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
{api-spring-framework}/web/socket/handler/ConcurrentWebSocketSessionDecorator.html[`ConcurrentWebSocketSessionDecorator`].
@@ -96,7 +96,7 @@ sending. One option is to wrap the `WebSocketSession` with
[[websocket-server-handshake]]
== WebSocket Handshake
[.small]#<<web-reactive.adoc#webflux-websocket-server-handshake, See equivalent in the Reactive stack>>#
[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-handshake[See equivalent in the Reactive stack]#
The easiest way to customize the initial HTTP WebSocket handshake request is through
a `HandshakeInterceptor`, which exposes methods for "`before`" and "`after`" the handshake.
@@ -149,7 +149,7 @@ the steps of the WebSocket handshake, including validating the client origin,
negotiating a sub-protocol, and other details. An application may also need to use this
option if it needs to configure a custom `RequestUpgradeStrategy` in order to
adapt to a WebSocket server engine and version that is not yet supported
(see <<websocket-server-deployment>> for more on this subject).
(see xref:web/websocket/server.adoc#websocket-server-deployment[Deployment] for more on this subject).
Both the Java configuration and XML namespace make it possible to configure a custom
`HandshakeHandler`.
@@ -230,7 +230,7 @@ Java initialization API. The following example shows how to do so:
[[websocket-server-runtime-configuration]]
== Server Configuration
[.small]#<<web-reactive.adoc#webflux-websocket-server-config, See equivalent in the Reactive stack>>#
[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-config[See equivalent in the Reactive stack]#
Each underlying WebSocket engine exposes configuration properties that control
runtime characteristics, such as the size of message buffer sizes, idle timeout,
@@ -353,7 +353,7 @@ The following example shows the XML configuration equivalent of the preceding ex
[[websocket-server-allowed-origins]]
== Allowed Origins
[.small]#<<web-reactive.adoc#webflux-websocket-server-cors, See equivalent in the Reactive stack>>#
[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-cors[See equivalent in the Reactive stack]#
As of Spring Framework 4.1.5, the default behavior for WebSocket and SockJS is to accept
only same-origin requests. It is also possible to allow all or a specified list of origins.

2
framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc
View File

@@ -7,7 +7,7 @@ made about HTTP versus raw TCP and how it lets Spring MVC and other web framewor
provide rich functionality. The following is a list of benefits:
* No need to invent a custom messaging protocol and message format.
* STOMP clients, including a <<websocket-stomp-client, Java client>>
* STOMP clients, including a xref:web/websocket/stomp/client.adoc[Java client]
in the Spring Framework, are available.
* You can (optionally) use message brokers (such as RabbitMQ, ActiveMQ, and others) to
manage subscriptions and broadcast messages.

4
framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc
View File

@@ -16,7 +16,7 @@ To begin, you can create and configure `WebSocketStompClient`, as the following
In the preceding example, you could replace `StandardWebSocketClient` with `SockJsClient`,
since that is also an implementation of `WebSocketClient`. The `SockJsClient` can
use WebSocket or HTTP-based transport as a fallback. For more details, see
<<websocket-fallback-sockjs-client>>.
xref:web/websocket/fallback.adoc#websocket-fallback-sockjs-client[`SockJsClient`].
Next, you can establish a connection and provide a handler for the STOMP session,
as the following example shows:
@@ -80,7 +80,7 @@ closes the connection).
other messages are sent. This can present a challenge when using an external broker
since messages with a non-broker destination represent activity but aren't actually
forwarded to the broker. In that case you can configure a `TaskScheduler`
when initializing the <<websocket-stomp-handle-broker-relay>> which ensures a
when initializing the xref:web/websocket/stomp/handle-broker-relay.adoc[External Broker] which ensures a
heartbeat is forwarded to the broker also when only messages with a non-broker
destination are sent.

2
framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc
View File

@@ -11,7 +11,7 @@ on how to reason about scaling.
In a messaging application, messages are passed through channels for asynchronous
executions that are backed by thread pools. Configuring such an application requires
good knowledge of the channels and the flow of messages. Therefore, it is
recommended to review <<websocket-stomp-message-flow>>.
recommended to review xref:web/websocket/stomp/message-flow.adoc[Flow of Messages].
The obvious place to start is to configure the thread pools that back the
`clientInboundChannel` and the `clientOutboundChannel`. By default, both

6
framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc
View File

@@ -3,7 +3,7 @@
STOMP over WebSocket support is available in the `spring-messaging` and
`spring-websocket` modules. Once you have those dependencies, you can expose a STOMP
endpoints, over WebSocket with <<websocket-fallback>>, as the following example shows:
endpoints, over WebSocket with xref:web/websocket/fallback.adoc[SockJS Fallback], as the following example shows:
[source,java,indent=0,subs="verbatim,quotes"]
----
@@ -95,8 +95,8 @@ Alternatively, if you connect through WebSocket (without SockJS), you can use th
Note that `stompClient` in the preceding example does not need to specify `login`
and `passcode` headers. Even if it did, they would be ignored (or, rather,
overridden) on the server side. See <<websocket-stomp-handle-broker-relay-configure>>
and <<websocket-stomp-authentication>> for more information on authentication.
overridden) on the server side. See xref:web/websocket/stomp/handle-broker-relay-configure.adoc[Connecting to a Broker]
and xref:web/websocket/stomp/authentication.adoc[Authentication] for more information on authentication.
For more example code see:

22
framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc
View File

@@ -5,9 +5,9 @@ Applications can use annotated `@Controller` classes to handle messages from cli
Such classes can declare `@MessageMapping`, `@SubscribeMapping`, and `@ExceptionHandler`
methods, as described in the following topics:
* <<websocket-stomp-message-mapping>>
* <<websocket-stomp-subscribe-mapping>>
* <<websocket-stomp-exception-handler>>
* xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-message-mapping[`@MessageMapping`]
* xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-subscribe-mapping[`@SubscribeMapping`]
* xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-exception-handler[`@MessageExceptionHandler`]
[[websocket-stomp-message-mapping]]
@@ -22,7 +22,7 @@ By default, the mapping values are Ant-style path patterns (for example `/thing*
including support for template variables (for example, pass:q[`/thing/{id}`]). The values can be
referenced through `@DestinationVariable` method arguments. Applications can also switch to
a dot-separated destination convention for mappings, as explained in
<<websocket-stomp-destination-separator>>.
xref:web/websocket/stomp/destination-separator.adoc[Dots as Separators].
[[supported-method-arguments]]
=== Supported Method Arguments
@@ -80,7 +80,7 @@ same as that of the inbound message but prefixed with `/topic`.
You can use the `@SendTo` and `@SendToUser` annotations to customize the destination of
the output message. `@SendTo` is used to customize the target destination or to
specify multiple destinations. `@SendToUser` is used to direct the output message
to only the user associated with the input message. See <<websocket-stomp-user-destination>>.
to only the user associated with the input message. See xref:web/websocket/stomp/user-destination.adoc[User Destinations].
You can use both `@SendTo` and `@SendToUser` at the same time on the same method, and both
are supported at the class level, in which case they act as a default for methods in the
@@ -94,7 +94,7 @@ Note that `@SendTo` and `@SendToUser` are merely a convenience that amounts to u
`SimpMessagingTemplate` to send messages. If necessary, for more advanced scenarios,
`@MessageMapping` methods can fall back on using the `SimpMessagingTemplate` directly.
This can be done instead of, or possibly in addition to, returning a value.
See <<websocket-stomp-handle-send>>.
See xref:web/websocket/stomp/handle-send.adoc[Sending Messages].
[[websocket-stomp-subscribe-mapping]]
@@ -102,7 +102,7 @@ See <<websocket-stomp-handle-send>>.
`@SubscribeMapping` is similar to `@MessageMapping` but narrows the mapping to
subscription messages only. It supports the same
<<websocket-stomp-message-mapping, method arguments>> as `@MessageMapping`. However
xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-message-mapping[method arguments] as `@MessageMapping`. However
for the return value, by default, a message is sent directly to the client (through
`clientOutboundChannel`, in response to the subscription) and not to the broker (through
`brokerChannel`, as a broadcast to matching subscriptions). Adding `@SendTo` or
@@ -123,7 +123,7 @@ for some reason. Inbound messages are handled in parallel. There are no guarante
a broker or a controller processes a given message first. If the goal is to be notified
when a subscription is stored and ready for broadcasts, a client should ask for a
receipt if the server supports it (simple broker does not). For example, with the Java
<<websocket-stomp-client, STOMP client>>, you could do the following to add a receipt:
xref:web/websocket/stomp/client.adoc[STOMP client], you could do the following to add a receipt:
[source,java,indent=0,subs="verbatim,quotes"]
----
@@ -143,7 +143,7 @@ receipt if the server supports it (simple broker does not). For example, with th
});
----
A server side option is <<websocket-stomp-interceptors, to register>> an
A server side option is xref:web/websocket/stomp/interceptors.adoc[to register] an
`ExecutorChannelInterceptor` on the `brokerChannel` and implement the `afterMessageHandled`
method that is invoked after messages, including subscriptions, have been handled.
@@ -173,13 +173,13 @@ The following example declares an exception through a method argument:
`@MessageExceptionHandler` methods support flexible method signatures and support
the same method argument types and return values as
<<websocket-stomp-message-mapping, `@MessageMapping`>> methods.
xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-message-mapping[`@MessageMapping`] methods.
Typically, `@MessageExceptionHandler` methods apply within the `@Controller` class
(or class hierarchy) in which they are declared. If you want such methods to apply
more globally (across controllers), you can declare them in a class marked with
`@ControllerAdvice`. This is comparable to the
<<web.adoc#mvc-ann-controller-advice, similar support>> available in Spring MVC.
xref:web/webmvc/mvc-controller/ann-advice.adoc[similar support] available in Spring MVC.

2
framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc
View File

@@ -16,7 +16,7 @@ values of `guest` and `guest`.
NOTE: The STOMP broker relay always sets the `login` and `passcode` headers on every `CONNECT`
frame that it forwards to the broker on behalf of clients. Therefore, WebSocket clients
need not set those headers. They are ignored. As the <<websocket-stomp-authentication>>
need not set those headers. They are ignored. As the xref:web/websocket/stomp/authentication.adoc[Authentication]
section explains, WebSocket clients should instead rely on HTTP authentication to protect
the WebSocket endpoint and establish the client identity.

2
framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc
View File

@@ -71,7 +71,7 @@ dependencies to your project for TCP connection management.
Furthermore, application components (such as HTTP request handling methods,
business services, and others) can also send messages to the broker relay, as described
in <<websocket-stomp-handle-send>>, to broadcast messages to subscribed WebSocket clients.
in xref:web/websocket/stomp/handle-send.adoc[Sending Messages], to broadcast messages to subscribed WebSocket clients.
In effect, the broker relay enables robust and scalable message broadcasting.

2
framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc
View File

@@ -7,7 +7,7 @@ destinations. The broker supports path-like destinations, including subscription
to Ant-style destination patterns.
NOTE: Applications can also use dot-separated (rather than slash-separated) destinations.
See <<websocket-stomp-destination-separator>>.
See xref:web/websocket/stomp/destination-separator.adoc[Dots as Separators].
If configured with a task scheduler, the simple broker supports
https://stomp.github.io/stomp-specification-1.2.html#Heart-beating[STOMP heartbeats].

2
framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc
View File

@@ -1,7 +1,7 @@
[[websocket-stomp-interceptors]]
= Interception
<<websocket-stomp-application-context-events>> provide notifications for the lifecycle
xref:web/websocket/stomp/application-context-events.adoc[Events] provide notifications for the lifecycle
of a STOMP connection but not for every client message. Applications can also register a
`ChannelInterceptor` to intercept any message and in any part of the processing chain.
The following example shows how to intercept inbound messages from clients:

2
framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc
View File

@@ -2,7 +2,7 @@
= WebSocket Server
To configure the underlying WebSocket server, the information in
<<websocket-server-runtime-configuration>> applies. For Jetty, however you need to set
xref:web/websocket/server.adoc#websocket-server-runtime-configuration[Server Configuration] applies. For Jetty, however you need to set
the `HandshakeHandler` and `WebSocketPolicy` through the `StompEndpointRegistry`:
[source,java,indent=0,subs="verbatim,quotes"]

2
framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc
View File

@@ -11,7 +11,7 @@ at the same time, ensuring no collisions with other users who subscribe to the s
destination so that each user can receive unique stock position updates.
TIP: When working with user destinations, it is important to configure broker and
application destination prefixes as shown in <<websocket-stomp-enable>>, or otherwise the
application destination prefixes as shown in xref:web/websocket/stomp/enable.adoc[Enable STOMP], or otherwise the
broker would handle "/user" prefixed messages that should only be handled by
`UserDestinationMessageHandler`.