Package org.apache.qpid.protonj2.engine

Interface Link<L extends Link<L>>

Type Parameters:
L - The link type that this Link represents, Sender or Receiver
All Superinterfaces:
Endpoint<L>
All Known Subinterfaces:
Receiver, Sender
All Known Implementing Classes:
ProtonLink, ProtonReceiver, ProtonSender
public interface Link<L extends Link<L>> extends Endpoint<L>
Base API for Sender and Receiver links.

  • Method Details

    • detach

      L detach()
      Detach this end of the link.
      Returns:
      this Link.
      Throws:
      EngineStateException - if an error occurs detaching the Link or the Engine is shutdown.

    • isLocallyDetached

      boolean isLocallyDetached()
      Returns true if this Link is currently locally detached meaning the state returned from getState() is equal to LinkState.DETACHED. A link is locally detached after a call to detach().
      Returns:
      true if the link is locally closed.
      See Also:

    • isLocallyClosedOrDetached

      boolean isLocallyClosedOrDetached()
      Returns true if this Link is currently locally detached or locally closed meaning the state returned from getState() is equal to LinkState.DETACHED or LinkState.CLOSED. A link is locally detached after a call to detach() and is locally closed after a call to Endpoint.close().
      Returns:
      true if the link is locally closed or detached.
      See Also:

    • getState

      LinkState getState()
      Returns:
      the local link state

    • getCredit

      int getCredit()
      Get the credit that is currently available or assigned to this link.
      Returns:
      the current link credit.

    • isDraining

      boolean isDraining()
      Indicates if the link is draining. For a Sender link this indicates that the remote has requested that the Sender transmit deliveries up to the currently available credit or indicate that it has no more to send. For a Receiver this indicates that the Receiver has requested that the Sender consume its outstanding credit.
      Returns:
      true if the Link is currently marked as draining.

    • getRole

      Role getRole()
      Returns:
      the Role that this end of the link is performing.

    • isSender

      boolean isSender()
      Returns:
      true if this link is acting in a sender Role.

    • isReceiver

      boolean isReceiver()
      Returns:
      true if this link is acting in a receiver Role.

    • getConnection

      Connection getConnection()
      Returns:
      the parent Connection for the Link

    • getSession

      Session getSession()
      Returns:
      the parent Session of the Link

    • getParent

      Session getParent()
      Description copied from interface: Endpoint
      Gets the parent of this Endpoint which can be itself for Connection instance.
      Specified by:
      getParent in interface Endpoint<L extends Link<L>>
      Returns:
      the parent Session of the Link

    • getName

      String getName()
      Returns:
      the link name that is assigned to this Link

    • setSenderSettleMode

      L setSenderSettleMode(SenderSettleMode senderSettleMode) throws IllegalStateException
      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 honoring the settlement mode. See Link.

      Parameters:
      senderSettleMode - The SenderSettleMode that will be set on the local end of this link.
      Returns:
      this Link.
      Throws:
      IllegalStateException - if the Link has already been opened.

    • getSenderSettleMode

      SenderSettleMode getSenderSettleMode()
      Gets the local link sender settlement mode.
      Returns:
      the local sender settlement mode, or null if none was set.
      See Also:

    • setReceiverSettleMode

      L setReceiverSettleMode(ReceiverSettleMode receiverSettleMode) throws IllegalStateException
      Sets the receiver 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. Used in analogous way to setSenderSettleMode(SenderSettleMode)

      Parameters:
      receiverSettleMode - The ReceiverSettleMode that will be set on the local end of this link.
      Returns:
      this Link.
      Throws:
      IllegalStateException - if the Link has already been opened.

    • getReceiverSettleMode

      ReceiverSettleMode getReceiverSettleMode()
      Gets the local link receiver settlement mode.
      Returns:
      the local receiver settlement mode, or null if none was set.
      See Also:

    • setSource

      L setSource(Source source) throws IllegalStateException
      Sets the Source to assign to the local end of this Link.

      Must be called during link setup, i.e. before calling the Endpoint.open() method.

      Parameters:
      source - The Source that will be set on the local end of this link.
      Returns:
      this Link.
      Throws:
      IllegalStateException - if the Link has already been opened.

    • getSource

      Source getSource()
      Returns:
      the Source for the local end of this link.

    • setTarget

      L setTarget(Target target) throws IllegalStateException
      Sets the Target to assign to the local end of this Link. Must be called during link setup, i.e. before calling the Endpoint.open() method.
      Parameters:
      target - The Target that will be set on the local end of this link.
      Returns:
      this Link.
      Throws:
      IllegalStateException - if the Link has already been opened.

    • setTarget

      L setTarget(Coordinator coordinator) throws IllegalStateException
      Sets the Coordinator target to assign to the local end of this Link.

      Must be called during link setup, i.e. before calling the Endpoint.open() method.

      Parameters:
      coordinator - The Coordinator target that will be set on the local end of this link.
      Returns:
      this Link.
      Throws:
      IllegalStateException - if the Link has already been opened.

    • getTarget

      <T extends Terminus> T getTarget()
      Returns the currently set Target for this Link. A link target can be either a Target type for a Sender or Receiver link or if the link is to be transaction resource then the target type will be a Coordinator instance.
      Type Parameters:
      T - The terminus type that the target should be cast to on return.
      Returns:
      the link target Terminus for the local end of this link.

    • setMaxMessageSize

      L setMaxMessageSize(UnsignedLong maxMessageSize) throws IllegalStateException
      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.
      Returns:
      this Link.
      Throws:
      IllegalStateException - if the Link has already been opened.

    • 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:

    • isRemotelyOpen

      boolean isRemotelyOpen()
      Returns true if this Link is currently remotely open meaning the state returned from getRemoteState() is equal to LinkState.ACTIVE. A link is remotely opened after an Attach has been received from the remote and before a Detach has been received from the remote.
      Specified by:
      isRemotelyOpen in interface Endpoint<L extends Link<L>>
      Returns:
      true if the link is remotely open.
      See Also:

    • isRemotelyClosed

      boolean isRemotelyClosed()
      Returns true if this Link is currently remotely closed meaning the state returned from getRemoteState() is equal to LinkState.CLOSED. A link is remotely closed after an Detach has been received from the remote with the close flag equal to true.
      Specified by:
      isRemotelyClosed in interface Endpoint<L extends Link<L>>
      Returns:
      true if the link is remotely closed.
      See Also:

    • isRemotelyDetached

      boolean isRemotelyDetached()
      Returns true if this Link is currently remotely detached meaning the state returned from getRemoteState() is equal to LinkState.DETACHED. A link is remotely detached after an Detach has been received from the remote with the close flag equal to false.
      Returns:
      true if the link is remotely detached.
      See Also:

    • isRemotelyClosedOrDetached

      boolean isRemotelyClosedOrDetached()
      Returns true if this Link is currently remotely detached or closed meaning the state returned from getRemoteState() is equal to LinkState.DETACHED or LinkState.CLOSED. A link is remotely detached or closed after a Detach has been received from the remote.
      Returns:
      true if the link is remotely detached or closed.
      See Also:

    • getRemoteSource

      Source getRemoteSource()
      Returns:
      the source Terminus for the remote end of this link.

    • getRemoteTarget

      <T extends Terminus> T getRemoteTarget()
      Returns the remote target Terminus cast to the given type. This can be used when the underlying type is known by the caller or as a control to validate the assumption of the underlying type.

      the currently set Target for this Link. A link target can be either a Target type for a Sender or Receiver link or if the link is to be transaction resource then the target type will be a Coordinator instance.

      Type Parameters:
      T - The type that the remote Terminus will be cast to on return.
      Returns:
      the source Terminus for the remote end of this link.

    • getRemoteSenderSettleMode

      SenderSettleMode getRemoteSenderSettleMode()
      Gets the remote link sender settlement mode, as conveyed from the peer via the Attach frame when attaching the link to the session.
      Returns:
      the sender settlement mode conveyed by the peer, or null if there was none.
      See Also:

    • getRemoteReceiverSettleMode

      ReceiverSettleMode getRemoteReceiverSettleMode()
      Gets the remote link receiver settlement mode, as conveyed from the peer via the Attach frame when attaching the link to the session.
      Returns:
      the sender receiver mode conveyed by the peer, or null if there was none.
      See Also:

    • 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.

    • getRemoteState

      LinkState getRemoteState()
      Returns:
      the remote link state (as last communicated)

    • localDetachHandler

      L localDetachHandler(EventHandler<L> localDetachHandler)
      Sets a EventHandler for when an this link is detached locally via a call to detach() This is a convenience event that supplements the normal Endpoint.localCloseHandler(EventHandler) event point if set. If no local detached event handler is set the endpoint will route the detached event to the local closed event handler if set and allow it to process the event in one location.

      Typically used by clients for logging or other state update event processing. Clients should not perform any blocking calls within this context. It is an error for the handler to throw an exception and the outcome of doing so is undefined.

      Parameters:
      localDetachHandler - The EventHandler to notify when this link is locally detached.
      Returns:
      the link for chaining.

    • detachHandler

      L detachHandler(EventHandler<L> remoteDetachHandler)
      Sets a EventHandler for when an AMQP Detach frame is received from the remote peer for this Link which would have been locally opened previously, the Detach from would have been marked as not having been closed.

      This is a convenience event that supplements the normal Endpoint.closeHandler(EventHandler) event point if set. If no detached event handler is set the endpoint will route the detached event to the closed event handler if set and allow it to process the event in one location.

      Parameters:
      remoteDetachHandler - The EventHandler to notify when this link is remotely closed.
      Returns:
      the Link for chaining.

    • creditStateUpdateHandler

      L creditStateUpdateHandler(EventHandler<L> handler)
      Handler for link credit updates that occur after a remote Flow arrives.
      Parameters:
      handler - An event handler that will be signaled when the link credit is updated by a remote flow.
      Returns:
      the Link for chaining.

    • parentEndpointClosedHandler

      L parentEndpointClosedHandler(EventHandler<L> handler)
      Sets a EventHandler for when the parent Session or Connection of this link is locally closed.

      Typically used by clients for logging or other state update event processing. Clients should not perform any blocking calls within this context. It is an error for the handler to throw an exception and the outcome of doing so is undefined.

      Parameters:
      handler - The EventHandler to notify when this link's parent Session is locally closed.
      Returns:
      the link for chaining.