001/*
002 * Copyright 2002-2018 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.support;
018
019import org.springframework.lang.Nullable;
020import org.springframework.messaging.Message;
021import org.springframework.messaging.MessageChannel;
022
023/**
024 * Interface for interceptors that are able to view and/or modify the
025 * {@link Message Messages} being sent-to and/or received-from a
026 * {@link MessageChannel}.
027 *
028 * @author Mark Fisher
029 * @author Rossen Stoyanchev
030 * @since 4.0
031 * @see Message
032 * @see MessageChannel
033 */
034public interface ChannelInterceptor {
035
036        /**
037         * Invoked before the Message is actually sent to the channel.
038         * This allows for modification of the Message if necessary.
039         * If this method returns {@code null} then the actual
040         * send invocation will not occur.
041         */
042        @Nullable
043        default Message<?> preSend(Message<?> message, MessageChannel channel) {
044                return message;
045        }
046
047        /**
048         * Invoked immediately after the send invocation. The boolean
049         * value argument represents the return value of that invocation.
050         */
051        default void postSend(Message<?> message, MessageChannel channel, boolean sent) {
052        }
053
054        /**
055         * Invoked after the completion of a send regardless of any exception that
056         * have been raised thus allowing for proper resource cleanup.
057         * <p>Note that this will be invoked only if {@link #preSend} successfully
058         * completed and returned a Message, i.e. it did not return {@code null}.
059         * @since 4.1
060         */
061        default void afterSendCompletion(
062                        Message<?> message, MessageChannel channel, boolean sent, @Nullable Exception ex) {
063        }
064
065        /**
066         * Invoked as soon as receive is called and before a Message is
067         * actually retrieved. If the return value is 'false', then no
068         * Message will be retrieved. This only applies to PollableChannels.
069         */
070        default boolean preReceive(MessageChannel channel) {
071                return true;
072        }
073
074        /**
075         * Invoked immediately after a Message has been retrieved but before
076         * it is returned to the caller. The Message may be modified if
077         * necessary; {@code null} aborts further interceptor invocations.
078         * This only applies to PollableChannels.
079         */
080        @Nullable
081        default Message<?> postReceive(Message<?> message, MessageChannel channel) {
082                return message;
083        }
084
085        /**
086         * Invoked after the completion of a receive regardless of any exception that
087         * have been raised thus allowing for proper resource cleanup.
088         * <p>Note that this will be invoked only if {@link #preReceive} successfully
089         * completed and returned {@code true}.
090         * @since 4.1
091         */
092        default void afterReceiveCompletion(@Nullable Message<?> message, MessageChannel channel,
093                        @Nullable Exception ex) {
094        }
095
096}