hunt.amqp.ProtonSession 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.ProtonSession;
12 
13 import hunt.amqp.Handler;
14 import hunt.proton.amqp.transport.ErrorCondition;
15 import hunt.proton.engine.Record;
16 import hunt.amqp.ProtonReceiver;
17 import hunt.String;
18 import hunt.amqp.ProtonLinkOptions;
19 import hunt.amqp.ProtonSender;
20 import hunt.amqp.ProtonConnection;
21 /**
22  * @author <a href="http://tfox.org">Tim Fox</a>
23  */
24 interface ProtonSession {
25 
26   /**
27    * Creates a receiver used to consumer messages from the given node address.
28    *
29    * @param address
30    *          The source address to attach the consumer to.
31    *
32    * @return the (unopened) consumer.
33    */
34   ProtonReceiver createReceiver(string address);
35 
36   /**
37    * Creates a receiver used to consumer messages from the given node address.
38    *
39    * @param address
40    *          The source address to attach the consumer to.
41    * @param receiverOptions
42    *          The options for this receiver.
43    *
44    * @return the (unopened) consumer.
45    */
46   ProtonReceiver createReceiver(string address, ProtonLinkOptions receiverOptions);
47 
48   /**
49    * Creates a sender used to send messages to the given node address. If no address (i.e null) is specified then a
50    * sender will be established to the 'anonymous relay' and each message must specify its destination address.
51    *
52    * @param address
53    *          The target address to attach to, or null to attach to the anonymous relay.
54    *
55    * @return the (unopened) sender.
56    */
57   ProtonSender createSender(string address);
58 
59   /**
60    * Creates a sender used to send messages to the given node address. If no address (i.e null) is specified then a
61    * sender will be established to the 'anonymous relay' and each message must specify its destination address.
62    *
63    * @param address
64    *          The target address to attach to, or null to attach to the anonymous relay.
65    * @param senderOptions
66    *          The options for this sender.
67    *
68    * @return the (unopened) sender.
69    */
70   ProtonSender createSender(string address, ProtonLinkOptions senderOptions);
71 
72   /**
73    * Opens the AMQP session, i.e. allows the Begin frame to be emitted. Typically used after any additional
74    * configuration is performed on the object.
75    *
76    * For locally initiated sessions, the {@link #openHandler(Handler)} may be used to handle the peer sending their
77    * Begin frame.
78    *
79    * @return the session
80    */
81   ProtonSession open();
82 
83   /**
84    * Closed the AMQP session, i.e. allows the End frame to be emitted.
85    *
86    * If the closure is being locally initiated, the {@link #closeHandler(Handler)} may be used to handle the peer
87    * sending their End frame. When use of the session is complete, i.e it is locally and
88    * remotely closed, {@link #free()} must be called to ensure related resources can be tidied up.
89    *
90    * @return the session
91    */
92   ProtonSession close();
93 
94   /**
95    * Retrieves the attachments record, upon which application items can be set/retrieved.
96    *
97    * @return the attachments
98    */
99   Record attachments();
100 
101   /**
102    * Sets the incoming capacity in bytes, used to govern session-level flow control.
103    *
104    * @param capacity
105    *          capacity in bytes
106    * @return the session
107    */
108   ProtonSession setIncomingCapacity(int capacity);
109 
110   /**
111    * Gets the incoming capacity in bytes, used to govern session-level flow control.
112    *
113    * @return capacity in bytes
114    */
115   int getIncomingCapacity();
116 
117   /**
118    * Gets the connection this session is on.
119    *
120    * @return the connection
121    */
122   ProtonConnection getConnection();
123 
124   /**
125    * Sets the local ErrorCondition object.
126    *
127    * @param condition
128    *          the condition to set
129    * @return the session
130    */
131   ProtonSession setCondition(ErrorCondition condition);
132 
133   /**
134    * Gets the local ErrorCondition object.
135    *
136    * @return the condition
137    */
138   ErrorCondition getCondition();
139 
140   /**
141    * Gets the remote ErrorCondition object.
142    *
143    * @return the condition
144    */
145   ErrorCondition getRemoteCondition();
146 
147   /**
148    * Sets a handler for when an AMQP Begin frame is received from the remote peer.
149    *
150    * Typically used by clients, servers rely on {@link ProtonConnection#sessionOpenHandler(Handler)}.
151    *
152    * @param remoteOpenHandler
153    *          the handler
154    * @return the session
155    */
156   ProtonSession openHandler(Handler!ProtonSession remoteOpenHandler);
157 
158   /**
159    * Sets a handler for when an AMQP End frame is received from the remote peer.
160    *
161    * @param remoteCloseHandler
162    *          the handler
163    * @return the session
164    */
165   ProtonSession closeHandler(Handler!ProtonSession remoteCloseHandler);
166 
167   /**
168    * Tidies up related session resources when complete with use. Call only after the
169    * session is finished with, i.e. locally and remotely closed.
170    */
171   void free();
172 }