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