hunt.amqp.ProtonReceiver source code

1 /*
2  * hunt-amqp: AMQP library for D programming language, based on hunt-net.
3  *
4  * Copyright (C) 2018-2019 HuntLabs
5  *
6  * Website: https://www.huntlabs.net
7  *
8  * Licensed under the Apache-2.0 License.
9  *
10  */
11 module hunt.amqp.ProtonReceiver;
12 
13 import hunt.Exceptions;
14 import hunt.amqp.Handler;
15 import hunt.amqp.ProtonLink;
16 import hunt.amqp.ProtonMessageHandler;
17 import hunt.Object;
18 /**
19  * @author <a href="http://tfox.org">Tim Fox</a>
20  */
21 interface ProtonReceiver : ProtonLink!ProtonReceiver {
22 
23   /**
24    * Sets the handler to process messages as they arrive. Should be set before opening unless prefetch is disabled and
25    * credit is being manually controlled.
26    *
27    * @param handler
28    *          the handler to process messages
29    * @return the receiver
30    */
31   ProtonReceiver handler(ProtonMessageHandler handler);
32 
33   /**
34    * Sets the number of message credits the receiver grants and replenishes automatically as messages are delivered.
35    *
36    * To manage credit manually, you can instead set prefetch to 0 before opening the consumer and then explicitly call
37    * {@link #flow(int)} as needed to manually grant credit.
38    *
39    * @param messages
40    *          the message prefetch
41    * @return the receiver
42    */
43   ProtonReceiver setPrefetch(int messages);
44 
45   /**
46    * Get the current prefetch value.
47    *
48    * @return the prefetch
49    * @see #setPrefetch(int)
50    */
51   int getPrefetch();
52 
53   /**
54    * Sets whether received deliveries should be automatically accepted (and settled) after the message handler runs for
55    * them, if no other disposition has been applied during handling.
56    *
57    * True by default.
58    *
59    * @param autoAccept
60    *          whether deliveries should be auto accepted after handling if no disposition was applied
61    * @return the receiver
62    */
63   ProtonReceiver setAutoAccept(bool autoAccept);
64 
65   /**
66    * Get whether the receiver is auto accepting.
67    *
68    * @return whether deliveries are being auto accepted after handling if no disposition was applied
69    * @see #setAutoAccept(boolean)
70    */
71   bool isAutoAccept();
72 
73   /**
74    * Grants the given number of message credits to the sender.
75    *
76    * For use when {@link #setPrefetch(int)} has been used to disable automatic prefetch credit handling.
77    *
78    * @param credits
79    *          the credits to flow
80    * @return the receiver
81    * @throws IllegalStateException
82    *           if prefetch is non-zero, or an existing drain operation is not yet complete
83    */
84   ProtonReceiver flow(int credits);
85 
86   /**
87    * Initiates a 'drain' of link credit from the remote sender.
88    *
89    * The timeout parameter allows scheduling a delay (in milliseconds) after which the handler should be fired with
90    * a failure result if the attempt has not yet completed successfully, with a value of 0 equivalent to no-timeout.
91    *
92    * If a drain attempt fails due to timeout, it is no longer possible to reason about the 'drain' state of the receiver
93    * and thus any further attempts to drain it should be avoided. The receiver should typically be closed in such cases.
94    *
95    * Only available for use when {@link #setPrefetch(int)} has been used to disable automatic credit handling.
96    *
97    * @param timeout
98    *          the delay in milliseconds before which the drain attempt should be considered failed, or 0 for no timeout.
99    * @param completionHandler
100    *          handler called when credit hits 0 due to messages arriving, or a 'drain response' flow
101    *
102    * @return the receiver
103    * @throws IllegalStateException
104    *           if prefetch is non-zero, or an existing drain operation is not yet complete
105    * @throws IllegalArgumentException
106    *           if no completion handler is given
107    */
108   ProtonReceiver drain(long timeout, Handler!Void completionHandler);
109 }