Document STOMP-related ApplicationContext events

Issue: SPR-11672

Author: rstoyanchev

src/asciidoc/index.adoc

@@ -37997,7 +37997,7 @@ it acts as a "relay" forwarding messages in both directions.
 
 [NOTE]
 ====
-Please add a dependency on `org.projectreactor:reactor-tcp` for TCP connection management.
+Please add a dependency on `org.projectreactor:reactor-net` for TCP connection management.
 ====
 
 Furthermore, application components (e.g. HTTP request handling methods,
@@ -38124,6 +38124,49 @@ for purging inactive destinations.
 
 
 
+[[websocket-stomp-appplication-context-events]]
+==== ApplicationContext Events
+
+The STOMP messaging support publishes the `ApplicationContext` events listed below.
+To subscribe to receive one or more of these events a Spring managed component can
+implement Spring's `ApplicationListener` interface. The events are:
+
+* `BrokerAvailabilityEvent` -- indicates when the broker becomes available/unavailable.
+While the "simple" broker becomes available immediately on startup and remains so while
+the application is running, the STOMP "broker relay" may lose its connection
+to the full featured broker for example if the broker is restarted. The broker relay
+has reconnect logic and will re-establish the "system" connection to the broker
+when it comes back, hence this event is published whenever the state changes from connected
+to disconnected and vice versa. Components using the `SimpMessagingTemplate` should
+subscribe to this event and avoid sending messages at times when the broker is not
+available. In any case they should be prepared to handle `MessageDeliveryException`
+when sending a message.
+* `SessionConnectEvent` -- published when a new STOMP CONNECT is received
+indicating the start of a new client session. The event contains the message representing the
+connect including the session id, user information (if any), and any custom headers the client
+may have sent. This is useful for tracking client sessions. Components subscribed
+to this event can wrap the contained message using `SimpMessageHeaderAccessor` or
+`StompMessageHeaderAccessor`.
+* `SessionConnectedEvent` -- published shortly after a `SessionConnectEvent` when the
+broker has sent a STOMP CONNECTED frame in response to the CONNECT. At this point the
+STOMP session can be considered fully established.
+* `SessionDisconnectEvent` -- published when a STOMP session ends. The DISCONNECT may
+have been sent from the client or it may also be automatically generated when the
+WebSocket session is closed. In some cases this event may be published more than once
+per session. Components should be idempotent to multiple disconnect events.
+
+[NOTE]
+====
+When using a full-featured broker, the STOMP "broker relay" automatically reconnects the
+"system" connection should the broker become temporarily unavailable. Client connections
+however are not automatically reconnected. Assuming heartbeats are enabled, the client
+will typically notice the broker is not responding within 10 seconds. Clients need to
+implement their own reconnect logic.
+====
+
+
+
+
 [[websocket-stomp-configuration-performance]]
 ==== Configuration and Performance