1 /*
2 * Copyright 2002-2013 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.web.socket;
18
19 /**
20 * A handler for WebSocket messages and lifecycle events.
21 *
22 * <p>Implementations of this interface are encouraged to handle exceptions locally where
23 * it makes sense or alternatively let the exception bubble up in which case by default
24 * the exception is logged and the session closed with
25 * {@link CloseStatus#SERVER_ERROR SERVER_ERROR(1011)}. The exception handling
26 * strategy is provided by
27 * {@link org.springframework.web.socket.handler.ExceptionWebSocketHandlerDecorator
28 * ExceptionWebSocketHandlerDecorator} and it can be customized or replaced by decorating
29 * the {@link WebSocketHandler} with a different decorator.
30 *
31 * @author Rossen Stoyanchev
32 * @author Phillip Webb
33 * @since 4.0
34 */
35 public interface WebSocketHandler {
36
37 /**
38 * Invoked after WebSocket negotiation has succeeded and the WebSocket connection is
39 * opened and ready for use.
40 * @throws Exception this method can handle or propagate exceptions; see class-level
41 * Javadoc for details.
42 */
43 void afterConnectionEstablished(WebSocketSession session) throws Exception;
44
45 /**
46 * Invoked when a new WebSocket message arrives.
47 * @throws Exception this method can handle or propagate exceptions; see class-level
48 * Javadoc for details.
49 */
50 void handleMessage(WebSocketSession session, WebSocketMessage<?> message) throws Exception;
51
52 /**
53 * Handle an error from the underlying WebSocket message transport.
54 * @throws Exception this method can handle or propagate exceptions; see class-level
55 * Javadoc for details.
56 */
57 void handleTransportError(WebSocketSession session, Throwable exception) throws Exception;
58
59 /**
60 * Invoked after the WebSocket connection has been closed by either side, or after a
61 * transport error has occurred. Although the session may technically still be open,
62 * depending on the underlying implementation, sending messages at this point is
63 * discouraged and most likely will not succeed.
64 * @throws Exception this method can handle or propagate exceptions; see class-level
65 * Javadoc for details.
66 */
67 void afterConnectionClosed(WebSocketSession session, CloseStatus closeStatus) throws Exception;
68
69 /**
70 * Whether the WebSocketHandler handles partial messages. If this flag is set to
71 * {@code true} and the underlying WebSocket server supports partial messages,
72 * then a large WebSocket message, or one of an unknown size may be split and
73 * maybe received over multiple calls to
74 * {@link #handleMessage(WebSocketSession, WebSocketMessage)}. The flag
75 * {@link org.springframework.web.socket.WebSocketMessage#isLast()} indicates if
76 * the message is partial and whether it is the last part.
77 */
78 boolean supportsPartialMessages();
79
80 }