Package org.apache.qpid.proton.engine

# Interface Link

All Superinterfaces:
  `Endpoint`, `Extendable`

All Known Subinterfaces:
  `Receiver`, `Sender`

All Known Implementing Classes:
  `LinkImpl`, `ReceiverImpl`, `SenderImpl`

public interface Link extends Endpoint
Link The settlement mode defaults are: Sender settle mode - `SenderSettleMode.MIXED`. Receiver settle mode - `ReceiverSettleMode.FIRST` TODO describe the application's responsibility to honour settlement.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`advance()`
Attempts to advance the current delivery.
`Delivery`
`current()`
Returns the current delivery
`Delivery`
`delivery(byte[] tag)`
Create a delivery object based on the specified tag and adds it to the this link's delivery list and its connection work list.
`Delivery`
`delivery(byte[] tag, int offset, int length)`
Create a delivery object based on the specified tag.
`void`
`detach()`
`boolean`
`detached()`
`int`
`drained()`
`int`
`getCredit()`
Gets the credit balance for a link.
`Symbol[]`
`getDesiredCapabilities()`
Gets the local link desired capabilities.
`boolean`
`getDrain()`
`UnsignedLong`
`getMaxMessageSize()`
Gets the local link max message size.
`String`
`getName()`
Returns the name of the link
`Symbol[]`
`getOfferedCapabilities()`
Gets the local link offered capabilities.
`Map<Symbol,Object>`
`getProperties()`
Gets the local link properties.
`int`
`getQueued()`
Gets the number of queued messages for a link.
`ReceiverSettleMode`
`getReceiverSettleMode()`
`int`
`getRemoteCredit()`
Returns a [locally generated] view of credit at the remote peer by considering the current link `credit` count as well as the effect of any locally `queued` messages.
`Symbol[]`
`getRemoteDesiredCapabilities()`
Gets the remote link desired capabilities, as conveyed from the peer via the Attach frame when attaching the link to the session.
`UnsignedLong`
`getRemoteMaxMessageSize()`
Gets the remote link max message size, as conveyed from the peer via the Attach frame when attaching the link to the session.
`Symbol[]`
`getRemoteOfferedCapabilities()`
Gets the remote link offered capabilities, as conveyed from the peer via the Attach frame when attaching the link to the session.
`Map<Symbol,Object>`
`getRemoteProperties()`
Gets the remote link properties, as conveyed from the peer via the Attach frame when attaching the link to the session.
`ReceiverSettleMode`
`getRemoteReceiverSettleMode()`
`SenderSettleMode`
`getRemoteSenderSettleMode()`
`Source`
`getRemoteSource()`
`Target`
`getRemoteTarget()`
`SenderSettleMode`
`getSenderSettleMode()`
`Session`
`getSession()`
`Source`
`getSource()`
`Target`
`getTarget()`
`int`
`getUnsettled()`
`Delivery`
`head()`
Returns the head delivery on the link.
`Link`
`next(EnumSet<EndpointState> local, EnumSet<EndpointState> remote)`
`void`
`setDesiredCapabilities(Symbol[] desiredCapabilities)`
Sets the local link desired capabilities, to be conveyed to the peer via the Attach frame when attaching the link to the session.
`void`
`setMaxMessageSize(UnsignedLong maxMessageSize)`
Sets the local link max message size, to be conveyed to the peer via the Attach frame when attaching the link to the session.
`void`
`setOfferedCapabilities(Symbol[] offeredCapabilities)`
Sets the local link offered capabilities, to be conveyed to the peer via the Attach frame when attaching the link to the session.
`void`
`setProperties(Map<Symbol,Object> properties)`
Sets the local link properties, to be conveyed to the peer via the Attach frame when attaching the link to the session.
`void`
`setReceiverSettleMode(ReceiverSettleMode receiverSettleMode)`
Sets the receiver settle mode.
`void`
`setRemoteSenderSettleMode(SenderSettleMode remoteSenderSettleMode)`
Deprecated.
`void`
`setSenderSettleMode(SenderSettleMode senderSettleMode)`
Sets the sender settle mode.
`void`
`setSource(Source address)`
Sets the source for this link.
`void`
`setTarget(Target address)`
Expected to be used in a similar manner to `setSource(Source)`

### Methods inherited from interface org.apache.qpid.proton.engine.Endpoint

`close, free, getCondition, getContext, getLocalState, getRemoteCondition, getRemoteState, open, setCondition, setContext`

### Methods inherited from interface org.apache.qpid.proton.engine.Extendable

`attachments`

## Method Details

### getName

String getName()
Returns the name of the link

Returns:
  the link name

### delivery

Delivery delivery(byte[] tag)
Create a delivery object based on the specified tag and adds it to the this link's delivery list and its connection work list. TODO to clarify - this adds the delivery to the connection list. It is not yet clear why this is done or if it is useful for the application to be able to discover newly created deliveries from the `Connection.getWorkHead()`.

Parameters:
  `tag` - a tag for the delivery
Returns:
  a new Delivery object

### delivery

Delivery delivery(byte[] tag, int offset, int length)
Create a delivery object based on the specified tag. This form of the method is intended to allow the tag to be formed from a subsequence of the byte array passed in. This might allow more optimisation options in future but at present is not implemented.

Parameters:
  `tag` - a tag for the delivery
  `offset` - (currently ignored and must be 0)
  `length` - (currently ignored and must be the length of the `tag` array
Returns:
  a Delivery object

### head

Delivery head()
Returns the head delivery on the link.

### current

Delivery current()
Returns the current delivery

### advance

boolean advance()
Attempts to advance the current delivery. Advances it to the next delivery if one exists, else null. The behaviour of this method is different for senders and receivers.

Returns:
  true if it can advance, false if it cannot TODO document the meaning of the return value more fully. Currently Senderimpl only returns false if there is no current delivery

### getSource

Source getSource()

### getTarget

Target getTarget()

### setSource

void setSource(Source address)
Sets the source for this link. The initiator of the link must always provide a Source. An application responding to the creation of the link should perform an application specific lookup on the `getRemoteSource()` to determine an actual Source. If it failed to determine an actual source, it should set null, and then go on to `Endpoint.close()` the link.

See Also:
  - "AMQP Spec 1.0 section 2.6.3"

### setTarget

void setTarget(Target address)
Expected to be used in a similar manner to `setSource(Source)`

### getRemoteSource

Source getRemoteSource()

See Also:
  - `setSource(Source)`

### getRemoteTarget

Target getRemoteTarget()

See Also:
  - `setTarget(Target)`

### next

Link next(EnumSet<EndpointState> local, EnumSet<EndpointState> remote)

### getCredit

int getCredit()
Gets the credit balance for a link. Note that a sending link may still be used to send deliveries even if link credit is/reaches zero, however those deliveries will end up being `queued` by the link until enough credit is obtained from the receiver to send them over the wire. In this case the balance reported will go negative.

Returns:
  the credit balance for the link

### getQueued

int getQueued()
Gets the number of queued messages for a link. Links may queue deliveries for a number of reasons, for example there may be insufficient `credit` to send them to the receiver, they may not have yet had a chance to be written to the wire, or the receiving application has simply not yet processed them.

Returns:
  the queued message count for the link

### getUnsettled

int getUnsettled()

### getSession

Session getSession()

### getSenderSettleMode

SenderSettleMode getSenderSettleMode()

### setSenderSettleMode

void setSenderSettleMode(SenderSettleMode senderSettleMode)
Sets the sender settle mode. Should only be called during link set-up, i.e. before calling `Endpoint.open()`. If this endpoint is the initiator of the link, this method can be used to set a value other than the default. If this endpoint is not the initiator, this method should be used to set a local value. According to the AMQP spec, the application may choose to accept the sender's suggestion (accessed by calling `getRemoteSenderSettleMode()`) or choose another value. The value has no effect on Proton, but may be useful to the application at a later point. In order to be AMQP compliant the application is responsible for honouring the settlement mode. See `Link`.

### getRemoteSenderSettleMode

SenderSettleMode getRemoteSenderSettleMode()

See Also:
  - `setSenderSettleMode(SenderSettleMode)`

### getReceiverSettleMode

ReceiverSettleMode getReceiverSettleMode()

### setReceiverSettleMode

void setReceiverSettleMode(ReceiverSettleMode receiverSettleMode)
Sets the receiver settle mode. Used in analogous way to `setSenderSettleMode(SenderSettleMode)`

### getRemoteReceiverSettleMode

ReceiverSettleMode getRemoteReceiverSettleMode()

See Also:
  - `setReceiverSettleMode(ReceiverSettleMode)`

### setRemoteSenderSettleMode

@Deprecated void setRemoteSenderSettleMode(SenderSettleMode remoteSenderSettleMode)
Deprecated.
TODO should this be part of the interface?

### getProperties

Map<Symbol,Object> getProperties()
Gets the local link properties.

See Also:
  - `setProperties(Map)`

### setProperties

void setProperties(Map<Symbol,Object> properties)
Sets the local link properties, to be conveyed to the peer via the Attach frame when attaching the link to the session. Must be called during link setup, i.e. before calling the `Endpoint.open()` method.

### getRemoteProperties

Map<Symbol,Object> getRemoteProperties()
Gets the remote link properties, as conveyed from the peer via the Attach frame when attaching the link to the session.

Returns:
  the properties Map conveyed by the peer, or null if there was none.

### drained

int drained()

### getRemoteCredit

int getRemoteCredit()
Returns a [locally generated] view of credit at the remote peer by considering the current link `credit` count as well as the effect of any locally `queued` messages.

Returns:
  view of effective remote credit

### getDrain

boolean getDrain()

### detach

void detach()

### detached

boolean detached()

### setOfferedCapabilities

void setOfferedCapabilities(Symbol[] offeredCapabilities)
Sets the local link offered capabilities, to be conveyed to the peer via the Attach frame when attaching the link to the session. Must be called during link setup, i.e. before calling the `Endpoint.open()` method.

Parameters:
  `offeredCapabilities` - the offered capabilities array to send, or null for none.

### getOfferedCapabilities

Symbol[] getOfferedCapabilities()
Gets the local link offered capabilities.

Returns:
  the offered capabilities array, or null if none was set.
See Also:
  - `setOfferedCapabilities(Symbol[])`

### getRemoteOfferedCapabilities

Symbol[] getRemoteOfferedCapabilities()
Gets the remote link offered capabilities, as conveyed from the peer via the Attach frame when attaching the link to the session.

Returns:
  the offered capabilities array conveyed by the peer, or null if there was none.

### setDesiredCapabilities

void setDesiredCapabilities(Symbol[] desiredCapabilities)
Sets the local link desired capabilities, to be conveyed to the peer via the Attach frame when attaching the link to the session. Must be called during link setup, i.e. before calling the `Endpoint.open()` method.

Parameters:
  `desiredCapabilities` - the desired capabilities array to send, or null for none.

### getDesiredCapabilities

Symbol[] getDesiredCapabilities()
Gets the local link desired capabilities.

Returns:
  the desired capabilities array, or null if none was set.
See Also:
  - `setDesiredCapabilities(Symbol[])`

### getRemoteDesiredCapabilities

Symbol[] getRemoteDesiredCapabilities()
Gets the remote link desired capabilities, as conveyed from the peer via the Attach frame when attaching the link to the session.

Returns:
  the desired capabilities array conveyed by the peer, or null if there was none.

### setMaxMessageSize

void setMaxMessageSize(UnsignedLong maxMessageSize)
Sets the local link max message size, to be conveyed to the peer via the Attach frame when attaching the link to the session. Null or 0 means no limit. Must be called during link setup, i.e. before calling the `Endpoint.open()` method.

Parameters:
  `maxMessageSize` - the local max message size value, or null to clear. 0 also means no limit.

### getMaxMessageSize

UnsignedLong getMaxMessageSize()
Gets the local link max message size.

Returns:
  the local max message size, or null if none was set. 0 also means no limit.
See Also:
  - `setMaxMessageSize(UnsignedLong)`

### getRemoteMaxMessageSize

UnsignedLong getRemoteMaxMessageSize()
Gets the remote link max message size, as conveyed from the peer via the Attach frame when attaching the link to the session.

Returns:
  the remote max message size conveyed by the peer, or null if none was set. 0 also means no limit.