Package org.apache.qpid.protonj2.engine

Interface IncomingDelivery

All Known Implementing Classes:
ProtonIncomingDelivery
public interface IncomingDelivery
API for an incoming Delivery.

  • Method Details

    • getLink

      Receiver getLink()
      Returns:
      the link that this IncomingDelivery is bound to.

    • available

      int available()
      Returns the number of bytes currently available for reading form this delivery, which may not be complete yet.

      Note that this value will change as bytes are received, and is in general not equal to the total length of a delivery, except the point where isPartial() returns false and no content has yet been received by the application.

      Returns:
      the number of bytes currently available to read from this delivery.

    • claimAvailableBytes

      IncomingDelivery claimAvailableBytes()
      Marks all available bytes as being claimed by the caller meaning that available byte count value can be returned to the session which can expand the session incoming window to allow more bytes to be sent from the remote peer.

      This method is useful in the case where the Session has been configured with a small incoming capacity and the receiver needs to expand the session window in order to read the entire contents of a delivery whose payload exceeds the configured session capacity. The IncomingDelivery implementation will track the amount of claimed bytes and ensure that it never releases back more bytes to the Session than has actually been received as a whole which allows this method to be called with each incoming Transfer frame of a large split framed delivery.

      Returns:
      this IncomingDelivery instance.

    • readAll

      ProtonBuffer readAll()
      Returns the current read buffer without copying it effectively consuming all currently available bytes from this delivery. If no data is available then this method returns null.
      Returns:
      the currently available read bytes for this delivery.

    • readBytes

      IncomingDelivery readBytes(ProtonBuffer buffer)
      Reads bytes from this delivery and writes them into the destination ProtonBuffer reducing the available bytes by the value of the number of bytes written to the target. The number of bytes written will be the equal to the writable bytes of the target buffer. The write index of the target buffer will be incremented by the number of bytes written into it.
      Parameters:
      buffer - The target buffer that will be written into.
      Returns:
      this IncomingDelivery instance.
      Throws:
      IndexOutOfBoundsException - if the target buffer has more writable bytes than this delivery has readable bytes.

    • readBytes

      IncomingDelivery readBytes(byte[] array, int offset, int length)
      Reads bytes from this delivery and writes them into the destination array starting at the given offset and continuing for the specified length reducing the available bytes by the value of the number of bytes written to the target.
      Parameters:
      array - The target buffer that will be written into.
      offset - The offset into the given array to begin writing.
      length - The number of bytes to write to the given array.
      Returns:
      this IncomingDelivery instance.
      Throws:
      IndexOutOfBoundsException - if the length is greater than this delivery has readable bytes.

    • setDefaultDeliveryState

      IncomingDelivery setDefaultDeliveryState(DeliveryState state)
      Configures a default DeliveryState to be used if a received delivery is settled/freed without any disposition state having been previously applied.
      Parameters:
      state - the default delivery state
      Returns:
      this IncomingDelivery instance.

    • getDefaultDeliveryState

      DeliveryState getDefaultDeliveryState()
      Returns:
      the default delivery state for this delivery

    • getAttachments

      Attachments getAttachments()
      Returns:
      the Attachments instance that is associated with this IncomingDelivery

    • setLinkedResource

      IncomingDelivery setLinkedResource(Object resource)
      Links a given resource to this IncomingDelivery.
      Parameters:
      resource - The resource to link to this IncomingDelivery.
      Returns:
      this IncomingDelivery instance.

    • getLinkedResource

      <T> T getLinkedResource()
      Type Parameters:
      T - The type that the linked resource should be cast to on return.
      Returns:
      the user set linked resource for this Endpoint instance.

    • getLinkedResource

      <T> T getLinkedResource(Class<T> typeClass)
      Gets the linked resource (if set) and returns it using the type information provided to cast the returned value.
      Type Parameters:
      T - The type to cast the linked resource to if one is set.
      Parameters:
      typeClass - the type's Class which is used for casting the returned value.
      Returns:
      the user set linked resource for this Context instance.
      Throws:
      ClassCastException - if the linked resource cannot be cast to the type requested.

    • getTag

      DeliveryTag getTag()
      Returns:
      the DeliveryTag assigned to this Delivery.

    • getState

      DeliveryState getState()
      Returns:
      the DeliveryState at the local side of this Delivery.

    • getMessageFormat

      int getMessageFormat()
      Gets the message-format for this Delivery, representing the 32bit value using an int.

      The default value is 0 as per the message format defined in the core AMQP 1.0 specification.

      See the following for more details:
      http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-transport-v1.0-os.html#type-transfer
      http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-transport-v1.0-os.html#type-message-format
      http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format
      http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#definition-MESSAGE-FORMAT

      Returns:
      the message-format for this Delivery.

    • isPartial

      boolean isPartial()
      Check for whether the delivery is still partial.

      For a receiving Delivery, this means the delivery does not hold a complete message payload as all the content hasn't been received yet. Note that an aborted delivery will also be considered partial and the full payload won't be received.

      For a sending Delivery, this means that the application has not marked the delivery as complete yet.

      Returns:
      true if the delivery is partial
      See Also:

    • isAborted

      boolean isAborted()
      Returns:
      true if the delivery has been aborted.

    • isSettled

      boolean isSettled()
      Returns:
      true if the delivery has been settled locally.

    • disposition

      IncomingDelivery disposition(DeliveryState state)
      updates the state of the delivery
      Parameters:
      state - the new delivery state
      Returns:
      this IncomingDelivery instance.

    • disposition

      IncomingDelivery disposition(DeliveryState state, boolean settle)
      Update the delivery with the given disposition if not locally settled and optionally settles the delivery if not already settled.

      Applies the given delivery state and local settlement value to this delivery writing a new Disposition frame if the remote has not already settled the delivery. Once locally settled no additional updates to the local DeliveryState can be applied and if attempted an IllegalStateException will be thrown to indicate this is not possible.

      Parameters:
      state - the new delivery state
      settle - if true the delivery is settled.
      Returns:
      this IncomingDelivery instance.

    • settle

      IncomingDelivery settle()
      Settles this delivery locally, transmitting a Disposition frame to the remote if the remote has not already settled the delivery. Once locally settled the delivery will not accept any additional updates to the DeliveryState via one of the disposition(DeliveryState) or disposition(DeliveryState, boolean) methods.
      Returns:
      this IncomingDelivery instance.

    • getRemoteState

      DeliveryState getRemoteState()
      Returns:
      the DeliveryState at the remote side of this Delivery.

    • isRemotelySettled

      boolean isRemotelySettled()
      Returns:
      true if the delivery has been settled by the remote.

    • getTransferCount

      int getTransferCount()
      Returns the total number of transfer frames that have occurred for the given IncomingDelivery.
      Returns:
      the number of Transfer frames that this OutgoingDelivery has initiated.

    • deliveryReadHandler

      IncomingDelivery deliveryReadHandler(EventHandler<IncomingDelivery> handler)
      Handler for incoming deliveries that is called for each incoming Transfer frame that comprises either one complete delivery or a chunk of a split framed Transfer. The handler should check that the delivery being read is partial or not and act accordingly, as partial deliveries expect additional updates as more frames comprising that IncomingDelivery arrive or the remote aborts the transfer.

      This handler is useful in cases where an incoming delivery is split across many incoming Transfer frames either due to a large size or a small max frame size setting and the processing is handed off to some other resource other than the Receiver that original handling the first transfer frame. If the initial Transfer carries the entire delivery payload then this event handler will never be called. Once set this event handler receiver all updates of incoming delivery Transfer frames which would otherwise have been sent to the Receiver.deliveryReadHandler(EventHandler) instance.

      Parameters:
      handler - The handler that will be invoked when Transfer frames arrive on this receiver link.
      Returns:
      this IncomingDelivery instance.

    • deliveryAbortedHandler

      IncomingDelivery deliveryAbortedHandler(EventHandler<IncomingDelivery> handler)
      Handler for aborted deliveries that is called if this delivery is aborted by the Sender.

      This handler is an optional convenience handler that supplements the standard deliveryReadHandler(EventHandler) in cases where the users wishes to break out the processing of inbound delivery data from abort processing. If this handler is not set the Receiver will call the registered deliveryAbortedHandler(EventHandler) if one is set.

      Parameters:
      handler - The handler that will be invoked when Transfer frames arrive on this receiver link.
      Returns:
      this IncomingDelivery instance.

    • deliveryStateUpdatedHandler

      IncomingDelivery deliveryStateUpdatedHandler(EventHandler<IncomingDelivery> handler)
      Handler for updates to the remote state of incoming deliveries that have previously been received.

      Remote state updates for an IncomingDelivery can happen when the remote settles a complete IncomingDelivery or otherwise modifies the delivery outcome and the user needs to act on those changes such as a spontaneous update to the DeliveryState. If the initial Transfer of an incoming delivery already indicates settlement then this handler will never be called.

      Parameters:
      handler - The handler that will be invoked when a new remote state update for an IncomingDelivery arrives on this link.
      Returns:
      this IncomingDelivery instance.