1 package com.atlassian.messagequeue.registry;
2
3 import com.atlassian.annotations.PublicApi;
4
5 import java.util.Optional;
6
7 /**
8 * Context that is passed to an execution of a message. This contains all information that is required by handlers of
9 * the message.
10 *
11 * @since 1.0
12 */
13 @PublicApi
14 public interface MessageContext {
15
16 /**
17 * @return the message ID.
18 */
19 Optional<String> getMessageId();
20
21 /**
22 * @return the payload that should be given to an executable message
23 */
24 Optional<String> getPayload();
25
26 /**
27 * Called by a message consumer to acknowledge the receipt of a message and prevent it's redelivery to another consumer.
28 *
29 * <p>Please note: due to the distributed nature of how messages are stored in some implementations, there are no
30 * guarantees that the message won't be redelivered to another consumer (even after this method is called).
31 * However, redelivery after <tt>acknowledge()</tt> is rare.
32 *
33 * <p>This method is thread-safe and idempotent.
34 *
35 * @throws com.atlassian.messagequeue.MessageAcknowledgementException if there is an error in acknowledgement.
36 */
37 void acknowledge();
38
39 /**
40 * Returns {@code true} if the {@code MessageRunner} should terminate its activities as gracefully as possible
41 * and exit; {@code false} to continue running normally.
42 * <p>
43 * {@code MessageRunner} cancellation is entirely cooperative. If a {@code MessageRunner} is likely to take longer
44 * than a few seconds to complete its work, then it should periodically check this value and react to it. Normally,
45 * cancellation is requested because the application is trying to shut down, and continuing to run
46 * after this flag has been set increases the chance that the system administrator will grow
47 * impatient and forcibly kill the application.
48 * </p>
49 *
50 * @return {@code true} if cancellation is requested; {@code false} otherwise
51 */
52 boolean isCancellationRequested();
53
54 /**
55 * @return {@code true} if the message in this context should automatically be acknowledged after <em>successful
56 * completion</em> of {@link MessageRunner#processMessage(MessageContext)}. If
57 * {@link MessageRunner#processMessage(MessageContext)} throws an exception, the message won't be acknowledged and
58 * will be redelivered after a delay (assuming the delivery count of the message has not exceeded the maximum count
59 * configured).
60 *
61 * <p>Returns {@code false} if the message should <em>not</em> be automatically acknowledged on successful completion.
62 */
63 default boolean shouldAutoAcknowledgeMessage() {
64 return true;
65 }
66
67 /**
68 * Cancels the auto-acknowledgement of the message in this context.
69 *
70 * <p>Auto-acknowledgement occurs after successful completion of {@link MessageRunner#processMessage(MessageContext)}.
71 */
72 default void cancelAutoAcknowledgementOfMessage() {}
73 }