001/*
002 * Copyright 2002-2013 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.socket;
018
019/**
020 * A handler for WebSocket messages and lifecycle events.
021 *
022 * <p>Implementations of this interface are encouraged to handle exceptions locally where
023 * it makes sense or alternatively let the exception bubble up in which case by default
024 * the exception is logged and the session closed with
025 * {@link CloseStatus#SERVER_ERROR SERVER_ERROR(1011)}. The exception handling
026 * strategy is provided by
027 * {@link org.springframework.web.socket.handler.ExceptionWebSocketHandlerDecorator
028 * ExceptionWebSocketHandlerDecorator} and it can be customized or replaced by decorating
029 * the {@link WebSocketHandler} with a different decorator.
030 *
031 * @author Rossen Stoyanchev
032 * @author Phillip Webb
033 * @since 4.0
034 */
035public interface WebSocketHandler {
036
037        /**
038         * Invoked after WebSocket negotiation has succeeded and the WebSocket connection is
039         * opened and ready for use.
040         * @throws Exception this method can handle or propagate exceptions; see class-level
041         * Javadoc for details.
042         */
043        void afterConnectionEstablished(WebSocketSession session) throws Exception;
044
045        /**
046         * Invoked when a new WebSocket message arrives.
047         * @throws Exception this method can handle or propagate exceptions; see class-level
048         * Javadoc for details.
049         */
050        void handleMessage(WebSocketSession session, WebSocketMessage<?> message) throws Exception;
051
052        /**
053         * Handle an error from the underlying WebSocket message transport.
054         * @throws Exception this method can handle or propagate exceptions; see class-level
055         * Javadoc for details.
056         */
057        void handleTransportError(WebSocketSession session, Throwable exception) throws Exception;
058
059        /**
060         * Invoked after the WebSocket connection has been closed by either side, or after a
061         * transport error has occurred. Although the session may technically still be open,
062         * depending on the underlying implementation, sending messages at this point is
063         * discouraged and most likely will not succeed.
064         * @throws Exception this method can handle or propagate exceptions; see class-level
065         * Javadoc for details.
066         */
067        void afterConnectionClosed(WebSocketSession session, CloseStatus closeStatus) throws Exception;
068
069        /**
070         * Whether the WebSocketHandler handles partial messages. If this flag is set to
071         * {@code true} and the underlying WebSocket server supports partial messages,
072         * then a large WebSocket message, or one of an unknown size may be split and
073         * maybe received over multiple calls to
074         * {@link #handleMessage(WebSocketSession, WebSocketMessage)}. The flag
075         * {@link org.springframework.web.socket.WebSocketMessage#isLast()} indicates if
076         * the message is partial and whether it is the last part.
077         */
078        boolean supportsPartialMessages();
079
080}