hunt.proton.engine.Link source code

1 /*
2  * hunt-proton: AMQP Protocol library for D programming language.
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 
12 module hunt.proton.engine.Link;
13 
14 import hunt.collection.Map;
15 import hunt.proton.amqp.Symbol;
16 import hunt.proton.amqp.UnsignedLong;
17 import hunt.proton.amqp.transport.ReceiverSettleMode;
18 import hunt.proton.amqp.transport.SenderSettleMode;
19 import hunt.proton.amqp.transport.Source;
20 import hunt.proton.amqp.transport.Target;
21 import hunt.proton.engine.Endpoint;
22 import hunt.proton.engine.Delivery;
23 import hunt.proton.engine.Session;
24 import hunt.collection.Set;
25 import hunt.proton.engine.EndpointState;
26 /**
27  * Link
28  *
29  * The settlement mode defaults are:
30  *
31  * Sender settle mode - {@link SenderSettleMode#MIXED}.
32  * Receiver settle mode - {@link ReceiverSettleMode#FIRST}
33  *
34  * TODO describe the application's responsibility to honour settlement.
35  */
36 interface Link : Endpoint
37 {
38 
39     /**
40      * Returns the name of the link
41      *
42      * @return the link name
43      */
44     string getName();
45 
46     /**
47      * Create a delivery object based on the specified tag and adds it to the
48      * this link's delivery list and its connection work list.
49      *
50      * TODO to clarify - this adds the delivery to the connection list.  It is not yet
51      * clear why this is done or if it is useful for the application to be able to discover
52      * newly created deliveries from the {@link Connection#getWorkHead()}.
53      *
54      * @param tag a tag for the delivery
55      * @return a new Delivery object
56      */
57     public Delivery delivery(byte[] tag);
58 
59     /**
60      * Create a delivery object based on the specified tag. This form
61      * of the method is intended to allow the tag to be formed from a
62      * subsequence of the byte array passed in. This might allow more
63      * optimisation options in future but at present is not
64      * implemented.
65      *
66      * @param tag a tag for the delivery
67      * @param offset (currently ignored and must be 0)
68      * @param length (currently ignored and must be the length of the <code>tag</code> array
69      * @return a Delivery object
70      */
71     public Delivery delivery(byte[] tag, int offset, int length);
72 
73     /**
74      * Returns the head delivery on the link.
75      */
76     Delivery head();
77 
78     /**
79      * Returns the current delivery
80      */
81     Delivery current();
82 
83     /**
84      * Attempts to advance the current delivery. Advances it to the next delivery if one exists, else null.
85      *
86      * The behaviour of this method is different for senders and receivers.
87      *
88      * @return true if it can advance, false if it cannot
89      *
90      * TODO document the meaning of the return value more fully. Currently Senderimpl only returns false if there is no current delivery
91      */
92     bool advance();
93 
94 
95     Source getSource();
96     Target getTarget();
97 
98     /**
99      * Sets the source for this link.
100      *
101      * The initiator of the link must always provide a Source.
102      *
103      * An application responding to the creation of the link should perform an application
104      * specific lookup on the {@link #getRemoteSource()} to determine an actual Source. If it
105      * failed to determine an actual source, it should set null, and then go on to {@link #close()}
106      * the link.
107      *
108      * @see "AMQP Spec 1.0 section 2.6.3"
109      */
110     void setSource(Source address);
111 
112     /**
113      * Expected to be used in a similar manner to {@link #setSource(Source)}
114      */
115     void setTarget(Target address);
116 
117     /**
118      * @see #setSource(Source)
119      */
120     Source getRemoteSource();
121 
122     /**
123      * @see #setTarget(Target)
124      */
125     Target getRemoteTarget();
126 
127     public Link next(Set!EndpointState local, Set!EndpointState remote);
128 
129     /**
130      * Gets the credit balance for a link.
131      *
132      * Note that a sending link may still be used to send deliveries even if
133      * link credit is/reaches zero, however those deliveries will end up being
134      * {@link #getQueued() queued} by the link until enough credit is obtained
135      * from the receiver to send them over the wire. In this case the balance
136      * reported will go negative.
137      *
138      * @return the credit balance for the link
139      */
140     public int getCredit();
141 
142     /**
143      * Gets the number of queued messages for a link.
144      *
145      * Links may queue deliveries for a number of reasons, for example there may be insufficient
146      * {@link #getCredit() credit} to send them to the receiver, they may not have yet had a chance
147      * to be written to the wire, or the receiving application has simply not yet processed them.
148      *
149      * @return the queued message count for the link
150      */
151     public int getQueued();
152 
153     public int getUnsettled();
154 
155     public Session getSession();
156 
157     SenderSettleMode getSenderSettleMode();
158 
159     /**
160      * Sets the sender settle mode.
161      *
162      * Should only be called during link set-up, i.e. before calling {@link #open()}.
163      *
164      * If this endpoint is the initiator of the link, this method can be used to set a value other than
165      * the default.
166      *
167      * If this endpoint is not the initiator, this method should be used to set a local value. According
168      * to the AMQP spec, the application may choose to accept the sender's suggestion
169      * (accessed by calling {@link #getRemoteSenderSettleMode()}) or choose another value. The value
170      * has no effect on Proton, but may be useful to the application at a later point.
171      *
172      * In order to be AMQP compliant the application is responsible for honouring the settlement mode. See {@link Link}.
173      */
174     void setSenderSettleMode(SenderSettleMode senderSettleMode);
175 
176     /**
177      * @see #setSenderSettleMode(SenderSettleMode)
178      */
179     SenderSettleMode getRemoteSenderSettleMode();
180 
181     ReceiverSettleMode getReceiverSettleMode();
182 
183     /**
184      * Sets the receiver settle mode.
185      *
186      * Used in analogous way to {@link #setSenderSettleMode(SenderSettleMode)}
187      */
188     void setReceiverSettleMode(ReceiverSettleMode receiverSettleMode);
189 
190     /**
191      * @see #setReceiverSettleMode(ReceiverSettleMode)
192      */
193     ReceiverSettleMode getRemoteReceiverSettleMode();
194 
195     /**
196      * TODO should this be part of the interface?
197      */
198     void setRemoteSenderSettleMode(SenderSettleMode remoteSenderSettleMode);
199 
200     /**
201      * Gets the local link properties.
202      *
203      * @see #setProperties(Map)
204      */
205     Map!(Symbol, Object) getProperties();
206 
207     /**
208      * Sets the local link properties, to be conveyed to the peer via the Attach frame when
209      * attaching the link to the session.
210      *
211      * Must be called during link setup, i.e. before calling the {@link #open()} method.
212      */
213     void setProperties(Map!(Symbol, Object) properties);
214 
215     /**
216      * Gets the remote link properties, as conveyed from the peer via the Attach frame
217      * when attaching the link to the session.
218      *
219      * @return the properties Map conveyed by the peer, or null if there was none.
220      */
221     Map!(Symbol, Object) getRemoteProperties();
222 
223     public int drained();
224 
225     /**
226      * Returns a [locally generated] view of credit at the remote peer by considering the
227      * current link {@link #getCredit() credit} count as well as the effect of
228      * any locally {@link #getQueued() queued} messages.
229      *
230      * @return view of effective remote credit
231      */
232     public int getRemoteCredit();
233 
234     public bool getDrain();
235 
236     public void detach();
237     public bool detached();
238 
239     /**
240      * Sets the local link offered capabilities, to be conveyed to the peer via the Attach frame
241      * when attaching the link to the session.
242      *
243      * Must be called during link setup, i.e. before calling the {@link #open()} method.
244      *
245      * @param offeredCapabilities
246      *          the offered capabilities array to send, or null for none.
247      */
248     public void setOfferedCapabilities(Symbol[] offeredCapabilities);
249 
250     /**
251      * Gets the local link offered capabilities.
252      *
253      * @return the offered capabilities array, or null if none was set.
254      *
255      * @see #setOfferedCapabilities(Symbol[])
256      */
257     Symbol[] getOfferedCapabilities();
258 
259     /**
260      * Gets the remote link offered capabilities, as conveyed from the peer via the Attach frame
261      * when attaching the link to the session.
262      *
263      * @return the offered capabilities array conveyed by the peer, or null if there was none.
264      */
265     Symbol[] getRemoteOfferedCapabilities();
266 
267     /**
268      * Sets the local link desired capabilities, to be conveyed to the peer via the Attach frame
269      * when attaching the link to the session.
270      *
271      * Must be called during link setup, i.e. before calling the {@link #open()} method.
272      *
273      * @param desiredCapabilities
274      *          the desired capabilities array to send, or null for none.
275      */
276     public void setDesiredCapabilities(Symbol[] desiredCapabilities);
277 
278     /**
279      * Gets the local link desired capabilities.
280      *
281      * @return the desired capabilities array, or null if none was set.
282      *
283      * @see #setDesiredCapabilities(Symbol[])
284      */
285     Symbol[] getDesiredCapabilities();
286 
287     /**
288      * Gets the remote link desired capabilities, as conveyed from the peer via the Attach frame
289      * when attaching the link to the session.
290      *
291      * @return the desired capabilities array conveyed by the peer, or null if there was none.
292      */
293     Symbol[] getRemoteDesiredCapabilities();
294 
295     /**
296      * Sets the local link max message size, to be conveyed to the peer via the Attach frame
297      * when attaching the link to the session. Null or 0 means no limit.
298      *
299      * Must be called during link setup, i.e. before calling the {@link #open()} method.
300      *
301      * @param maxMessageSize
302      *            the local max message size value, or null to clear. 0 also means no limit.
303      */
304     void setMaxMessageSize(UnsignedLong maxMessageSize);
305 
306     /**
307      * Gets the local link max message size.
308      *
309      * @return the local max message size, or null if none was set. 0 also means no limit.
310      *
311      * @see #setMaxMessageSize(UnsignedLong)
312      */
313     UnsignedLong getMaxMessageSize();
314 
315     /**
316      * Gets the remote link max message size, as conveyed from the peer via the Attach frame
317      * when attaching the link to the session.
318      *
319      * @return the remote max message size conveyed by the peer, or null if none was set. 0 also means no limit.
320      */
321     UnsignedLong getRemoteMaxMessageSize();
322 }