hunt.amqp.ProtonConnection 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.ProtonConnection;
12 
13 import hunt.amqp.Handler;
14 
15 import hunt.collection.Map;
16 
17 import hunt.proton.amqp.Symbol;
18 import hunt.proton.amqp.transport.ErrorCondition;
19 import hunt.proton.engine.Record;
20 import hunt.amqp.ProtonReceiver;
21 import hunt.amqp.ProtonLinkOptions;
22 import hunt.amqp.ProtonSender;
23 import hunt.amqp.ProtonSession;
24 
25 // import hunt.Functions;
26 import hunt.String;
27 
28 /**
29  * @author <a href="http://tfox.org">Tim Fox</a>
30  * @author <a href="http://hiramchirino.com">Hiram Chirino</a>
31  */
32 interface ProtonConnection {
33 
34   /**
35    * Opens the AMQP connection, i.e. allows the Open frame to be emitted. Typically used after any additional
36    * configuration is performed on the connection object.
37    *
38    * For locally initiated connections, the {@link #openHandler(Handler)} may be used to handle the peer sending their
39    * Open frame.
40    *
41    * @return the connection
42    */
43   ProtonConnection open();
44 
45   /**
46    * Closes the AMQP connection, i.e. allows the Close frame to be emitted.
47    *
48    * For locally initiated connections, the {@link #closeHandler(Handler)} may be used to handle the peer sending their
49    * Close frame (if they haven't already).
50    *
51    * @return the connection
52    */
53   ProtonConnection close();
54 
55   /**
56    * Creates a receiver used to consumer messages from the given node address.
57    *
58    * @param address
59    *          The source address to attach the consumer to.
60    *
61    * @return the (unopened) consumer.
62    */
63   ProtonReceiver createReceiver(string address);
64 
65   /**
66    * Creates a receiver used to consumer messages from the given node address.
67    *
68    * @param address
69    *          The source address to attach the consumer to.
70    * @param receiverOptions
71    *          The options for this receiver.
72    *
73    * @return the (unopened) consumer.
74    */
75   ProtonReceiver createReceiver(string address, ProtonLinkOptions receiverOptions);
76 
77   /**
78    * Creates a sender used to send messages to the given node address. If no address (i.e null) is specified then a
79    * sender will be established to the 'anonymous relay' and each message must specify its destination address.
80    *
81    * @param address
82    *          The target address to attach to, or null to attach to the anonymous relay.
83    *
84    * @return the (unopened) sender.
85    */
86   ProtonSender createSender(string address);
87 
88   /**
89    * Creates a sender used to send messages to the given node address. If no address (i.e null) is specified then a
90    * sender will be established to the 'anonymous relay' and each message must specify its destination address.
91    *
92    * @param address
93    *          The target address to attach to, or null to attach to the anonymous relay.
94    * @param senderOptions
95    *          The options for this sender.
96    *
97    * @return the (unopened) sender.
98    */
99   ProtonSender createSender(string address, ProtonLinkOptions senderOptions);
100 
101   /**
102    * Sets the container id value advertised to peers in the AMQP Open frame. Sometimes used as a 'client-id' by clients.
103    *
104    * @param container
105    *          the container id to set
106    * @return the connection
107    */
108   ProtonConnection setContainer(string container);
109 
110   /**
111    * Gets the container id value requested of/advertised to peers in the AMQP Open frame.
112    *
113    * @return the container id
114    */
115   string getContainer();
116 
117   /**
118    * Retrieves the attachments record, upon which application items can be set/retrieved.
119    *
120    * @return the attachments
121    */
122   Record attachments();
123 
124   /**
125    * Sets the connection properties map to be sent to the remote peer in our Open frame.
126    *
127    * If non-null, the given map will be copied and augmented with the default map containing "product" and "version"
128    * entries if not present in the given properties. If null, no properties map will be sent.
129    *
130    * @param properties
131    *          the properties map, or null to request not sending any properties map
132    * @return the connection
133    */
134   ProtonConnection setProperties(Map!(Symbol, Object) properties);
135 
136   /**
137    * Returns the connection properties map if sent by the remote peer in its Open frame. May be null.
138    *
139    * @return the remote connection properties map, or null if no map was sent.
140    */
141   Map!(Symbol, Object) getRemoteProperties();
142 
143   /**
144    * Allows querying (once the connection has remotely opened) whether the peer advertises support for the anonymous
145    * relay (sender with null address).
146    *
147    * @return true if the peer advertised support for the anonymous relay
148    */
149   bool isAnonymousRelaySupported();
150 
151   /**
152    * Creates a new session, which can be used to create new senders/receivers on.
153    *
154    * @return the (unopened) session.
155    */
156   ProtonSession createSession();
157 
158   /**
159    * Disconnects the underlying transport connection. This can occur asynchronously
160    * and may not complete until some time after the method has returned.
161    *
162    * @see #disconnectHandler(Handler)
163    */
164   void disconnect();
165 
166   /**
167    * Gets whether the underlying transport has indicated it is disconnected.
168    *
169    * @return whether the underlying transport indicated it is disconnected.
170    */
171   bool isDisconnected();
172 
173   /**
174    * Sets the hostname value requested of/advertised to peers in the AMQP Open frame.
175    *
176    * @param hostname
177    *          the hostname to set
178    * @return the connection
179    */
180   ProtonConnection setHostname(string hostname);
181 
182   /**
183    * Gets the hostname value requested of/advertised to peers in the AMQP Open frame.
184    *
185    * @return the hostname
186    */
187   string getHostname();
188 
189   /**
190    * Returns the container value requested by/advertised by remote peer in their AMQP Open frame.
191    *
192    * @return the container id
193    */
194   string getRemoteContainer();
195 
196   /**
197    * Sets the desired connection capabilities to be sent to the remote peer in our Open frame.
198    *
199    * If non-null, the given array will be copied and augmented with any default capabilities. If null, no capabilities
200    * will be sent.
201    *
202    * @param capabilities
203    *          the capabilities, or null to request not sending any capabilities
204    * @return the connection
205    */
206   ProtonConnection setDesiredCapabilities(Symbol[] capabilities);
207 
208   /**
209    * Returns the desired connection capabilities sent by the remote peer in its Open frame. May be null.
210    *
211    * @return the remote desired connection capabilities, or null if no capabilities were sent.
212    */
213   Symbol[] getRemoteDesiredCapabilities();
214 
215   /**
216    * Sets the offered connection capabilities to be sent to the remote peer in our Open frame.
217    *
218    * If non-null, the given array will be copied and augmented with any default capabilities. If null, no capabilities
219    * will be sent.
220    *
221    * @param capabilities
222    *          the capabilities, or null to request not sending any capabilities
223    * @return the connection
224    */
225   ProtonConnection setOfferedCapabilities(Symbol[] capabilities);
226 
227   /**
228    * Returns the offered connection capabilities sent by the remote peer in its Open frame. May be null.
229    *
230    * @return the remote offered connection capabilities, or null if no capabilities were sent.
231    */
232   Symbol[] getRemoteOfferedCapabilities();
233 
234 
235   /**
236    * Returns the container value requested by/advertised by remote peer in their AMQP Open frame.
237    *
238    * @return the container id
239    */
240   string getRemoteHostname();
241 
242   /**
243    * Sets the local ErrorCondition object.
244    *
245    * @param condition
246    *          the condition to set
247    * @return the connection
248    */
249   ProtonConnection setCondition(ErrorCondition condition);
250 
251   /**
252    * Gets the local ErrorCondition object.
253    *
254    * @return the condition
255    */
256   ErrorCondition getCondition();
257 
258   /**
259    * Gets the remote ErrorCondition object.
260    *
261    * @return the condition
262    */
263   ErrorCondition getRemoteCondition();
264 
265   /**
266    * Sets a handler for when an AMQP Open frame is received from the remote peer.
267    *
268    * @param remoteOpenHandler
269    *          the handler
270    * @return the connection
271    */
272   ProtonConnection openHandler(Handler!ProtonConnection remoteOpenHandler);
273 
274   /**
275    * Sets a handler for when an AMQP Close frame is received from the remote peer.
276    *
277    * @param remoteCloseHandler
278    *          the handler
279    * @return the connection
280    */
281   ProtonConnection closeHandler(AsyncResultHandler!ProtonConnection closeHandler);
282 
283   /**
284    * Sets a handler for when an AMQP Begin frame is received from the remote peer.
285    *
286    * Used to process remotely initiated Sessions. Locally initiated sessions have their own handler invoked instead.
287    * Typically used by servers.
288    *
289    * @param remoteSessionOpenHandler
290    *          the handler
291    * @return the connection
292    */
293   ProtonConnection sessionOpenHandler(AmqpEventHandler!ProtonSession remoteSessionOpenHandler);
294 
295   /**
296    * Sets a handler for when an AMQP Attach frame is received from the remote peer for a sending link.
297    *
298    * Used to process remotely initiated sending link. Locally initiated links have their own handler invoked instead.
299    * Typically used by servers.
300    *
301    * @param remoteSenderOpenHandler
302    *          the handler
303    * @return the connection
304    */
305   ProtonConnection senderOpenHandler(Handler!ProtonSender remoteSenderOpenHandler);
306 
307   /**
308    * Sets a handler for when an AMQP Attach frame is received from the remote peer for a receiving link.
309    *
310    * Used to process remotely initiated receiving link. Locally initiated links have their own handler invoked instead.
311    * Typically used by servers.
312    *
313    * @param remoteReceiverOpenHandler
314    *          the handler
315    * @return the connection
316    */
317   ProtonConnection receiverOpenHandler(Handler!ProtonReceiver remoteReceiverOpenHandler);
318 
319   /**
320    * Sets a handler for when the underlying transport connection indicates it has disconnected.
321    *
322    * @return the connection
323    * @param disconnectHandler
324    *          the handler
325    */
326   ProtonConnection disconnectHandler(AmqpEventHandler!ProtonConnection disconnectHandler);
327 
328 }