001/*-
002 * #%L
003 * HAPI FHIR Storage api
004 * %%
005 * Copyright (C) 2014 - 2025 Smile CDR, Inc.
006 * %%
007 * Licensed under the Apache License, Version 2.0 (the "License");
008 * you may not use this file except in compliance with the License.
009 * You may obtain a copy of the License at
010 *
011 *      http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 * #L%
019 */
020package ca.uhn.fhir.broker.api;
021
022import ca.uhn.fhir.rest.server.messaging.IMessage;
023import ca.uhn.fhir.rest.server.messaging.IMessageDeliveryContext;
024import jakarta.annotation.Nonnull;
025
026/**
027 * This is a message listener that expects to be called within a retrying context
028 * @param <T> the type of payload this message listener is expecting to receive
029 */
030public interface IRetryAwareMessageListener<T> extends IMessageListener<T> {
031
032        /**
033         * Use {@link IRetryAwareMessageListener#handleMessage(IMessageListener, IMessageDeliveryContext, IMessage)} to properly
034         * call instances of {@link IRetryAwareMessageListener}
035         */
036        default void handleMessage(@Nonnull IMessage<T> theMessage) {
037                IMessageDeliveryContext messageDeliveryContext;
038
039                if (theMessage instanceof IMessageDeliveryContext) {
040                        messageDeliveryContext = (IMessageDeliveryContext) theMessage;
041                } else {
042                        messageDeliveryContext = () -> 0;
043                }
044
045                IRetryAwareMessageListener.handleMessage(this, messageDeliveryContext, theMessage);
046        }
047
048        /**
049         * This method is called whenever a new message is received.
050         *
051         * @param theMessageDeliveryContext details about the message delivery if available
052         * @param theMessage                the message that was received
053         */
054        void handleMessage(@Nonnull IMessageDeliveryContext theMessageDeliveryContext, @Nonnull IMessage<T> theMessage);
055
056        /**
057         *
058         * Static helper method to call handleMessage on a message listener when it is not known whether the
059         * listener is an instance of {@link IRetryAwareMessageListener}
060         *
061         * @param theMessageListener the message listener to call
062         * @param theMessageDeliveryContext details about the message delivery if available
063         * @param theMessage the message that was received
064         * @param <P> the type of payload this message listener is expecting to receive
065         */
066        static <P> void handleMessage(
067                        IMessageListener<P> theMessageListener,
068                        @Nonnull IMessageDeliveryContext theMessageDeliveryContext,
069                        IMessage<P> theMessage) {
070                if (theMessageListener instanceof IRetryAwareMessageListener) {
071                        IRetryAwareMessageListener<P> listener = (IRetryAwareMessageListener<P>) theMessageListener;
072                        listener.handleMessage(theMessageDeliveryContext, theMessage);
073                } else {
074                        theMessageListener.handleMessage(theMessage);
075                }
076        }
077}