Package org.apache.qpid.protonj2.engine

Interface IncomingDelivery

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

    • Method Detail

      • 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:
        java.lang.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:
        java.lang.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

      • 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​(java.lang.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:
        java.lang.ClassCastException - if the linked resource cannot be cast to the type requested.

      • 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()

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

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

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