001/*
002 * Copyright 2002-2017 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.messaging.simp.stomp;
018
019import org.springframework.lang.Nullable;
020
021/**
022 * A contract for client STOMP session lifecycle events including a callback
023 * when the session is established and notifications of transport or message
024 * handling failures.
025 *
026 * <p>This contract also extends {@link StompFrameHandler} in order to handle
027 * STOMP ERROR frames received from the broker.
028 *
029 * <p>Implementations of this interface should consider extending
030 * {@link StompSessionHandlerAdapter}.
031 *
032 * @author Rossen Stoyanchev
033 * @since 4.2
034 * @see StompSessionHandlerAdapter
035 */
036public interface StompSessionHandler extends StompFrameHandler {
037
038        /**
039         * Invoked when the session is ready to use, i.e. after the underlying
040         * transport (TCP, WebSocket) is connected and a STOMP CONNECTED frame is
041         * received from the broker.
042         * @param session the client STOMP session
043         * @param connectedHeaders the STOMP CONNECTED frame headers
044         */
045        void afterConnected(StompSession session, StompHeaders connectedHeaders);
046
047        /**
048         * Handle any exception arising while processing a STOMP frame such as a
049         * failure to convert the payload or an unhandled exception in the
050         * application {@code StompFrameHandler}.
051         * @param session the client STOMP session
052         * @param command the STOMP command of the frame
053         * @param headers the headers
054         * @param payload the raw payload
055         * @param exception the exception
056         */
057        void handleException(StompSession session, @Nullable StompCommand command,
058                        StompHeaders headers, byte[] payload, Throwable exception);
059
060        /**
061         * Handle a low level transport error which could be an I/O error or a
062         * failure to encode or decode a STOMP message.
063         * <p>Note that
064         * {@link org.springframework.messaging.simp.stomp.ConnectionLostException
065         * ConnectionLostException} will be passed into this method when the
066         * connection is lost rather than closed normally via
067         * {@link StompSession#disconnect()}.
068         * @param session the client STOMP session
069         * @param exception the exception that occurred
070         */
071        void handleTransportError(StompSession session, Throwable exception);
072
073}